Publishing Codemods

This guide covers all the ways to publish codemods to the Codemod Registry, from local development to automated CI/CD pipelines.

Authentication Methods

Codemod supports three authentication methods for publishing:

Method	Best For	Secrets Required	Setup
Interactive Login	Local development	None	None
API Keys	CI/CD pipelines, automation	Yes (`CODEMOD_API_KEY`)	Create key in UI
Trusted Publishers	GitHub Actions, secure CI/CD	None (uses OIDC)	None for org scopes*

_{* If your GitHub organization name matches your package scope, trusted publishing works automatically with zero configuration. See Organization Scopes.} The simplest way to authenticate for local development. Opens a browser for OAuth authentication.

# Login to the registry
npx codemod login

# Verify authentication
npx codemod whoami

After logging in, you can publish packages:

npx codemod publish

When to Use

Local development and testing
Quick one-off publishes
When you prefer browser-based authentication

API Keys

API keys allow non-interactive authentication, perfect for CI/CD pipelines and automation.

Creating an API Key

Go to codemod.com/api-keys
Click Create API Key
Give it a descriptive name (e.g., “GitHub Actions - my-repo”)
Select the permissions (typically “Publish Packages”)
Copy the key (it won’t be shown again)

Using API Keys

Option 1: Login with API key

npx codemod login --api-key $CODEMOD_API_KEY
npx codemod publish

Option 2: Environment variable

CODEMOD_AUTH_TOKEN=$CODEMOD_API_KEY npx codemod publish

GitHub Actions Example

name: Publish Codemod
on:
  release:
    types: [published]

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

      - name: Login to Codemod Registry
        run: npx codemod login --api-key ${{ secrets.CODEMOD_API_KEY }}

      - name: Publish codemod
        run: npx codemod publish

Store your API key as a repository secret. Never commit API keys to your repository.

When to Use

CI/CD pipelines without GitHub Actions OIDC
GitLab CI, CircleCI, Jenkins, etc.
Automated publishing from any environment
When you need explicit control over credentials

Trusted Publishers

Trusted publishers enable passwordless publishing from GitHub Actions using OpenID Connect (OIDC). No secrets to manage or rotate.

How OIDC Works

GitHub Actions can request short-lived tokens that cryptographically prove the workflow’s identity. Codemod verifies these tokens against your configured trusted publishers.

Benefits

No secrets to manage – No API keys to create, rotate, or accidentally leak
Cryptographically secure – Tokens are signed by GitHub and verified by Codemod
Fine-grained control – Restrict by repository, workflow, environment, or git ref
Short-lived tokens – Tokens expire in ~5 minutes, limiting exposure

Organization Scopes (Zero Configuration)

This is the recommended approach for organizations. If your GitHub organization name matches your package scope, trusted publishing works automatically with no UI configuration needed.

For packages under an organization scope (e.g., @my-org/my-codemod), trusted publishers work automatically when:

Your GitHub organization name matches the package scope (e.g., GitHub org my-org → scope @my-org)
You’ve linked your GitHub organization to your Codemod organization

That’s it. Any repository in your GitHub organization can publish packages under your scope—both new packages and updates to existing ones. Example: If your GitHub organization is acme-corp and you’ve linked it to your Codemod organization with scope @acme-corp:

name: Publish Codemod
on:
  release:
    types: [published]

permissions:
  id-token: write  # Required for OIDC
  contents: read

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

This workflow can publish @acme-corp/any-codemod from any repository in the acme-corp GitHub organization.

Individual Packages (Manual Configuration)

For packages that don’t match an organization scope (unscoped packages or packages where the GitHub org doesn’t match), you need to configure a trusted publisher manually:

Configure Trusted Publisher in UI

Go to codemod.com/api-keys
Scroll to Trusted Publishers
Click Add Trusted Publisher
Select your package and enter the GitHub repository details
(Optional) Add restrictions for extra security

Configure Your Workflow

name: Publish Codemod
on:
  release:
    types: [published]

permissions:
  id-token: write  # Required for OIDC
  contents: read

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

Field	Description	Example
Package	The package to publish to	`my-codemod` or `@org/my-codemod`
Repository Owner	GitHub org or username	`my-org`
Repository Name	Repository name	`my-codemod-repo`

Once configured, any workflow in that repository can publish to the package.

Optional Restrictions

Add restrictions for additional security:

