CI/CD Integrations

LPM supports multiple authentication patterns for CI/CD — installing packages, decrypting the env vault, and publishing — all OIDC-first where possible.

Use case	Method	Plan
Install LPM packages (OIDC, recommended)	lpm setup --oidc	Any
Install LPM packages (static token)	LPM_TOKEN secret + lpm setup	Any
Decrypt project env vault in CI	lpm env pull --oidc	Pro/Org
Publish via Trusted Publishers (OIDC)	Dashboard config + workflow	Any
Bitbucket Pipelines (no OIDC available)	LPM_TOKEN secret	Any

---

1. Secret-Free Installs with OIDC (recommended)

Use lpm setup --oidc to install LPM packages without storing any secrets. The CI provider proves its identity via OIDC, and LPM issues a 30-minute read-only token automatically.

Prerequisites:

• Your GitHub or GitLab account must be linked to your LPM account at Settings > Security
• The workflow must have id-token: write permission

GitHub Actions

name: Build
on: push

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Configure LPM registry (OIDC)
        run: npx @lpm-registry/cli setup --oidc

      - name: Install dependencies
        run: npm install

      - name: Build
        run: npm run build

No LPM_TOKEN secret needed. The OIDC token exchange happens automatically during lpm setup --oidc.

GitLab CI

build:
  stage: build
  image: node:22
  id_tokens:
    LPM_GITLAB_OIDC_TOKEN:
      aud: https://lpm.dev
  script:
    - npx @lpm-registry/cli setup --oidc
    - npm install
    - npm run build

GitLab (15.7+) injects the signed JWT directly as the LPM_GITLAB_OIDC_TOKEN environment variable.

How OIDC install works

1. CI provider generates a signed identity token (JWT)
2. lpm setup --oidc detects the CI environment and requests this token
3. LPM verifies the JWT signature and matches the CI user to a linked LPM account
4. LPM issues a 30-minute read-only token
5. The token is written to .npmrc — npm install works immediately

If OIDC exchange fails (wrong setup, unlinked account), the command falls back to the ${LPM_TOKEN} placeholder with a warning.

---

2. Decrypt the Env Vault in CI (Pro/Org)

lpm env pull --oidc decrypts your project's encrypted environment vault inside CI without storing a long-lived LPM_TOKEN or copying secrets into the platform UI. The CI run's identity token is exchanged for short-lived decrypt access, the lpm.dev server decrypts the blob, filters by environment, and returns plaintext over TLS — never persisted, never logged.

This requires a Pro or Org plan and a one-time opt-in per vault (lpm env oidc allow). See OIDC for CI for the architecture and the policy form.

GitHub Actions

name: Build
on: push

permissions:
  id-token: write
  contents: read

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install LPM
        run: npm install -g @lpm-registry/cli

      - name: Decrypt env vault
        run: lpm env pull --oidc --env=production --output=.env

      - run: npm ci
      - run: npm run build

The OIDC token is fetched automatically from GitHub Actions' runtime — the workflow just needs permissions: id-token: write.

GitLab CI

build:
  stage: build
  image: node:22
  id_tokens:
    LPM_OIDC_TOKEN:
      aud: https://lpm.dev
  script:
    - npm install -g @lpm-registry/cli
    - lpm env pull --oidc --env=production --output=.env
    - npm ci
    - npm run build

GitLab mints the JWT via the id_tokens: block; the CLI picks up LPM_OIDC_TOKEN automatically.

Combined: install packages + decrypt env in one job

jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 22 }

      - run: npm install -g @lpm-registry/cli
      - run: lpm setup --oidc                  # OIDC → 30-min .npmrc token
      - run: lpm env pull --oidc --env=production --output=.env
      - run: npm ci
      - run: npm test
      - run: npm run build

A single OIDC token round-trip is reused — the workflow stays secret-free for both installs and env decrypt.

---

3. Secret-Free Publishing with Trusted Publishers

For publishing via OIDC, you need a Trusted Publisher configuration (more restrictive than install, since publishing modifies packages).

Step 1 — Add a trusted publisher in the dashboard

1. Open your package in the LPM dashboard
2. Go to the Trusted Publishers tab
3. Click Add Trusted Publisher
4. Select GitHub Actions or GitLab CI
5. Fill in repository owner, repository name, workflow/config file, and optional environment
6. Save

The repository, workflow filename, and environment (if set) must match exactly what the CI pipeline sends.

