ワークフローで GITHUB_TOKEN を使用する

このチュートリアルでは、GitHub Actions ワークフローでの認証に GITHUB_TOKEN を使う方法を見ていきます。これには、トークンをアクションに渡す例、API 要求を行う例、セキュリティ保護された自動化のためのアクセス許可の構成の例が含まれます。

参考情報については、「Workflow syntax for GitHub Actions」をご覧ください。

ワークフローでの GITHUB_TOKEN の使用

シークレットを参照するための標準構文 ${{ secrets.GITHUB_TOKEN }} を使って、GITHUB_TOKEN を使用できます。 GITHUB_TOKEN の使用例には、トークンをアクションへの入力として渡すことや、トークンを使用して認証済みの GitHub API リクエストを作成することが含まれます。

例 1: 入力として GITHUB_TOKEN を渡す

このワークフローの例では、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 }}

例 2: REST API を呼び出す

GITHUB_TOKEN を使用して、認証済みの API 呼び出しを行うことができます。 以下のワークフローの例では、GitHub REST APIを使ってIssueを作成しています。

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 http(s)://HOSTNAME/api/v3/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

GITHUB_TOKEN のアクセス許可の変更

ワークフロー全体または個々のジョブに対する GITHUB_TOKEN のアクセス許可を変更するには、ワークフロー ファイルで permissions キーを使います。 これにより、ワークフローまたはジョブに最低限必要な権限を設定できます。 優れたセキュリティ プラクティスとして、GITHUB_TOKEN に必要最小限のアクセス権を付与することをお勧めします。

この記事で前に示した 2 つのワークフロー例では、permissions キーがジョブ レベルで使われています。

追加の権限を付与する

GITHUB_TOKEN で利用できないアクセス許可を要求するトークンが必要な場合は、GitHub App を作成し、ワークフロー内でインストール アクセス トークンを生成します。 詳しくは、「GitHub Actions ワークフローで GitHub App を使用して認証済み API 要求を作成する」をご覧ください。 または、personal access tokenを作成して、シークレットとしてリポジトリに格納し、ワークフロー内のトークンを ${{ secrets.SECRET_NAME }} 構文で使用することができます。 詳細については、「個人用アクセス トークンを管理する」および「Using secrets in GitHub Actions」を参照してください。

次のステップ

• GITHUB_TOKEN
• Workflow syntax for GitHub Actions