Skip to content
Shorebird

Trust Rules

A trust rule lets a GitHub Actions workflow sign in as a service account with the OIDC token GitHub issues to each job, instead of an API key stored as a secret. There is no Shorebird secret in GitHub to leak or rotate, and the job can do what the service account’s role allows.

Use a trust rule for workflows that run in GitHub Actions. For other CI systems and for scripts, use a service account key.

Adding a trust rule needs:

  • A Business or Enterprise plan. If your organization moves to a plan without trust rules, its existing rules keep working and can still be deleted, but new ones can’t be added.
  • The Admin or Owner role in the organization.
  • Shorebird 1.6.129 or newer in the workflow.

Add a trust rule

Section titled “Add a trust rule”

On a service account in the console, under GitHub Actions, click Add workflow and enter the repository’s owner and name, the workflow file, and optionally an environment and a ref pattern. The console then lists what the workflow needs: permissions: id-token: write on the job, the environment if the rule names one, SHOREBIRD_PROJECT_ID set to your project’s ID, and no SHOREBIRD_TOKEN.

For the full walkthrough, including the workflow file and the commands that add a rule from the command line, see Sign in with OIDC instead of a stored key.

What a rule matches

Section titled “What a rule matches”

A job signs in only when everything the rule names matches it:

  • Repository: the owner and repository name. When you add the rule, Shorebird looks up the owner’s GitHub account and records its ID, so if the name is later deleted and registered by someone else, their workflows don’t match. If you rename the GitHub user, organization, or repository, add the rule again with the new name.
  • Workflow file: the file that defines the job, directly in .github/workflows/ and ending in .yml or .yaml, such as .github/workflows/release.yaml. In the console, a bare file name like release.yaml is taken to be in .github/workflows/. If the job is in a reusable workflow in the same repository, name that file, not the workflow that calls it. A reusable workflow from another repository can’t sign in.
  • Environment (optional): the GitHub environment the job runs in, ignoring letter case. Without one, the rule matches jobs in any environment or none.
  • Ref pattern (optional): a full ref such as refs/heads/main, or a prefix ending in a single *, such as refs/tags/* or refs/heads/release/*. Without one, the rule matches any ref, including pull request refs.

A rule doesn’t limit which events can start the job. To keep a workflow from signing in from any branch or pull request, set an environment that has required reviewers or branch restrictions in GitHub, or a ref pattern.

Only the rules in the project named by SHOREBIRD_PROJECT_ID are considered. If rules on two different service accounts in that project match the same job, the sign-in is refused, so keep each workflow’s rules on one service account.

How a signed-in job works

Section titled “How a signed-in job works”

The Shorebird CLI exchanges the job’s OIDC token for a Shorebird access token that lasts 15 minutes, and exchanges a new one before it expires, so long builds keep working. Each sign-in is recorded in the audit log as service_account.sign_in, with the run it came from.

When SHOREBIRD_TOKEN is set, the CLI uses that key instead of signing in with OIDC. Once a workflow is signing in with a trust rule, remove its SHOREBIRD_TOKEN secret and revoke any service account keys nothing else uses. The console suggests this once one of the account’s rules has been used.

See and delete trust rules

Section titled “See and delete trust rules”

Each rule is listed on its service account with its repository, workflow file, environment, ref pattern, and when it was last used. To stop a workflow from signing in, click Remove next to its rule and confirm. Jobs that already signed in keep their access token until it expires, within 15 minutes. To cut off access right away, delete the service account. A change to its role also applies from the next request.

From the command line, signed in with shorebird login and with SHOREBIRD_TOKEN unset:

# List a service account's trust rules
shorebird api organizations/<project id>/service-accounts/<service account id>/trust-rules

# Delete one
shorebird api -X DELETE organizations/<project id>/service-accounts/<service account id>/trust-rules/<rule id>

Deleting a service account deletes its trust rules too.

When a sign-in is refused

Section titled “When a sign-in is refused”

The CLI prints the reason. The common ones:

  • No trust rule matches this workflow: check that the job’s repository, workflow file, environment, and ref match a rule, and that SHOREBIRD_PROJECT_ID is the ID of the project the rule is in.
  • Trust rules on more than one service account in this project match this workflow: delete the extra rules so only one service account’s rules match.
  • The job runs a workflow from another repository: the job is defined in a reusable workflow from another repository. Move the steps that run Shorebird into a workflow in the repository itself.
  • Signing in with GitHub Actions OIDC requires SHOREBIRD_PROJECT_ID: set SHOREBIRD_PROJECT_ID in the job’s env.
  • You must be logged in to run this command, in GitHub Actions: the job has neither SHOREBIRD_TOKEN nor permissions: id-token: write.