GitHub ActionsランナーをAWS CodeBuildで実行しVPC内リソースにアクセスする方法

quiver
2025.05.07
2024年4月から、GitHub ActionsのセルフホステッドランナーとしてAWS CodeBuildを利用できるようになりました。
https://aws.amazon.com/about-aws/whats-new/2024/04/aws-codebuild-managed-github-action-runners/
CodeBuildを経由することで、GPUインスタンスやArm CPUを利用したり、VPC内リソースにアクセスしたりできます。
本ブログでは、GitHubとAWSが連携されていない状態を前提に、以下について解説します。
GitHub Actions用ワークフローファイルを作成
ConnectionからGitHub AppでGitHubとAWS間を連携
非VPC版AWS CodeBuildでランナー実行
VPC版AWS CodeBuildでランナー実行
本機能はGitHub ActionsランナーをGitHub上(GitHub-hosted)ではなくCodeBuild上(CodeBuild-hosted)で動かすものであり、GitHubでソースコードだけを管理し、buildspec.yml を設定して、CodeBuildでビルドするわけではありません。
 0. GitHub Actions用ワークフローファイルを作成GitHub Actions用ワークフローファイルを リポジトリルート/.github/workflows/ に用意します。
name: Hello World
on: [push]
jobs:
  Hello-World-Job:
    runs-on:
      - codebuild-foo-${{ github.run_id }}-${{ github.run_attempt }}
    steps:
      - run: echo "Hello World"
 1. ConnectionからGitHub AppでGitHubとAWS間を連携AWS側からGitHubリポジトリを操作できるように、セキュアなGitHub Appを利用します。
デベロッパー用ツール→設定→接続からGitHub App接続用リソースを作成します。
動線がわかりにくいため、CodeBuildに一旦飛び、そこからサイドメニューで設定→接続と移動するのがおすすめです。
次のURLからたどれます。
https://console.aws.amazon.com/codesuite/settings/connections
プロバイダーとして「GitHub」を選択します
「新しいアプリをインストールする」を実行します
GitHub に遷移後、GitHub Appのインストール・権限を許可します。
GitHub側では、Integations→ApplicationsからGitHub Appを確認できます。
https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html
 2. 非VPC版AWS CodeBuildでランナー実行まずは、シンプルに、GitHub ActionsランナーをCodeBuildで動かすことを目指します。
CodeBuildから、以下の内容でビルドプロジェクトを作成します。
 プロジェクトの設定重要な設定は以下です。
プロジェクトタイプ : ランナープロジェクト
 ランナー重要な設定は以下です。
ランナープロバイダー : GitHub
認証情報 : 「このプロジェクトにのみオーバーライド認証情報を使用」をチェックし、接続に、作成したGitHubアプリを指定
「追加設定」からわかるように、 WORKFLOW_JOB_QUEUED の webhook イベントでCodeBuildがトリガーされます。
 環境デフォルト設定のままで大丈夫です。
コンピューティングは以下の組み合わせを利用できます
EC2
コンテナ ※ デフォルト。今回のケース
インスタンス(=VPC内で実行)

Lambda
Lambda

今回は EC2コンテナ で評価します。
GPU を利用したい場合はEC2系、VPCアクセスが必要な場合は EC2インスタンス、軽量・高速に実行したい場合はLambdaなどが考えられますが、実行形態ごとに細かな制限があります。
 Buildspec注意書きの通り、GitHub Actionsと連携する際は Builderspe は無視されるため、設定不要です。
 動作確認リポジトリを更新し、ランナーを実行させます。
GitHub 側のアクションログを確認しましょう。
CodeBuild のログも確認しましょう。
AWS CodeBuildログ[Container] 2025/05/02 07:51:26.890383 Running on CodeBuild On-demand
[Container] 2025/05/02 07:51:26.890392 Waiting for agent ping
[Container] 2025/05/02 07:51:28.897727 Waiting for DOWNLOAD_SOURCE
[Container] 2025/05/02 07:51:31.292825 Phase is DOWNLOAD_SOURCE
[Container] 2025/05/02 07:51:31.293766 CODEBUILD_SRC_DIR=/codebuild/output/src2390794023/src
[Container] 2025/05/02 07:51:31.293889 YAML location is /codebuild/readonly/buildspec.yml
[Container] 2025/05/02 07:51:31.296650 Processing environment variables
[Container] 2025/05/02 07:51:32.654553 No runtime version selected in buildspec.
[Container] 2025/05/02 07:51:33.836395 Configuring runner with labels: codebuild-foo-14791138251-1
[Container] 2025/05/02 07:51:33.849470 Moving to directory /codebuild/output/src2390794023/src
[Container] 2025/05/02 07:51:33.849491 Cache is not defined in the buildspec
[Container] 2025/05/02 07:51:34.462427 Skip cache due to: no paths specified to be cached
[Container] 2025/05/02 07:51:34.462802 Registering with agent
[Container] 2025/05/02 07:51:35.041803 Phases found in YAML: 1
[Container] 2025/05/02 07:51:35.041822  BUILD: 1 commands
[Container] 2025/05/02 07:51:35.042117 Phase complete: DOWNLOAD_SOURCE State: SUCCEEDED
[Container] 2025/05/02 07:51:35.042137 Phase context status code:  Message: 
[Container] 2025/05/02 07:51:35.755418 Entering phase INSTALL
[Container] 2025/05/02 07:51:36.342539 Phase complete: INSTALL State: SUCCEEDED
[Container] 2025/05/02 07:51:36.342556 Phase context status code:  Message: 
[Container] 2025/05/02 07:51:36.387914 Entering phase PRE_BUILD
[Container] 2025/05/02 07:51:36.389214 Phase complete: PRE_BUILD State: SUCCEEDED
[Container] 2025/05/02 07:51:36.389227 Phase context status code:  Message: 
[Container] 2025/05/02 07:51:36.436273 Entering phase BUILD
[Container] 2025/05/02 07:51:36.436289 Ignoring BUILD phase commands for self-hosted runner build.
[Container] 2025/05/02 07:51:37.020631 Checking if docker is running. Running command: docker version

