Copy page

SDK Library

CI/CD & NPM Publishing

CI/CD & NPM Publishing

Relevant source files

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

• .github/workflows/ci.yml
• .npmrc
• LICENSE

The @primebrick/sdk employs a modern, secure, and automated delivery pipeline using GitHub Actions. The workflow is designed to ensure code quality through rigorous build gates and to maximize supply-chain security by leveraging OpenID Connect (OIDC) for passwordless authentication and build provenance.

Release Trigger & Workflow Activation

The CI/CD pipeline is exclusively triggered by the creation of a numeric version tag .github/workflows/ci.yml:3-7. The workflow filters for tags matching the Semantic Versioning (SemVer) pattern X.Y.Z (e.g., 1.0.4).

Once triggered, the workflow executes on an ubuntu-latest runner .github/workflows/ci.yml:18-18. The environment is initialized with Node.js version 24 .github/workflows/ci.yml:26-26 and the pnpm package manager .github/workflows/ci.yml:30-30.

Build and Quality Gates

Before any code is published, the environment undergoes three critical validation steps:

1. Dependency Integrity: Uses pnpm install --frozen-lockfile to ensure the exact dependency tree from the lockfile is used, preventing "dependency drift" .github/workflows/ci.yml:33-33.
2. Compilation: Executes pnpm run build to generate the distribution files .github/workflows/ci.yml:36-36.
3. Static Analysis: Runs npx tsc --noEmit as a final type-check gate to ensure no TypeScript errors exist that might have been missed during local development .github/workflows/ci.yml:39-39.

OIDC Trusted Publishing

The SDK utilizes OIDC Trusted Publishing, which eliminates the need for a long-lived NPM_TOKEN stored in GitHub Secrets .github/workflows/ci.yml:9-11. Instead, GitHub Actions generates a short-lived OIDC token that npmjs.com verifies against a pre-configured Trusted Publisher link .github/workflows/ci.yml:41-46.

Permissions Model

The workflow operates under a principle of least privilege, requiring only two specific permissions .github/workflows/ci.yml:12-15:

• contents: read: Necessary to checkout the repository code.
• id-token: write: Mandatory for the OIDC handshake with npmjs.com.

Data Flow: Tag to NPM Registry

The following diagram illustrates the lifecycle of a release, from the git tag event to the final registry update.

Release Pipeline Data Flow

Code
graph TD
    ["Git Tag (e.g. 1.2.3)"] -- "Triggers" --> ["GitHub Actions Runner"]
    subgraph "CI Environment"
        ["GitHub Actions Runner"] -- "pnpm install" --> ["node_modules"]
        ["node_modules"] -- "pnpm run build" --> ["dist/"]
        ["dist/"] -- "tsc --noEmit" --> ["Type Validation"]
    end
    ["Type Validation"] -- "Success" --> ["OIDC Handshake"]
    subgraph "Authentication & Publishing"
        ["OIDC Handshake"] -- "Exchange GitHub Token" --> ["NPM Registry"]
        ["NPM Registry"] -- "Verify Publisher" --> ["@primebrick/sdk"]
        ["@primebrick/sdk"] -- "npm publish --provenance" --> ["Public Registry"]
    end

Sources: .github/workflows/ci.yml:1-47

Supply Chain Security & Provenance

The publishing step includes the --provenance flag .github/workflows/ci.yml:47-47. This generates a verifiable attestation that links the published npm package directly to the specific GitHub Actions run and the source commit that produced it. This allows consumers of the SDK to verify the authenticity and integrity of the artifacts.

The package is published with public access .github/workflows/ci.yml:47-47 to the default npm registry .npmrc:1-2.

Publishing Process Entities

This diagram maps the CLI commands and configurations to the external entities involved in the publishing process.

Code-to-Registry Mapping

Code
graph LR
    subgraph "Local Config"
        ["pnpm-lock.yaml"]
        [".npmrc"]
    end
    subgraph "GitHub Workflow (.github/workflows/ci.yml)"
        ["setup-node@v6"]
        ["pnpm/action-setup@v4"]
        ["npm_publish_step"]
    end
    subgraph "NPM Ecosystem"
        ["npmjs.com"]
        ["@primebrick/sdk"]
    end

    ["pnpm-lock.yaml"] --> ["pnpm/action-setup@v4"]
    [".npmrc"] --> ["npm_publish_step"]
    ["npm_publish_step"] -- "npm publish --provenance" --> ["@primebrick/sdk"]
    ["@primebrick/sdk"] -- "Verify OIDC" --> ["npmjs.com"]

Sources: .github/workflows/ci.yml:24-47, .npmrc:1-3

Licensing

The SDK is distributed under the MIT License LICENSE:1-1. This permissive license is included in the root of the repository and is bundled with the published package to allow for broad integration within both open-source and proprietary microservices LICENSE:5-10.

Sources: LICENSE:1-22

---