Automatic token authentication

About the GITHUB_TOKEN secret

At the start of each workflow job, GitHub 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 GitHub Actions, GitHub installs a GitHub App on your repository. The GITHUB_TOKEN secret is a GitHub App installation access token. You can use the installation access token to authenticate on behalf of the 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, GitHub fetches an installation access token for the job. ジョブが終了するか最大 24 時間後に、GITHUB_TOKEN の有効期限が切れます。

The token is also available in the github.token context. For more information, see ワークフロー実行に関するコンテキスト情報へのアクセス.

Using the GITHUB_TOKEN in a workflow

You can use the GITHUB_TOKEN by using the standard syntax for referencing secrets: ${{ secrets.GITHUB_TOKEN }}. Examples of using the GITHUB_TOKEN include passing the token as an input to an action, or using it to make an authenticated GitHub API request.

リポジトリの GITHUB_TOKEN を使ってタスクを実行した場合、GITHUB_TOKEN によってトリガーされたイベントでは (workflow_dispatch と repository_dispatch を除きます)、新しいワークフロー実行は作成されません。 これによって、予想外の再帰的なワークフローの実行が生じないようになります。 たとえば、ワークフロー実行でリポジトリの GITHUB_TOKEN を使用してコードがプッシュされた場合、push イベントの発生時に実行するように構成されたワークフローがリポジトリに含まれている場合でも、新しいワークフローは実行されません。

GITHUB_TOKEN を使う GitHub Actions ワークフローによってプッシュされたコミットでは、GitHub Pages ビルドがトリガーされません。

Example 1: passing the GITHUB_TOKEN as an input

このワークフローの例では、GH_TOKEN 入力パラメーターの値として GITHUB_TOKEN を必要とする GitHub CLI が使用されます。

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

name: Open new issue
on: workflow_dispatch

jobs:
  open-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - run: |
          gh issue --repo ${{ github.repository }} \
            create --title "Issue title" --body "Issue body"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Example 2: calling the REST API

You can use the GITHUB_TOKEN to make authenticated API calls. This example workflow creates an issue using the GitHub REST API:

name: Create issue on commit

on: [ push ]

jobs:
  create_issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Create issue using REST API
        run: |
          curl --request POST \
          --url https://api.github.com/repos/${{ github.repository }}/issues \
          --header 'authorization: Bearer ${{ secrets.GITHUB_TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ github.sha }}",
            "body": "This issue was automatically created by the GitHub Action workflow **${{ github.workflow }}**. \n\n The commit hash was: _${{ github.sha }}_."
            }' \
          --fail

Permissions for the GITHUB_TOKEN

For information about the API endpoints GitHub Apps can access with each permission, see GitHub Appに必要な権限.

The following table shows the permissions granted to the GITHUB_TOKEN by default. People with admin permissions to an enterprise, organization, or repository, 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 エンタープライズで GitHub Actions のポリシーを適用する, Organization について GitHub Actions を無効化または制限する, or リポジトリの GitHub Actions の設定を管理する.

Modifying the permissions for the GITHUB_TOKEN

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 Using workflow run logs.

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.

permissions キーを使用して、フォークされたリポジトリの読み取り権限を追加および削除できますが、通常は書き込みアクセス権を付与することはできません。 この動作の例外としては、管理者ユーザーが GitHub Actions の設定で [Send write tokens to workflows from pull requests](pull request からワークフローに書き込みトークンを送信する) を選択している場合があります。 詳しくは、「リポジトリの GitHub Actions の設定を管理する」をご覧ください。

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 GitHub Actions　のワークフロー構文.

How the permissions are calculated for a workflow job

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.

Granting additional permissions

If you need a token that requires permissions that aren't available in the GITHUB_TOKEN, you can create a GitHub App and generate an installation access token within your workflow. For more information, see GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する. Alternatively, you can create a personal access token, store it as a secret in your repository, and use the token in your workflow with the ${{ secrets.SECRET_NAME }} syntax. For more information, see 個人用アクセス トークンを管理する and Using secrets in GitHub Actions.

Further reading

• REST API のレート制限