CI/CD Publishing

Chuks supports automated package publishing through API tokens — scoped, expiring personal access tokens designed for CI/CD pipelines. Instead of interactive OAuth login, you generate a token from the dashboard and use it in your pipeline to publish packages.

Generating an API Token

1. Go to your Chuks Registry dashboard and click the API Tokens tab
2. Click Generate Token
3. Give it a descriptive name (e.g. GitHub Actions — my_package)
4. Select the scopes you need:

Scope	Description
packages:read	List your packages and view download stats
packages:publish	Publish new package versions
packages:yank	Yank and restore package versions
packages:permissions	Update package permissions

5. Choose an expiration period (7 to 365 days)
6. Click Generate — the raw token is shown once. Copy it immediately.

Tokens look like chuks_pk_a1b2c3d4... — the chuks_pk_ prefix distinguishes them from OAuth tokens.

Using the Token

Command-Line Flag

Pass the token directly with --token:

chuks publish --token chuks_pk_a1b2c3d4...

Environment Variable

Set CHUKS_TOKEN and run chuks publish without any flags:

export CHUKS_TOKEN=chuks_pk_a1b2c3d4...
chuks publish

Priority: --token flag takes precedence over CHUKS_TOKEN.

CI/CD Examples

GitHub Actions

name: Publish Package
on:
  push:
    tags:
      - "v*"

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

      - name: Install Chuks
        run: curl -fsSL https://chuks.org/install.sh | bash

      - name: Publish to registry
        run: chuks publish --token ${{ secrets.CHUKS_TOKEN }}

Store your token as a repository secret named CHUKS_TOKEN in Settings → Secrets and variables → Actions.

GitLab CI

publish:
  stage: deploy
  image: ubuntu:latest
  only:
    - tags
  script:
    - curl -fsSL https://chuks.org/install.sh | bash
    - chuks publish
  variables:
    CHUKS_TOKEN: $CHUKS_TOKEN

Add your token as a CI/CD variable in Settings → CI/CD → Variables (masked).

Bitbucket Pipelines

pipelines:
  tags:
    "v*":
      - step:
          name: Publish
          script:
            - curl -fsSL https://chuks.org/install.sh | bash
            - chuks publish
          variables:
            CHUKS_TOKEN: $CHUKS_TOKEN

How It Works

When you run chuks publish --token <token>:

1. The CLI sets Authorization: Bearer chuks_pk_... on the publish request
2. The registry detects the chuks_pk_ prefix and validates the token
3. The token hash is checked against stored hashes — the raw token is never stored
4. The registry verifies the token hasn’t expired or been revoked
5. The required scope (packages:publish) is checked
6. The publisher identity is resolved from the token — no publisherId needed in the payload

This means CI pipelines don’t need any OAuth flow or stored login sessions.

Security Best Practices

• Use the minimum scopes needed. A publish-only pipeline should only have packages:publish.
• Set short expiration periods. For active projects, 30–90 days is reasonable. Rotate tokens before they expire.
• Never commit tokens to source control. Always use your CI provider’s secret management.
• Use one token per pipeline. This makes revocation easy — if a pipeline is compromised, revoke just that token.
• Monitor last-used dates. The dashboard shows when each token was last used. Tokens that haven’t been used recently may be safe to revoke.

Revoking Tokens

If a token is compromised or no longer needed:

1. Go to your Chuks Registry dashboard → API Tokens tab
2. Click Revoke on the token
3. The token is immediately invalidated — any pipeline using it will fail on the next run

Revoked tokens remain visible in your list with a revoked status for audit purposes.

Publish Workflow Summary

A typical publish workflow for a Chuks package:

1. Develop and test your package locally
2. Bump the version in chuks.json
3. Commit, push, and tag with git tag v1.2.0 && git push origin v1.2.0
4. CI detects the tag and runs chuks publish --token $CHUKS_TOKEN
5. The package is published to the registry, and the git tag is confirmed

Developer → git tag → CI/CD → chuks publish --token → Registry