GitHub App setup

If your IssueOps workflow requires access to anything outside of the repository it is running in, you will need to provide it with a token. This token is used to authenticate with the GitHub API and should be scoped to the minimum permissions needed to do the job. Tokens can be provided two ways:

• Personal access tokens (PAT)
• GitHub App installation tokens

Since PATs are scoped to a single user, they are not recommended for use in IssueOps workflows. GitHub Apps are a better choice because they can be scoped to a repository or organization to provide access to the APIs you need.

Ownership

When creating a GitHub App, you have the option to specify your personal account or an organization as the owner. Choosing an organization as the owner allows you to grant access to multiple repositories in the organization and simplifies permissions management.

Setup

Create a GitHub App

For instructions on how to create a GitHub App, see Creating GitHub Apps.

The following settings are a good starting point for IssueOps workflows:

Create a private key

For instructions on how to create a private key, see Managing private keys for GitHub Apps.

Create GitHub Actions secrets

After creating your GitHub App, you will need to create secrets that your IssueOps workflows can use to authenticate with the GitHub API. You can create these at the organization, repository, or environment level depending on your needs.

You will need to create the following secrets. Make sure to note the names you give them as you will need to reference them in your workflows.

For instructions on how to create secrets, see the following links:

• Creating secrets for a repository
• Creating secrets for an environment
• Creating secrets for an organization

Usage

Update the workflow permissions

In any workflow that needs to authenticate as a GitHub App, the following permissions must be specified at the workflow or job level.

permissions:
  contents: read
  id-token: write

Generate the installation access token

There are various examples and open source actions available to create installation access tokens for GitHub Actions workflows. In this documentation, we will use the actions/create-github-app-token action.

Within any workflow job that needs to authenticate as your GitHub App, you will need to include the following step.

steps:
  - uses: actions/create-github-app-token@vX.X.X
    id: token
    with:
      app_id: ${{ secrets.MY_GITHUB_APP_ID }}
      private_key: ${{ secrets.MY_GITHUB_APP_PEM }}
      owner: ${{ github.repository_owner }}

Make sure to update the following:

• Set the version (vX.X.X) of the action to the latest published version.
• Update the secret names to match the ones you created previously.

Use the token in your workflow

Now that the token is being generated, you can reference it in your workflows as an output from the token generation step! This can be referenced as ${{ steps.<step-id>.outputs.token }} (e.g. ${{ steps.token.outputs.token }}).

steps:
  - uses: actions/github-script@vX.X.X
    id: create-org-project
    with:
      github-token: ${{ steps.token.outputs.token }}
      script: |
        await github.rest.projects.createForOrg({
          org: 'octo-org',
          name: 'My awesome project'
        })

Example

The following can be used as a starting point for your own workflows. Make sure to update the following information:

name: Example Workflow

# This workflow runs any time an issue is opened or edited.
on:
  issues:
    types:
      - opened
      - edited

jobs:
  example-job:
    name: Example Job
    runs-on: ubuntu-latest

    permissions:
      contents: read
      id-token: write

    steps:
      # Get the GitHub App installation access token.
      - uses: actions/create-github-app-token@vX.X.X
        id: token
        with:
          app_id: ${{ secrets.MY_GITHUB_APP_ID }}
          private_key: ${{ secrets.MY_GITHUB_APP_PEM }}
          owner: ${{ github.repository_owner }}

      - run: echo "Add your custom steps here!"