actions/create-github-app-tokenPublic

NotificationsYou must be signed in to change notification settings
Fork137
Star729

GitHub Action for creating a GitHub App Installation Access Token

github.com/marketplace/actions/create-github-app-token

License

MIT license

729 stars 137 forks Branches Tags Activity

Star

Notifications

You must be signed in to change notification settings

Use this GitHub action with your project

Add this Action to an existing workflow or create a new one

View on Marketplace

Branches Tags

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit History 208 Commits
.github		.github
dist		dist
lib		lib
scripts		scripts
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
action.yml		action.yml
main.js		main.js
package-lock.json		package-lock.json
package.json		package.json
post.js		post.js

Repository files navigation

Create GitHub App Token

GitHub Action for creating a GitHub App installation access token.

Usage

In order to use this action, you need to:

Register new GitHub App.
Store the App's ID or Client ID in your repository environment variables (example:APP_ID).
Store the App's private key in your repository secrets (example:PRIVATE_KEY).

Important

An installation access token expires after 1 hour. Pleasesee this comment for alternative approaches if you have long-running processes.

Create a token for the current repository

name:Run tests on stagingon:push:branches:      -mainjobs:hello-world:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:app-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}      -uses:./actions/staging-testswith:token:${{ steps.app-token.outputs.token }}

Use app token with`actions/checkout`

on:[pull_request]jobs:auto-format:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:# requiredapp-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}      -uses:actions/checkout@v4with:token:${{ steps.app-token.outputs.token }}ref:${{ github.head_ref }}# Make sure the value of GITHUB_TOKEN will not be persisted in repo's configpersist-credentials:false      -uses:creyD/prettier_action@v4.3with:github_token:${{ steps.app-token.outputs.token }}

Create a git committer string for an app installation

on:[pull_request]jobs:auto-format:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:# requiredapp-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}      -name:Get GitHub App User IDid:get-user-idrun:echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"env:GH_TOKEN:${{ steps.app-token.outputs.token }}      -id:committerrun:echo "string=${{ steps.app-token.outputs.app-slug }}[bot] <${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com>"  >> "$GITHUB_OUTPUT"      -run:echo "committer string is ${{ steps.committer.outputs.string }}"

Configure git CLI for an app's bot user

on:[pull_request]jobs:auto-format:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:# requiredapp-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}      -name:Get GitHub App User IDid:get-user-idrun:echo "user-id=$(gh api "/users/${{ steps.app-token.outputs.app-slug }}[bot]" --jq .id)" >> "$GITHUB_OUTPUT"env:GH_TOKEN:${{ steps.app-token.outputs.token }}      -run:|          git config --global user.name '${{ steps.app-token.outputs.app-slug }}[bot]'          git config --global user.email '${{ steps.get-user-id.outputs.user-id }}+${{ steps.app-token.outputs.app-slug }}[bot]@users.noreply.github.com'# git commands like commit work using the bot user      -run:|          git add .          git commit -m "Auto-generated changes"          git push

Tip

The<BOT USER ID> is the numeric user ID of the app's bot user, which can be found underhttps://api.github.com/users/<app-slug>%5Bbot%5D.

For example, we can check athttps://api.github.com/users/dependabot[bot] to see the user ID of Dependabot is 49699333.

Alternatively, you can use theoctokit/request-action to get the ID.

Create a token for all repositories in the current owner's installation

on:[workflow_dispatch]jobs:hello-world:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:app-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}owner:${{ github.repository_owner }}      -uses:peter-evans/create-or-update-comment@v3with:token:${{ steps.app-token.outputs.token }}issue-number:${{ github.event.issue.number }}body:"Hello, World!"

Create a token for multiple repositories in the current owner's installation

on:[issues]jobs:hello-world:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:app-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}owner:${{ github.repository_owner }}repositories:|            repo1            repo2      -uses:peter-evans/create-or-update-comment@v3with:token:${{ steps.app-token.outputs.token }}issue-number:${{ github.event.issue.number }}body:"Hello, World!"

Create a token for all repositories in another owner's installation

on:[issues]jobs:hello-world:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:app-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}owner:another-owner      -uses:peter-evans/create-or-update-comment@v3with:token:${{ steps.app-token.outputs.token }}issue-number:${{ github.event.issue.number }}body:"Hello, World!"

Create a token with specific permissions

Note

Selected permissions must be granted to the installation of the specified app and repository owner. Setting a permission that the installation does not have will result in an error.

on:[issues]jobs:hello-world:runs-on:ubuntu-lateststeps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:app-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}owner:${{ github.repository_owner }}permission-issues:write      -uses:peter-evans/create-or-update-comment@v3with:token:${{ steps.app-token.outputs.token }}issue-number:${{ github.event.issue.number }}body:"Hello, World!"

Create tokens for multiple user or organization accounts

You can use a matrix strategy to create tokens for multiple user or organization accounts.

