本文へスキップ

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

self-hosted-runner-actions-results-url

サマリ

  • 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側のリクエスト数で判別する

前提となる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:には設定した値が残る。

sequenceDiagram participant W as workflow participant R as Runner participant S as JavaScriptのaction
(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で接続先の値を比べるテストは、置換が外れても通る。

関連事例

  • セキュリティ診断・対策

    事例:基盤システムのセキュリティ常時監視と対策

    人材サービスの会社は専門の人材を採用せずに、自社のシステムの安全の状態を把握できるようになりました。同社は業務の基盤システムを開発会社に発注しており、社内にエンジニアはいません。開発支援会社の KDOT はこの開発会社の下で開発に参加し、クラウドの状態を仕組みで常に自動点検する常時監視を、機能の開発と並行して導入しました。そのうえで常時監視が検出した 200件を超える指摘に対応し、件数と対応の計画を開発会社経由で同社に報告しました。監視と対応は現在も KDOT の担当です。

  • データ基盤構築 / 技術顧問(技術企業向け)

    事例:効果検証の分析処理基盤

    効果検証を提供する分析会社との取り組みです。同社は分析者の人数に比例してしか売上と利益を伸ばせない事業の形を、効果検証をプロダクトとして提供することで変革しようとしていました。手法とモデルは同社のまま、社内では開発できなかった、データと機械学習の重い推定を製品として動かす仕組みの開発を、開発支援会社の KDOT に任せました。推定を案件ごとの手作業ではなくシステムで実行できるようになったことで、同社は人数に比例しない形で売上と利益を伸ばすことを目指せるようになりました。

お問い合わせ・ご相談

システム開発、データ活用、プロダクトづくりのことならお気軽にご相談ください。要件が固まる前の整理や、お見積もりだけのご依頼も承ります。