GHA self-hosted runner build triggered by /actions/runs/14791138251/job/41528358235

Creating GHA self-hosted runner workspace folder: actions-runner

Downloading GHA self-hosted runner binary

  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed

  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0
  9  114M    9 10.7M    0     0  77.7M      0  0:00:01 --:--:--  0:00:01 77.6M
 92  114M   92  106M    0     0  93.2M      0  0:00:01  0:00:01 --:--:-- 93.2M
100  114M  100  114M    0     0  93.3M      0  0:00:01  0:00:01 --:--:-- 93.2M

Running GHA self-hosted runner binary

√ Connected to GitHub

Current runner version: '2.323.0'
2025-05-02 07:51:47Z: Listening for Jobs
2025-05-02 07:51:51Z: Running job: Hello-World-Job
2025-05-02 07:51:59Z: Job Hello-World-Job completed with result: Succeeded
√ Removed .credentials
√ Removed .runner
Runner listener exit with 0 return code, stop the service, no retry needed.
Exiting runner...

[Container] 2025/05/02 07:52:00.110375 Phase complete: BUILD State: SUCCEEDED
[Container] 2025/05/02 07:52:00.110389 Phase context status code:  Message: 
[Container] 2025/05/02 07:52:00.158890 Entering phase POST_BUILD
[Container] 2025/05/02 07:52:00.161572 Phase complete: POST_BUILD State: SUCCEEDED
[Container] 2025/05/02 07:52:00.161585 Phase context status code:  Message: 
[Container] 2025/05/02 07:52:00.218522 Set report auto-discover timeout to 5 seconds
[Container] 2025/05/02 07:52:00.218630 Expanding base directory path:  .
[Container] 2025/05/02 07:52:00.221698 Assembling file list
[Container] 2025/05/02 07:52:00.221710 Expanding .
[Container] 2025/05/02 07:52:00.224799 Expanding file paths for base directory .
[Container] 2025/05/02 07:52:00.224812 Assembling file list
[Container] 2025/05/02 07:52:00.224815 Expanding **/*
[Container] 2025/05/02 07:52:00.255259 No matching auto-discover report paths found
[Container] 2025/05/02 07:52:00.255316 Report auto-discover file discovery took 0.036793 seconds
[Container] 2025/05/02 07:52:00.255358 Phase complete: UPLOAD_ARTIFACTS State: SUCCEEDED
[Container] 2025/05/02 07:52:00.255365 Phase context status code:  Message: 
 3. VPC版AWS CodeBuildでランナー実行CodeBuildはVPC内での実行に対応しているため、GitHub ActionsランナーとしてもVPC利用できます。VPC内からアクセス可能なデータベース等と連動したランナー実行が可能です。
特に、以下が大事です
VPC CodeBuildの前提
VPCにNATを用意

CodeBuild の環境設定
コンピューティングに EC2 、実行モードに インスタンス を選択
「追加設定」で、VPC、サブネット、セキュリティグループを指定。

 AWS インフラの変更ランナーを実行するVPC環境を用意します。
GitHubと通信するために、NAT経由でインターネット通信できるように VPC を構築しましょう。
 CodeBuildの環境設定コンピューティングに EC2 、実行モードに インスタンス を選択します。
CodeBuildは2023年11月にLambdaコンピューティングに対応しましたが、2025年5月時点でもVPC Lambdaには対応していません。
次に「追加設定」でVPC、サブネット、セキュリティグループを選択します。
「VPC設定の確認」を実行し、疎通が成功することを確認しましょう。
 ワークフローファイルの更新GitHub Actionsのワークフローファイルを変更し、インスタンスID を取得するようにします。
name: Hello World
on: [push]
jobs:
  Hello-World-Job:
    runs-on:
      - codebuild-foo-${{ github.run_id }}-${{ github.run_attempt }}
    steps:
      - run: echo "Hello World"
      - run: |
          uname -m
          TOKEN=$(curl -s -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 600")
          curl -s -H "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/instance-id
 実行先程と同様に、リポジトリを更新し、ランナーのログを確認すると、確かにEC2インスタンス情報を取得できていました。
 まとめGitHub ActionsランナーをCodeBuild-managedランナーで実行する方法を紹介しました。
GitHub Actionsのエコシステムを活かしながら、AWS環境でランナーを実行することで、VPCリソースへのアクセスが可能になるなど、CI/CDの柔軟性が大きく向上します。
また、ランナージョブのキューイング含めてCodeBuildにオフロードできるため、従来のセルフホステッドランナーに比べて運用負荷を大幅に軽減できます。
 参考Self-hosted GitHub Actions runners in AWS CodeBuild - AWS CodeBuild
GitHub ActionsランナーをAWS CodeBuildで実行しVPC内リソースにアクセスする方法

0. GitHub Actions用ワークフローファイルを作成

1. ConnectionからGitHub AppでGitHubとAWS間を連携

2. 非VPC版AWS CodeBuildでランナー実行

プロジェクトの設定

ランナー

環境

Buildspec

動作確認

3. VPC版AWS CodeBuildでランナー実行

AWS インフラの変更

CodeBuildの環境設定

ワークフローファイルの更新

実行

まとめ

参考

関連記事

主なカテゴリ

AWSで探す

注目のテーマ

プロダクトやサービスで探す

特集やシリーズから探す

お問い合わせ

運営会社
