# Create an Assumable Identity for a GitHub Actions Workflow

URL: https://deploy-preview-3616--ornate-narwhal-088216.netlify.app/platform/administration/assumable-ids/identity-examples/github-identity.md
Last Modified: July 21, 2026
Tags: Chainguard Containers

Tutorial outlining how to create a Chainguard identity that can be assumed by a GitHub Actions workflow.

Chainguard’s assumable identities are identities that can be assumed by external applications or workflows in order to perform certain tasks that would otherwise have to be done by a human. For instance, an assumable identity can be used to allow a GitHub Actions workflow to pull images from cgr.dev without a static pull token.
This tutorial outlines how to create an identity, and then create a GitHub Actions workflow that will assume the identity to interact with Chainguard resources.
Prerequisites To complete this guide, you will need the following.
One of: chainctl — the Chainguard command line interface tool — installed on your local machine. Follow our guide on How to Install chainctl to set this up. terraform installed on your local machine. Terraform is an Infrastructure as Code tool which this guide will use to create various cloud resources. Follow the official Terraform documentation for instructions on installing the tool. A GitHub repository you can use for testing out GitHub identity federation. To complete this guide, you must have permissions to create GitHub Actions on this testing repo. Creating an Identity Note: GitHub issues OIDC tokens whose sub claim embeds immutable numeric IDs for the repository owner and the repository. For example, the subject repo:my-org@123456/repo-name@654321:ref:refs/heads/main replaces the older name-only form repo:my-org/repo-name:ref:refs/heads/main. This format is the default for repositories created after July 15, 2026, and is available as an opt-in for older repositories through GitHub’s OIDC settings.
An identity that matches the older name-only subject will not match a token that carries the immutable subject, so the workflow fails to authenticate. The examples that follow use the immutable format. If your repository still sends the name-only subject, leave out the @<owner-id> and @<repo-id> portions.
Finding your repository’s numeric identifiers The immutable subject claim uses the numeric ID of the repository owner and the numeric ID of the repository.
To retrieve the subject claim in the GitHub UI, modify and browse to this URL:
https://github.com/<org-name>/<repo-name>/settings/actions/oidc-configurationTo retrieve the subject claim with the GitHub CLI:
gh api repos/OWNER/REPO --jq '{owner_id: .owner.id, repo_id: .id}'You can also preview the exact subject your repository sends from its OIDC settings in the GitHub web interface. To confirm the subject a running workflow presents, inspect the sub claim of the OIDC token in the workflow logs. For background on the format, see GitHub’s changelog announcing immutable subject claims for GitHub Actions OIDC tokens.
Chainctl This command creates an identity that can be assumed by workflows in the my-org/repo-name repository. Substitute the owner and repository IDs you retrieved earlier. The identity is bound to the registry.pull role.
chainctl iam identities create github my-identity-name \ --github-repo=my-org@<owner-id>/repo-name@<repo-id> \ --role registry.pullYou can also include the --github-ref flag to restrict it to workflows that run from a specific branch. For instance, the main branch.
chainctl iam identities create github my-identity-name \ --github-repo=my-org@<owner-id>/repo-name@<repo-id> \ --github-ref=refs/heads/main \ --role registry.pullRegex is also available. For example, you can create an identity that can be assumed by multiple repositories and multiple branches. Because every repository in an organization shares the same owner ID, a single pattern can match all of them.
chainctl iam identities create github my-identity-name \ --github-repo='my-org@<owner-id>/.*' \ --github-ref='refs/heads/main|master' \ --role registry.pullThis will return the identity’s UIDP (unique identity path). Note this value down, as you’ll need it to set up the GitHub Actions workflow.
If you need to retrieve the UIDP later on, you can always run the following chainctl command to list the identity.
chainctl iam identities list --name=my-identity-name Terraform Alternatively, you could create the identity with the Chainguard Terraform provider.
Substitute your Chainguard organization name, GitHub organization, and GitHub repository for <org-name>, <github-org>, and <github-repo>, respectively. Substitute the numeric owner and repository IDs for <owner-id> and <repo-id>, following the steps in Finding your repository’s numeric identifiers.
data "chainguard_group" "org" { name = "<org-name>" } resource "chainguard_identity" "my_identity_name" { parent_id = data.chainguard_group.org.id name = "my-identity-name" claim_match { issuer = "https://token.actions.githubusercontent.com" subject = "repo:<github-org>@<owner-id>/<github-repo>@<repo-id>:ref:refs/heads/main" } } data "chainguard_role" "registry_pull" { name = "registry.pull" } resource "chainguard_rolebinding" "my_identity_name_registry_pull" { identity = chainguard_identity.my_identity_name.id group = data.chainguard_group.org.id role = data.chainguard_role.registry_pull.items[0].id } output "my_identity_name_id" { value = chainguard_identity.my_identity_name.id }In this example the chainguard_identity.my_identity_name resource defines an identity in your organization that can be assumed by a GitHub workflow that matches the claims in the claim_match block.
The chainguard_rolebinding.my_identity_name_registry_pull resource binds the registry.pull role to the identity.
The my_identity_name_id output provides the identity’s UIDP (unique identity path). You’ll need this value to set up the GitHub Actions workflow.
Creating and Testing a GitHub Actions Workflow This example workflow definition assumes an identity with the setup-chainctl GitHub Action, lists repositories with chainctl and pulls an image from cgr.dev.
Commit this workflow to the main branch of your repository as .github/workflows/assume-and-explore.yaml, substituting <identity-id> with the UIDP of the assumable identity you created in the previous step and <org-name> with the name of your Chainguard organization.
name: Assume and Explore on: workflow_dispatch: {} jobs: assume-and-explore: name: actions assume example permissions: id-token: write runs-on: ubuntu-latest steps: - uses: chainguard-dev/setup-chainctl@main with: identity: <identity-id> - run: | chainctl image repo list --parent=<org-name> - run: | docker pull cgr.dev/<org-name>/example-image:latestOnce its committed, you can trigger the workflow by navigating to Actions > Assume And Explore from the home page of your repository and selecting Run workflow.
Learn more For more information about how assumable identities work in Chainguard, check out our conceptual overview of assumable identities. Additionally, the Terraform documentation includes a section on recommended best practices which you can refer to if you’d like to build on the provided Terraform configuration for a production environment. Likewise, for more information on using GitHub Actions, we encourage you to check out the official documentation on the subject.