はじめに
Ansible Automation Platform (AAP) のジョブテンプレートをGitHubと連携させ、git push をトリガーに自動で実行する設定方法を解説します。
環境
・HW: IBM Power10 S1022
仮想マシン：
OS: RHEL 9.4 ppc64le (PU Desired 0.5, VP Max 1, Memory 32GB)
・Ansible Automation Platform 2.5.9 (1 ノード構成) (略称 AAP)
・GitHub
手順1: GitHub Personal Access Token の作成
まず、AAPがGitHubリポジトリへアクセスしたり、Webhookを設定したりするために必要な「Personal Access Token」を作成します。
参考：参考: 個人アクセストークンを管理する - GitHub Docs
今回は Personal access token (classic) を使用します。推奨されている Fine-grained personal access token では、本記事で必要なWebhookの権限設定がうまく機能しないケースがあったためです。
- GitHub右上のプロフィールアイコンから Settings に移動します。
- 左側のメニュー下部にある Developer settings をクリックします。
- Personal access tokens > Tokens (classic) を選択し、Generate new token をクリックします。
- generate new token を実行
名前, Expiration, Select scopes を選択して作成を続けます。
トークンの設定を行います。
トークンの目的がわかる名前を入力します (例: AAP Webhook Token)。
・Expiration: トークンの有効期限を選択します。
・Select scopes: AAPに必要な権限を付与します。以下の 2つに必ずチェックを入れてください。
・repo: プライベートリポジトリへのフルコントロールを許可します。（AAPがソースコードを読むために必要）
・admin:repo_hook: リポジトリのWebhookに対する読み取り・書き込み権限を許可します。（AAPがWebhookを自動で設定するために必要）
Generate token をクリックしてトークンを生成し、表示されたトークン文字列を必ずコピーして安全な場所に保管してください。この文字列は二度と表示されません。
【セキュリティに関する注意】
Personal Access Token (classic) は強力な権限を持ちます。取り扱いには十分注意してください。
有効期限 (Expiration) は、可能な限り短く設定することを推奨します。
生成したトークンはパスワードと同様に扱い、漏洩しないよう厳重に管理してください。
不要になったトークンは、速やかにGitHub上から削除しましょう。
手順2: AAPでの認証情報とプロジェクトの設定
AAP側で、GitHubと連携するための設定を行います。ここでは目的の異なる2種類の認証情報を作成するのがポイントです。
手順2: AAPでの認証情報とプロジェクトの設定
2-1. ソースコントロール認証情報の作成 (AAPがリポジトリを読むため)
2-1. ソースコントロール認証情報の作成 (AAPがリポジトリを読むため)
AAPがGitHubプライベートリポジトリからPlaybookのソースコードを読み取る (git clone する) ための認証情報を作成します。
参考： プライベートリポジトリーのソースコントロール認証情報の設定
- Git hub access token をパスワードに指定
・AAPのUIで 認証情報 > 追加 をクリックします。
・認証情報タイプ: ソースコントロール を選択します。
・ユーザー名: 任意の名前で構いません (GitHubに実在するユーザーでなくても可)。
・パスワード: 手順1で作成したGitHub Personal Access Token を貼り付けます。
2-2. プロジェクトの作成
Gitリポジトリと連携するプロジェクトを作成します。
参照：自動化実行プロジェクトの作成
・AAPのUIで プロジェクト > 追加 をクリックします。
・ソースコントロールのタイプ: Git を選択します。
・ソースコントロールのURL: 連携したいGitHubリポジトリのURLを入力します。(例: https://github.com/AAP-test/hello-world.git)
・ソースコントロールの認証情報: 上で作成した「ソースコントロール」認証情報 を選択します。
2-3. GitHub Personal Access Token 認証情報の作成 (AAPがWebhookを受け付けるため)
GitHubからのWebhookをAAPが正しく受信・検証するために必要な認証情報を作成します。
・AAPのUIで 認証情報 > 追加 をクリックします。
・認証情報タイプ: GitHub Personal Access Token を選択します。
・トークン: 手順1で作成したGitHub Personal Access Token を再度貼り付けます。
2-4. ジョブテンプレートの作成とWebhookの有効化
実行するジョブテンプレートを作成し、Webhookを有効にします。
・上で作成したプロジェクト (hello_world) を使うジョブテンプレートを作成します。
・一度テンプレートを保存し、再度編集画面を開きます。
・Webhookを有効にする のトグルをONにします。
・Webhookサービス で GitHub を選択します。
・Webhook認証情報 で、手順2-3で作成した「GitHub Personal Access Token」認証情報 を選択します。
・保存すると、Webhook URL と Webhookキー が自動で生成されます。この2つの値を後で使うので控えておきます。
手順3: GitHubリポジトリでのWebhook設定
GitHubリポジトリ側に「pushイベントがあったらAAPに通知する」設定を追加します。
対象のGitHubリポジトリで Settings > Webhooks に移動します。
- 以下の情報を入力します。
・Payload URL: AAPのジョブテンプレートで生成された Webhook URL を貼り付けます。
・Content type: application/json を選択します。
・Secret: AAPのジョブテンプレートで生成された Webhook キー を貼り付けます。
・Add webhook をクリックして設定を保存します。
Git pushによるJob実行稼働確認
設定は以上です。実際に動作を確認してみます。
・ローカル環境でGitリポジトリのファイルを修正し、git push を実行します。
・push 後、GitHubリポジトリの Settings > Webhooks を見ると、Webhookが実行されたログ（緑のチェックマーク）が確認できます。
ほぼ同じ時刻に、AAP側で該当のジョブが自動的に実行されていることが確認できました。
【TIPS】もしうまく動かない場合
git push してもジョブが実行されない場合は、まずGitHubリポジトリの Settings > Webhooks を確認します。
設定したWebhookの Recent Deliveries タブで、GitHubからAAPへ送信されたリクエストの履歴と、AAPからの応答（Response）を確認できます。
ここでエラー（赤色のビックリマーク）が出ている場合、Payload URLやSecretキーの間違い、またはAAPサーバーへのネットワーク経路（ファイアウォールなど）に問題がある可能性が高いです。
おわりに
AAPとGitHubリポジトリをWebhookで連携させ、git push をトリガーにジョブテンプレートを実行する手順を確認しました。
設定の過程で「ソースコントロール」と「GitHub Personal Access Token」という2種類の似た認証情報が登場しますが、本記事で解説した通り、それぞれ「リポジトリを読むため」と「Webhookを受け付けるため」という異なる役割を持っています。この点を理解することがスムーズな設定の鍵です。
次は、類似の仕組みであるAAPのEvent-Driven Ansibleについても確認してみたいと思います。
以上です。