セルフホストGitHub Actions runnerの登録期限・実行期限をREST APIで確認する方法

セルフホストGitHub Actions runnerの更新時期を判断するときは、runnerを新規登録・再登録できる期限と、登録済みrunnerの実行サポートが終了する期限を分けて確認する必要があります。

GitHubは2026年9月、指定したrunnerバージョンについて、登録サポートと実行サポートの終了日時を取得できるREST APIを追加しました。組織で管理しているrunnerの場合は、GET /orgs/{org}/actions/runners/deprecations/{version}を使用します。([GitHub Blog][1])

このAPIで重要なのは、取得した日時を単なる「runnerの有効期限」としてまとめないことです。registration_deprecates_atとruntime_deprecates_atを別々に管理すれば、再構築や増設への影響と、稼働中runnerへの影響を切り分けて更新計画を立てられます。

登録期限と実行期限の違い

APIから確認する主要なフィールドは次の3つです。GitHubの発表では、指定バージョン、登録サポート終了日時、実行サポート終了日時が返されると説明されています。([GitHub Blog][1])

フィールド	意味	運用上の判断
`runner_version`	確認対象のrunnerバージョン	問い合わせたバージョンと一致しているか確認する
`registration_deprecates_at`	そのバージョンの登録サポート終了日時	新規構築、再構築、再登録、増設に備えて更新する
`runtime_deprecates_at`	そのバージョンの実行サポート終了日時	稼働中runnerを更新する最終期限として管理する

registration_deprecates_atが影響する場面

registration_deprecates_atは、指定バージョンのrunnerを登録する運用に関係する日時です。

特に注意したいのは、次のような環境です。

runnerを頻繁に作り直している
オートスケールで新しいrunnerを起動している
障害時に別サーバーへ再構築する
OSイメージやコンテナイメージからrunnerを展開している
災害復旧手順でrunnerの再登録を予定している

現在動いているrunnerがジョブを実行できていても、古いバージョンのインストーラーやマシンイメージを使い続けていると、再構築時に登録できなくなる可能性があります。

そのため、登録期限への対策では、稼働中のrunnerだけでなく、構築スクリプト、ゴールデンイメージ、コンテナイメージ、復旧手順に記載されたバージョンも確認することが重要です。

runtime_deprecates_atが影響する場面

runtime_deprecates_atは、登録済みrunnerの実行サポートが終了する日時です。

この日時が近い場合は、現在オンラインになっているrunnerを更新対象として扱います。ただし、「日時を過ぎた瞬間に必ずすべてのジョブが停止する」と断定するのではなく、そのバージョンでの継続稼働を前提にしない期限として管理するのが安全です。

登録期限と実行期限は目的が異なるため、どちらか一方だけを更新台帳に記録する運用は避けましょう。

組織のrunnerバージョン終了日時を取得するREST API

組織単位で確認する場合のエンドポイントは次のとおりです。

GET https://api.github.com/orgs/{org}/actions/runners/deprecations/{version}

指定するパスパラメーターは2つです。

パラメーター	内容	例
`org`	GitHubの組織名	`octo-org`
`version`	確認するrunnerバージョン	`2.300.0`

公式ドキュメントの例では、Accept: application/vnd.github+json、Bearerトークン、X-GitHub-Api-Version: 2026-03-10が指定されています。APIバージョンは将来変更される可能性があるため、実装時には最新の公式ドキュメントも確認してください。([GitHub Docs][2])

cURLで確認する例

トークンをコマンド内へ直接書かず、環境変数GITHUB_TOKENへ設定して実行します。

ORG="octo-org"
VERSION="2.300.0"

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/orgs/${ORG}/actions/runners/deprecations/${VERSION}"

ORGとVERSIONは実際の組織名、runnerバージョンへ置き換えてください。

runnerバージョンは、公式例のように2.300.0形式で指定します。管理中のrunnerから取得したバージョン文字列をそのまま使用すれば、余計な接頭辞を付けるミスを防げます。

PowerShellで確認する例

Windows環境では、Invoke-RestMethodでも取得できます。

$org = "octo-org"
$runnerVersion = "2.300.0"
$token = $env:GITHUB_TOKEN

if ([string]::IsNullOrWhiteSpace($token)) {
    throw "環境変数 GITHUB_TOKEN が設定されていません。"
}

$headers = @{
    Accept                 = "application/vnd.github+json"
    Authorization          = "Bearer $token"
    "X-GitHub-Api-Version" = "2026-03-10"
}

$uri = "https://api.github.com/orgs/$org/actions/runners/deprecations/$runnerVersion"

