Skip to content

Latest commit

 

History

History
146 lines (102 loc) · 3.6 KB

DEPLOYMENT.md

File metadata and controls

146 lines (102 loc) · 3.6 KB

Deployment Guide

This document describes how to deploy @astro-api/astroapi-typescript to NPM using GitHub Actions with OIDC Trusted Publishing.

Prerequisites

Before deploying, ensure you have:

  • Access to the GitHub repository with admin permissions
  • An NPM account with publish access to @astro-api scope
  • NPM organization @astro-api created

Initial Setup

1. Configure NPM Trusted Publishing (OIDC)

NPM Trusted Publishing allows GitHub Actions to publish packages without storing any secrets.

  1. Log in to npmjs.com
  2. Go to your package page: @astro-api/astroapi-typescript
  3. Click Settings → Publishing access
  4. Under Trusted publishing, click Add trusted publisher
  5. Configure the trusted publisher:
    • Provider: GitHub Actions
    • Repository owner: astro-api
    • Repository name: astroapi-typescript
    • Workflow filename: release.yml
    • Environment: (leave empty)
  6. Click Add

Note: For new packages, publish the first version manually, then configure trusted publishing.

2. First-time Package Creation (if new)

npm login
npm publish --access public

3. Configure Branch Protection (Recommended)

  1. Go to Settings → Branches
  2. Add protection for master branch:
    • Require a pull request before merging
    • Require status checks to pass

How Releases Work

This project uses Changesets for version management.

Release Flow

Developer creates changeset → Bump version → Create PR → Merge PR → Auto-publish to npm

Creating a Release

  1. Create changeset (describe your changes):

    npx changeset

    Select change type: patch, minor, or major

  2. Bump version (updates package.json and CHANGELOG):

    npx changeset version

  3. Commit and create PR:

    git add .
git commit -m "chore: release vX.Y.Z"
git push origin HEAD

    Create PR manually on GitHub

  4. Merge PR → Workflow auto-publishes to npm with OIDC provenance

Workflows

CI Workflow (ci.yml)

Triggers: Push to master, Pull requests

  • Runs ESLint
  • Runs tests with coverage
  • Builds package

Release Workflow (release.yml)

Triggers: Push to master

  • Checks if pending changesets exist (skips publish if yes)
  • Publishes to npm when no pending changesets (version already bumped)
  • Creates GitHub Release with auto-generated notes

Troubleshooting

NPM Publish Failed

Problem: PR merged but publish failed

Solutions:

  1. Verify trusted publishing is configured on npm
  2. Check repository owner/name matches exactly
  3. Ensure id-token: write permission is set
  4. Verify repository is public (required for provenance)

OIDC Token Issues

Problem: "Unable to get OIDC token" error

Solutions:

  1. Ensure id-token: write in workflow permissions
  2. Verify registry-url in setup-node action
  3. Confirm trusted publisher on npm matches workflow

Quick Reference

# Local development
npm install
npm run lint
npm run test
npm run build

# Before releasing - create a changeset
npx changeset

# Commit and push
git add .
git commit -m "feat: add new feature"
git push

Version Strategy

  • patch: Bug fixes, minor updates
  • minor: New features, backward compatible
  • major: Breaking changes

Support