Skip to content
Blog

Product updates 3 min read

OIDC sign-in for service accounts

Shorebird service accounts can now sign in from GitHub Actions with OIDC, so CI runs releases and patches without a stored SHOREBIRD_TOKEN to rotate.

Wesley Peck

Lead Product Manager

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.

  1. Open your organization settings in the Shorebird Console and select the Service accounts tab.
  2. 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.
  3. Add a trust rule. In the GitHub Actions section, click Add workflow 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.
  4. Update your workflow YAML in GitHub. The console lists what the job needs: permission to request an OIDC token, SHOREBIRD_PROJECT_ID set to your project’s ID, the environment if your rule names one, and no SHOREBIRD_TOKEN. Your project’s ID is the number after /orgs/ in the console’s address bar, not the app_id in your shorebird.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:

  1. Add a trust rule for the workflow.
  2. Add id-token: write to the job’s permissions, and the environment if your rule names one. If the job had no permissions block, list contents: read in the new one too: GitHub sets every permission a block leaves out to none, and checking out your code needs contents: read.
  3. Set SHOREBIRD_PROJECT_ID in the job’s env to your project’s ID.
  4. Remove SHOREBIRD_TOKEN from 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.

All posts
  • Product updates 4 min read

    Shorebird improvements for enterprises

    Meet the enterprise console: your whole company's Shorebird setup in one place, with SCIM from Okta and Entra ID, organization members, contract billing, offboarding and one audit log.

    Wesley Peck

    Lead Product Manager

  • Product updates 2 min read

    Orgs at Shorebird just got better

    Shorebird now has one kind of organization. Your personal org works like any other org, and org membership replaces app collaborators.

    Wesley Peck

    Lead Product Manager

Ship your first patch today.

Install the CLI, create a release and send a patch. Free for 5,000 patch installs a month.

Larger team? Talk to sales