$response = Invoke-RestMethod `
    -Method Get `
    -Uri $uri `
    -Headers $headers

$response | Format-List

トークンをスクリプトへ直接記述すると、Gitリポジトリへの誤登録やログへの出力につながります。環境変数やシークレット管理機能を利用してください。

APIを利用するために必要な権限

組織向けエンドポイントを利用する認証ユーザーには、対象組織へのadmin accessが必要です。

Fine-grained tokenを使用する場合は、組織権限としてSelf-hosted runnersのreadが必要です。対応するトークンは、GitHub Appのuser access token、installation access token、fine-grained personal access tokenです。従来型のpersonal access tokenやOAuth app tokenでは、admin:orgスコープが必要です。([GitHub Docs][2])

認証方式	必要な権限
Fine-grained personal access token	組織の`Self-hosted runners: read`
GitHub App user access token	組織の`Self-hosted runners: read`
GitHub App installation access token	組織の`Self-hosted runners: read`
Personal access token（classic）	`admin:org`
OAuth app token	`admin:org`

このAPIは参照用なので、fine-grained tokenではwriteを付ける必要はありません。最小権限の原則に従い、期限確認だけを行う仕組みに不要な書き込み権限を与えないようにします。

また、トークン権限だけでなく、対象組織へのアクセス条件も満たしている必要があります。「Self-hosted runners: readを付与したのに取得できない」という場合は、トークンの対象組織や認証主体のアクセス権も確認してください。

APIレスポンスの読み方

公式ドキュメントには、次のレスポンス例が掲載されています。

{
  "runner_version": "2.300.0",
  "runtime_deprecates_at": "2026-09-01T00:00:00Z"
}

この例ではrunner_versionとruntime_deprecates_atが返されていますが、registration_deprecates_atは表示されていません。一方、GitHubの変更案内では、レスポンスに登録サポート終了日時と実行サポート終了日時が含まれると説明されています。([GitHub Blog][1])

したがって、実装では「必ず両方の日時が返る」という前提で処理しない方が安全です。

返らない日時は「未取得」として扱う

日時フィールドが存在しない場合や、値がnullの場合に、次のような値へ勝手に読み替えてはいけません。

期限なし
サポート継続中
0
現在日時
遠い将来の日付
登録期限と実行期限が同じ

正しい扱いは未取得または不明です。

運用台帳では、次のように状態を分けます。

APIの状態	台帳へ記録する値	対応
日時が返った	返された日時	更新計画へ反映する
フィールドがない	未取得	後日再確認する
値が`null`	未取得	期限なしと判断しない
API自体を取得できない	確認失敗	権限、組織名、バージョンを確認する

jqで欠損を判定する例

jqを利用できる環境では、フィールドが存在しない場合に「未取得」と表示できます。

ORG="octo-org"
VERSION="2.300.0"

curl -sS -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer ${GITHUB_TOKEN}" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  "https://api.github.com/orgs/${ORG}/actions/runners/deprecations/${VERSION}" |
jq '{
  runner_version: .runner_version,
  registration_deprecates_at: (
    if has("registration_deprecates_at")
       and .registration_deprecates_at != null
    then .registration_deprecates_at
    else "未取得"
    end
  ),
  runtime_deprecates_at: (
    if has("runtime_deprecates_at")
       and .runtime_deprecates_at != null
    then .runtime_deprecates_at
    else "未取得"
    end
  )
}'

これにより、フィールドの欠損と実際に返された日時を明確に区別できます。

UTCと日本時間を取り違えない

公式レスポンス例の末尾にあるZはUTCを表します。

たとえば、次の日時が返された場合です。

2026-09-01T00:00:00Z

日本時間では9時間を加えた次の時刻になります。

2026-09-01 09:00:00 JST

期限を日付だけで台帳へ転記すると、最大9時間の認識差が発生します。APIの戻り値は元のUTC値も保存し、通知や運用表ではタイムゾーンを明記するのが安全です。

runner全体を管理する場合の確認手順

組織内で複数バージョンのrunnerが動いている場合、1つのバージョンだけを確認しても十分ではありません。

組織のrunner一覧は、次のAPIで取得できます。

GET /orgs/{org}/actions/runners

runner一覧のレスポンスには各runnerのversionが含まれます。組織内のrunnerを列挙し、重複を除いたバージョンごとに終了日時APIを呼び出すと、混在環境を漏れなく確認できます。runner一覧APIはページネーションに対応しているため、台数が多い場合は最初のページだけで確認を終えないようにしてください。([GitHub Docs][2])

実務では次の順序で進めます。

組織内のrunner一覧を取得する
versionを抽出して重複を除く
各バージョンのdeprecations APIを呼び出す
登録期限と実行期限を別々に台帳へ保存する
更新対象となるrunnerと構築イメージを特定する
検証環境で新バージョンのジョブを実行する
本番runnerを順次更新する
runner一覧を再取得し、更新後のversionを確認する

APIを呼び出しただけでは、runnerの更新は実行されません。期限取得と、実際のrunnerバイナリや展開イメージの更新は別の作業です。

登録期限と実行期限から更新優先度を決める

更新計画では、runnerの運用方式によって優先する日時が変わります。

runnerの運用方式	優先して確認する期限	主な対応
オートスケール型	登録期限	起動イメージや構築処理を更新する
使い捨て・短命runner	登録期限	新規生成されるrunnerのバージョンを更新する
常時稼働型	実行期限	稼働中runnerを計画的に更新する
障害時に再構築する構成	両方	復旧イメージと稼働中runnerを更新する
複数バージョン混在	バージョンごとの両期限	古いバージョンから優先的に更新する

常時稼働型であっても、障害が発生すれば再登録が必要になる可能性があります。そのため、実行期限に余裕があっても、登録期限を無視してよいわけではありません。

更新作業は、登録期限または実行期限の直前ではなく、業務上必要な検証期間や切り戻し期間を差し引いて開始します。

たとえば、検証に7日、段階展開に7日、予備期間に7日必要なら、期限の少なくとも21日前を内部期限に設定します。

よくある間違い

2つの日時を同じ期限として扱う

登録サポートと実行サポートでは影響する作業が異なります。

1列の「サポート期限」にまとめるのではなく、台帳や監視項目を2列に分けてください。

registration_deprecates_atを登録トークンの有効期限と混同する

registration_deprecates_atは、runnerバージョンの登録サポートに関する日時です。

runnerを構成するときに発行する一時的なregistration tokenの有効期限とは別の情報です。名称が似ているため、監視項目や変数名を明確に分けましょう。

フィールドがないことを「期限なし」と判断する

公式レスポンス例にも、登録期限が表示されていません。

取得できなかった値は「未取得」とし、期限なしとは判断しないでください。

1台だけ確認して組織全体の状態と判断する

組織内でrunnerバージョンが混在していると、新しいrunnerを1台確認しただけでは古いrunnerを見落とします。

runner一覧からバージョンを集計し、すべての異なるバージョンを確認します。

API取得後にrunnerが更新されたと思い込む

deprecations APIは期限情報を取得するGET APIです。

バイナリ、コンテナイメージ、仮想マシンイメージ、構築スクリプトは更新されません。更新後はrunner一覧などを使って実際のバージョンを再確認してください。

登録期限と実行期限を分けて更新計画へ反映する

セルフホストGitHub Actions runnerの期限確認では、registration_deprecates_atとruntime_deprecates_atを別々に管理することが重要です。

まず、組織のrunner一覧から使用中のバージョンを洗い出します。その後、バージョンごとにdeprecations APIを呼び出し、登録期限と実行期限を更新台帳へ記録してください。

返されない日時は「期限なし」ではなく「未取得」とします。また、このAPIはrunnerを自動更新しないため、構築イメージ、展開スクリプト、稼働中runnerを別途更新し、最後に実際のバージョンを確認するところまでを一連の作業として管理しましょう。
[1]: https://github.blog/changelog/2026-09-03-github-actions-early-september-2026-updates/ “GitHub Actions: Early September 2026 updates – GitHub Changelog”
[2]: https://docs.github.com/en/rest/actions/self-hosted-runners “REST API endpoints for self-hosted runners – GitHub Docs”

この記事を書いた人

佐藤健司

実務の現場で詰まりがちなポイントを地図にするITブログ「IT trip」を運営。Windows／Office（Teams・Excel）からSQL、サーバ運用、ガジェットまで、再現性のある手順と“なぜそうなるか”を丁寧に解説します。読んだらすぐ試せること、そして迷った人の次の一歩が見えることを大切にしています。

セルフホストGitHub Actions runnerの登録期限・実行期限をREST APIで確認する方法

登録期限と実行期限の違い

registration_deprecates_atが影響する場面

runtime_deprecates_atが影響する場面

組織のrunnerバージョン終了日時を取得するREST API

cURLで確認する例

PowerShellで確認する例

APIを利用するために必要な権限

APIレスポンスの読み方

返らない日時は「未取得」として扱う

jqで欠損を判定する例

UTCと日本時間を取り違えない

runner全体を管理する場合の確認手順

登録期限と実行期限から更新優先度を決める

よくある間違い

2つの日時を同じ期限として扱う

registration_deprecates_atを登録トークンの有効期限と混同する

フィールドがないことを「期限なし」と判断する

1台だけ確認して組織全体の状態と判断する

API取得後にrunnerが更新されたと思い込む

登録期限と実行期限を分けて更新計画へ反映する

この記事を書いた人

コメント

コメントするコメントをキャンセル

セルフホストGitHub Actions runnerの登録期限・実行期限をREST APIで確認する方法

登録期限と実行期限の違い

registration_deprecates_atが影響する場面

runtime_deprecates_atが影響する場面

組織のrunnerバージョン終了日時を取得するREST API

cURLで確認する例

PowerShellで確認する例

APIを利用するために必要な権限

APIレスポンスの読み方

返らない日時は「未取得」として扱う

jqで欠損を判定する例

UTCと日本時間を取り違えない

runner全体を管理する場合の確認手順

登録期限と実行期限から更新優先度を決める

よくある間違い

2つの日時を同じ期限として扱う

registration_deprecates_atを登録トークンの有効期限と混同する

フィールドがないことを「期限なし」と判断する

1台だけ確認して組織全体の状態と判断する

API取得後にrunnerが更新されたと思い込む

登録期限と実行期限を分けて更新計画へ反映する

この記事を書いた人

関連記事

コメント

コメントする コメントをキャンセル

コメントするコメントをキャンセル