This repository holds a GitHub App called octo-sts that acts like a Security
Token Service (STS) for the GitHub API. Using this App, workloads running
essentially anywhere that can produce OIDC tokens can federate with this App's
STS API in order to produce short-lived tokens for interacting with GitHub.
The ultimate goal of this App is to wholly eliminate the need for GitHub Personal Access Tokens (aka PATs).
The original blog post.
For the App to produce credentials that work with resources in your organization
it must be installed into the organization and have access to any repositories
that you will want workloads to be able to interact with. Unfortunately due to
limitations with GitHub Apps, the App must ask for a superset of the permissions
needed for federation, so the full set of permissions the App requests will be
large, but with one exception (contents: read reading policy files) the App
only creates tokens with these scopes based on the "trust policies" you have
configured.
Trust policies are checked into .github/chainguard/{name}.sts.yaml, and
consist of a few key parts:
- The claim matching criteria for federation,
- The permissions to grant the identity, and
- (for Org-level policies) The list of repositories to grant access.
Here is a simple example that allows the GitHub actions workflows in
chainguard-dev/foo running on the main branch to read the repo contents and
interact with issues:
issuer: https://token.actions.githubusercontent.com
subject: repo:chainguard-dev/foo:ref:refs/heads/main
permissions:
contents: read
issues: writeThe Trust Policy can also match the issuer, subject, and even custom claims with regular expressions. For example:
issuer: https://accounts.google.com
subject_pattern: '[0-9]+'
claim_pattern:
email: '.*@chainguard.dev'
permissions:
contents: readThis policy will allow OIDC tokens from Google accounts of folks with a Chainguard email address to federate and read the repo contents.
The GitHub App implements the Chainguard SecurityTokenService GRPC service
definition here.
If a ${TOKEN} suitable for federation is sent like so:
curl -H "Authorization: Bearer ${TOKEN}" \
"https://octo-sts.dev/sts/exchange?scope=${REPO}&identity=${NAME}"
The App will attempt to load the trust policy from
.github/chainguard/${NAME}.sts.yaml from ${REPO} and if the provided ${TOKEN}
satisfies those rules, it will return a token with the permissions in the trust
policy.
Our release cadence at this moment is set to when is needed, meaning if we have a bug fix or a new feature we will might make a new release.
Sometimes we need to add or remove a GitHub Permission in order to add/remove permissions that will be include in the octo-sts token for the users. Due to the nature of GitHub Apps, OctoSTS must request all permissions it might need to use, even if you don't want to use them for your particular installation or policy.
To avoid disruptions for the users, making them to review and approve the changes in the installed GitHub App we
will apply permissions changes for the octo-sts app quarterly at any day during the quarter.
An issue will be created to explain what permissions is being added or removed.
Special cases will be discussed in a GitHub issue in https://github.com/octo-sts/app/issues and we might apply more than one change during the quarter.
The following permissions are the currently enabled in octo-Sts and will be available when installing the GitHub APP
- Actions:
Read/Write - Administration :
Read-only - Attestations:
No Access - Checks:
Read/Write - Code Scanning Alerts:
No Access - Codespaces:
No Access - Codespaces lifecycle admin:
No Access - Codespaces metadata:
No Access - Codespaces secrets:
No Access - Commit statuses:
Read/Write - Contents:
Read/Write - Custom properties:
No Access - Dependabot alerts:
No Access - Dependabot secrets:
No Access - Deployments:
Read/Write - Discussions:
Read/Write - Environments:
No Access - Issues:
Read/Write - Merge queues:
No Access - Metadata (Mandatory):
Read-only - Packages:
Read/Write - Pages:
No Access - Projects:
Read/Write - Pull requests:
Read/Write - Repository security advisories:
No Access - Secret scanning alerts:
No Access - Secrets:
No Access - Single file:
No Access - Variables:
No Access - Webhooks:
No Access - Workflows:
Read/Write
- API Insights:
No Access - Administration:
Read-only - Blocking users:
No Access - Custom organizations roles:
No Access - Custom properties:
No Access - Custom repository roles:
No Access - Events:
Read-only - GitHub Copilot Business:
No Access - Knowledge bases:
No Access - Members:
Read-only - Organization codespaces:
No Access - Organization codespaces secrets:
No Access - Organization codespaces settings:
No Access - Organization dependabot secrets:
No Access - Personal access token requests:
No Access - Personal access tokens:
No Access - Plan:
No Access - Projects:
Read/Write - Secrets:
No Access - Self-hosted runners:
No Access - Team discussions:
No Access - Variables:
No Access - Webhooks:
No Access
- Block another user:
No Access - Codespaces user secrets:
No Access - Copilot Chat:
No Access - Email addresses:
No Access - Events:
No Access - Followers:
No Access - GPG keys:
No Access - Gists:
No Access - Git SSH keys:
No Access - Interaction limits:
No Access - Plan:
No Access - Profile:
No Access - SSH signing keys:
No Access - Starring:
No Access - Watching:
No Access