title | shortTitle | intro | versions | topics | redirect_from | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Making authenticated API requests with a GitHub App in a GitHub Actions workflow |
Authenticate in Actions workflow |
You can use an installation access token from a {% data variables.product.prodname_github_app %} to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow. You can also pass the token to a custom action to enable the action to make authenticated API requests. |
|
|
|
If you need to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow or need to execute a custom action that requires a token, you should use the built-in GITHUB_TOKEN
if possible. However, the GITHUB_TOKEN
can only access resources within the workflow's repository. If you need to access additional resources, such as resources in an organization or in another repository, you can use a {% data variables.product.prodname_github_app %}. For more information about why you might use a {% data variables.product.prodname_github_app %} over a {% data variables.product.pat_generic %}, see AUTOTITLE.
In order to use a {% data variables.product.prodname_github_app %} to make authenticated API requests, you must register a {% data variables.product.prodname_github_app %}, store your app's credentials, and install your app. Once this is done, you can use your app to create an installation access token, which can be used to make authenticated API requests in a {% data variables.product.prodname_actions %} workflow. You can also pass the installation access token to a custom action that requires a token.
-
Register a {% data variables.product.prodname_github_app %}. Give your {% data variables.product.prodname_github_app %} registration the necessary permissions to access the desired resources. For more information, see AUTOTITLE and AUTOTITLE.
-
Store the app ID of your {% data variables.product.prodname_github_app %} as a {% data variables.product.prodname_actions %} configuration variable. You can find the app ID on the settings page for your app. The app ID is different from the client ID. For more information about navigating to the settings page for your {% data variables.product.prodname_github_app %}, see AUTOTITLE. For more information about storing configuration variables, see AUTOTITLE.
-
Generate a private key for your app. Store the contents of the resulting file as a secret. (Store the entire contents of the file, including
-----BEGIN RSA PRIVATE KEY-----
and-----END RSA PRIVATE KEY-----
.) For more information, see AUTOTITLE. For more information about storing secrets, see AUTOTITLE. -
Install the {% data variables.product.prodname_github_app %} on your user account or organization and grant it access to any repositories that you want your workflow to access. For more information, see AUTOTITLE.
-
In your {% data variables.product.prodname_actions %} workflow, create an installation access token, which you can use to make API requests.
To do this, you can use a {% data variables.product.company_short %}-owned action as demonstrated in the following example. If you prefer to not use this action, you can fork and modify the
actions/create-github-app-token
action, or you can write a script to make your workflow create an installation token manually. For more information, see AUTOTITLE.The following example workflow uses the
actions/create-github-app-token
action to generate an installation access token. Then, the workflow uses the token to make an API request via the {% data variables.product.prodname_cli %}.In the following workflow, replace
APP_ID
with the name of the configuration variable where you stored your app ID. ReplaceAPP_PRIVATE_KEY
with the name of the secret where you stored your app private key.
on:
workflow_dispatch:
jobs:
demo_app_authentication:
runs-on: ubuntu-latest
steps:
- name: Generate a token
id: generate-token
uses: actions/create-github-app-token@v1
with:
app-id: {% raw %}${{ vars.APP_ID }}{% endraw %}
private-key: {% raw %}${{ secrets.APP_PRIVATE_KEY }}{% endraw %}
- name: Use the token
env:
GH_TOKEN: {% raw %}${{ steps.generate-token.outputs.token }}{% endraw %}
run: |
gh api octocat