Publishing from GitHub Actions

Trusted publishing lets a GitHub Actions workflow publish a package’s versions with no token stored anywhere. The registry trusts one repository’s one workflow; when it runs, fb asks GitHub for a token that proves where it’s running, trades it for a registry token that lasts 30 minutes, publishes, and revokes it.

1. Publish the first version yourself

Trusted publishing publishes new versions of a package that’s already on the registry, so the first one comes from your machine:

fb login
fb publish

Writing a package goes through that.

2. Trust the workflow

On the package site, open your dashboard, choose Manage beside the package, and under Trusted publishers add:

Only the package’s owners can add one. The repository can be public or private. The registry remembers the repository’s and its owner’s GitHub ids, so a repository deleted and made again under the same name isn’t trusted. A private repository, which GitHub doesn’t show the registry, is kept by its name until the first token from its workflow, which gives the registry those ids, and every later token has to match them.

3. Write the workflow

.github/workflows/publish.yml, which publishes when a version’s tag is pushed:

name: publish

on:
  push:
    tags: ["v*"]

permissions:
  contents: read
  id-token: write

jobs:
  publish:
    runs-on: ubuntu-24.04
    environment: release
    steps:
      - uses: actions/checkout@v4
      - name: Install FutureBlitz
        run: |
          curl -fsSL https://futureblitz.dev/install.sh | sh
          echo "$HOME/.futureblitz/bin" >> "$GITHUB_PATH"
      - run: fb test
      - run: fb publish

• The install script checks the release against its SHA256SUMS before unpacking it, and downloads it without GitHub’s API, so the API’s rate limit never stops the job.
• id-token: write lets the job ask GitHub for its token. Without it, fb can’t publish.
• environment: release has to match the trusted publisher’s environment, when it names one. A GitHub environment can require a person’s approval before the job runs.
• fb publishes the version project.toml says, so the tag and project.toml should agree.

4. Release

git tag v0.2.0
git push origin v0.2.0

The registry records that a trusted publisher published the version, and from which repository.

When it doesn’t publish

• No token: the job lacks id-token: write, or FB_REGISTRY_TOKEN is set to something else. fb uses FB_REGISTRY_TOKEN first when it’s set.
• Not trusted: the repository, the workflow’s file name, or the environment isn’t the trusted publisher’s.
• The version is there already: a version is published once; change project.toml’s version.