|
| 1 | +--- |
| 2 | +title: Use GITHUB_TOKEN in workflows |
| 3 | +intro: 'Learn how to use the `GITHUB_TOKEN` to authenticate on behalf of {% data variables.product.prodname_actions %}.' |
| 4 | +redirect_from: |
| 5 | + - /github/automating-your-workflow-with-github-actions/authenticating-with-the-github_token |
| 6 | + - /actions/automating-your-workflow-with-github-actions/authenticating-with-the-github_token |
| 7 | + - /actions/configuring-and-managing-workflows/authenticating-with-the-github_token |
| 8 | + - /actions/reference/authentication-in-a-workflow |
| 9 | + - /actions/security-guides/automatic-token-authentication |
| 10 | + - /actions/security-for-github-actions/security-guides/automatic-token-authentication |
| 11 | + - /actions/how-tos/security-for-github-actions/security-guides/automatic-token-authentication |
| 12 | +versions: |
| 13 | + fpt: '*' |
| 14 | + ghes: '*' |
| 15 | + ghec: '*' |
| 16 | +shortTitle: Use `GITHUB_TOKEN` |
| 17 | +--- |
| 18 | + |
| 19 | +## Using the `GITHUB_TOKEN` in a workflow |
| 20 | + |
| 21 | +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. |
| 22 | + |
| 23 | +> [!IMPORTANT] |
| 24 | +> 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 [AUTOTITLE](/actions/reference/github_token-reference#permissions-for-the-github_token). |
| 25 | +
|
| 26 | +### Example 1: passing the `GITHUB_TOKEN` as an input |
| 27 | + |
| 28 | +{% data reusables.actions.github_token-input-example %} |
| 29 | + |
| 30 | +### Example 2: calling the REST API |
| 31 | + |
| 32 | +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: |
| 33 | + |
| 34 | +```yaml |
| 35 | +name: Create issue on commit |
| 36 | + |
| 37 | +on: [ push ] |
| 38 | + |
| 39 | +jobs: |
| 40 | + create_issue: |
| 41 | + runs-on: ubuntu-latest |
| 42 | + permissions: |
| 43 | + issues: write |
| 44 | + steps: |
| 45 | + - name: Create issue using REST API |
| 46 | + run: | |
| 47 | + curl --request POST \ |
| 48 | + --url {% data variables.product.rest_url %}/repos/${% raw %}{{ github.repository }}{% endraw %}/issues \ |
| 49 | + --header 'authorization: Bearer ${% raw %}{{ secrets.GITHUB_TOKEN }}{% endraw %}' \ |
| 50 | + --header 'content-type: application/json' \ |
| 51 | + --data '{ |
| 52 | + "title": "Automated issue for commit: ${% raw %}{{ github.sha }}{% endraw %}", |
| 53 | + "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 %}_." |
| 54 | + }' \ |
| 55 | + --fail |
| 56 | +``` |
| 57 | +
|
| 58 | +## Modifying the permissions for the `GITHUB_TOKEN` |
| 59 | + |
| 60 | +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. |
| 61 | + |
| 62 | +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](/actions/monitoring-and-troubleshooting-workflows/using-workflow-run-logs). |
| 63 | + |
| 64 | +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. |
| 65 | + |
| 66 | +{% data reusables.actions.forked-write-permission %} |
| 67 | + |
| 68 | +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. |
| 69 | + |
| 70 | +For full details of the `permissions` key, see [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#permissions). |
| 71 | + |
| 72 | +> [!NOTE] |
| 73 | +> 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](/organizations/managing-organization-settings/disabling-or-limiting-github-actions-for-your-organization#setting-the-permissions-of-the-github_token-for-your-organization){% ifversion not fpt %} and [AUTOTITLE](/admin/policies/enforcing-policies-for-your-enterprise/enforcing-policies-for-github-actions-in-your-enterprise#enforcing-a-policy-for-workflow-permissions-in-your-enterprise).{% else %}.{% endif %} |
| 74 | +> |
| 75 | +> 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. |
| 76 | + |
| 77 | +## Granting additional permissions |
| 78 | + |
| 79 | +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](/apps/creating-github-apps/guides/making-authenticated-api-requests-with-a-github-app-in-a-github-actions-workflow). 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](/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) and [AUTOTITLE](/actions/security-guides/using-secrets-in-github-actions). |
| 80 | + |
| 81 | +## Configuring `GITHUB_TOKEN` permissions with private repositories |
| 82 | + |
| 83 | +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](/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#enabling-workflows-for-forks-of-private-repositories). |
| 84 | + |
| 85 | +## Next steps |
| 86 | + |
| 87 | +* [AUTOTITLE](/actions/concepts/security/github_token) |
| 88 | +* [AUTOTITLE](/actions/reference/github_token-reference) |
0 commit comments