feat(examples): add multi-runner-v2 example by edersonbrilhante · Pull Request #5367 · github-aws-runners/terraform-aws-github-runner

edersonbrilhante · 2026-09-04T14:38:19Z

Description

Adds the examples/multi-runner-v2 example for the unified experimental v2 interface.

Demonstrates global defaults and per-lane runner, webhook, and compute-provider settings.
Uses the v2 module inputs without the legacy v1 compatibility arguments.
Adds example documentation, Terraform verification, provider locks, and navigation entries.

Test Plan

terraform init -backend=false -input=false for examples/multi-runner-v2
terraform validate for the example
Terraform formatting, validation/TFLint, and merge-conflict checks

Related Issues

Depends on #5368, which depends on #5346.

github-actions · 2026-09-04T14:38:38Z

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

The merge-base changed after approval.

## Description Consolidates the complete experimental GitHub Actions runner scale-set stack into one PR. It provides the Terraform orchestration, the ECS controller that consumes it, the EC2 compute-provider implementation, the example deployment, and the validation and delivery workflows needed to operate the stack. ### Status and implementation basis - This stack is experimental and its interfaces and behavior may evolve as the scale-set integration matures. - The scale-set service was written based on reverse-engineering the behavior and protocol implemented by the Go code in [`actions/scaleset`](https://github.com/actions/scaleset), which provides the GitHub Actions Runner Scale Set API client and message-session primitives. - Additional user-facing and operational documentation can be added in a follow-up PR. This PR therefore focuses on the implementation, integration coverage, and delivery plumbing; documentation-only jobs are not required to gate this PR. ### Terraform and AWS orchestration - Adds the standalone `modules/orchestration-providers/scale-set` module, which deploys one hardened ECS Fargate controller service per resolved controller group, with private networking, security groups, CloudWatch logging, health checks, deployment rollback, and task-definition safeguards. - Routes scale-set lanes through the provider-aware multi-runner and runner-config composition, with plan-known grouping by compute provider, runner configuration, or explicit membership. - Delivers versioned non-secret reconciler configuration through SSM Parameter Store while keeping GitHub App credentials as SSM references and restricting task- and compute-role permissions to the configured resources. - Adds validation for GitHub scope and scale-set ownership, grouping coverage, plan-time inputs, provider contracts, configuration and task-definition limits, reserved environment variables, wildcard IAM actions, and AWS inline-policy quotas. - Defines the compute-provider capability boundary and implements the EC2 adapter for scale-up, tagging, termination, JIT configuration storage, AMI access, owned-runner discovery, and scale-down reconciliation. ### Scale-set controller and runtime - Adds the reusable GitHub Actions scale-set client for GitHub.com, GHES, and data-residency endpoints, including GitHub App authentication, runner-group and scale-set discovery, JIT configuration, runner removal, and message-session handling. - Adds the long-running ECS controller service with SSM-backed configuration loading, independent reconcilers, liveness/readiness endpoints, bounded shutdown, and session recovery. - Reconciles EC2 capacity from assigned jobs, preserves busy or unknown runners during scale-down, tracks provider-owned instances with tags, and supports task-role or assumed-role credentials. - Keeps sensitive tokens, message bodies, and JIT configurations out of manifests and logs; TLS verification changes are scoped to the relevant client. ### Example, CI, and integration coverage - Adds the `examples/multi-runner-scale-set` deployment, provider locks, outputs, documentation, and the required multi-runner wiring. - Adds Dependabot and CI coverage for formatting, linting, Terraform/OpenTofu tests, TypeScript tests and builds, multi-architecture container builds, and release publication with SBOM, provenance, and registry attestations. - Adds a hardened scale-set container smoke test using a read-only filesystem, dropped capabilities, `no-new-privileges`, and no network access. - Adds MiniStack ECS/MockServer lifecycle coverage for image build and push, controller startup, GitHub App and scale-set protocol requests, runner registration, scale-up, scale-down, EC2 termination, and cleanup. - The Terraform module adopts scale sets that already exist in GitHub by name; it does not create or delete GitHub scale-set resources. ### Merged stack contributions This PR now contains the following merged scale-set PRs: - [#5350](#5350) — wire scale-set orchestration through the provider-aware runner configuration. - [#5405](#5405) — restore the multi-runner scale-set example and its generated/provider metadata. This replaces the earlier [#5378](#5378) example PR. - [#5300](#5300) — add the ECS scale-set controller, client, and EC2 provider runtime. - [#5347](#5347) — add documentation, CI, release, and MiniStack integration support. - [#5375](#5375) — add the scale-set service-container and ECS/MockServer lifecycle smoke coverage, included through #5347. ## Test Plan - Added and updated focused Terraform/OpenTofu tests for the scale-set module, computed inputs, grouping, ownership validation, configuration delivery, IAM policy construction, quota checks, and configuration resolution. - Added TypeScript unit tests covering the scale-set client, HTTP and message-session behavior, service configuration and credentials, controller lifecycle and health, and EC2 provider inventory and reconciliation. - Terraform/OpenTofu formatting, validation, current-interface documentation generation, `tofu test`, TypeScript type-check/build/format/lint/test targets, container smoke tests, and MiniStack lifecycle workflows cover the affected paths. - Broader user-facing and operational documentation is intentionally deferred to a separate PR, so documentation-only jobs do not need to be required for this PR. - `git diff --check` and the repository CI workflows were run for the combined stack. ## Related Issues - Builds on the multi-runner v2 interface from [#5367](#5367). - The scale-set service implementation is informed by [`actions/scaleset`](https://github.com/actions/scaleset). - This PR is the Terraform and deployment stack consumed by the scale-set controller and service changes listed above. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Guilherme Caulada <guilherme.caulada@gmail.com>