Step 2 — Add the workflow

GitHub Actions — .github/workflows/publish.yml:

name: Publish to LPM
on:
  push:
    tags:
      - 'v*'

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - run: npm ci

      - run: npx lpm publish
        env:
          LPM_PACKAGE: "@lpm.dev/your-username.your-package"

GitLab CI — .gitlab-ci.yml:

publish:
  stage: publish
  image: node:22
  id_tokens:
    LPM_GITLAB_OIDC_TOKEN:
      aud: https://lpm.dev
  script:
    - npm ci
    - LPM_PACKAGE="@lpm.dev/your-username.your-package" npx lpm publish
  rules:
    - if: '$CI_COMMIT_TAG =~ /^v/'

OIDC install + publish in one workflow

You can combine both in a single workflow — OIDC handles both the install and publish steps:

name: CI + Publish
on:
  push:
    tags:
      - 'v*'

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Configure LPM registry (OIDC)
        run: npx @lpm-registry/cli setup --oidc

      - run: npm ci

      - run: npm test

      - run: npx lpm publish
        env:
          LPM_PACKAGE: "@lpm.dev/your-username.your-package"

---

4. Bitbucket Pipelines

Bitbucket Pipelines uses token-based authentication with the LPM_TOKEN environment variable. OIDC is not currently available for Bitbucket because Bitbucket's OIDC tokens do not include user identity claims needed for authentication.

Bitbucket's OIDC implementation is designed for cloud provider authentication (AWS, GCP) and does not yet support package registry workflows. This is a known limitation — we'll add OIDC support when Bitbucket adds the necessary claims. In the meantime, LPM_TOKEN works reliably.

Install packages

pipelines:
  default:
    - step:
        name: Build
        image: node:22
        script:
          - npx @lpm-registry/cli setup
          - npm ci
          - npm run build
          - npm test

Add LPM_TOKEN as a repository variable under Repository settings > Pipelines > Repository variables.

Publish packages

pipelines:
  tags:
    'v*':
      - step:
          name: Publish
          image: node:22
          script:
            - npx @lpm-registry/cli setup
            - npm ci
            - npx lpm publish

Install + publish

definitions:
  steps:
    - step: &build
        name: Build & Test
        image: node:22
        script:
          - npx @lpm-registry/cli setup
          - npm ci
          - npm run build
          - npm test

pipelines:
  default:
    - step: *build
  tags:
    'v*':
      - step: *build
      - step:
          name: Publish
          image: node:22
          script:
            - npx @lpm-registry/cli setup
            - npm ci
            - npx lpm publish

---

5. Token-Based Authentication (any platform)

For CI platforms without OIDC support, or deployment platforms like Vercel and Netlify, use the LPM_TOKEN environment variable.

GitHub Actions (with token)

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npx @lpm-registry/cli setup
      - run: npm ci
        env:
          LPM_TOKEN: ${{ secrets.LPM_TOKEN }}

Add LPM_TOKEN under Settings > Secrets and variables > Actions.

GitLab CI (with token)

build:
  stage: build
  image: node:22
  script:
    - npx @lpm-registry/cli setup
    - npm ci
    - npm run build
  variables:
    LPM_TOKEN: $LPM_TOKEN

Add LPM_TOKEN under Settings > CI/CD > Variables.

---

6. Version Management

Before triggering a publish workflow, bump the version in package.json. Two common approaches:

Manual tagging:

npm version patch   # or minor / major
git push --tags

npm version updates package.json, commits the bump, and creates a vX.Y.Z git tag in one step. The push --tags triggers the workflow.

Automated with Changesets or Release Please:

• Changesets — popular for monorepos; contributors add changeset files, a release PR aggregates them
• Release Please — Google's GitHub Action for automated versioning from Conventional Commits

---

7. Verifying a Publish

After your first OIDC publish:

1. Open your package in the LPM dashboard > Trusted Publishers tab
2. Scroll to Recent CI Publishes — each row shows the version, repository, commit SHA, workflow file, and publish date
3. On the public package page, the Versions tab shows provenance metadata (repository, workflow, commit) next to each version published via OIDC

---

8. Validating Before Publishing

Run lpm publish --dry-run locally or in CI to verify your setup before the real publish:

npx lpm publish --dry-run

This builds the tarball, runs quality checks, and prints a summary — including OIDC detection status — without uploading anything.