自動トークン認証

メモ

ホステッドランナーは、現在 Enterprise Server ではサポートされていません。 public roadmap で、今後の計画的なサポートの詳細を確認できます。

各ワークフロージョブの開始時に、によって、ワークフローで使用する一意の _TOKEN シークレットが自動的に作成されます。 _TOKEN はワークフロージョブでの認証に使用できます。

Actionsを有効化すると、はリポジトリに Appをインストールします。 _TOKEN シークレットは App インストールアクセストークンです。このインストールアクセストークンは、リポジトリにインストールされた Appの代わりに認証を受けるために利用できます。このトークンの権限は、ワークフローを含むリポジトリに限定されます。詳細については、「_TOKEN のアクセス許可」を参照してください。

各ジョブの開始前に、はジョブのインストールアクセストークンをフェッチします。ジョブが終了するか最大 24 時間後に、_TOKEN の有効期限が切れます。

トークンは .token コンテキストでも使用できます。詳しくは、「ワークフロー実行に関するコンテキスト情報へのアクセス」をご覧ください。

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

重要

ワークフローで _TOKEN がアクションに明示的に渡されない場合でも、アクションでは .token コンテキストを介して _TOKEN にアクセスできます。セキュリティを強化するには、_TOKEN に付与されるアクセス許可を制限することにより、アクションに必要な最小限のアクセスのみが含まれるようにする必要があります。詳細については、「_TOKEN のアクセス許可」を参照してください。

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

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

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

YAML

name: Open new issue
on: workflow_dis

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

name: Open new issue
on: workflow_dis

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

_TOKEN を使用して、認証済みの API 呼び出しを行うことができます。以下のワークフローの例では、 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/${{ .repository }}/issues \
          --header 'authorization: Bearer ${{ secrets._TOKEN }}' \
          --header 'content-type: application/json' \
          --data '{
            "title": "Automated issue for commit: ${{ .sha }}",
            "body": "This issue was automatically created by the  Action workflow **${{ .workflow }}**. \n\n The commit hash was: _${{ .sha }}_."
            }' \
          --fail

Apps が各権限でアクセできる API エンドポイントについては、「 Appに必要な権限」を参照してください。

次の表は、_TOKEN に既定で付与されるアクセス許可を示したものです。組織またはリポジトリへの管理者アクセス許可を持つユーザーは、既定のアクセス許可を制限なしまたは制限ありに設定できます。 Enterprise、organization、またはリポジトリの _TOKEN に対して既定のアクセス許可を設定する方法については、「エンタープライズで Actions のポリシーを適用する」、「Organization について Actions を無効化または制限する」、または「リポジトリの Actions の設定を管理する」を参照してください。

メモ

pull_request_target イベントによってワークフローがトリガーされると、パブリックフォークからトリガーされた場合でも、_TOKEN にはリポジトリの読み取り/書き込みアクセス許可が付与されます。詳しくは、「ワークフローをトリガーするイベント」をご覧ください。
プライベートリポジトリでは、フォークからの pull request がワークフローを実行できるかどうかを制御でき、_TOKEN に割り当てられるアクセス許可を構成できます。詳しくは、「リポジトリの Actions の設定を管理する」をご覧ください。
Dependabot pull request によってトリガーされるワークフロー実行は、フォークされたリポジトリからのものであるかのように実行されるため、読み取り専用の _TOKEN を使用します。それらのワークフローの実行は、シークレットにはアクセスできません。これらのワークフローをセキュリティで保護するための戦略については、「 Actions のセキュリティ強化」を参照してください。

_TOKEN のアクセス許可は、個々のワークフローファイルで変更できます。 _TOKEN の既定のアクセス許可が制限されている場合は、一部のアクションとコマンドを正常に実行できるように、アクセス許可を昇格させる必要がある場合があります。既定のアクセス許可が許容されている場合は、ワークフローファイルを編集して _TOKEN から一部のアクセス許可を削除できます。優れたセキュリティプラクティスとして、_TOKEN に必要最小限のアクセス権を付与することをお勧めします。

_TOKEN が特定のジョブに対して保持していたアクセス許可は、ワークフロー実行ログの [ジョブを設定する] セクションで確認できます。詳しくは、「ワークフロー実行ログの使用」をご覧ください。

ワークフローファイル内の permissions キーを使用して、ワークフロー全体または個々のジョブの _TOKEN のアクセス許可を変更することができます。これにより、ワークフローまたはジョブに最低限必要な権限を設定できます。

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

この記事の前半の 2 つのワークフロー例では、アクセス許可のスコープを制限するのがベストプラクティスであるため、ジョブレベルで使用されている permissions キーを示します。

permissions キーの詳細については、「 Actions　のワークフロー構文」を参照してください。

メモ

Organizationとエンタープライズの所有者は、リポジトリレベルで _TOKEN への書き込みアクセス権限を付与できないようにすることができます。詳細については、「Organization について Actions を無効化または制限する」と「エンタープライズで Actions のポリシーを適用する」を参照してください。

permissions キーが使用されている場合は、すべての未指定のアクセス許可が [アクセスなし] に設定されます。ただし、metadata スコープは例外であり、常に読み取りアクセス権を取得します。

_TOKEN のアクセス許可は最初に、エンタープライズ、組織、またはリポジトリの既定値に設定されます。デフォルトがこれらのレベルのいずれかで制限付きの権限に設定されている場合、これは関連するリポジトリに適用されます。たとえば、Organization レベルで制限付きのデフォルトを選択した場合、その Organization 内のすべてのリポジトリは、制限付きの権限をデフォルトとして使用します。次に、ワークフローファイル内の構成に基づいて、最初にワークフローレベルで、次にジョブレベルで権限が調整されます。最後に、ワークフローがフォークされたリポジトリからの pull request によってトリガーされ、 [pull request からワークフローに書き込みトークンを送信する] 設定が選択されていない場合、アクセス許可が調整され、書き込みアクセス許可はすべて読み取り専用に変更されます。

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

REST API のレート制限

この記事の内容