GitHub ActionsのセルフホステッドランナーをAzure Container Appsで構成する(PAT認証編)
0. はじめに
GitHub ActionsはデフォルトでGitHubが提供するホストランナー上でワークフローを実行できますが、カスタム環境や機密情報を独自の環境下で扱いたい場合、自前のセルフホステッドランナーを用意することができます。
本記事では、Azure Container Apps 上にセルフホステッドランナーを構成し、GitHub Actionsと連携する手順をご紹介します。PAT認証を利用してAzure Container AppsのジョブとGitHubへの接続を確立します。
以下の手順は、主に Microsoft公式ドキュメント を参考にしています。
1. 前提条件
- Azure アカウントがあること(無料アカウントでOK)
- Azure CLI がローカル環境にインストールされていること
2. 本記事で利用するAzureコンポーネント
コンポーネント | 概要 |
---|---|
Resource Group | Azure上でリソースをまとめるためのグループ |
Azure Container Registry (ACR) | コンテナイメージを保存・管理するプライベートレジストリ |
Azure Container Apps (ACA) | サーバーレスなコンテナ実行環境 |
Log Analytics | Azure Monitorに統合されたログ管理・分析サービス |
3. 事前準備
Azure Container Appsを操作するには、最新版のAzure CLIおよびその拡張機能が必要です。
以下のコマンドを実行してCLIと拡張機能を最新版へ更新します。
# Azure CLI を最新バージョンへ
az upgrade
# Azure Container Apps拡張機能を追加または更新
az extension add --name containerapp --upgrade
最新バージョンの拡張機能またはモジュールがインストールされたら、Microsoft.App
および Microsoft.OperationalInsights
名前空間を登録します。
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights
4. セットアップ全体の流れ
4.1. ワークフローを実行するためのGitHubリポジトリを作成
- セキュリティ上、パブリックよりプライベートを推奨
ワークフローを実行するには、ワークフローの定義を含むGitHubリポジトリを作成する必要があります。
適当にGitHubリポジトリをプライベートで作成してください。
4.2. GitHub PAT(Personal Access Token)の準備
- リポジトリレベルでアクセスを最小限に絞ることが望ましい
セルフホステッド ランナーを実行するには、GitHub で個人用アクセス トークン (PAT) を作成する必要があります。 ランナーが開始するたびに、PAT を使って、GitHub にランナーを登録するためのトークンが生成されます。 PAT は、リポジトリのワークフロー キューを監視し、必要に応じてランナーを開始するために、GitHub Actions ランナー スケール ルールでも使われます。
[Repository permissions] (リポジトリのアクセス許可) に次の値を入力します。
設定 | 値 |
---|---|
アクション | [Read-only] (読み取りのみ) |
管理 | [Read and write] (読み取りと書き込み) |
Metadata | [Read-only] (読み取りのみ) |
4.3. 必要なAzureリソースを作成
環境変数は下記を前提としますが、ご自身の環境の値に変更してください。
$RESOURCE_GROUP="rg-github-selfhosted-001"
$LOCATION="japaneast"
$ENVIRONMENT="cae-github-selfhosted-sample"
$JOB_NAME="ca-job-github-actions-runner"
$GITHUB_PAT="<GITHUB_PAT>"
$REPO_OWNER="<REPO_OWNER>"
$REPO_NAME="<REPO_NAME>"
$CONTAINER_IMAGE_NAME="github-actions-runner:1.0"
$CONTAINER_REGISTRY_NAME="<CONTAINER_REGISTRY_NAME>"
プレースホルダーを次の値に置き換えます。
プレースホルダー | 値 |
---|---|
<GITHUB_PAT> |
生成した GitHub PAT。 |
<REPO_OWNER> |
前に作成したリポジトリの所有者。通常、この値は GitHub のユーザー名です。 |
<REPO_NAME> |
前に作成したリポジトリの名前。これは [Repository name] フィールドに入力した名前と同じです。 |
<CONTAINER_REGISTRY_NAME> |
コンテナー レジストリを作成するための一意の名前に置き換えます。 コンテナー レジストリ名は、"Azure 内で一意" であり、数字と小文字のみを含む 5 文字から 50 文字の長さにする必要があります。 |
下記でそれぞれAzureコンポーネントを作成します
※Log AnalyticsはACAを作成した際に自動的に作成されます
# リソースグループの作成
az group create --name "$RESOURCE_GROUP" --location "$LOCATION"
# Azure Container Apps 環境の作成
az containerapp env create --name "$ENVIRONMENT" --resource-group "$RESOURCE_GROUP" --location "$LOCATION"
# Azure Container Registryの作成
az acr create --name "$CONTAINER_REGISTRY_NAME" --resource-group "$RESOURCE_GROUP" --location "$LOCATION" --sku Basic --admin-enabled true
4.4. セルフホステッドランナー用のコンテナイメージをビルド
セルフホステッドランナーを実行するためのDockerfileを用意し、ビルド後、ACRにプッシュします。
詳細なDockerfileの例は、公式ドキュメントを参照してください。
次のコマンドを実行してリポジトリをクローンし、クラウドで az acr build コマンドを使ってコンテナー イメージを構築します。
az acr build `
--registry "$CONTAINER_REGISTRY_NAME" `
--image "$CONTAINER_IMAGE_NAME" `
--file "Dockerfile.github" "https://github.com/Azure-Samples/container-apps-ci-cd-runner-tutorial.git"
4.5. セルフホステッドランナーをジョブとしてデプロイする
コンテナレジストリへプッシュしたイメージをAzure Container Appsに適用し、セルフホステッドランナー用のコンテナを起動します。その際、環境変数としてGitHub PATやリポジトリ情報を渡します。
ここでは事前に生成した PAT を使って GitHub での認証を行うジョブを作成します。
az containerapp job create `-n "$JOB_NAME" -g "$RESOURCE_GROUP" `
--environment "$ENVIRONMENT" `
--trigger-type Event `
--replica-timeout 1800 `
--replica-retry-limit 0 `
--replica-completion-count 1 `
--parallelism 1 `
--image "$CONTAINER_REGISTRY_NAME.azurecr.io/$CONTAINER_IMAGE_NAME" `
--min-executions 0 `
--max-executions 10 `
--polling-interval 30 `
--scale-rule-name "github-runner" `
--scale-rule-type "github-runner" `
--scale-rule-metadata "githubAPIURL=https://api.github.com" "owner=$REPO_OWNER" "runnerScope=repo" "repos=$REPO_NAME" "targetWorkflowQueueLength=1" `
--scale-rule-auth "personalAccessToken=personal-access-token" `
--cpu "2.0" `
--memory "4Gi" `
--secrets "personal-access-token=$GITHUB_PAT" `
--env-vars "GITHUB_PAT=secretref:personal-access-token" "GH_URL=https://github.com/$REPO_OWNER/$REPO_NAME" "REGISTRATION_TOKEN_API_URL=https://api.github.com/repos/$REPO_OWNER/$REPO_NAME/actions/runners/registration-token" `
--registry-server "$CONTAINER_REGISTRY_NAME.azurecr.io"
キーパラメータの説明は下記となります。
パラメーター | 説明 |
---|---|
--replica-timeout | レプリカが実行できる最長時間。 |
--replica-retry-limit | 失敗したレプリカを再試行する回数。 |
--replica-completion-count | このレプリカ数が正常に完了すると、ジョブの実行を成功と見なします。 |
--parallelism | ジョブの実行ごとに開始するレプリカ数。 |
--min-executions | ポーリング間隔ごとに実行するジョブの実行の最小数。 |
--max-executions | ポーリング間隔ごとに実行するジョブの実行の最大数。 |
--polling-interval | スケール ルールを評価するポーリング間隔。 |
--scale-rule-name | スケール ルールの名前。 |
--scale-rule-type | 使うスケール ルールの種類。 GitHub ランナー スケーラーについて詳しくは、KEDA のドキュメントをご覧ください。 |
--scale-rule-metadata | スケール ルールのメタデータ。 GitHub Enterprise を使用している場合は、その API URL を使用して githubAPIURL を更新します。 |
--scale-rule-auth | スケール ルールの認証。 |
--secrets | ジョブに使うシークレット。 |
--env-vars | ジョブに使う環境変数。 |
--registry-server | ジョブに使うコンテナー レジストリ サーバー。Azure Container Registry の場合、このコマンドによって認証が自動的に構成されます。 |
4.6. ワークフローを編集し動作確認
GitHubリポジトリの .github/workflows/
配下に以下のようなワークフローを作成します。runs-on: self-hosted
を指定することで、先ほど構築したAzure Container Apps上のセルフホステッドランナーでジョブが実行されます。
name: CI
on:
push:
branches: [ "main" ]
pull_request:
branches: [ "main" ]
workflow_dispatch:
jobs:
build:
# >>> ここを変更
#runs-on: ubuntu-latest
runs-on: self-hosted
# <<< ここを変更
steps:
- uses: actions/checkout@v4
- name: Run a one-line script
run: echo Hello, world!
- name: Run a multi-line script
run: |
echo Add other actions to build,
echo test, and deploy your project.
これでmain
ブランチへのpushやPR作成時に、Azure上のセルフホステッドランナーがトリガーされてジョブを実行するようになります。
4.7. Azure Container Appsでのステータス確認
以下のコマンドで、Container Apps上で稼働しているコンテナの状態を確認できます。
az containerapp job execution list --name "$JOB_NAME" --resource-group "$RESOURCE_GROUP" --output table --query "[].{Status: properties.status, Name: name, StartTime: properties.startTime}"
また、ログアナリティクスを用いて実行ログやエラー情報を確認することもできます。
まとめ
本記事では、Azure Container Apps上にセルフホステッドランナーを構成し、GitHub Actionsで利用するまでの一連の流れを説明しました。
このアプローチにより、任意のカスタム環境でGitHub Actionsを実行できるようになり、柔軟なCI/CDパイプラインの構築が可能になります。
今回は認証形式をPAT編としましたが、後日GitHub Apps編を別途記事に起こします。
リファレンス
Discussion