Skip to content

github-packages-setup.md

Latest commit

 

History

History
94 lines (65 loc) · 2.62 KB

github-packages-setup.md

File metadata and controls

94 lines (65 loc) · 2.62 KB
Raw

GitHub Packages Setup for @multiplier-labs/stepflow

This document describes how to publish stepflow to GitHub Packages and how to install it in your projects.

Publishing (Maintainers)

Automated Publishing via Release

  1. Ensure your changes are merged to the main branch
  2. Go to Releases in the GitHub repository
  3. Click Draft a new release
  4. Create a tag matching the version in package.json (e.g., v0.1.0)
  5. Publish the release

The GitHub Actions workflow (.github/workflows/publish.yml):

  • Installs dependencies, audits, builds, typechecks and tests
  • Stages the release on npmjs.org via trusted publishing (OIDC, no stored token), with provenance

A staged release is not live until a maintainer approves it with 2FA:

npm stage list @multiplier-labs/stepflow --registry=https://registry.npmjs.org
npm stage approve <stage-id> --otp=<code> --registry=https://registry.npmjs.org

Staged releases can also be approved on npmjs.com. npm stage requires npm 12 or later.

The trusted publisher is configured on npmjs.com under the package's Settings → Trusted Publisher (Multiplier-Labs/stepflow, publish.yml). Renaming the workflow file requires updating it there.

Installing in Projects

Step 1: Configure npm for the @multiplier-labs scope

Create or update .npmrc in your project root:

@multiplier-labs:registry=https://npm.pkg.github.com

Step 2: Authenticate with GitHub Packages

Generate a Personal Access Token (PAT):

  1. Go to GitHub → Settings → Developer settings → Personal access tokens
  2. Generate a token with read:packages scope
  3. Authenticate npm:
npm login --registry=https://npm.pkg.github.com
# Username: your GitHub username
# Password: your PAT
# Email: your email

Alternatively, add to your ~/.npmrc (for global auth):

//npm.pkg.github.com/:_authToken=YOUR_PAT_HERE

Step 3: Install the package

npm install @multiplier-labs/stepflow

Usage in CI/CD

For GitHub Actions, use the built-in GITHUB_TOKEN:

- uses: actions/setup-node@v4
  with:
    node-version: '22'
    registry-url: 'https://npm.pkg.github.com'
    scope: '@multiplier-labs'

- run: npm ci
  env:
    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For other CI systems, set NODE_AUTH_TOKEN environment variable to a PAT with read:packages scope.

Versioning

Update the version in package.json before creating a release:

npm version patch  # 0.1.0 → 0.1.1
npm version minor  # 0.1.0 → 0.2.0
npm version major  # 0.1.0 → 1.0.0

Then push the tag and create a release on GitHub.