Skip to content
anchor

GitHub Action

Use App token

v2.1.1 Latest version

Use App token

anchor

Use App token

Run GitHub Actions as a GitHub App by using the app's authentication token

Installation

Copy and paste the following snippet into your .yml file.

 
              
- name: Use App token

              
  uses: wow-actions/use-app-token@v2.1.1
Learn more about this action in wow-actions/use-app-token

Choose a version

🔑 Use App Token

Run GitHub Actions as a GitHub App by using the app's authentication token

build MIT License Language PRs Welcome website

This GitHub Action can be used to impersonate a GitHub App when secrets.GITHUB_TOKEN's limitations are too restrictive and a personal access token is not suitable. secrets.GITHUB_TOKEN has limitations such as not being able to triggering a new workflow from another workflow. A workaround is to use a personal access token from a personal user/bot account. However, for organizations, GitHub Apps are a more appropriate automation solution.

We can also use an app token to custom an action's name and avatar.

screenshot

Usage

Before staring, we should get the "APP ID" and "Private Key" in the app's setting page. For example, find the two values in my app's setting page https://github.com/settings/apps/wow-actions-bot.

Get the app's "APP ID"

get-app-id

Get or create a "Private Key"

get-private-key

Do not have a Github App? Get a quick start with probot.

Then add "APP ID" and "Private Key" to the target repo's secrets. For example, we can add two secrets named APP_ID and PRIVATE_KEY with corresponding values.

secrets

Now we can config our workflows.

Method 1: Use action's output in the next steps

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: wow-actions/use-app-token@v2
        id: generate_token
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.PRIVATE_KEY }}

      # Use token in next steps
      - uses: 'any other action'
        with:
          # Use app token in outpus of the 'generate_token' step
          GITHUB_TOKEN: ${{ steps.generate_token.outputs.BOT_TOKEN }}
        env:
          # Use app name in outpus of the 'generate_token' step
          GIT_AUTHOR_NAME: ${{ steps.generate_token.outputs.BOT_NAME }}[bot]
          GIT_AUTHOR_EMAIL: ${{ steps.generate_token.outputs.BOT_NAME }}[bot]@users.noreply.github.com
          GIT_COMMITTER_NAME: ${{ steps.generate_token.outputs.BOT_NAME }}[bot]
          GIT_COMMITTER_EMAIL: ${{ steps.generate_token.outputs.BOT_NAME }}[bot]@users.noreply.github.com

Method 2: Use environment variables in the next steps

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: wow-actions/use-app-token@v2
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.PRIVATE_KEY }}

      # Use token in next steps
      - uses: 'any other action'
        with:
          # Use app token in the environment variable named "BOT_TOKEN"
          GITHUB_TOKEN: ${{ env.BOT_TOKEN }}
        env:
          # Use app name in the environment variable named "BOT_NAME"
          GIT_AUTHOR_NAME: ${{ env.BOT_NAME }}[bot]
          GIT_AUTHOR_EMAIL: ${{ env.BOT_NAME }}[bot]@users.noreply.github.com
          GIT_COMMITTER_NAME: ${{ env.BOT_NAME }}[bot]
          GIT_COMMITTER_EMAIL: ${{ env.BOT_NAME }}[bot]@users.noreply.github.com

Method 3: Use secrets in the next steps

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - uses: wow-actions/use-app-token@v2
        with:
          app_id: ${{ secrets.APP_ID }}
          private_key: ${{ secrets.PRIVATE_KEY }}
          # Specify true to save app token and app slug into the secrets of current repository
          secret: true
          # Specify true to clean saved secrets when workflow run completed
          clean: true
      - uses: 'any other action'
        with:
          GITHUB_TOKEN: ${{ secrets.BOT_TOKEN }}
        env:
          GIT_AUTHOR_NAME: ${{ secrets.BOT_NAME }}[bot]
          GIT_AUTHOR_EMAIL: ${{ secrets.BOT_NAME }}[bot]@users.noreply.github.com
          GIT_COMMITTER_NAME: ${{ secrets.BOT_NAME }}[bot]
          GIT_COMMITTER_EMAIL: ${{ secrets.BOT_NAME }}[bot]@users.noreply.github.com

Inputs

Various inputs are defined to let you configure the action:

Note: Workflow command and parameter names are not case-sensitive.

Name Description Default
app_id The ID of the GitHub App. Create an secret named 'APP_ID' to store your app ID, then used by ${{ secrets.APP_ID }} N/A
private_key The private key of the GitHub App (can be Base64 encoded). Create an secret named 'PRIVATE_KEY' to store your app private key, then used by ${{ secrets.APP_ID }} N/A
fallback The fallback token when app token generate failed N/A
app_slug_name The app slug name exported to env or saved to secrets "BOT_NAME"
app_token_name The app token name exported to env or saved to secrets "BOT_TOKEN"
secret Specify true to save app token and app slug into the secrets of current repository false
clean Specify true to clean saved secrets when workflow run completed. Only used when secret specfiied to true true

License

The scripts and documentation in this project are released under the MIT License