🤖 I have created a release *beep* *boop* --- ## [8.0.0](v7.11.0...v8.0.0) (2026-10-21) ### ⚠ BREAKING CHANGES * **terraform:** require Terraform 1.5.6 ([#5261](#5261)) ### Features * **compute-providers:** add AWS EC2 provider modules ([#5343](#5343)) ([ffa299f](ffa299f)) * **dynamic-labels:** add a capacity-type label to choose spot or on-demand per job ([#5485](#5485)) ([edecd36](edecd36)) * **dynamic-labels:** add allow-list mode to the AWS dynamic labels policy ([#5411](#5411)) ([05984f6](05984f6)) * **examples:** add multi-runner-v2 example ([#5367](#5367)) ([f2779cc](f2779cc)) * **github-app:** select app by rate limit budget ([#5391](#5391)) ([668d8da](668d8da)) * **github-app:** use ssm manifest for extra apps ([#5282](#5282)) ([33c3332](33c3332)) * **multi-runner:** add experimental config translation ([#5284](#5284)) ([dd24d33](dd24d33)) * **multi-runner:** consume resolved experimental config ([#5340](#5340)) ([ff8bfc2](ff8bfc2)) * **multi-runner:** move v1 state into v2 modules ([#5415](#5415)) ([e8d7956](e8d7956)) * **orchestration-providers:** add webhook provider modules ([#5344](#5344)) ([c05c9b3](c05c9b3)) * **runner-config:** add provider-aware runner configuration ([#5345](#5345)) ([42b1261](42b1261)) * **runners:** add network_interfaces for advanced EC2 launch template configuration ([#5427](#5427)) ([1e72c14](1e72c14)) * **scale-down:** opt-in idle confirmation window before terminating not-busy runners ([#5397](#5397)) ([595f3e5](595f3e5)) * **scale-set:** add scale set orchestration in Terraform ([#5299](#5299)) ([937fe15](937fe15)) * **storage:** add runner config consumer ([#5358](#5358)) ([138309c](138309c)) * support native SSM expiration policies for runner token parameters ([#5265](#5265)) ([2dca7f9](2dca7f9)) * **terraform:** add SSM storage provider boundary ([#5454](#5454)) ([d04c5da](d04c5da)) * **terraform:** require Terraform 1.5.6 ([#5261](#5261)) ([f335b32](f335b32)) ### Bug Fixes * allow null amd_sev_snp/nested_virtualization in cpu_options vali… ([#5430](#5430)) ([0b5ec3d](0b5ec3d)) * **control-plane:** clarify partial runner creation test name ([#5339](#5339)) ([b1dd396](b1dd396)) * **deps:** bump actions/deploy-pages from 5.0.0 to 5.0.1 in the github group ([#5418](#5418)) ([1a691ea](1a691ea)) * **deps:** bump github/codeql-action/upload-sarif from 4.36.3 to 4.37.8 ([#5317](#5317)) ([fdb4385](fdb4385)) * **deps:** bump google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml from 2.5.0 to 2.5.1 ([#5331](#5331)) ([1523a66](1523a66)) * **deps:** bump ossf/scorecard-action from 2.4.3 to 2.4.4 ([#5319](#5319)) ([d798070](d798070)) * **deps:** bump step-security/harden-runner from 2.19.4 to 2.21.0 ([#5318](#5318)) ([c81927a](c81927a)) * **deps:** bump step-security/harden-runner from 2.19.4 to 2.21.1 ([#5386](#5386)) ([48b0c42](48b0c42)) * **deps:** bump step-security/harden-runner from 2.21.1 to 2.22.1 ([#5532](#5532)) ([5ccf8b3](5ccf8b3)) * **deps:** bump terraform-linters/setup-tflint from 6.3.0 to 6.3.1 ([#5419](#5419)) ([5f0ecef](5f0ecef)) * **deps:** bump terraform-linters/setup-tflint from 6.3.1 to 6.3.2 ([#5515](#5515)) ([4c4191f](4c4191f)) * **deps:** bump the github group with 3 updates ([#5330](#5330)) ([ab6edf5](ab6edf5)) * **deps:** bump the github group with 3 updates ([#5446](#5446)) ([7bb9280](7bb9280)) * **deps:** bump the github group with 3 updates ([#5504](#5504)) ([aa08de3](aa08de3)) * **deps:** bump the github group with 5 updates ([#5531](#5531)) ([c5b9a47](c5b9a47)) * **deps:** bump zizmorcore/zizmor-action from 0.6.2 to 0.6.3 ([#5387](#5387)) ([62aef5d](62aef5d)) * **deps:** bump zizmorcore/zizmor-action from 0.6.3 to 0.6.4 ([#5447](#5447)) ([aa24dc0](aa24dc0)) * **ec2:** avoid launch template tag conflict for on-demand capacity-type overrides ([#5522](#5522)) ([dc9e820](dc9e820)) * **ec2:** improve failure observability ([#5335](#5335)) ([91751ef](91751ef)) * fail over rate-limited GitHub App requests ([#5523](#5523)) ([7453956](7453956)) * fix typo in variable ([#5462](#5462)) ([0786125](0786125)) * **github-runner:** record the rate-limit metric even when the call fails ([#5426](#5426)) ([5026cd9](5026cd9)) * **lambda:** bump @babel/core from 7.23.9 to 7.29.7 in /lambdas ([#5181](#5181)) ([3729cf7](3729cf7)) * **lambda:** bump @humanfs/node from 0.16.6 to 0.16.8 in /lambdas ([#5336](#5336)) ([f7dd7cb](f7dd7cb)) * **lambda:** bump axios from 1.18.0 to 1.18.1 in /lambdas ([#5223](#5223)) ([21d27f1](21d27f1)) * **lambda:** bump axios from 1.18.1 to 1.20.0 in /lambdas ([#5502](#5502)) ([e2f9e5e](e2f9e5e)) * **lambda:** bump browserslist from 4.22.3 to 4.28.8 in /lambdas ([#5329](#5329)) ([27e7d53](27e7d53)) * **lambda:** bump fast-uri from 3.1.2 to 3.1.5 in /lambdas ([#5242](#5242)) ([9c3e28c](9c3e28c)) * **lambda:** bump fast-uri from 3.1.5 to 3.1.6 in /lambdas ([#5337](#5337)) ([07bbc87](07bbc87)) * **lambda:** bump fast-uri from 3.1.6 to 3.1.8 in /lambdas ([#5488](#5488)) ([3062702](3062702)) * **lambda:** bump follow-redirects from 1.16.0 to 1.16.1 in /lambdas ([#5540](#5540)) ([a7b6dea](a7b6dea)) * **lambda:** bump js-yaml from 3.15.0 to 3.15.1 in /lambdas ([#5264](#5264)) ([a3116bd](a3116bd)) * **lambda:** bump js-yaml from 3.15.1 to 3.15.2 in /lambdas ([#5398](#5398)) ([3db123f](3db123f)) * **lambda:** bump proxy-addr from 2.0.7 to 2.0.8 in /lambdas ([#5510](#5510)) ([faf57cd](faf57cd)) * **lambda:** bump source-map-js from 1.2.1 to 1.2.2 in /lambdas ([#5511](#5511)) ([e058e05](e058e05)) * **lambda:** bump undici from 6.28.0 to 6.28.1 in /lambdas ([#5489](#5489)) ([3ff5877](3ff5877)) * **lambda:** create log groups before functions ([#5324](#5324)) ([2f844ab](2f844ab)), closes [#5323](#5323) * **migration-test:** preserve unreserved job retry concurrency ([#5516](#5516)) ([feba645](feba645)) * **multi-runner:** gate v2 routing with experimental feature ([#5404](#5404)) ([b448845](b448845)) * **multi-runner:** make v2 inputs independent ([#5368](#5368)) ([45d3d0e](45d3d0e)) * **multi-runner:** route v1 and v2 runners separately ([#5346](#5346)) ([cfac174](cfac174)) * **pages:** configure GitHub Pages deployment environment ([#5334](#5334)) ([f081004](f081004)) * **pool-lambda:** grant permission to terminate failed EC2 runners ([#5538](#5538)) ([0043890](0043890)) * re-indent commands in CONTRIBUTING.md guide ([#5305](#5305)) ([547a98b](547a98b)) * retain arm64 build coverage in lambda workflow ([#5535](#5535)) ([80078d7](80078d7)) * **runners:** guard SEGMENT against set -u in start-runner.sh ([#5233](#5233)) ([182b37d](182b37d)) * **runners:** support instance requirements in EC2 Fleet overrides ([#5314](#5314)) ([4f80654](4f80654)) * **scale-set:** implement review followups ([#5477](#5477)) ([445269c](445269c)) * **ssm:** batch housekeeper parameter deletions ([#5469](#5469)) ([28a5135](28a5135)) * **ssm:** delete expired runner parameters as pages are listed ([#5464](#5464)) ([d815b76](d815b76)) * **ssm:** restore incremental housekeeper cleanup ([#5508](#5508)) ([22b9310](22b9310)) * **storage:** add SSM adapter diagnostics ([#5385](#5385)) ([d08be31](d08be31)) * **webhook:** cache only a successful config load ([#5519](#5519)) ([a2fea96](a2fea96)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). --------- Signed-off-by: Brend Smits <brend.smits@philips.com> Co-authored-by: runners-releaser[bot] <194412594+runners-releaser[bot]@users.noreply.github.com> Co-authored-by: Brend Smits <brend.smits@philips.com>

