| title | intro | redirect_from | versions | shortTitle | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Automatic token authentication | {% data variables.product.prodname_dotcom %} provides a token that you can use to authenticate on behalf of {% data variables.product.prodname_actions %}. |
|
| Automatic token authentication |
{% data reusables.actions.enterprise-github-hosted-runners %}
At the start of each workflow job, {% data variables.product.prodname_dotcom %} automatically creates a unique GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in the workflow job.
When you enable {% data variables.product.prodname_actions %}, {% data variables.product.prodname_dotcom %} installs a {% data variables.product.prodname_github_app %} on your repository. The GITHUB_TOKEN secret is a {% data variables.product.prodname_github_app %} installation access token. You can use the installation access token to authenticate on behalf of the {% data variables.product.prodname_github_app %} installed on your repository. The token's permissions are limited to the repository that contains your workflow. For more information, see Permissions for the GITHUB_TOKEN.
Before each job begins, {% data variables.product.prodname_dotcom %} fetches an installation access token for the job. {% data reusables.actions.github-token-expiration %}
The token is also available in the github.token context. For more information, see AUTOTITLE.
You can use the GITHUB_TOKEN by using the standard syntax for referencing secrets: {% raw %}${{ secrets.GITHUB_TOKEN }}{% endraw %}. Examples of using the GITHUB_TOKEN include passing the token as an input to an action, or using it to make an authenticated {% data variables.product.github %} API request.
Important
An action can access the GITHUB_TOKEN through the github.token context even if the workflow does not explicitly pass the GITHUB_TOKEN to the action. As a good security practice, you should always make sure that actions only have the minimum access they require by limiting the permissions granted to the GITHUB_TOKEN. For more information, see Permissions for the GITHUB_TOKEN.
{% data reusables.actions.actions-do-not-trigger-workflows %}
{% data reusables.actions.actions-do-not-trigger-pages-rebuilds %}
{% data reusables.actions.github_token-input-example %}
You can use the GITHUB_TOKEN to make authenticated API calls. This example workflow creates an issue using the {% data variables.product.prodname_dotcom %} REST API:
name: Create issue on commiton: [ push ]jobs: create_issue: runs-on: ubuntu-latestpermissions: issues: writesteps: - name: Create issue using REST APIrun: | curl --request POST \ --url {% data variables.product.rest_url %}/repos/${% raw %}{{ github.repository }}{% endraw %}/issues \ --header 'authorization: Bearer ${% raw %}{{ secrets.GITHUB_TOKEN }}{% endraw %}' \ --header 'content-type: application/json' \ --data '{ "title": "Automated issue for commit: ${% raw %}{{ github.sha }}{% endraw %}", "body": "This issue was automatically created by the GitHub Action workflow **${% raw %}{{ github.workflow }}{% endraw %}**. \n\n The commit hash was: _${% raw %}{{ github.sha }}{% endraw %}_." }' \ --failFor information about the API endpoints {% data variables.product.prodname_github_apps %} can access with each permission, see AUTOTITLE.
The following table shows the permissions granted to the GITHUB_TOKEN by default. People with admin permissions to an {% ifversion not ghes %}enterprise, organization, or repository,{% else %}organization or repository{% endif %} can set the default permissions to be either permissive or restricted. For information on how to set the default permissions for the GITHUB_TOKEN for your enterprise, organization, or repository, see AUTOTITLE, AUTOTITLE, or AUTOTITLE.
{% rowheaders %}
| Scope | Default access (permissive) | Default access (restricted) | Maximum access for pull requests from public forked repositories |
|---|---|---|---|
| actions | read/write | none | read |
| {% ifversion artifact-attestations %} | |||
| attestations | read/write | none | read |
| {% endif %} | |||
| checks | read/write | none | read |
| contents | read/write | read | read |
| deployments | read/write | none | read |
| discussions | read/write | none | read |
| {% ifversion fpt or ghec %} | |||
| id-token | none | none | none |
| {% endif %} | |||
| issues | read/write | none | read |
| metadata | read | read | read |
| models | read | none | none |
| packages | read/write | read | read |
| pages | read/write | none | read |
| pull-requests | read/write | none | read |
| {% ifversion projects-v1 %} | |||
| repository-projects | read/write | none | read |
| {% endif %} | |||
| security-events | read/write | none | read |
| statuses | read/write | none | read |
{% endrowheaders %}
Note
- When a workflow is triggered by the
pull_request_targetevent, theGITHUB_TOKENis granted read/write repository permission, even when it is triggered from a public fork. For more information, see AUTOTITLE. - Private repositories can control whether pull requests from forks can run workflows, and can configure the permissions assigned to
GITHUB_TOKEN. For more information, see AUTOTITLE. - {% data reusables.actions.workflow-runs-dependabot-note %}
You can modify the permissions for the GITHUB_TOKEN in individual workflow files. If the default permissions for the GITHUB_TOKEN are restrictive, you may have to elevate the permissions to allow some actions and commands to run successfully. If the default permissions are permissive, you can edit the workflow file to remove some permissions from the GITHUB_TOKEN. As a good security practice, you should grant the GITHUB_TOKEN the least required access.
You can see the permissions that GITHUB_TOKEN had for a specific job in the "Set up job" section of the workflow run log. For more information, see AUTOTITLE.
You can use the permissions key in your workflow file to modify permissions for the GITHUB_TOKEN for an entire workflow or for individual jobs. This allows you to configure the minimum required permissions for a workflow or job.
{% data reusables.actions.forked-write-permission %}
The two workflow examples earlier in this article show the permissions key being used at the job level, as it is best practice to limit the permissions' scope.
For full details of the permissions key, see AUTOTITLE.
Note
Organization{% ifversion not fpt %} and enterprise{% endif %} owners can prevent you from granting write access to the GITHUB_TOKEN at the repository level. For more information, see AUTOTITLE{% ifversion not fpt %} and AUTOTITLE.{% else %}.{% endif %}
When the permissions key is used, all unspecified permissions are set to no access, with the exception of the metadata scope, which always gets read access.
The permissions for the GITHUB_TOKEN are initially set to the default setting for the enterprise, organization, or repository. If the default is set to the restricted permissions at any of these levels then this will apply to the relevant repositories. For example, if you choose the restricted default at the organization level then all repositories in that organization will use the restricted permissions as the default. The permissions are then adjusted based on any configuration within the workflow file, first at the workflow level and then at the job level. Finally, if the workflow was triggered by a pull request from a forked repository, and the Send write tokens to workflows from pull requests setting is not selected, the permissions are adjusted to change any write permissions to read only.
If you need a token that requires permissions that aren't available in the GITHUB_TOKEN, you can create a {% data variables.product.prodname_github_app %} and generate an installation access token within your workflow. For more information, see AUTOTITLE. Alternatively, you can create a {% data variables.product.pat_generic %}, store it as a secret in your repository, and use the token in your workflow with the {% raw %}${{ secrets.SECRET_NAME }}{% endraw %} syntax. For more information, see AUTOTITLE and AUTOTITLE.
