GitHub Actions Access Tokens

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.

Concept

1. This GitHub action will request an access token for a Target Repository from the App Server, authorize by the GitHub Action OIDC Token.
2. The App Server requests a GitHub App Installation Token to read .github/access-token.yaml file in Granting Repository.
3. The App Server reads .github/access-token.yaml file from Target Repository and determine which permissions should be granted to Requesting GitHub Action Identity.
4. 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..
5. This GitHub action sets the token as the step output field token
6. Further job steps can then utilize this token to access resources of the Granting Repository e.g. ${{ steps.<ACCESS_TOKEN_STEP_ID>.outputs.token }}.

Usage

See Action Metadata and Example Use Cases.

Prerequisites

Install Access Manager App to Target Repositories

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 to Protect access token policy
• Set Enforcement status to Active
• Hit Add bypass, select Repository admin and hit Add selected
• Set Target repositories to All repositories
• Enable Restrict file paths, hit Add file path, set File path to .github/access-token.yaml and hit Add file path
• Hit Create button

Grant Repository Permissions

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 with this template content

Repository Access Policy Example

Grant Owner Permissions

Click me

To grant owner specific or owner wide permission create a OWNER/.github-access-token repository and create an access-token.yaml file at root of the repository with this template content

Example Use Cases

Update Secrets

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 }}

Clone an Internal or Private Repository

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 }}

Trigger a Workflow

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}}
    # ...

---

Development

Action Release Workflow

• Run actions-release workflow to create a new action release

Resources

• App icon: https://img.icons8.com/cotton/256/000000/grand-master-key.png

TODO

• add token hash to output in main and post action