# CI/CD and Release Process

# CI/CD and Release Process

<details>
<summary>Relevant source files</summary>

The following files were used as context for generating this wiki page:

- [.github/workflows/ci.yml](.github/workflows/ci.yml)
- [docs/gitflow.md](docs/gitflow.md)
- [package.json](package.json)
- [scripts/version-sync.mjs](scripts/version-sync.mjs)

</details>



This page documents the automated pipeline and organizational workflows used to build, test, and publish the `@primebrick/dal-pg` package. The process relies on GitHub Actions for automation, OIDC for secure publishing, and a strict GitFlow-based branching model to ensure version integrity.

## Pipeline Overview

The CI/CD pipeline is designed to ensure that every release is verifiable and secure. It utilizes **OIDC (OpenID Connect) Trusted Publishing**, which eliminates the need for long-lived NPM tokens by allowing GitHub Actions to authenticate directly with NPM via short-lived identity tokens.

### CI Workflow Steps
The release workflow triggers on numeric version tags (e.g., `0.1.0`) and performs the following sequence:

1.  **Environment Setup**: Initializes Node.js and `pnpm` using the version specified in `packageManager` [[package.json:44-44](), [.github/workflows/ci.yml:23-30]()].
2.  **Dependency Installation**: Runs `pnpm install --frozen-lockfile` to ensure reproducible builds [[.github/workflows/ci.yml:33-33]()].
3.  **Build**: Executes `pnpm run build` (which invokes `tsc`) [[package.json:34-34](), [.github/workflows/ci.yml:36-36]()].
4.  **Verification**: Performs a secondary type check via `tsc --noEmit` to catch any compilation issues [[.github/workflows/ci.yml:39-39]()].
5.  **Publishing**: Publishes the package to the NPM registry with the `--provenance` flag, linking the published artifact back to the specific GitHub Actions run [[.github/workflows/ci.yml:47-47]()].

### Versioning Logic
The system uses a custom script, `version-sync.mjs`, to keep the `package.json` version in sync with the Git branch name during the release process.

| Component | Role | Source |
| :--- | :--- | :--- |
| `version:auto` | Script to manually trigger version synchronization. | [package.json:32-32]() |
| `prebuild` hook | Safety net that runs `version-sync.mjs` before every build. | [package.json:33-33]() |
| `version-sync.mjs` | Logic to parse `release/X.Y.Z` or `hotfix/X.Y.Z` and update `package.json`. | [scripts/version-sync.mjs:17-21]() |

**Sources:** [.github/workflows/ci.yml:1-48](), [package.json:31-39](), [scripts/version-sync.mjs:1-65]()

## Branching and GitFlow

The project follows a strict GitFlow methodology. AI agents and human contributors must adhere to specific branch naming and merging rules to maintain a stable `main` branch and accurate version history.

### Branching Strategy
*   **`main`**: Production-ready code. Only receives merges from `release/` or `hotfix/` branches.
*   **`develop`**: Integration branch for features.
*   **`feature/<slug>`**: New functionality. Created from `develop`.
*   **`release/<version>`**: Preparation for a new release. Created from `develop`.
*   **`hotfix/<version>`**: Urgent production fixes. Created from `main`.

### Release Tagging Convention
The project uses a strict numeric tagging convention without prefixes:
*   **Format**: `MAJOR.MINOR.PATCH` (e.g., `0.1.8`).
*   **Constraint**: Never use a 'v' prefix (e.g., `v0.1.8` is invalid) [[docs/gitflow.md:77-80]()].

For a detailed breakdown of branch closing procedures and merge requirements, see [GitFlow and Branching Rules](#8.1).

**Sources:** [docs/gitflow.md:16-21](), [docs/gitflow.md:76-83]()

## AI Agent Integration

This repository is optimized for AI agents (specifically Devin). Specific guardrails are in place to prevent accidental commits and ensure compliance with the DAL's architectural standards.

### Core Guardrails
*   **Explicit Instruction**: AI agents must never commit changes without a direct user command (e.g., "commit") [[docs/gitflow.md:5-15]()].
*   **Automated Sync**: The `version-sync.mjs` script acts as a guardrail to prevent mismatched versions between the branch name and the `package.json` file [[docs/gitflow.md:64-74]()].

For more information on agent skills and file operation rules, see [AI Agent Rules and Skills](#8.2).

**Sources:** [docs/gitflow.md:3-15](), [docs/gitflow.md:64-75]()

## Release Lifecycle Diagram

The following diagram illustrates the transition from development to a published NPM package, mapping the natural language stages to the code entities and scripts involved.

### Release Flow: Branch to Registry
```mermaid
graph TD
    subgraph "Local Development"
        A["feature/branch"] -- "merge --no-ff" --> B["develop"]
        B -- "checkout" --> C["release/0.2.0"]
    end

    subgraph "Version Synchronization"
        C -- "pnpm run version:auto" --> D["version-sync.mjs"]
        D -- "Updates version: '0.2.0'" --> E["package.json"]
    end

    subgraph "Git Finalization"
        E -- "git commit & merge" --> F["main"]
        F -- "git tag 0.2.0" --> G["Git Tag"]
    end

    subgraph "GitHub Actions CI"
        G -- "Trigger" --> H[".github/workflows/ci.yml"]
        H -- "pnpm run build" --> I["tsc"]
        I -- "npm publish --provenance" --> J["NPM Registry"]
    end

    style D stroke-dasharray: 5 5
    style H stroke-width:2px
```
**Sources:** [docs/gitflow.md:52-60](), [scripts/version-sync.mjs:47-64](), [.github/workflows/ci.yml:3-7]()

## Trusted Publishing and Provenance

The release process utilizes OIDC for security. This allows the GitHub Actions runner to request a token from GitHub, which is then presented to NPM. NPM verifies that the token was generated by the specific repository and workflow defined in the package settings.

### Security Mapping
| Security Concept | Implementation in Code |
| :--- | :--- |
| **Identity Provider** | `permissions: id-token: write` [[.github/workflows/ci.yml:14-14]()] |
| **Provenance** | `npm publish --provenance` [[.github/workflows/ci.yml:47-47]()] |
| **Trusted Publisher** | Configured on NPM for `michaelsogos/primebrick-v3-dal` [[.github/workflows/ci.yml:43-46]()] |

**Sources:** [.github/workflows/ci.yml:9-15](), [.github/workflows/ci.yml:41-47]()

---

## Child Pages
- [GitFlow and Branching Rules](#8.1) — Detailed rules for branch management, naming, and closing procedures.
- [AI Agent Rules and Skills](#8.2) — Configuration and guardrails for AI agents working within this repository.

---