Alternative Architecture DOJO

オルターブースのクラウドネイティブ特化型ブログです。

トップ > GitHub > GitHub Actions内で、GitHub Appsの認証情報を使って別Organizationのリポジトリへのアクセスを行う

GitHub Actions内で、GitHub Appsの認証情報を使って別Organizationのリポジトリへのアクセスを行う

GitHub GitHub Actions

こんにちは！エンジニアのみっつーです。
今回やることは↓です。

docs.github.com

GitHub Actions内でのGitHub操作には基本的にはGITHUB_TOKENを使えばOKですが、それでは権限が足りないといった場合に検討される手段のご紹介です。

GitHub Appsについて

GitHub Appsは、ユーザーのサインインやサービスアカウントの作成を必要とせずにGitHubの機能を統合するために使用できるものです。
ユーザーまたはOrganizationはGitHub Appsをインストールする際に、GitHub Appsに対してアクセス権限を付与することを許可します。
GitHub Appsのプライベートキーを使用した認証で払い出されたトークンを使用することで、インストール先のOrganizationやリポジトリに対する操作を行うことができます。

docs.github.com

GitHub ActionsにおけるGITHUB_TOKEN、PAT使用との違いについて

GitHub Actions内でGitHub APIを使用した何かしら操作をしたい場合の認証方法について、GitHub Apps以外にもいくつかやり方があるので違いを紹介します。

GITHUB_TOKEN

まずGITHUB_TOKENが使えるワークフロー内容であれば、GITHUB_TOKENを使用すべきです。
但し、GITHUB_TOKENの権限はワークフローを含むリポジトリに限定されるため、他のリポジトリに対する操作が必要になった場合はGitHub Appsを検討します。

docs.github.com

PAT

PATは最も簡単にセットアップ・検証できますが、ユーザーアカウントから発行する必要があるため、権限が必要以上に強くなってしまうことやローテーション管理が自動化できない且つ属人化してしまうことが懸念されます。
GITHUB_TOKENやGitHub Appsに対応していないものを使用する場合でない限りは、GitHub Actions内での使用はできるだけ避けた方が良いでしょう。

このあたりのベストプラクティスについて、ドキュメント上では↓に記載があります。

docs.github.com

GitHub Appsセットアップ

では、実際にGitHub Appsのセットアップ手順を見ていきましょう。

GitHub Apps作成

↓がGitHub Apps作成画面のURLとなります（2024/8現在）。
https://github.com/settings/apps/new

GUI上で辿る場合は、Settingsメニューを開き、Developer Settingsを選択します。
遷移先でGitHub Appsを選択し、New GitHub Appボタンを押下することで作成画面を開きます。
GitHub Appsの作成者をOrganizationとする場合は上記URLと異なりますが、Settingsメニューからほぼ同様の手順で辿れるのでご参考ください。

必須項目を入力したのち、Permissions欄でGitHub Appsに付与する権限を選択します。
横にあるインフォメーションボタンから、該当権限でコールできるAPI一覧のドキュメントへアクセスすることも可能です。使いたいAPIがどのPermissionsに該当しているかを事前に確認しましょう。
今回はRepository permissionsの Contents に対してRead-only権限を選択します。

また、今回はOrganizationにインストールするため、Where can this GitHub App be installed?の欄でAny accountを選択しておきます。

作成後、プライベートキーを発行しておきましょう。

GitHub Appsインストール

今回検証に使用する、アクセスする先のOrganizationでGitHub Appsをインストールしておきます。
GitHub Appsの設定画面を開き、Install Appメニューからインストール先のOrganizationを選択してインストールします。

GitHub Actionsセットアップ

次に、GitHub Appsの認証情報を使用して別Organizationのリポジトリへアクセスする内容のワークフローを実装していきます。

Actions Secrets/Variables 追加

ActionsのSecretsにキー名 APP_PRIVATE_KEY としてGitHub Appsのプライベートキーを、Variablesにキー名 APP_ID としてApp IDを登録しておきます。
プライベートキーはダウンロードしたファイルの中身を丸コピでOKです。

ワークフロー実装

下記ワークフローを実装します。
ポイントとなるのは actions/create-github-app-token のwithパラメータで、例えばownerを指定することでワークフロー実行とは別のOrganization配下にあるリポジトリを参照することが可能です。

name: GitHub Apps Authentication Demo
on:
  workflow_dispatch:
jobs:
  demo_app_authentication:
    runs-on: ubuntu-latest
    steps:
      # GitHub Apps認証、トークンを出力
      - name: Generate a token
        id: generate-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ vars.APP_ID }}
          private-key: ${{ secrets.APP_PRIVATE_KEY }}
          owner: TARGET_ORGANIZATION_NAME

      # ブランチ一覧を取得するAPIをコール
      - name: Call GitHub API
        env:
          GH_TOKEN: ${{ steps.generate-token.outputs.token }}
        run: |
          gh api /repos/TARGET_ORGANIZATION_NAME/TARGET_REPO_NAME/branches --method GET

actions/create-github-app-token のドキュメント：

github.com

動作確認

トリガーをworkflow_dispatchにしてあるので、手動発火します。
ログを確認して、トークンの発行とAPIコールにそれぞれ成功していることが確認できればOKです。
APIレスポンス内容も見ておきましょう。

まとめ

今回はGitHub Actionsワークフロー内で別リポジトリを覗きに行きたくなった場合の対処法について紹介させていただきました。

上記では owner パラメータを使用して別Organization配下のリポジトリにアクセスするワークフロー例を挙げましたが、アクセス先を絞りたい場合であればリポジトリ名を actions/create-github-app-token のwithパラメータ repositories に持たせるといった感じの使い方になります。
余談ですが、複数リポジトリに対して同じ操作をしたければ matrix strategyキーワードの活用ができるよとの記載 もあり、なるほどと思いました。

もしワークフロー内で別リポジトリへのアクセスが必要になったり、複数リポジトリそれぞれに対するバッチ処理の実装を行いたくなった際（あるっちゃあるのか？）は今回の内容を是非ご参考いただければと思います！

サービス一覧 www.alterbooth.com cloudpointer.tech www.alterbooth.com