edersonbrilhante requested review from a team September 4, 2026 14:38

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from 9f4aa53 to 33549be Compare September 4, 2026 15:14

edersonbrilhante changed the base branch from fix-multi-runner-v2-routing to remove-v2-legacy-input-requirements September 4, 2026 15:15

edersonbrilhante force-pushed the add-multi-runner-v2-example branch 3 times, most recently from e64aa6b to 183410b Compare September 4, 2026 15:32

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from 183410b to 7c89295 Compare September 4, 2026 17:59

edersonbrilhante added the experimental-v2 label Sep 4, 2026

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from 7c89295 to 9f6ba4c Compare September 4, 2026 19:19

edersonbrilhante mentioned this pull request Sep 4, 2026

fix(perf): Avoid server-side tag filtering in listEC2Runners DescribeInstances call #5328

Open

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from 9f6ba4c to 0c30cc2 Compare September 7, 2026 15:00

edersonbrilhante force-pushed the add-multi-runner-v2-example branch 2 times, most recently from 5bc0e9c to 45bbaec Compare September 8, 2026 11:20

This was referenced Sep 8, 2026

feat(scale-set): add scale set orchestration in Terraform #5299

Merged

feat(microvm): add standalone Terraform provider baseline #5362

Closed

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from de96903 to b6366f5 Compare September 8, 2026 13:42

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from b6366f5 to d119225 Compare September 8, 2026 14:51

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from d119225 to bd9b382 Compare September 8, 2026 15:16

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from bd9b382 to e70c5a0 Compare September 8, 2026 15:41

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from e70c5a0 to e97749a Compare September 8, 2026 16:07

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from 7976e29 to a06ec8a Compare September 10, 2026 16:08

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from a06ec8a to 44a3f55 Compare September 10, 2026 16:11

