Starting with CLI 1.6.129, Shorebird supports the keyless CI sign-in behind PyPI’s and npm’s trusted publishing: OpenID Connect (OIDC) sign-in from GitHub Actions.
Why OIDC beats a stored token
A SHOREBIRD_TOKEN in your repository secrets works, but it’s a long-lived
credential sitting in your CI configuration. Someone has to remember to rotate
it, and if it ever leaks, it keeps working until someone notices and revokes it.
With OIDC, nothing long-lived exists to leak. When your workflow runs, GitHub issues the job an OIDC token tied to the repository and workflow. The Shorebird CLI exchanges that token for a service account token that lasts 15 minutes, but only if the job matches a trust rule on one of your service accounts. The CLI gets a fresh token before the old one expires, so long builds keep running.
The service account token can do exactly what the service account’s role allows and no more.
Setting it up
You need the Owner or Admin role in an organization on the Business or Enterprise plan. GitHub OIDC requires Shorebird 1.6.129 or newer.
- Open your organization settings in the Shorebird Console and select the tab.
- Create a service account, or select an existing one, and give it the role your CI needs. Developer, the default, can create releases and patches.
- Add a trust rule. In the GitHub Actions section, click
and enter the repository and
workflow file that should be allowed to sign in. Name a ref pattern such as
refs/heads/main, a GitHub environment protected by required reviewers or branch rules, or both. A rule with neither, or with only an unprotected environment, lets anyone who can push a branch to the repository sign in. Learn what a rule matches. - Update your workflow YAML in GitHub. The console lists what the job
needs: permission to request an OIDC token,
SHOREBIRD_PROJECT_IDset to your project’s ID, the environment if your rule names one, and noSHOREBIRD_TOKEN. Your project’s ID is the number after/orgs/in the console’s address bar, not theapp_idin yourshorebird.yaml.
jobs:
release:
runs-on: ubuntu-latest
environment: production # Only if your trust rule names an environment
permissions:
contents: read
id-token: write
env:
SHOREBIRD_PROJECT_ID: '123' # From the console. Not a secret.
steps:
- uses: actions/checkout@v7
- uses: shorebirdtech/setup-shorebird@v1
with:
cache: true
- run: shorebird release android
The GitHub Actions guide has the full setup, including how to add a trust rule from the command line.
Moving off your stored token
If you already run Shorebird in CI with a SHOREBIRD_TOKEN, you can switch over
one workflow at a time:
- Add a trust rule for the workflow.
- Add
id-token: writeto the job’s permissions, and the environment if your rule names one. If the job had nopermissionsblock, listcontents: readin the new one too: GitHub sets every permission a block leaves out to none, and checking out your code needscontents: read. - Set
SHOREBIRD_PROJECT_IDin the job’senvto your project’s ID. - Remove
SHOREBIRD_TOKENfrom the job, since the CLI uses it instead of OIDC whenever it’s set, and run the job once to confirm it signs in.
When nothing else uses the old token, remember to delete the secret from GitHub and revoke the key in the console.
Questions?
If you’re setting this up and something doesn’t line up with what you see, we want to hear about it. Find us on Discord, email us at contact@shorebird.dev, or read the full setup guide in the docs.

