self-hosted runnerでactions/cacheを自前のcache serverに向ける

サマリ
- self-hosted runnerで
ACTIONS_RESULTS_URLを自前のcache serverのURLにしても、actions/cacheのリクエストはcache serverに届かないGITHUB_ENV、jobのenv、stepのenvのどれで設定しても結果は同じであるrun:のstepで値を表示すると、設定した値が出る
- RunnerがJavaScriptとDockerのactionの環境変数で、
ACTIONS_RESULTS_URLをGitHubのresults serviceのURLに上書きするためである- 上書きはenvコンテキストの値を含めた後なので、workflowの側では差し替えられない
run:のstepでは上書きしないので、表示した値は設定どおりになる
Runner.Worker.dllの中の変数名をACTIONS_RESULTS_ORLに置換すると、Runnerは上書きしなくなる- job container(
container:)のstepとDocker actionには、この方法では接続先が渡らない - 接続先はRunnerのコンテナの環境変数で与える
- 切り替わったかは
run:の表示ではなく、cache server側のリクエスト数で判別する
- job container(
前提となるcacheの保存先とstepの種類
GitHubの提供形態
GitHubの提供形態には、GitHubが運用するgithub.com(GitHub Enterprise Cloudを含む)と、自社のサーバーで運用するGitHub Enterprise Serverがある。
この記事はgithub.comの場合である。
GitHub Enterprise Serverでは標準のcacheのクライアントが旧方式を選ぶので、この記事の直し方は当てはまらない。
results service
results serviceは、GitHub Actionsのcacheとartifactの保存を担当するGitHubのサービスである。
actions/cacheでsaveしたcacheも、upload-artifactで保存したartifactも、ここに保存される。
自前のcache server
自前のcache serverは、results serviceと同じAPIでcacheを保存するサーバーである。
自社ではfalcondev-oss/github-actions-cache-serverをARC(Actions Runner Controller)のクラスタ内に設置した。
このserverはcacheのリクエストを処理し、artifactなどほかのリクエストはDEFAULT_ACTIONS_RESULTS_URL(デフォルトはGitHubのresults service)へ転送する。
ACTIONS_RESULTS_URL
ACTIONS_RESULTS_URLは、results serviceのURLを保持する環境変数である。
actions/cacheやsetup-nodeのcache:のようなクライアントは、この変数のURLに接続してcacheを保存し、取得する。
自前のcache serverへ接続させるには、この変数の値をcache serverのURLにする必要がある。
actionのstepとrun:のstep
stepにはactionのstepとrun:のstepの2種類がある。
actionのstepはuses:でactionを実行し、run:のstepはシェルのコマンドを実行する。
actionのstepにはJavaScriptで実装されたもの(actions/cacheなど)と、Dockerのコンテナで実行されるものがある。
どちらのstepでもRunnerがstepごとに環境変数を用意する。
envコンテキスト
envコンテキストはworkflowで設定した環境変数の集まりである。
workflow、job、stepのenvに記述した値と、前のstepがGITHUB_ENVに追記した値が含まれる。
Runnerはstepの環境変数を用意するときに、envコンテキストの値を含める。
envで設定してもactions/cacheのリクエストはcache serverに届かない
ACTIONS_RESULTS_URLの設定方法ごとにactions/cache/restoreとactions/upload-artifactを実行し、接続先に指定したserverへのリクエストを数えた。
次のworkflowはGITHUB_ENVで設定する場合で、jobのenvとstepのenvの場合も同じ値を与えた。
jobs:
github-env:
runs-on: <self-hosted runnerのラベル>
steps:
- run: echo "ACTIONS_RESULTS_URL=http://<cache-server-host>/" >> "$GITHUB_ENV"
- run: echo "$ACTIONS_RESULTS_URL" # http://<cache-server-host>/ と表示される
- uses: actions/cache/restore@v6
with:
path: spike-data
key: spike-${{ github.run_id }}
# cache serverへのリクエストは0件で、cacheはGitHubのresults serviceへ向かう
ACTIONS_RESULTS_URLの設定方法 |
serverへのリクエスト | cacheとartifactのリクエスト先 | run:で表示した値 |
|---|---|---|---|
| 設定しない | 0件 | GitHub | 空 |
GITHUB_ENVに書く |
0件 | GitHub | 設定したURL |
jobのenv |
0件 | GitHub | 設定したURL |
stepのenv |
0件 | GitHub | 設定したURL |
RunnerはJavaScriptとDockerのactionでACTIONS_RESULTS_URLを上書きする
cacheのクライアントは、cache service v2ではACTIONS_RESULTS_URLのみを読む。
artifactのクライアントもこの変数を読み、未設定ならUnable to get the ACTIONS_RESULTS_URL env variableで失敗する。
Runnerは、envコンテキストの値でstepの環境変数を用意した後に、JavaScriptのactionを実行するNodeScriptActionHandlerで、ジョブの接続情報のResultsServiceUrlをACTIONS_RESULTS_URLに書き込む。
ResultsServiceUrlはGitHubのresults serviceのURLである。
// Environment には envコンテキストの値が入っている
// Add Actions Runtime server info
var systemConnection = ExecutionContext.Global.Endpoints.Single(...SystemVssConnection...);
Environment["ACTIONS_RUNTIME_URL"] = systemConnection.Url.AbsoluteUri;
Environment["ACTIONS_RUNTIME_TOKEN"] = systemConnection.Authorization.Parameters[...AccessToken];
if (systemConnection.Data.TryGetValue("ResultsServiceUrl", out var resultsUrl) && !string.IsNullOrEmpty(resultsUrl))
{
Environment["ACTIONS_RESULTS_URL"] = resultsUrl;
}
GITHUB_ENV、jobのenv、stepのenvはどれもenvコンテキストに入るため、この上書きで消える。
Docker actionのContainerActionHandlerも、この順で上書きする。
run:を処理するScriptHandlerはこの変数を書かないので、run:には設定した値が残る。
(actions/cache など) participant C as 自前のcache server participant G as GitHubのresults service alt 標準のRunner W->>R: env / GITHUB_ENV で ACTIONS_RESULTS_URL を設定 R->>R: envコンテキストを展開した後に
ACTIONS_RESULTS_URL を GitHub の値で上書き R->>S: ACTIONS_RESULTS_URL = GitHub の URL S->>G: cache のリクエスト Note over C: リクエストは届かない else 変数名を置換したRunner(後述) R->>R: ACTIONS_RESULTS_ORL に書き込む
(ACTIONS_RESULTS_URL は上書きしない) R->>S: ACTIONS_RESULTS_URL = Runnerのコンテナの
環境変数の値(自前の URL) S->>C: cache と artifact のリクエスト C->>G: artifact など cache 以外のリクエストを転送 end
ACTIONS_CACHE_URLを設定すれば向き先を変えられるという情報もある。
この変数を読むのはcache service v1の場合に限られ、旧cache serviceは2025年4月15日に停止した。
server側のリクエスト数で接続先を判別する
run:で表示した値では判別できないので、cacheのstepの実行前後でserver側のリクエスト数を比べる。
falcondevのserverなら/metricsのcache_requests_totalが、cacheのstepの実行ごとに増える。
curl -s http://<cache-server-host>/metrics | grep cache_requests_total
増えなければ、cacheのリクエストはserverで処理されていない。
接続先の値が正しく、Runnerからserverに接続できるのに増えない場合は、Runnerの上書きが原因である。
リクエストが届かない原因はもう1つあり、接続先の値の末尾に/がないと、cacheのstepは警告を出してcacheを使わない。
Runnerの上書きを避ける3つの方法
| 方法 | 内容 | 制約 |
|---|---|---|
Runner.Worker.dllの変数名を置換する |
Runnerが書く変数名をACTIONS_RESULTS_ORLに変え、Runnerのコンテナの環境変数で接続先を与える |
Runnerを更新するたびにイメージを作り直す |
| serverが提供するforkのRunnerを使う | CUSTOM_ACTIONS_RESULTS_URLで接続先を受け取る |
Runnerの更新がforkのリリースを待つ |
| S3に直接つなぐ互換のactionに置き換える | runs-on/cacheなどを使う | 置き換えたstepのリクエストだけが変わる |
この記事では置換の手順を説明する。
互換のactionに置き換える方法では、setup-nodeなどのcache:は標準のactions/cacheを使い続けるので、上書きの影響が残る。
置換したRunnerでも、Runnerのコンテナに設定しただけでは、job container(container:)のstepとDocker actionにACTIONS_RESULTS_URLが渡らない。
job containerへのdocker execはstepの環境変数の辞書にあるキーのみを渡し、Docker actionもその辞書をコンテナに渡すため、Runnerのコンテナの環境変数は届かない。
Docker actionではartifactのuploadが失敗した報告がある。
ARCのcontainerMode: kubernetesはjob containerを必須にするので、この構成では接続先が step まで届かない。
.NETはDLLの中の文字列をUTF-16で格納するため、変数名はgrepでは見つからない。
1文字違いで長さの等しい名前にすると、DLLの中の位置はずれず、変わるのは1バイトになる。
置換後もWorkerは起動する。
置換の対象が見つからなければ失敗させ、Runnerの実装が変わったことにビルドで気付けるようにした。
#!/usr/bin/env python3
"""Runner.Worker.dll 内の ACTIONS_RESULTS_URL(UTF-16)を同じ長さの別名に置換する。"""
import sys
from pathlib import Path
ORIGINAL = "ACTIONS_RESULTS_URL".encode("utf-16-le")
PATCHED = "ACTIONS_RESULTS_ORL".encode("utf-16-le")
path = Path(sys.argv[1])
data = path.read_bytes()
count = data.count(ORIGINAL)
if count == 0:
sys.exit("ACTIONS_RESULTS_URL not found; the runner implementation changed")
path.write_bytes(data.replace(ORIGINAL, PATCHED))
print(f"patched {count} occurrence(s)")
公式のRunnerイメージのDockerfileで適用する。
スクリプトはbind mountで渡し、イメージに残さない。
bind mountするスクリプトは、runnerのユーザーから読める権限にしておく。
作業ディレクトリがRunnerを展開したディレクトリなので、DLLは相対パスで指定できる。
FROM ghcr.io/actions/actions-runner:<version>
RUN --mount=type=bind,source=patch_runner_results_url.py,target=/tmp/patch_runner_results_url.py \
python3 /tmp/patch_runner_results_url.py bin/Runner.Worker.dll
ARCでは、scale setのhelm valuesで、Pod templateのrunnerコンテナに環境変数を与える。
値の末尾の/は省かない。
cacheとartifactのリクエストにはACTIONS_RUNTIME_TOKENが付くので、クラスタの外を通る接続先はHTTPSにする。
次の例は、クラスタ内のServiceに接続する場合である。
template:
spec:
containers:
- name: runner
image: <置換したRunnerのイメージ>
# command などの既存の設定は残す
env:
- name: ACTIONS_RESULTS_URL
value: http://<cache-server-host>/
artifactのクライアントはURLのパスを捨ててoriginを使うため、serverはホストのルートで公開する。
JavaScriptのactionはRunnerの子プロセスとして起動し、Runnerのコンテナの環境変数を引き継ぐ。
Runnerはこの変数を上書きしなくなるので、JavaScriptのactionのstepにはこの値が渡る。
DLLの置換で増えるcache serverへの依存と運用
置換したRunnerでは、artifactのリクエストもcache serverを経由する。
cache serverが止まると、artifactのstepも失敗する。
ARCのscale setは、自己更新を無効にしてRunnerを登録する。
ARC以外で登録したRunnerは、自己更新すると置換していないRunner.Worker.dllに戻り、エラーを出さずにGitHubのcacheへ戻るため、config.sh --disableupdateで登録する。
GitHubは新しいRunnerのリリースから30日以内に更新しないRunnerにはジョブを割り当てないので、リリースごとに置換したイメージを作り直す。
置換するとRunnerはstepごとに接続先を固定し直さなくなる。
上のソースのとおりGITHUB_ENVの値はenvコンテキストに入るため、ジョブ内で任意のコードを実行できる者が接続先を書き換えると、後続のstepのリクエストはACTIONS_RUNTIME_TOKENを付けたまま別のホストへ向かう。
戻すときは、環境変数を外しても元に戻らない。
置換したRunnerはACTIONS_RESULTS_URLを書かないため、環境変数を外すとcacheとartifactのstepが接続先を失う。
イメージを置換前に戻すのと同時に環境変数を外す。
置換が外れたことに気付くには、cacheとartifactを往復させるテストのジョブを置き、cache server側のリクエスト数を見る。
run:のstepで接続先の値を比べるテストは、置換が外れても通る。