Restriction	Description	Example
Workflow Path	Only allow specific workflow files	`.github/workflows/publish.yml`
Environment	Require GitHub Environment approval	`production`
Ref Pattern	Only allow specific git refs	`refs/tags/v*`

Example with restrictions:

name: Publish Codemod
on:
  release:
    types: [published]

permissions:
  id-token: write
  contents: read

jobs:
  publish:
    runs-on: ubuntu-latest
    environment: production  # Matches "Environment" restriction
    steps:
      - uses: actions/checkout@v4
      - uses: codemod/publish-action@v1

Manual OIDC Setup

If you prefer not to use the action, you can manually obtain and use the OIDC token:

name: Publish Codemod
on:
  release:
    types: [published]

permissions:
  id-token: write
  contents: read

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

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install codemod CLI
        run: npm install -g codemod@latest

      - name: Get OIDC token
        id: oidc
        uses: actions/github-script@v7
        with:
          script: |
            const token = await core.getIDToken('https://codemod.com');
            core.setOutput('token', token);
            core.setSecret(token);

      - name: Publish codemod
        env:
          CODEMOD_AUTH_TOKEN: ${{ steps.oidc.outputs.token }}
        run: codemod publish

Troubleshooting

No trusted publisher found

Verify your trusted publisher configuration matches:

Repository owner (case-insensitive)
Repository name (exact match)
Any configured restrictions (workflow path, environment, ref pattern)

Permission denied

Ensure your workflow has the required permissions:

permissions:
  id-token: write  # Required for OIDC token
  contents: read   # Required to checkout code

Token audience mismatch

The OIDC token audience must be https://codemod.com. If using a custom registry, configure GITHUB_OIDC_AUDIENCE on the server.

Comparison

Feature	Interactive Login	API Keys	Trusted Publishers
Secrets to manage	None	Yes	None
Works locally	Yes	Yes	No
Works in CI/CD	No	Yes	GitHub Actions only
New package publish	Yes	Yes	Yes*
Token lifetime	Long-lived	Long-lived	~5 minutes
Rotation needed	No	Recommended	No
UI configuration	None	Create key	None for org scopes**

_{* Trusted publishers can publish new packages when using a matching organization scope.} _{** Organization scopes that match your GitHub org name require no configuration in app.codemod.com. Individual packages require adding a trusted publisher in the UI.}

Best Practices

Use Trusted Publishers

For GitHub Actions, prefer trusted publishers over API keys. No secrets to leak or rotate.

Restrict Access

When using trusted publishers, add restrictions like environment protection for sensitive packages.

Rotate API Keys

If using API keys, rotate them periodically and use the minimum required permissions.

Tag Releases

Use git tags and GitHub releases to trigger publish workflows for clear version history.

Next Steps

Registry

Learn about package access levels and discovery.

Building Packages

Create and configure Codemod packages.

CLI Reference

Complete publish command options.

API Keys

Manage your API keys and trusted publishers.

First steps

Enterprise

Community

Other Resources

Authentication Methods

When to Use

API Keys

Creating an API Key

Using API Keys

GitHub Actions Example

When to Use

Trusted Publishers

How OIDC Works

Benefits

Organization Scopes (Zero Configuration)

Individual Packages (Manual Configuration)

Optional Restrictions

Manual OIDC Setup

Troubleshooting

Comparison

Best Practices

Use Trusted Publishers

Restrict Access

Rotate API Keys

Tag Releases

Next Steps

Registry

Building Packages

CLI Reference

API Keys

First steps

Enterprise

Community

Other Resources

​Authentication Methods

​Interactive Login

​When to Use

​API Keys

​Creating an API Key

​Using API Keys

​GitHub Actions Example

​When to Use

​Trusted Publishers

How OIDC Works

​Benefits

​Organization Scopes (Zero Configuration)

​Individual Packages (Manual Configuration)

​Optional Restrictions

​Manual OIDC Setup

​Troubleshooting

​Comparison

​Best Practices

Use Trusted Publishers

Restrict Access

Rotate API Keys

Tag Releases

​Next Steps

Registry

Building Packages

CLI Reference

API Keys

Authentication Methods

Interactive Login

When to Use

API Keys

Creating an API Key

Using API Keys

GitHub Actions Example

When to Use

Trusted Publishers

Benefits

Organization Scopes (Zero Configuration)

Individual Packages (Manual Configuration)

Optional Restrictions

Manual OIDC Setup

Troubleshooting

Comparison

Best Practices

Next Steps