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

1. 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 Team or 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
  • Click Add file path, set File path to .github/access-token.yaml and hit Add file path
    • Also add file path .github/access-token.yml
• Hit Create button

2. Create and Configure Owner Policy

Create a OWNER/.github-access-token repository and create an owner access-token.yaml policy file at the root directory of the repository.

Grant Permissions to Workflow Run

Grant Repository Permissions

To grant repository permission create an repository access-token.yaml policy file within the .github/ directory of the target repository.

Important

Ensure repository permissions have been granted (allowed-repository-permissions) within the owner access policy file see Create and Configure Owner Policy

Note

You can also grant repository permissions to all organization repositories within the owner access policy file see Create and Configure Owner Policy

Grant Owner Permissions

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

Configure Custom App Server Endpoint

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
        app-server: |
          url: https://app-server.example.com
          # auth:
          #   type: aws
          #   roleArn: arn:aws:iam::123456789012:role/# github-actions-access-token-api-access
          #   region: eu-central-1
          #   service: lambda

    - 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