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

## 前提となる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](https://gha-cache-server.falcondev.io/how-it-works)をARC（Actions Runner Controller）のクラスタ内に設置した。
このserverはcacheのリクエストを処理し、artifactなどほかのリクエストは[`DEFAULT_ACTIONS_RESULTS_URL`（デフォルトはGitHubのresults service）](https://gha-cache-server.falcondev.io/configuration)へ転送する。

### 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`の場合も同じ値を与えた。

```yaml
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`のみを読む](https://github.com/actions/toolkit/blob/main/packages/cache/src/internal/config.ts)。
artifactのクライアントも[この変数を読み、未設定なら`Unable to get the ACTIONS_RESULTS_URL env variable`で失敗する](https://github.com/actions/toolkit/blob/main/packages/artifact/src/internal/shared/config.ts)。

Runnerは、envコンテキストの値でstepの環境変数を用意した後に、JavaScriptのactionを実行する[NodeScriptActionHandler](https://github.com/actions/runner/blob/v2.338.2/src/Runner.Worker/Handlers/NodeScriptActionHandler.cs)で、ジョブの接続情報の`ResultsServiceUrl`を`ACTIONS_RESULTS_URL`に書き込む。
`ResultsServiceUrl`はGitHubのresults serviceのURLである。

```csharp
// 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](https://github.com/actions/runner/blob/v2.338.2/src/Runner.Worker/Handlers/ContainerActionHandler.cs)も、この順で上書きする。
`run:`を処理する[ScriptHandler](https://github.com/actions/runner/blob/v2.338.2/src/Runner.Worker/Handlers/ScriptHandler.cs)はこの変数を書かないので、`run:`には設定した値が残る。

```mermaid
sequenceDiagram
  participant W as workflow
  participant R as Runner
  participant S as JavaScriptのaction<br/>（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コンテキストを展開した後に<br/>ACTIONS_RESULTS_URL を GitHub の値で上書き
    R->>S: ACTIONS_RESULTS_URL = GitHub の URL
    S->>G: cache のリクエスト
    Note over C: リクエストは届かない
  else 変数名を置換したRunner（後述）
    R->>R: ACTIONS_RESULTS_ORL に書き込む<br/>（ACTIONS_RESULTS_URL は上書きしない）
    R->>S: ACTIONS_RESULTS_URL = Runnerのコンテナの<br/>環境変数の値（自前の URL）
    S->>C: cache と artifact のリクエスト
    C->>G: artifact など cache 以外のリクエストを転送
  end
```

`ACTIONS_CACHE_URL`を設定すれば向き先を変えられるという情報もある。
この変数を読むのは[cache service v1の場合に限られ](https://github.com/actions/toolkit/blob/main/packages/cache/src/internal/config.ts)、旧cache serviceは[2025年4月15日に停止した](https://github.blog/changelog/2025-03-20-notification-of-upcoming-breaking-changes-in-github-actions/)。

## server側のリクエスト数で接続先を判別する

`run:`で表示した値では判別できないので、cacheのstepの実行前後でserver側のリクエスト数を比べる。
falcondevのserverなら[`/metrics`の`cache_requests_total`](https://gha-cache-server.falcondev.io/troubleshooting)が、cacheのstepの実行ごとに増える。

```bash
curl -s http://<cache-server-host>/metrics | grep cache_requests_total
```

増えなければ、cacheのリクエストはserverで処理されていない。
接続先の値が正しく、Runnerからserverに接続できるのに増えない場合は、Runnerの上書きが原因である。

リクエストが届かない原因はもう1つあり、[接続先の値の末尾に`/`がないと、cacheのstepは警告を出してcacheを使わない](https://gha-cache-server.falcondev.io/troubleshooting)。

## Runnerの上書きを避ける3つの方法

| 方法 | 内容 | 制約 |
| --- | --- | --- |
| `Runner.Worker.dll`の変数名を置換する | Runnerが書く変数名を`ACTIONS_RESULTS_ORL`に変え、Runnerのコンテナの環境変数で接続先を与える | Runnerを更新するたびにイメージを作り直す |
| serverが提供するforkのRunnerを使う | [`CUSTOM_ACTIONS_RESULTS_URL`で接続先を受け取る](https://gha-cache-server.falcondev.io/how-it-works) | Runnerの更新がforkのリリースを待つ |
| S3に直接つなぐ互換のactionに置き換える | [runs-on/cache](https://github.com/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の環境変数の辞書にあるキーのみを渡し](https://github.com/actions/runner/blob/v2.338.2/src/Runner.Worker/Handlers/StepHost.cs)、Docker actionもその辞書をコンテナに渡すため、Runnerのコンテナの環境変数は届かない。
Docker actionでは[artifactのuploadが失敗した報告](https://github.com/falcondev-oss/github-actions-cache-server/issues/126)がある。
ARCの`containerMode: kubernetes`は[job containerを必須にする](https://github.com/actions/actions-runner-controller/blob/master/charts/gha-runner-scale-set/values.yaml)ので、この構成では接続先が step まで届かない。

.NETはDLLの中の文字列をUTF-16で格納するため、変数名は[`grep`では見つからない](https://github.com/falcondev-oss/github-actions-cache-server/issues/265)。
1文字違いで長さの等しい名前にすると、DLLの中の位置はずれず、変わるのは1バイトになる。
置換後もWorkerは起動する。
置換の対象が見つからなければ失敗させ、Runnerの実装が変わったことにビルドで気付けるようにした。

```python
#!/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は相対パスで指定できる。

```dockerfile
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に接続する場合である。

```yaml
template:
  spec:
    containers:
      - name: runner
        image: <置換したRunnerのイメージ>
        # command などの既存の設定は残す
        env:
          - name: ACTIONS_RESULTS_URL
            value: http://<cache-server-host>/
```

artifactのクライアントは[URLのパスを捨ててoriginを使う](https://github.com/actions/toolkit/blob/main/packages/artifact/src/internal/shared/config.ts)ため、serverはホストのルートで公開する。
JavaScriptのactionはRunnerの子プロセスとして起動し、Runnerのコンテナの環境変数を引き継ぐ。
Runnerはこの変数を上書きしなくなるので、JavaScriptのactionのstepにはこの値が渡る。

## DLLの置換で増えるcache serverへの依存と運用

置換したRunnerでは、artifactのリクエストもcache serverを経由する。
cache serverが止まると、artifactのstepも失敗する。

ARCのscale setは、[自己更新を無効にしてRunnerを登録する](https://github.com/actions/actions-runner-controller/blob/master/controllers/actions.github.com/autoscalingrunnerset_controller.go)。
ARC以外で登録したRunnerは、自己更新すると置換していない`Runner.Worker.dll`に戻り、エラーを出さずにGitHubのcacheへ戻るため、[`config.sh --disableupdate`で登録する](https://gha-cache-server.falcondev.io/troubleshooting)。
GitHubは[新しいRunnerのリリースから30日以内に更新しないRunnerにはジョブを割り当てない](https://github.blog/changelog/2026-06-12-github-actions-minimum-version-enforcement-timeline-for-self-hosted-runners/)ので、リリースごとに置換したイメージを作り直す。

置換するとRunnerはstepごとに接続先を固定し直さなくなる。
上のソースのとおり`GITHUB_ENV`の値はenvコンテキストに入るため、ジョブ内で任意のコードを実行できる者が接続先を書き換えると、後続のstepのリクエストは`ACTIONS_RUNTIME_TOKEN`を付けたまま別のホストへ向かう。

戻すときは、環境変数を外しても元に戻らない。
置換したRunnerは`ACTIONS_RESULTS_URL`を書かないため、環境変数を外すとcacheとartifactのstepが接続先を失う。
イメージを置換前に戻すのと同時に環境変数を外す。

置換が外れたことに気付くには、cacheとartifactを往復させるテストのジョブを置き、cache server側のリクエスト数を見る。
`run:`のstepで接続先の値を比べるテストは、置換が外れても通る。
