🌟

GitHub Apps を用いた GitHub Actions 向け Token の払い出し

2023/05/02に公開

GitHub

tech

前提: GitHub Token の種類

同じようなことを書いているドキュメントは他にもあるので、そちらを Reference として記し、当該ドキュメントの記述は最小限にします。

GitHub Actions で使用できる GITHUB_TOKEN

GitHub Actions では secrets.GITHUB_TOKEN という　Token が自動的に使用できるようになっています。

GitHub Actions では、特別な理由がない場合は、この Token を使用することにします。
割り当てられる権限については以下ドキュメントなどを参照ください。

GitHub Actions の yaml の設定で、当該 Actions で使用する権限を細かく調整することができます。

    permissions:
      contents: read
      pull-requests: write

contents はリポジトリで管理しているリソースです。git clone する場合は read、Actions 上で何かしらのファイルを push する場合は write を指定することになると思います。
pull-requests は PR の内容への権限です。Actions 上で Lint などを動かし、その結果を PR のコメントとして投稿するなどする場合は write を指定することになると思います。

Actions から指定可能な permission については以下ドキュメントを参照ください。

この Token では権限が足らない場合、後述の GitHub Apps から生成する Token を使用することになります。

Personal Access Token (PAT)

Personal Access Token は GitHub のユーザー単位で発行することのできる Token です。
PAT 発行時に、そのユーザーが所持することができる権限の範囲内で、任意の権限を付与することができます。

Personal Access Token には以下2種類があります。 Fine-grained な Token のほうがよりきめ細かな権限設定が行えるようになっています。

Classic
Fine-grained (beta)

Fine-grained Token については、GitHub が提供する API 単位で権限を設定することができます。またリポジトリごとに権限の付与有無を設定することも可能です。
この辺の仕組みは後述の GitHub Apps から生成できる　Token と同じです。

では、Fine-grained Token を使えばよいのでは…と思うのですが、現状 Beta なこともあり、多くのツールで未対応なこともあるため、基本的には今のところ Classic 版の PAT を発行することをおすすめします。

e.g. terraform provider 、というか GitHub の GraphQL では Fine-grained Token に未対応
https://github.com/cli/cli/issues/6680

PAT でも、柔軟に権限の調整ができるという意味では要件に足ります。
ただし会社や組織で開発する場合は、PAT のような個人に紐づく Token を CI/CD パイプラインに埋め込むのは避けたほうが無難です。
PAT の代替手段として、ここでは GitHub Apps Token を用いた方法について記述していきます。

GitHub Apps Token

GitHub Apps は、各 organization や repository にインストール可能な Apps で、主に GitHub に対して bot 的な振る舞いをする処理を作成する時に使用します。
インストールする organization や repository については自由に調整することができます。
また、GitHub Apps が保持する権限についても、先述の Fine-grained な PAT と同じように API レベルで細かく調整することができます。

Token 生成の仕組みもサポートしているため、GITHUB_TOKEN よりも広い範囲の権限を持つ Token を GitHub Apps 経由で発行する、ということも可能になります。ここではこのユースケースについて記します。

GitHub Apps Token 生成に必要なもの

GitHub Apps の作成
権限の設定
任意の organization, repository へのインストール
Apps 作成時に払い出された情報を用いた Token の生成

以降では、GitHub Actions 上での terraform plan や、GitHub Actions から他リポジトリの clone を行うために作成した GitHub Apps について解説します。

GitHub Apps

GitHub Apps の詳細な作成手順は割愛します。
作成すると以下の情報が払い出され、これらは GitHub Apps の認証の際に用います（参照方法は後述）

application id
pem file

installation

作成した GitHub Apps は、適用したい Organization にインストールする必要があります。

install 時に、どのリポジトリに許可をするかを選択することができます。

All repositories
Only select repositories

permission

GitHub Apps ごとに、許可をする権限を設定することができます。
GitHub Apps 経由で実施したい処理にあわせて適切な Permission を設定します

GitHub Actions Secrets の設定

GitHub Actions 上で Apps 経由で Token を生成するために、以下のような GitHub Actions Secrets を登録します。

key	value
GITHUB_APP_ID	application id
GITHUB_PRIVATE_KEY	pem file

GitHub Actions での Token 生成

以下の GitHub Actions を用いて、GitHub Apps から一時的な Token を払い出すことができます。

      - name: Generate github token
        id: generate_token
        uses: tibdex/github-app-token@v1
        with:
          app_id: ${{ secrets.GITHUB_APP_ID }}
          private_key: ${{ secrets.GITHUB_PRIVATE_KEY }}

生成した Token は後続で以下のように使用することができます。

      - name: checkout other repository
        uses: actions/checkout@v3
        with:
          repository: moaikids/sada
          token: ${{ steps.generate_token.outputs.token }}
          ref: main