GitHub App setup
- Alpha
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:
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.
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.
For instructions on how to create a GitHub App, see Creating GitHub Apps.
The following settings are a good starting point for IssueOps workflows:
Setting | Value |
---|---|
Name | A clear name that describes its purpose and permissions |
Description | A description of what the app does and what it can access |
Homepage URL | The URL to the repository with your IssueOps code |
Webhook | Disable webhooks |
Permissions | Select the minimum permissions needed for your workflow |
For instructions on how to create a private key, see Managing private keys for GitHub Apps.
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.
Name | Description |
---|---|
App ID | The ID of your GitHub App |
Private Key | The private key you created |
For instructions on how to create secrets, see the following links:
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
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:
vX.X.X
) of the action to the latest published version.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'
})
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!"