DevOpsを進めるにあたり、GitHubのissueやPRへのコメントなどのGitHub APIの利用、もしくはIssueや PRのオープンなどのGitHubのイベントをトリガーとした外部サービスへのアクセスなど、GitHubを起点とした自動化が必要なケースが多々あります。
前者であれば、 personal access token（PAT）を発行することで、お手軽に実現することができますが、その反面、PATは個人アカウントに紐づくため、そのアカウントが組織を離れた際のPATの再発行・再設定、またPATの有効期限などの管理も必要になってきます。*1
このようなユースケースに利用できるのが、GitHub Appsになります。
GitHub Apps
GitHub Apps は、GitHub の機能を拡張するツールです。 GitHub Apps を使うと、GitHub で、issue を開く、pull request にコメントする、プロジェクトを管理する、といったことを行うことができます。 また、GitHub で発生するイベントに基づいて、GitHub の外部で何かを行うこともできます。 たとえば、GitHub で issue が開かれたときに、GitHub App で Slack に投稿できます。
GitHub Appsは様々な形でGitHubの機能を拡張できますが、誤解を恐れずに要約すると下記の２つになります。
またPATと比べての利点は下記のようになります。
- 個人アカウント単位だけでなく、Organization単位で作成できる
- Repository単位でGitHub Appsを利用するかどうか決定できる*2
- PATに比べて、詳細に利用できる認可を設定できる*3
以降で、実際にGitHub Appsを作成し、どのように利用できるかを見て行きましょう。
GitHub Appsの作成
GitHub Appsを利用してPRをOpenしたら、自動的にコメントするGitHub Actionsを作成してみましょう。実用的な観点は皆無ですが、GitHub ActionsからどのようにGitHub Appsを利用できるか理解することができます。
GitHub Appsは Settings/Developer Settings から作成できます。
まずはApp Nameを入力します。GitHub Appsは公開することもできるため、Homepage URLはその際に表示されるURLになります。組織内で利用するだけであれば、何を入力しても問題ないです。
WebhookはGitHubイベントが発生した場合に、リクエストを送りたいエンドポイントを指定します。今回はGitHub Actionsからの利用のため、無効化しておきます。
作成するGitHub Appsで許可するPermissionを指定します。今回はPRへのコメントのみのため、Repository Permissionsの中のPull Requestにread/write権限を付与します。
最後にこのGitHub Appsを利用できる範囲を指定します。公開しない前提であれば、「Only on this account」で問題ありません。
作成後、GeneralからGitHub Appsの App IDをメモしておきましょう
またGeneralの画面の下部からprivate Keyも発行しておきましょう。後ほど GitHub Actionsに設定します。
GitHub Appsのインストール
作成したGitHub Appsを利用するためには、インストールをする必要があります。Install Appから全てのRepositoryまたは指定したRepositoryでインストールすることができます。ここで指定したRepositoryに対して、GitHub Appsに付与した権限で操作することが可能になります。
インストールしている GitHub Appsは Settings/Applications から確認することができます。
GitHub ActionsからGitHub Appsを利用する
GitHub APIの操作はGitHub Appsからtokenを取得し、取得したtokenを利用して、GitHub APIにアクセスします。
GitHub Actionsからtokenを取得する場合は、GitHubがactionsを提供しているので、簡単に利用することができます。
利用するためには、作成時に取得したAPP_IDを環境変数に、private keyをsecretに設定する必要があります。
PRオープン時にコメントするGitHub Actionsは下記のようになります。
name: GitHub Apps Test on: pull_request: types: [opened] jobs: comment-on-pull-request: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/create-github-app-token@v1 id: app-token with: private-key: ${{ secrets.PRIVATE_KEY }} app-id: ${{ vars.APP_ID }} - uses: actions/github-script@v7 with: github-token: ${{ steps.app-token.outputs.token }} script: | github.rest.issues.createComment({ issue_number: context.issue.number, owner: context.repo.owner, repo: context.repo.repo, body: `PRがオープンされました！` })
PRを作成すると自動的にコメントが作成されます。
今回のユースケースであれば、実際にはデフォルトのGITHUB_TOKENの権限を利用するほうが簡単です。しかし別のprivate repositoryを参照したい等のGITHUB_TOKENの権限外の操作が必要な場合にGitHub Appsを活用できます。
まとめ
GitHub Appsの利用方法について簡単に紹介しました。
PATは利用が簡単な反面、実際に運用するとなった際に管理等々で運用が面倒に感じることが多いと思います。GitHub Appsを利用することで、PATを利用せずに柔軟にGitHubのRepositoryやActionsなどに対して操作をすることができます。
またGitHub Appsで発行されるtokenはshort livedなtokenのため、PATに比べてもセキュリティ的に優れていると言えます。
今回紹介した内容以外にもevetを利用したWebhookの利用など、様々な機能があります。
また折を見て紹介できればと思います。
それでは良いGitHub Apps Lifeを！
