Obtain temporary Access Tokens for GitHub Actions workflows by requesting GitHub App Installation Access Tokens.
Authorization is based on the GitHub Actions OIDC tokens and .github/access-token.yaml
file in the target repositories.
- This GitHub action will request an access token for a Target Repository from the App Server, authorize by the GitHub Action ID Token (JWT signed by GitHub).
- The App Server requests a GitHub App Installation Token to read
.github/access-token.yaml
file in Granting Repository. - The App Server reads
.github/access-token.yaml
file from Target Repository and determine which permissions should be granted to Requesting GitHub Action Identity. - The App Server requests a GitHub App Installation Token with granted permissions for Requesting GitHub Action Identity and send it back in response to this GitHub action from step
1.
. - This GitHub action sets the token as the step output field
token
- Further job steps can then utilize this token to access resources of the Granting Repository e.g.
${{ steps.<ACCESS_TOKEN_STEP_ID>.outputs.token }}
.
See Action Metadata and Example Use Cases.
Install Access Tokens for GitHub Actions from Marketplace or host and install your own GitHub App
Warning
Be aware by installing the access token GitHub App everybody with write
assess to .github/access-token.yaml
can grant repository access permissions to GitHub Actions workflow runs.
Tip
For organizations on GitHub Enterprise plan it is possible to restrict write
access to .github/access-token.yaml
to repository admins only by using a push ruleset
Protect access token policy ruleset
- Create a new push ruleset
- Set
Ruleset Name
toProtect access token policy
- Set
Enforcement status
toActive
- Hit
Add bypass
, selectRepository admin
and hitAdd selected
- Set
Target repositories
toAll repositories
- Enable
Restrict file paths
, hitAdd file path
, setFile path
to.github/access-token.yaml
and hitAdd file path
- Hit
Create
button
Warning
Every statement will always implicitly grant metadata: read
permission.
Note
You can also grant repository permissions by owner access token policy see Setup Owner Permission Access
Click me
To grant repository permission create an access-token.yaml
file within the .github
directory of the target repository.
origin: octocat/sandbox # needs to equals to the repository name the policy file belongs to
statements:
- subjects:
# grant access to jobs running on any branches or tags
- ref:refs/*
# Fully qualified subject
# - repo:octocat/sandbox:ref:refs/heads/main
# --- Variables ---
# - ${origin} - the origin repository name
# e.g. repo:${origin}:job_workflow_ref:${origin}/.github/workflows/build.yml@refs/heads/main
# --- Job Identities or Subjects ---
# A GitHub Actions job always has the following identities or subjects
# - The original OIDC token 'sub' claim
# e.g. repo:${origin}:ref:refs/heads/main or repo:${origin}:environment:production
# - repo:${origin}:ref:<ref>
# e.g. repo:${origin}:ref:refs/heads/main
# - repo:${origin}:environment:<environment>
# e.g. repo:${origin}:environment:production
# - repo:${origin}:workflow_ref:<workflow_ref>
# e.g. repo:${origin}:workflow_ref:${origin}/.github/workflows/build.yml@refs/heads/main
# - repo:${origin}:job_workflow_ref:<job_workflow_ref>
# e.g. repo:${origin}:job_workflow_ref:${origin}/.github/workflows/build.yml@refs/heads/main
# --- Subject examples ---
# grant access to jobs running on the main branch
# - repo:${origin}:ref:refs/heads/main
# grant access jobs running on any tag starting with a v
# - repo:${origin}:ref:refs/tags/v*
# grant access to jobs using production environment
# - repo:${origin}:environment:production
# grant access to jobs of a specific workflow file
# - repo:${origin}:workflow_ref:${origin}/.github/workflows/build.yml@refs/heads/main
permissions: # https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps
contents: read
# --- Repository permissions ---
# actions: read | write
# actions_variables: read | write
# checks: read | write
# codespaces: read | write
# codespaces_lifecycle_admin: read | write
# codespaces_metadata: read | write
# codespaces_secrets: read | write
# contents: read | write
# dependabot_secrets: read | write
# deployments: read | write
# discussions: read | write
# environments: read | write
# issues: read | write
# merge_queues: read | write
# metadata: read | write
# packages: read | write
# pull_requests: read | write
# repository_advisories: read | write
# repository_hooks: read | write
# repository_projects: read | write | admin
# secret_scanning_alerts: read | write
# secrets: read | write
# security_events: read | write
# statuses: read | write
# team_discussions: read | write
# vulnerability_alerts: read | write
# workflows: read | write
# pages: read | write
Warning
Every statement will always implicitly grant metadata: read
permission.
Click me
To grant owner specific or owner wide permission create a OWNER/.github-access-token
repository and create an access-token.yaml
file within.
statements
are alike to the repository access policy file, but you can grant any permission including organization permissions and/or user permissions
origin: OWNER/.github-access-token # needs to equals to the repository name the policy file belongs to
statements:
- subjects:
# --- This repository subject examples ---
- ref:refs/heads/main # grant access to jobs running on the main branch
# - ref:refs/tags/v* # grant access jobs running on any tag starting with a v
# - ref:refs/* # grant access to jobs running on any branches and tags
# - environment:production # grant access to jobs using production environment
# - workflow_ref:/.github/workflows/build.yml@refs/heads/main # grant access to jobs of a specific workflow file
# --- Remote repository subject examples ---
# - repo:remote_owner/sandbox:ref:refs/heads/main grant access to jobs running on the main branch
# - repo:remote_owner/sandbox:ref:refs/* # grant access to jobs running on any branches and tags
# - repo:remote_owner/sandbox:environment:production # grant access to jobs using production environment
# - repo:remote_owner/sandbox:workflow_ref:/.github/workflows/build.yml@refs/heads/main # grant access to a remote job, if it uses a reusable workflow from this repository
permissions: # https://docs.github.com/en/rest/authentication/permissions-required-for-github-apps
members: read
# --- Organization permissions ---
# members: read | write
# organization_actions_variables: read | write
# organization_administration: read | write
# organization_announcement_banners: read | write
# organization_codespaces: read | write
# organization_codespaces_secrets: read | write
# organization_codespaces_settings: read | write
# organization_copilot_seat_management: read | write
# organization_custom_org_roles: read | write
# organization_custom_properties: read | write | admin
# organization_custom_roles: read | write
# organization_dependabot_secrets: read | write
# organization_events: read
# organization_hooks: read | write
# organization_personal_access_token_requests: read | write
# organization_personal_access_tokens: read | write
# organization_plan: read
# organization_projects: read | write | admin
# organization_secrets: read | write
# organization_self_hosted_runners: read | write
# organization_user_blocking: read | write
# --- Repository permissions ---
# actions: read | write
# actions_variables: read | write
# checks: read | write
# codespaces: read | write
# codespaces_lifecycle_admin: read | write
# codespaces_metadata: read | write
# codespaces_secrets: read | write
# contents: read | write
# custom_properties: read | write
# dependabot_secrets: read | write
# deployments: read | write
# discussions: read | write
# environments: read | write
# issues: read | write
# merge_queues: read | write
# metadata: read | write
# packages: read | write
# pull_requests: read | write
# repository_advisories: read | write
# repository_hooks: read | write
# repository_projects: read | write | admin
# secret_scanning_alerts: read | write
# secrets: read | write
# security_events: read | write
# statuses: read | write
# team_discussions: read | write
# vulnerability_alerts: read | write
# workflows: read | write
# pages: read | write
Click me
on:
workflow_dispatch:
schedule:
- cron: '0 12 * * *' # every day at 12:00 UTC
jobs:
update-secret:
runs-on: ubuntu-latest
permissions:
id-token: write
steps:
- uses: qoomon/actions--access-token@v3
id: access-token
with:
permissions: |
secrets: write
- name: Update secret
run: >-
gh secret
set 'API_KEY'
--body "$(date +%s)"
--repo ${{ github.repository }}
env:
GITHUB_TOKEN: ${{ steps.access-token.outputs.token }}
read-secret:
needs: update-secret
runs-on: ubuntu-latest
steps:
- run: echo ${{ secrets.API_KEY }}
Click me
name: GitHub Actions Access Manager Example
on:
workflow_dispatch:
push:
branches:
- main
jobs:
checkout:
runs-on: ubuntu-latest
permissions:
contents: read
id-token: write
steps:
- uses: qoomon/actions--access-token@v3
id: access-token
with:
repository: [target repository]
permissions: |
contents: read
- uses: actions/checkout@v4
with:
repository: [target repository]
token: ${{ steps.access-token.outputs.token }}
Click me
on:
workflow_dispatch:
push:
branches:
- main
permissions:
id-token: write
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: qoomon/actions--access-token@v3
id: access-token
with:
permissions: |
actions: write
- name: Trigger workflow
run: >-
gh workflow
run [target workflow].yml
--field logLevel=debug
env:
GITHUB_TOKEN: ${{steps.access-token.outputs.token}}
# ...
- Run actions-release workflow to create a new action release