# CI/CD & NPM Publishing

# CI/CD & NPM Publishing

<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)
- [.npmrc](.npmrc)
- [LICENSE](LICENSE)

</details>



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**
```mermaid
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**
```mermaid
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`]()

---