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

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 publishing 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 (see setup steps below)

Any repository in your GitHub organization can then publish packages under your scope, including new packages and updates to existing ones.

Linking Your GitHub Organization

To enable automatic trusted publishing for your organization scope, you need to install the Codemod GitHub App:

Install the Codemod GitHub App

Install the Codemod GitHub App and select your GitHub organization (requires org admin permissions)
Grant access to at least one repository

Go to Codemod platform and sign in with GitHub. Your organization will be automatically linked.

Once linked, anyone who can trigger GitHub Actions workflows (e.g., via push, release, or workflow_dispatch) in your organization’s repositories can publish codemods under that scope. The publisher identity in Codemod’s system is tied to the user who installed the GitHub App.

Complete GitHub Actions Workflow

Here’s a complete workflow file for publishing. You can create this manually or use codemod init to generate it automatically: For a single codemod repository:

# .github/workflows/publish.yml
name: Publish Codemod
on:
  push:
    tags:
      - "v*"  # Triggers on tags like v1.0.0, v2.1.3, etc.

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

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

For a monorepo with multiple codemods: If you have multiple codemods in a single repository (e.g., in a codemods/ directory), use tags like [email protected]:

# .github/workflows/publish.yml
name: Publish Codemod
on:
  push:
    tags:
      - "*@v*"  # Triggers on tags like [email protected]

permissions:
  id-token: write
  contents: read

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

      - name: Extract codemod name from tag
        id: extract
        run: |
          TAG="${GITHUB_REF#refs/tags/}"
          CODEMOD_NAME="${TAG%@v*}"
          echo "codemod_name=$CODEMOD_NAME" >> $GITHUB_OUTPUT

      - name: Publish codemod
        uses: codemod/publish-action@v1
        with:
          path: codemods/${{ steps.extract.outputs.codemod_name }}

You can also run npx codemod init to generate this workflow automatically. It creates the single-codemod or monorepo format based on your project structure.

Individual Packages (Manual Configuration)

For unscoped packages or cases where the GitHub org doesn’t match the package scope, 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

# .github/workflows/publish.yml
name: Publish Codemod
on:
  push:
    tags:
      - "v*"

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 (required)	`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 specified 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)

For organization scopes: Ensure the GitHub App is installed on at least one repository in your organization and you’ve signed in to Codemod with a GitHub account that has access to the organization.

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.

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

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 Codemod platform. 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.

Package Structure

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

Trusted Publishers

How OIDC Works

Benefits

Organization Scopes (Zero Configuration)

Linking Your GitHub Organization

Complete GitHub Actions Workflow

Individual Packages (Manual Configuration)

Optional Restrictions

Manual OIDC Setup

Troubleshooting

API Keys

Creating an API Key

Using API Keys

GitHub Actions Example

When to Use

Comparison

Best Practices

Use Trusted Publishers

Restrict Access

Rotate API Keys

Tag Releases

Next Steps

Registry

Package Structure

CLI Reference

API Keys

First steps

Enterprise

Community

Other Resources

​Authentication Methods

​Interactive Login

​When to Use

​Trusted Publishers

How OIDC Works

​Benefits

​Organization Scopes (Zero Configuration)

​Linking Your GitHub Organization

​Complete GitHub Actions Workflow

​Individual Packages (Manual Configuration)

​Optional Restrictions

​Manual OIDC Setup

​Troubleshooting

​API Keys

​Creating an API Key

​Using API Keys

​GitHub Actions Example

​When to Use

​Comparison

​Best Practices

Use Trusted Publishers

Restrict Access

Rotate API Keys

Tag Releases

​Next Steps

Registry

Package Structure

CLI Reference

API Keys

Authentication Methods

Interactive Login

When to Use

Trusted Publishers

Benefits

Organization Scopes (Zero Configuration)

Linking Your GitHub Organization

Complete GitHub Actions Workflow

Individual Packages (Manual Configuration)

Optional Restrictions

Manual OIDC Setup

Troubleshooting

API Keys

Creating an API Key

Using API Keys

GitHub Actions Example

When to Use

Comparison

Best Practices

Next Steps