Base automatically changed from remove-v2-legacy-input-requirements to main September 10, 2026 16:13

edersonbrilhante and others added 13 commits September 10, 2026 18:13

feat(examples): add multi-runner-v2 configuration

c958e47

docs: auto update terraform docs

da85a40

fix(examples): rely on v2 module inputs

927c769

chore(examples): require Terraform 1.4

6e9f422

docs: auto update terraform docs

0053c8a

docs(examples): require Terraform 1.4

f742a50

test(ministack): cover multi-runner-v2 example

9848d4e

fix(examples): remove experimental v2 input prefixes

a90ddfb

fix(examples): track linux provider checksums

1075b19

fix(ministack): configure v2 AMIs through Terraform variables

e4f4e68

fix(ministack): shorten multi-runner v2 prefix

e43d719

fix(ministack): use localhost endpoint

10d7e6e

fix(ministack): use localhost in workflow endpoint

cf30c0f

edersonbrilhante force-pushed the add-multi-runner-v2-example branch from 44a3f55 to cf30c0f Compare September 10, 2026 16:13

Brend-Smits self-requested a review September 10, 2026 16:14

Brend-Smits approved these changes Sep 10, 2026

View reviewed changes

edersonbrilhante merged commit f2779cc into main Sep 10, 2026
64 of 65 checks passed

edersonbrilhante deleted the add-multi-runner-v2-example branch September 10, 2026 16:17

runners-releaser Bot mentioned this pull request Sep 10, 2026

chore(main): release 8.0.0 #5276

Merged

edersonbrilhante restored the add-multi-runner-v2-example branch September 10, 2026 16:32

edersonbrilhante deleted the add-multi-runner-v2-example branch September 10, 2026 16:32

edersonbrilhante mentioned this pull request Sep 11, 2026

feat(microvm): add Terraform provider #5413

Draft

Navigation Menu

Repository navigation

feat(examples): add multi-runner-v2 example - #5367

feat(examples): add multi-runner-v2 example#5367
edersonbrilhante merged 13 commits into
mainfrom
add-multi-runner-v2-example

edersonbrilhante commented Sep 4, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Sep 4, 2026

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

edersonbrilhante commented Sep 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Test Plan

Related Issues

Uh oh!

github-actions Bot commented Sep 4, 2026

Dependency Review

Scanned Files

Uh oh!

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

edersonbrilhante commented Sep 4, 2026 •

edited

Loading