Zenn
🦔

GitHub ActionsのセルフホステッドランナーをAzure Container Appsで構成する(PAT認証編)

2024/12/17に公開

0. はじめに

GitHub ActionsはデフォルトでGitHubが提供するホストランナー上でワークフローを実行できますが、カスタム環境や機密情報を独自の環境下で扱いたい場合、自前のセルフホステッドランナーを用意することができます。
本記事では、Azure Container Apps 上にセルフホステッドランナーを構成し、GitHub Actionsと連携する手順をご紹介します。PAT認証を利用してAzure Container AppsのジョブとGitHubへの接続を確立します。

以下の手順は、主に Microsoft公式ドキュメント を参考にしています。

1. 前提条件

  • Azure アカウントがあること(無料アカウントでOK)
  • Azure CLI がローカル環境にインストールされていること

https://learn.microsoft.com/ja-jp/cli/azure/install-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編を別途記事に起こします。

リファレンス

https://learn.microsoft.com/ja-jp/azure/container-apps/tutorial-ci-cd-runners-jobs?tabs=bash&pivots=container-apps-jobs-self-hosted-ci-cd-github-actions

GitHubで編集を提案

Discussion

ログインするとコメントできます