🔑 Use App Token

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

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.

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 or create a "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.

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