Note

Seethis documentation for information on using multiline strings in workflows.

on:[workflow_dispatch]jobs:set-matrix:runs-on:ubuntu-latestoutputs:matrix:${{ steps.set.outputs.matrix }}steps:      -id:setrun:echo 'matrix=[{"owner":"owner1"},{"owner":"owner2","repos":["repo1"]}]' >>"$GITHUB_OUTPUT"use-matrix:name:"@${{ matrix.owners-and-repos.owner }} installation"needs:[set-matrix]runs-on:ubuntu-lateststrategy:matrix:owners-and-repos:${{ fromJson(needs.set-matrix.outputs.matrix) }}steps:      -uses:actions/create-github-app-token@v2id:app-tokenwith:app-id:${{ vars.APP_ID }}private-key:${{ secrets.PRIVATE_KEY }}owner:${{ matrix.owners-and-repos.owner }}repositories:${{ join(matrix.owners-and-repos.repos) }}      -uses:octokit/request-action@v2.xid:get-installation-repositorieswith:route:GET /installation/repositoriesenv:GITHUB_TOKEN:${{ steps.app-token.outputs.token }}      -run:echo "$MULTILINE_JSON_STRING"env:MULTILINE_JSON_STRING:${{ steps.get-installation-repositories.outputs.data }}

Run the workflow in a github.com repository against an organization in GitHub Enterprise Server

on:[push]jobs:create_issue:runs-on:self-hostedsteps:      -name:Create GitHub App tokenid:create_tokenuses:actions/create-github-app-token@v2with:app-id:${{ vars.GHES_APP_ID }}private-key:${{ secrets.GHES_APP_PRIVATE_KEY }}owner:${{ vars.GHES_INSTALLATION_ORG }}github-api-url:${{ vars.GITHUB_API_URL }}      -name:Create issueuses:octokit/request-action@v2.xwith:route:POST /repos/${{ github.repository }}/issuestitle:"New issue from workflow"body:"This is a new issue created from a GitHub Action workflow."env:GITHUB_TOKEN:${{ steps.create_token.outputs.token }}

Inputs

`app-id`

Required: GitHub App ID.

`private-key`

Required: GitHub App private key. Escaped newlines (\\n) will be automatically replaced with actual newlines.

Some other actions may require the private key to be Base64 encoded. To avoid recreating a new secret, it can be decoded on the fly, but it needs to be managed securely. Here is an example of how this can be achieved:

steps:  -name:Decode the GitHub App Private Keyid:decoderun:|      private_key=$(echo "${{ secrets.PRIVATE_KEY }}" | base64 -d | awk 'BEGIN {ORS="\\n"} {print}' | head -c -2) &> /dev/null      echo "::add-mask::$private_key"      echo "private-key=$private_key" >> "$GITHUB_OUTPUT"  -name:Generate GitHub App Tokenid:app-tokenuses:actions/create-github-app-token@v2with:app-id:${{ vars.APP_ID }}private-key:${{ steps.decode.outputs.private-key }}

`owner`

Optional: The owner of the GitHub App installation. If empty, defaults to the current repository owner.

`repositories`

Optional: Comma or newline-separated list of repositories to grant access to.

Note

Ifowner is set andrepositories is empty, access will be scoped to all repositories in the provided repository owner's installation. Ifowner andrepositories are empty, access will be scoped to only the current repository.

`permission-<permission name>`

Optional: The permissions to grant to the token. By default, the token inherits all of the installation's permissions. We recommend to explicitly list the permissions that are required for a use case. This follows GitHub's own recommendation tocontrol permissions ofGITHUB_TOKEN in workflows. The documentation also lists all available permissions, just prefix the permission key withpermission- (e.g.,pull-requests →permission-pull-requests).

The reason we define onepermision-<permission name> input per permission is to benefit from type intelligence and input validation built into GitHub's action runner.

`skip-token-revoke`

Optional: If true, the token will not be revoked when the current job is complete.

`github-api-url`

Optional: The URL of the GitHub REST API. Defaults to the URL of the GitHub Rest API where the workflow is run from.

Outputs

`token`

GitHub App installation access token.

`installation-id`

GitHub App installation ID.

`app-slug`

GitHub App slug.

How it works

The action creates an installation access token usingthePOST /app/installations/{installation_id}/access_tokens endpoint. By default,

The token is scoped to the current repository orrepositories if set.
The token inherits all the installation's permissions.
The token is set as outputtoken which can be used in subsequent steps.
Unless theskip-token-revoke input is set to true, the token is revoked in thepost step of the action, which means it cannot be passed to another job.
The token is masked, it cannot be logged accidentally.

Note

Installation permissions can differ from the app's permissions they belong to. Installation permissions are set when an app is installed on an account. When the app adds more permissions after the installation, an account administrator will have to approve the new permissions before they are set on the installation.