Copy page

DAL Library

CI/CD and Release Process

CI/CD and Release Process

Relevant source files

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

• .github/workflows/ci.yml
• docs/gitflow.md
• package.json
• scripts/version-sync.mjs

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.

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.

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

Code
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 — Detailed rules for branch management, naming, and closing procedures.
• AI Agent Rules and Skills — Configuration and guardrails for AI agents working within this repository.

---