cdk-github-runner-switch 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+cdk-github-runner-switch
+Copyright 2026 uarch-solutions
+
+This product is licensed under the Apache License, Version 2.0 (see LICENSE).

package/README.md

@@ -1,3 +1,145 @@
-# Temporary Holding Version
+# cdk-github-runner-switch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Leia em português](README.pt-BR.md)
+
+An AWS CDK construct for teams on GitHub's free Actions minutes. It keeps your workflows on **GitHub-hosted runners
+while the free minutes last**. When the monthly minutes run out, it **switches automatically to disposable EC2 Spot
+machines (Graviton, arm64) in your AWS account**. On the 1st of the next month it switches back.
+
+There is nothing to remember and no blocked pipeline at the end of the month. You don't pay for idle machines.
+
+```mermaid
+flowchart LR
+  subgraph GitHub
+    W[Workflow job<br/>runs-on uses vars.RUNNER] -->|webhook workflow_job| A[GitHub App]
+    V[(Repository variable<br/>RUNNER = github / aws)]
+  end
+  subgraph AWS
+    F[Lambda<br/>Function URL] -->|RunInstances Spot → on-demand| E[EC2 arm64<br/>1 job, then terminates]
+    S[EventBridge<br/>every 30 min] -->|check-usage| F
+    R[EventBridge<br/>every 5 min] -->|reconcile| F
+    I[Image Builder<br/>monthly Ubuntu 24.04 AMI] --> P[(SSM parameter)]
+  end
+  A --> F
+  F -->|minutes used ≥ threshold| V
+  E -->|JIT runner| W
+  P --> F
+```
+
+## Why
+
+- **The free plan is enough most of the month.** Paying for runners all the time is a waste, and so is a blocked
+  pipeline on the 25th.
+- **Self-hosted runners usually stay on all the time, or need a lot of moving parts.** Here each job gets a fresh
+  machine with a single-use runner registration ([JIT](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/autoscaling-with-self-hosted-runners#using-just-in-time-runners)).
+  The machine terminates when the job ends.
+- **The switch is a repository variable.** Workflows choose the runner with one expression. There is no
+  fork of your workflows and no manual step.
+
+## What you get
+
+| Piece | What it does |
+|---|---|
+| Webhook (Lambda Function URL) | Checks the GitHub signature. Each queued job that asks for the AWS label gets one machine: Spot on every instance type × subnet first, then on-demand. |
+| Switch (every 30 min) | Reads the Actions minutes used this month and flips `RUNNER` to `aws` at the threshold (default 1,900 of 2,000). It flips back to `github` when the month resets. When it moves to AWS, it re-runs the runs that failed because the minutes ran out. |
+| Reconciliation (every 5 min) | Queued jobs without a machine get one. This covers a lost webhook and jobs that hit the machine cap. |
+| On-demand label | Jobs labeled `aws-ondemand` (for example, deploys) skip Spot, so an interruption never cuts a deploy in half. |
+| Runner image | Ubuntu 24.04 arm64 from Canonical with Docker, Node.js, Python, git, GitHub CLI, AWS CLI and the runner. EC2 Image Builder rebuilds it monthly. You can add cached container images and extra commands. |
+| Safety | Security group with no inbound rules, IMDSv2, encrypted disk, shutdown → terminate, a 2-hour guard against hung jobs. The function may only launch, tag and list instances. |
+
+## Quick start
+
+```bash
+npm install cdk-github-runner-switch
+```
+
+```ts
+import { GitHubRunnerSwitch } from 'cdk-github-runner-switch';
+
+const vpc = new ec2.Vpc(stack, 'Vpc', { natGateways: 0, subnetConfiguration: [{ name: 'public', subnetType: ec2.SubnetType.PUBLIC }] });
+const runners = new GitHubRunnerSwitch(stack, 'Runners', { vpc, repository: 'my-org/my-repo' });
+new CfnOutput(stack, 'WebhookUrl', { value: runners.webhookUrl });
+new CfnOutput(stack, 'SecretArn', { value: runners.secret.secretArn });
+new CfnOutput(stack, 'ImagePipelineArn', { value: runners.imagePipelineArn });
+```
+
+Then, once per account and repository:
+
+1. **Spot service-linked role** (only if the account has never used Spot):
+   `aws iam create-service-linked-role --aws-service-name spot.amazonaws.com`
+2. **Deploy** the stack (`cdk deploy`).
+3. **Build the first image** (about 30 minutes). After that, it is rebuilt on schedule:
+   `aws imagebuilder start-image-pipeline-execution --image-pipeline-arn <ImagePipelineArn>`
+4. **Create the GitHub App and store its key.** Run [`scripts/setup-github-app.sh <stack-name>`](scripts/setup-github-app.sh)
+   in your terminal. It prints the webhook URL, the generated webhook secret and the permissions to grant. Then it
+   asks for the App ID and the `.pem` file. The key goes straight to Secrets Manager.
+5. **Point the workflows at the switch:**
+
+   ```yaml
+   runs-on: ${{ vars.RUNNER == 'aws' && fromJSON('["self-hosted","linux","arm64","aws"]') || 'ubuntu-24.04-arm' }}
+   ```
+
+   See [`examples/workflow.yml`](examples/workflow.yml) (with an on-demand deploy job) and
+   [`examples/canary.yml`](examples/canary.yml), a weekly liveness test that uses no GitHub minutes.
+
+To flip the switch by hand: `gh variable set RUNNER --body aws` (or `github`).
+
+## Configuration
+
+| Property | Default | Notes |
+|---|---|---|
+| `vpc` | (required) | Machines need outbound internet access. |
+| `subnets` | public subnets | Public subnets avoid paying for a NAT gateway. The machines still have no inbound port. |
+| `repository` | (required) | `owner/name`. |
+| `billing` | `ORGANIZATION` | `USER` for personal accounts. That needs a fine-grained token with *Plan: read*, which the setup script stores as `billingToken`. |
+| `label` / `onDemandLabel` | `aws` / `aws-ondemand` | Labels used in `runs-on`. |
+| `instanceTypes` | `m7g.large`, `m6g.large`, `m8g.large` | Graviton (arm64), in order of preference. |
+| `thresholdMinutes` | `1900` | When to move to AWS. Set it a little below your plan's quota. |
+| `maxInstances` | `6` | Machine cap. Jobs above it wait and are launched by the reconciliation. |
+| `switchVariable` | `RUNNER` | Repository variable that the construct flips. |
+| `maxJobDuration` | 2 hours | The machine shuts down after this, even if a job hangs. |
+| `rootVolumeSize` | `40` GiB | |
+| `nodeMajorVersion` | `24` | Node.js installed in the image. |
+| `cachedImages` | `[]` | Container images pulled into the AMI, for faster `services:`. |
+| `extraImageCommands` | `[]` | Extra setup, e.g. `npx -y playwright install-deps chromium`. |
+| `imageSchedule` | monthly (day 1, 05:00 UTC) | EventBridge cron for the image rebuild. |
+| `reconcileInterval` / `usageCheckInterval` | 5 min / 30 min | |
+
+## Cost
+
+You pay only while jobs run:
+
+- the EC2 Spot price of the instance;
+- a few cents of Lambda, EventBridge and Secrets Manager;
+- the storage of one AMI snapshot;
+- one monthly image build (about 30 minutes of a `large` instance).
+
+There is no NAT gateway, no load balancer and no machine waiting for work. Check the Spot prices in your region; for
+`m7g.large` they are usually a fraction of the on-demand price.
+
+## Security notes
+
+- The webhook is a public Function URL. Every request is authenticated with the App's HMAC signature
+  (`X-Hub-Signature-256`). Requests without a valid signature get 401.
+- The GitHub App only needs: repository *Administration* (to create JIT runners), *Actions* (read runs and re-run
+  failed ones), *Variables* (the switch), and organization *Administration: read* (billing usage).
+- The machine role only has Session Manager access, for debugging. Give your jobs their own credentials, for
+  example with GitHub OIDC.
+- One machine per job, never reused. A job cannot see another job's workspace.
+
+## Limitations
+
+- arm64 (Graviton) only, for now. Your workflows need arm64-compatible actions and images.
+- One repository per construct. Instantiate it again for other repositories.
+- Linux only.
+
+## Prior art
+
+[github-aws-runners/terraform-aws-github-runner](https://github.com/github-aws-runners/terraform-aws-github-runner) (formerly philips-labs) and
+[CloudSnorkel/cdk-github-runners](https://github.com/CloudSnorkel/cdk-github-runners) are mature, feature-rich
+projects for running GitHub runners on AWS. This construct does something narrower: it **uses GitHub's free minutes
+first and only spills over to AWS when they run out**, with as few moving parts as possible.
+
+## License
+
+[Apache-2.0](LICENSE)

package/README.pt-BR.md

@@ -0,0 +1,62 @@
+# cdk-github-runner-switch
+
+[Read in English](README.md)
+
+Construct do AWS CDK para quem usa os minutos gratuitos do GitHub Actions. A pipeline roda **nas máquinas do GitHub
+enquanto os minutos gratuitos durarem**. Quando eles acabam, ela **passa sozinha para máquinas EC2 Spot descartáveis
+(Graviton, arm64) na sua conta AWS**. No dia 1º do mês seguinte, volta para o GitHub.
+
+Ninguém precisa lembrar de nada, a pipeline não trava no fim do mês, e você não paga por máquina parada.
+
+## Por que
+
+- **O plano gratuito dá conta da maior parte do mês.** Pagar runner o tempo todo é desperdício, e ver a pipeline
+  travar no dia 25 também.
+- **Runner próprio costuma ficar ligado direto, ou exige muita peça.** Aqui cada job ganha uma máquina nova com um
+  registro de runner de uso único (JIT), e ela é encerrada quando o job termina.
+- **A chave é uma variável do repositório.** O workflow escolhe o runner com uma expressão, sem duplicar workflows
+  nem passo manual.
+
+## Como funciona
+
+| Peça | O que faz |
+|---|---|
+| Webhook (Function URL da Lambda) | Confere a assinatura do GitHub. Cada job na fila que pede o rótulo da AWS ganha uma máquina: primeiro Spot, em cada tipo de máquina × sub-rede, depois sob demanda. |
+| Chave (a cada 30 min) | Lê os minutos do Actions usados no mês e vira `RUNNER` para `aws` no limite (padrão: 1.900 de 2.000). Volta para `github` quando o mês vira. Ao ir para a AWS, refaz as execuções que falharam por falta de minutos. |
+| Reconciliação (a cada 5 min) | Job na fila sem máquina ganha uma. Cobre aviso do GitHub que se perdeu e o teto de máquinas. |
+| Rótulo sob demanda | Jobs com `aws-ondemand` (ex.: deploy) não usam Spot, então uma interrupção nunca corta um deploy no meio. |
+| Imagem | Ubuntu 24.04 arm64 da Canonical com Docker, Node.js, Python, git, GitHub CLI, AWS CLI e o runner. O EC2 Image Builder refaz a imagem todo mês. Dá para incluir imagens de contêiner em cache e comandos extras. |
+| Segurança | Sem porta de entrada, IMDSv2, disco criptografado, desligar = encerrar, limite de 2 horas para job travado. A função só lança, marca e lista máquinas. |
+
+## Começando
+
+```bash
+npm install cdk-github-runner-switch
+```
+
+```ts
+const runners = new GitHubRunnerSwitch(stack, 'Runners', { vpc, repository: 'minha-org/meu-repo' });
+```
+
+Depois, uma vez por conta e repositório:
+
+1. **Papel do Spot** (só se a conta nunca usou Spot):
+   `aws iam create-service-linked-role --aws-service-name spot.amazonaws.com`
+2. **Publique** a stack (`cdk deploy`).
+3. **Gere a primeira imagem** (cerca de 30 min). Depois disso, ela é refeita sozinha:
+   `aws imagebuilder start-image-pipeline-execution --image-pipeline-arn <ImagePipelineArn>`
+4. **Crie o GitHub App e guarde a chave** com [`scripts/setup-github-app.sh <stack>`](scripts/setup-github-app.sh),
+   no seu terminal. A chave vai direto para o Secrets Manager.
+5. **Aponte os workflows para a chave:**
+
+   ```yaml
+   runs-on: ${{ vars.RUNNER == 'aws' && fromJSON('["self-hosted","linux","arm64","aws"]') || 'ubuntu-24.04-arm' }}
+   ```
+
+Para trocar à mão: `gh variable set RUNNER --body aws` (ou `github`).
+
+As opções, os custos, a segurança e as limitações estão no [README em inglês](README.md#configuration).
+
+## Licença
+
+[Apache-2.0](LICENSE)

package/lambda/index.mjs

@@ -0,0 +1,310 @@
+// cdk-github-runner-switch — control function.
+//
+// 1. Webhook `workflow_job` from the GitHub App → one disposable EC2 machine (Spot first) with a single-use (JIT)
+//    runner registration for the queued job.
+// 2. Every few minutes (`reconcile`) → queued jobs that have no machine (lost webhook, cap reached) get one.
+// 3. Every half hour (`check-usage`) → flips the repository variable (default `RUNNER`) between `github` and `aws`
+//    according to the GitHub Actions minutes used this month, and re-runs the runs that failed for lack of minutes.
+//
+// No dependencies: the AWS SDK comes with the Lambda runtime; `fetch` and `crypto` come with Node.
+import crypto from 'node:crypto';
+
+const sdk = {
+  ec2: () => import('@aws-sdk/client-ec2'),
+  secrets: () => import('@aws-sdk/client-secrets-manager'),
+  ssm: () => import('@aws-sdk/client-ssm'),
+};
+const GH = 'https://api.github.com';
+const CAPACITY = /InsufficientInstanceCapacity|SpotMaxPriceTooLow|MaxSpotInstanceCountExceeded|InstanceLimitExceeded|Unsupported/;
+
+/** Settings from the environment (set by the construct). Pure functions take them as a parameter for testing. */
+export function config(env = process.env) {
+  const label = env.LABEL || 'aws';
+  return {
+    label,
+    onDemandLabel: env.ON_DEMAND_LABEL || `${label}-ondemand`,
+    instanceTypes: (env.INSTANCE_TYPES || 'm7g.large,m6g.large,m8g.large').split(',').map((s) => s.trim()).filter(Boolean),
+    thresholdMinutes: Number(env.THRESHOLD_MINUTES || 1900),
+    maxInstances: Number(env.MAX_INSTANCES || 6),
+    switchVariable: env.SWITCH_VARIABLE || 'RUNNER',
+    billing: env.BILLING === 'user' ? 'user' : 'organization',
+    runnerGroupId: Number(env.RUNNER_GROUP_ID || 1),
+    maxJobMinutes: Number(env.MAX_JOB_MINUTES || 120),
+    switchId: env.SWITCH_ID || 'default',
+    repository: env.REPOSITORY || '',
+  };
+}
+
+// ---------------------------------------------------------------- pure rules (unit tested)
+
+/** `X-Hub-Signature-256` header of the webhook (HMAC-SHA256 of the raw body with the shared secret). */
+export function validSignature(secret, body, header) {
+  if (!secret || !header || !header.startsWith('sha256=')) return false;
+  const expected = Buffer.from(`sha256=${crypto.createHmac('sha256', secret).update(body).digest('hex')}`);
+  const got = Buffer.from(header);
+  return got.length === expected.length && crypto.timingSafeEqual(got, expected);
+}
+
+/** A queued job asking for one of our runners? Returns `{ onDemand }` or null. */
+export function runnerRequest(payload, c = config()) {
+  if (payload?.action !== 'queued') return null;
+  const labels = payload.workflow_job?.labels ?? [];
+  if (!labels.includes('self-hosted')) return null;
+  if (labels.includes(c.onDemandLabel)) return { onDemand: true };
+  if (labels.includes(c.label)) return { onDemand: false };
+  return null;
+}
+
+/** New position of the switch, or null to keep it: `aws` at the threshold; `github` when the month resets. */
+export function nextRunner(usedMinutes, current, c = config()) {
+  if (usedMinutes >= c.thresholdMinutes && current !== 'aws') return 'aws';
+  if (usedMinutes < c.thresholdMinutes && current === 'aws') return 'github';
+  return null;
+}
+
+/** GitHub Actions minutes used in the current month (billing usage report; storage is not counted). */
+export function minutesThisMonth(usage, now = new Date()) {
+  const month = now.toISOString().slice(0, 7);
+  return (usage?.usageItems ?? [])
+    .filter((i) => i.product === 'actions' && i.unitType === 'Minutes' && String(i.date).startsWith(month))
+    .reduce((t, i) => t + Number(i.quantity || 0), 0);
+}
+
+/** Launch attempts in order: Spot on every type × subnet, then on-demand. On-demand jobs skip Spot. */
+export function launchPlan(onDemand, subnets, c = config()) {
+  const plan = [];
+  if (!onDemand) for (const type of c.instanceTypes) for (const subnet of subnets) plan.push({ type, subnet, spot: true });
+  for (const type of c.instanceTypes) for (const subnet of subnets) plan.push({ type, subnet, spot: false });
+  return plan;
+}
+
+/**
+ * Reconciliation: machines missing per label. Each machine carries one runner that is booting, idle or busy;
+ * idle = active − busy. Never exceeds the total cap.
+ */
+export function missingRunners({ queued, active, busy }, c = config()) {
+  let room = c.maxInstances - Object.values(active).reduce((t, n) => t + n, 0);
+  const out = {};
+  for (const label of [c.onDemandLabel, c.label]) {
+    const idle = Math.max(0, (active[label] ?? 0) - (busy[label] ?? 0));
+    const need = Math.max(0, Math.min((queued[label] ?? 0) - idle, room));
+    if (need > 0) { out[label] = need; room -= need; }
+  }
+  return out;
+}
+
+/** Boot script: runs exactly one job (JIT) and shuts down — the launch template turns shutdown into terminate. */
+export function userData(jitConfig, c = config()) {
+  if (!/^[A-Za-z0-9+/=]+$/.test(jitConfig)) throw new Error('invalid JIT config');
+  return Buffer.from(`#!/bin/bash
+shutdown -h +${c.maxJobMinutes}
+cd /opt/actions-runner
+sudo -u runner -H ./run.sh --jitconfig '${jitConfig}' > /var/log/actions-runner.log 2>&1 || true
+shutdown -h now
+`).toString('base64');
+}
+
+/** Billing usage endpoint: organization report, or the user report for personal accounts. */
+export function usagePath(repository, billing) {
+  const owner = repository.split('/')[0];
+  return billing === 'user' ? `/users/${owner}/settings/billing/usage` : `/orgs/${owner}/settings/billing/usage`;
+}
+
+// ---------------------------------------------------------------- GitHub App
+
+let secretCache;
+async function secret() {
+  if (secretCache && Date.now() - secretCache.at < 300_000) return secretCache.value;
+  const { SecretsManagerClient, GetSecretValueCommand } = await sdk.secrets();
+  const r = await new SecretsManagerClient({}).send(new GetSecretValueCommand({ SecretId: process.env.SECRET_ID }));
+  secretCache = { at: Date.now(), value: JSON.parse(r.SecretString) };
+  return secretCache.value;
+}
+
+const b64url = (b) => Buffer.from(b).toString('base64url');
+function appJwt(appId, privateKey) {
+  const now = Math.floor(Date.now() / 1000);
+  const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+  const body = b64url(JSON.stringify({ iat: now - 60, exp: now + 540, iss: String(appId) }));
+  const sig = crypto.createSign('RSA-SHA256').update(`${head}.${body}`).sign(privateKey, 'base64url');
+  return `${head}.${body}.${sig}`;
+}
+
+async function gh(path, { token, method = 'GET', body } = {}) {
+  const res = await fetch(`${GH}${path}`, {
+    method,
+    headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json', 'x-github-api-version': '2022-11-28', 'user-agent': 'cdk-github-runner-switch' },
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  const text = await res.text();
+  if (!res.ok && res.status !== 404) throw new Error(`GitHub ${method} ${path} → ${res.status} ${text.slice(0, 200)}`);
+  return { status: res.status, json: text ? JSON.parse(text) : null };
+}
+
+async function installationToken(c) {
+  const s = await secret();
+  if (!s.appId || !s.privateKey) throw new Error('GitHub App not configured in the secret (appId, privateKey)');
+  const jwt = appJwt(s.appId, s.privateKey);
+  const inst = await gh(`/repos/${c.repository}/installation`, { token: jwt });
+  if (inst.status === 404) throw new Error(`GitHub App is not installed on ${c.repository}`);
+  const t = await gh(`/app/installations/${inst.json.id}/access_tokens`, { token: jwt, method: 'POST' });
+  return t.json.token;
+}
+
+// ---------------------------------------------------------------- AWS
+
+let ec2Client;
+async function ec2() {
+  const m = await sdk.ec2();
+  ec2Client ??= new m.EC2Client({});
+  return { client: ec2Client, ...m };
+}
+
+async function activeByLabel(c) {
+  const { client, DescribeInstancesCommand } = await ec2();
+  const r = await client.send(new DescribeInstancesCommand({
+    Filters: [{ Name: 'tag:runner-switch', Values: [c.switchId] }, { Name: 'instance-state-name', Values: ['pending', 'running'] }],
+  }));
+  const out = {};
+  for (const i of (r.Reservations ?? []).flatMap((x) => x.Instances ?? [])) {
+    const label = i.Tags?.find((t) => t.Key === 'runner-label')?.Value ?? c.label;
+    out[label] = (out[label] ?? 0) + 1;
+  }
+  return out;
+}
+
+async function launch(c, jobId, onDemand, jit) {
+  const { SSMClient, GetParameterCommand } = await sdk.ssm();
+  const ami = (await new SSMClient({}).send(new GetParameterCommand({ Name: process.env.AMI_PARAMETER }))).Parameter.Value;
+  const { client, RunInstancesCommand } = await ec2();
+  const label = onDemand ? c.onDemandLabel : c.label;
+  let last;
+  for (const p of launchPlan(onDemand, process.env.SUBNET_IDS.split(','), c)) {
+    try {
+      const r = await client.send(new RunInstancesCommand({
+        MinCount: 1, MaxCount: 1, ImageId: ami, InstanceType: p.type,
+        LaunchTemplate: { LaunchTemplateId: process.env.LAUNCH_TEMPLATE_ID, Version: '$Latest' },
+        NetworkInterfaces: [{ DeviceIndex: 0, SubnetId: p.subnet, Groups: [process.env.SECURITY_GROUP_ID], AssociatePublicIpAddress: true, DeleteOnTermination: true }],
+        UserData: userData(jit, c),
+        ...(p.spot ? { InstanceMarketOptions: { MarketType: 'spot', SpotOptions: { SpotInstanceType: 'one-time', InstanceInterruptionBehavior: 'terminate' } } } : {}),
+        TagSpecifications: [{
+          ResourceType: 'instance',
+          Tags: [
+            { Key: 'Name', Value: `github-runner-${c.switchId}` }, { Key: 'runner-switch', Value: c.switchId }, { Key: 'github-job', Value: String(jobId) },
+            { Key: 'market', Value: p.spot ? 'spot' : 'on-demand' }, { Key: 'runner-label', Value: label },
+          ],
+        }],
+      }));
+      const id = r.Instances?.[0]?.InstanceId;
+      console.log(JSON.stringify({ launched: id, job: jobId, ...p }));
+      return id;
+    } catch (e) {
+      last = e;
+      if (!CAPACITY.test(`${e.name} ${e.message}`)) throw e;
+      console.log(JSON.stringify({ unavailable: p, reason: e.name }));
+    }
+  }
+  throw last ?? new Error('no capacity');
+}
+
+async function launchFor(c, token, jobId, onDemand) {
+  const jit = await gh(`/repos/${c.repository}/actions/runners/generate-jitconfig`, {
+    token, method: 'POST',
+    body: {
+      name: `aws-${jobId}-${Date.now().toString(36)}`, runner_group_id: c.runnerGroupId, work_folder: '_work',
+      labels: ['self-hosted', 'linux', 'arm64', onDemand ? c.onDemandLabel : c.label],
+    },
+  });
+  return launch(c, jobId, onDemand, jit.json.encoded_jit_config);
+}
+
+// ---------------------------------------------------------------- tasks
+
+async function onWebhook(event, c) {
+  const raw = event.isBase64Encoded ? Buffer.from(event.body ?? '', 'base64').toString('utf8') : event.body ?? '';
+  const headers = Object.fromEntries(Object.entries(event.headers ?? {}).map(([k, v]) => [k.toLowerCase(), v]));
+  if (!validSignature((await secret()).webhookSecret, raw, headers['x-hub-signature-256'])) return { statusCode: 401, body: 'invalid signature' };
+  if (headers['x-github-event'] !== 'workflow_job') return { statusCode: 204 };
+  const payload = JSON.parse(raw);
+  const req = runnerRequest(payload, c);
+  if (!req) return { statusCode: 204 };
+  const active = Object.values(await activeByLabel(c)).reduce((t, n) => t + n, 0);
+  if (active >= c.maxInstances) {
+    // The reconciliation launches it as soon as there is room.
+    console.log(JSON.stringify({ capped: payload.workflow_job.id }));
+    return { statusCode: 202, body: 'cap reached; will be reconciled' };
+  }
+  const id = await launchFor(c, await installationToken(c), payload.workflow_job.id, req.onDemand);
+  return { statusCode: 201, body: id };
+}
+
+/** Queued jobs without a machine (lost webhook or cap reached) get one. */
+export async function reconcile(c = config()) {
+  const token = await installationToken(c);
+  const queued = {};
+  for (const status of ['queued', 'in_progress']) {
+    const runs = await gh(`/repos/${c.repository}/actions/runs?status=${status}&per_page=50`, { token });
+    for (const run of runs.json?.workflow_runs ?? []) {
+      const jobs = await gh(`/repos/${c.repository}/actions/runs/${run.id}/jobs?per_page=100`, { token });
+      for (const j of jobs.json?.jobs ?? []) {
+        if (j.status !== 'queued') continue;
+        const req = runnerRequest({ action: 'queued', workflow_job: j }, c);
+        if (req) { const l = req.onDemand ? c.onDemandLabel : c.label; queued[l] = (queued[l] ?? 0) + 1; }
+      }
+    }
+  }
+  const runners = await gh(`/repos/${c.repository}/actions/runners?per_page=100`, { token });
+  const busy = {};
+  for (const r of runners.json?.runners ?? []) {
+    if (!r.busy) continue;
+    const names = (r.labels ?? []).map((x) => x.name);
+    const l = names.includes(c.onDemandLabel) ? c.onDemandLabel : names.includes(c.label) ? c.label : null;
+    if (l) busy[l] = (busy[l] ?? 0) + 1;
+  }
+  const active = await activeByLabel(c);
+  const missing = missingRunners({ queued, active, busy }, c);
+  console.log(JSON.stringify({ reconcile: { queued, active, busy, missing } }));
+  for (const [label, n] of Object.entries(missing)) {
+    for (let k = 0; k < n; k++) await launchFor(c, token, `reconcile-${Date.now().toString(36)}`, label === c.onDemandLabel);
+  }
+  return missing;
+}
+
+/** Checks the minutes used and flips the switch; when moving to AWS, re-runs the runs blocked for lack of minutes. */
+export async function checkUsage(c = config(), now = new Date()) {
+  const token = await installationToken(c);
+  const s = await secret();
+  // Personal accounts: the user billing report needs a fine-grained token with "Plan: read" (`billingToken`).
+  const usage = await gh(usagePath(c.repository, c.billing), { token: s.billingToken || token });
+  const used = minutesThisMonth(usage.json, now);
+  const v = await gh(`/repos/${c.repository}/actions/variables/${c.switchVariable}`, { token });
+  const current = v.status === 404 ? 'github' : v.json.value;
+  const next = nextRunner(used, current, c);
+  console.log(JSON.stringify({ usedMinutes: used, current, next }));
+  if (!next) return { used, runner: current };
+  if (v.status === 404) await gh(`/repos/${c.repository}/actions/variables`, { token, method: 'POST', body: { name: c.switchVariable, value: next } });
+  else await gh(`/repos/${c.repository}/actions/variables/${c.switchVariable}`, { token, method: 'PATCH', body: { name: c.switchVariable, value: next } });
+  if (next === 'aws') {
+    const since = new Date(now.getTime() - 6 * 3600_000).toISOString();
+    const runs = await gh(`/repos/${c.repository}/actions/runs?status=failure&created=>=${since}&per_page=50`, { token });
+    for (const run of runs.json?.workflow_runs ?? []) {
+      const jobs = await gh(`/repos/${c.repository}/actions/runs/${run.id}/jobs`, { token });
+      // Without minutes GitHub does not even start the job: it fails with no step executed.
+      const blocked = (jobs.json?.jobs ?? []).some((j) => j.conclusion === 'failure' && (j.steps ?? []).length === 0);
+      if (blocked) await gh(`/repos/${c.repository}/actions/runs/${run.id}/rerun-failed-jobs`, { token, method: 'POST' }).catch((e) => console.log(e.message));
+    }
+  }
+  return { used, runner: next };
+}
+
+export async function handler(event) {
+  const c = config();
+  if (event?.task === 'check-usage') return checkUsage(c);
+  if (event?.task === 'reconcile') return reconcile(c);
+  try {
+    return await onWebhook(event, c);
+  } catch (e) {
+    console.error(e);
+    return { statusCode: 500, body: 'error' };
+  }
+}

package/lib/index.d.ts

@@ -0,0 +1 @@
+export * from './runner-switch';

package/lib/index.js

@@ -0,0 +1,17 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./runner-switch"), exports);

package/lib/runner-switch.d.ts

@@ -0,0 +1,83 @@
+import { Duration } from 'aws-cdk-lib';
+import * as ec2 from 'aws-cdk-lib/aws-ec2';
+import * as lambda from 'aws-cdk-lib/aws-lambda';
+import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
+import { Construct } from 'constructs';
+/** Where the GitHub Actions minutes are counted. */
+export declare enum BillingScope {
+    /** Organization billing report (`/orgs/{org}/settings/billing/usage`), read with the GitHub App token. */
+    ORGANIZATION = "organization",
+    /** Personal account billing report; needs a fine-grained token with "Plan: read" stored as `billingToken`. */
+    USER = "user"
+}
+export interface GitHubRunnerSwitchProps {
+    /** VPC for the runner machines. They need outbound internet access; by default they use public subnets (no NAT). */
+    readonly vpc: ec2.IVpc;
+    /** @default - public subnets */
+    readonly subnets?: ec2.SubnetSelection;
+    /** Repository served by the runners, as `owner/name`. */
+    readonly repository: string;
+    /** @default BillingScope.ORGANIZATION */
+    readonly billing?: BillingScope;
+    /** Label of the Spot runners (`runs-on: [self-hosted, linux, arm64, <label>]`). @default 'aws' */
+    readonly label?: string;
+    /** Label of the on-demand runners (e.g. deploy jobs that must not be interrupted). @default `${label}-ondemand` */
+    readonly onDemandLabel?: string;
+    /** Graviton (arm64) instance types, in order of preference. @default ['m7g.large', 'm6g.large', 'm8g.large'] */
+    readonly instanceTypes?: string[];
+    /** Minutes used this month at which the switch moves to AWS. @default 1900 (free plan: 2,000) */
+    readonly thresholdMinutes?: number;
+    /** Maximum machines at the same time. @default 6 */
+    readonly maxInstances?: number;
+    /** Repository variable flipped between `github` and `aws`. @default 'RUNNER' */
+    readonly switchVariable?: string;
+    /** Runner group of the JIT registrations. @default 1 (Default) */
+    readonly runnerGroupId?: number;
+    /** Safety net: the machine shuts down after this long even if the job hangs. @default Duration.hours(2) */
+    readonly maxJobDuration?: Duration;
+    /** Root disk in GiB. @default 40 */
+    readonly rootVolumeSize?: number;
+    /** Node.js major version installed in the image. @default 24 */
+    readonly nodeMajorVersion?: number;
+    /** Container images pulled into the image ahead of time (faster `services:`). @default [] */
+    readonly cachedImages?: string[];
+    /** Extra shell commands run as root while building the image (e.g. `npx -y playwright install-deps chromium`). @default [] */
+    readonly extraImageCommands?: string[];
+    /** When the image is rebuilt (EventBridge cron, UTC). @default 'cron(0 5 1 * ? *)' — monthly, day 1 at 05:00 */
+    readonly imageSchedule?: string;
+    /** @default Duration.minutes(5) */
+    readonly reconcileInterval?: Duration;
+    /** @default Duration.minutes(30) */
+    readonly usageCheckInterval?: Duration;
+}
+/**
+ * GitHub Actions runners that switch between GitHub-hosted (free minutes) and disposable EC2 Spot machines on AWS when
+ * the monthly minutes run out, and back when the month resets.
+ *
+ * - A GitHub App sends `workflow_job` webhooks to a Lambda Function URL; each queued job gets its own machine with a
+ *   single-use (JIT) runner registration. The machine terminates when the job ends.
+ * - The Lambda flips a repository variable (`RUNNER`) by the minutes used; workflows pick the runner with
+ *   `runs-on: ${{ vars.RUNNER == 'aws' && fromJSON('["self-hosted","linux","arm64","aws"]') || 'ubuntu-24.04-arm' }}`.
+ * - An EC2 Image Builder pipeline rebuilds the Ubuntu 24.04 arm64 image on a schedule.
+ */
+export declare class GitHubRunnerSwitch extends Construct {
+    /** URL to configure as the GitHub App webhook. */
+    readonly webhookUrl: string;
+    /** Secret holding `webhookSecret` (generated), `appId` and `privateKey` (filled by the setup script). */
+    readonly secret: secretsmanager.ISecret;
+    /** SSM parameter with the current runner AMI (written by Image Builder). */
+    readonly amiParameterName: string;
+    /** Image Builder pipeline: run it once after the first deploy. */
+    readonly imagePipelineArn: string;
+    /** The control function (webhook, reconciliation and usage check). */
+    readonly function: lambda.IFunction;
+    /** Security group of the runner machines (no inbound rules). */
+    readonly securityGroup: ec2.ISecurityGroup;
+    constructor(scope: Construct, id: string, props: GitHubRunnerSwitchProps);
+}
+/** Image Builder component (YAML). Step names: letters, digits, `-` and `_` only. */
+export declare function runnerComponent(o: {
+    nodeMajorVersion: number;
+    cachedImages: string[];
+    extraCommands: string[];
+}): string;

package/lib/runner-switch.js

@@ -0,0 +1,257 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitHubRunnerSwitch = exports.BillingScope = void 0;
+exports.runnerComponent = runnerComponent;
+const crypto = __importStar(require("crypto"));
+const path = __importStar(require("path"));
+const aws_cdk_lib_1 = require("aws-cdk-lib");
+const ec2 = __importStar(require("aws-cdk-lib/aws-ec2"));
+const events = __importStar(require("aws-cdk-lib/aws-events"));
+const targets = __importStar(require("aws-cdk-lib/aws-events-targets"));
+const iam = __importStar(require("aws-cdk-lib/aws-iam"));
+const imagebuilder = __importStar(require("aws-cdk-lib/aws-imagebuilder"));
+const lambda = __importStar(require("aws-cdk-lib/aws-lambda"));
+const logs = __importStar(require("aws-cdk-lib/aws-logs"));
+const secretsmanager = __importStar(require("aws-cdk-lib/aws-secretsmanager"));
+const constructs_1 = require("constructs");
+/** Where the GitHub Actions minutes are counted. */
+var BillingScope;
+(function (BillingScope) {
+    /** Organization billing report (`/orgs/{org}/settings/billing/usage`), read with the GitHub App token. */
+    BillingScope["ORGANIZATION"] = "organization";
+    /** Personal account billing report; needs a fine-grained token with "Plan: read" stored as `billingToken`. */
+    BillingScope["USER"] = "user";
+})(BillingScope || (exports.BillingScope = BillingScope = {}));
+/**
+ * GitHub Actions runners that switch between GitHub-hosted (free minutes) and disposable EC2 Spot machines on AWS when
+ * the monthly minutes run out, and back when the month resets.
+ *
+ * - A GitHub App sends `workflow_job` webhooks to a Lambda Function URL; each queued job gets its own machine with a
+ *   single-use (JIT) runner registration. The machine terminates when the job ends.
+ * - The Lambda flips a repository variable (`RUNNER`) by the minutes used; workflows pick the runner with
+ *   `runs-on: ${{ vars.RUNNER == 'aws' && fromJSON('["self-hosted","linux","arm64","aws"]') || 'ubuntu-24.04-arm' }}`.
+ * - An EC2 Image Builder pipeline rebuilds the Ubuntu 24.04 arm64 image on a schedule.
+ */
+class GitHubRunnerSwitch extends constructs_1.Construct {
+    /** URL to configure as the GitHub App webhook. */
+    webhookUrl;
+    /** Secret holding `webhookSecret` (generated), `appId` and `privateKey` (filled by the setup script). */
+    secret;
+    /** SSM parameter with the current runner AMI (written by Image Builder). */
+    amiParameterName;
+    /** Image Builder pipeline: run it once after the first deploy. */
+    imagePipelineArn;
+    /** The control function (webhook, reconciliation and usage check). */
+    function;
+    /** Security group of the runner machines (no inbound rules). */
+    securityGroup;
+    constructor(scope, id, props) {
+        super(scope, id);
+        if (!/^[\w.-]+\/[\w.-]+$/.test(props.repository))
+            throw new Error(`repository must be "owner/name", got "${props.repository}"`);
+        const name = aws_cdk_lib_1.Names.uniqueResourceName(this, { maxLength: 48, separator: '-' }).toLowerCase();
+        const label = props.label ?? 'aws';
+        const onDemandLabel = props.onDemandLabel ?? `${label}-ondemand`;
+        const instanceTypes = props.instanceTypes ?? ['m7g.large', 'm6g.large', 'm8g.large'];
+        if (!instanceTypes.length)
+            throw new Error('instanceTypes must not be empty');
+        const rootVolumeSize = props.rootVolumeSize ?? 40;
+        // Image Builder can only write SSM parameters under /imagebuilder/ (its service role).
+        this.amiParameterName = `/imagebuilder/${name}/ami`;
+        const subnets = props.vpc.selectSubnets(props.subnets ?? { subnetType: ec2.SubnetType.PUBLIC });
+        // Runner machine: no inbound port, outbound only.
+        const sg = new ec2.SecurityGroup(this, 'RunnerSecurityGroup', { vpc: props.vpc, description: 'GitHub runners: no inbound', allowAllOutbound: true });
+        this.securityGroup = sg;
+        const instanceRole = new iam.Role(this, 'RunnerRole', {
+            assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),
+            description: 'GitHub runner machine: Session Manager access only (jobs use their own OIDC role)',
+            managedPolicies: [iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonSSMManagedInstanceCore')],
+        });
+        const template = new ec2.LaunchTemplate(this, 'RunnerTemplate', {
+            role: instanceRole,
+            instanceInitiatedShutdownBehavior: ec2.InstanceInitiatedShutdownBehavior.TERMINATE,
+            requireImdsv2: true,
+            blockDevices: [{
+                    deviceName: '/dev/sda1',
+                    volume: ec2.BlockDeviceVolume.ebs(rootVolumeSize, { volumeType: ec2.EbsDeviceVolumeType.GP3, encrypted: true, deleteOnTermination: true }),
+                }],
+        });
+        // Image: Canonical Ubuntu 24.04 arm64 + runner tooling. Components are immutable, so the version follows the content.
+        const componentData = runnerComponent({
+            nodeMajorVersion: props.nodeMajorVersion ?? 24, cachedImages: props.cachedImages ?? [], extraCommands: props.extraImageCommands ?? [],
+        });
+        const version = `1.0.${parseInt(crypto.createHash('sha256').update(componentData).digest('hex').slice(0, 7), 16) % 1_000_000}`;
+        const builderRole = new iam.Role(this, 'ImageBuilderRole', {
+            assumedBy: new iam.ServicePrincipal('ec2.amazonaws.com'),
+            managedPolicies: [
+                iam.ManagedPolicy.fromAwsManagedPolicyName('AmazonSSMManagedInstanceCore'),
+                iam.ManagedPolicy.fromAwsManagedPolicyName('EC2InstanceProfileForImageBuilder'),
+            ],
+        });
+        const builderProfile = new iam.CfnInstanceProfile(this, 'ImageBuilderProfile', { roles: [builderRole.roleName] });
+        const component = new imagebuilder.CfnComponent(this, 'RunnerComponent', { name, platform: 'Linux', version, data: componentData });
+        const recipe = new imagebuilder.CfnImageRecipe(this, 'RunnerRecipe', {
+            name, version,
+            parentImage: 'ssm:/aws/service/canonical/ubuntu/server/24.04/stable/current/arm64/hvm/ebs-gp3/ami-id',
+            components: [{ componentArn: component.attrArn }],
+            blockDeviceMappings: [{ deviceName: '/dev/sda1', ebs: { volumeSize: rootVolumeSize, volumeType: 'gp3', deleteOnTermination: true } }],
+        });
+        const infra = new imagebuilder.CfnInfrastructureConfiguration(this, 'RunnerBuildInfrastructure', {
+            name, instanceProfileName: builderProfile.ref, instanceTypes: instanceTypes.slice(0, 2),
+            subnetId: subnets.subnetIds[0], securityGroupIds: [sg.securityGroupId], terminateInstanceOnFailure: true,
+        });
+        const distribution = new imagebuilder.CfnDistributionConfiguration(this, 'RunnerDistribution', {
+            name,
+            distributions: [{
+                    region: aws_cdk_lib_1.Stack.of(this).region,
+                    amiDistributionConfiguration: { Name: `${name}-{{ imagebuilder:buildDate }}` },
+                    ssmParameterConfigurations: [{ parameterName: this.amiParameterName, dataType: 'aws:ec2:image' }],
+                }],
+        });
+        const pipeline = new imagebuilder.CfnImagePipeline(this, 'RunnerImagePipeline', {
+            name,
+            imageRecipeArn: recipe.attrArn, infrastructureConfigurationArn: infra.attrArn, distributionConfigurationArn: distribution.attrArn,
+            schedule: { scheduleExpression: props.imageSchedule ?? 'cron(0 5 1 * ? *)', pipelineExecutionStartCondition: 'EXPRESSION_MATCH_ONLY' },
+            imageTestsConfiguration: { imageTestsEnabled: false },
+        });
+        this.imagePipelineArn = pipeline.attrArn;
+        // GitHub App credentials: the webhook secret is generated here; the setup script adds appId and privateKey.
+        const secret = new secretsmanager.Secret(this, 'AppSecret', {
+            description: `GitHub App of the runners for ${props.repository} (cdk-github-runner-switch)`,
+            generateSecretString: {
+                secretStringTemplate: JSON.stringify({ appId: '', privateKey: '' }),
+                generateStringKey: 'webhookSecret', excludePunctuation: true, passwordLength: 40,
+            },
+        });
+        this.secret = secret;
+        const fn = new lambda.Function(this, 'Control', {
+            runtime: lambda.Runtime.NODEJS_22_X,
+            architecture: lambda.Architecture.ARM_64,
+            handler: 'index.handler',
+            code: lambda.Code.fromAsset(path.join(__dirname, '..', 'lambda')),
+            timeout: aws_cdk_lib_1.Duration.seconds(60),
+            memorySize: 256,
+            logGroup: new logs.LogGroup(this, 'ControlLogs', { retention: logs.RetentionDays.ONE_MONTH, removalPolicy: aws_cdk_lib_1.RemovalPolicy.DESTROY }),
+            description: `GitHub runner switch for ${props.repository}: webhook, reconciliation and minutes check`,
+            environment: {
+                SECRET_ID: secret.secretArn,
+                REPOSITORY: props.repository,
+                BILLING: props.billing ?? BillingScope.ORGANIZATION,
+                LABEL: label,
+                ON_DEMAND_LABEL: onDemandLabel,
+                INSTANCE_TYPES: instanceTypes.join(','),
+                THRESHOLD_MINUTES: String(props.thresholdMinutes ?? 1900),
+                MAX_INSTANCES: String(props.maxInstances ?? 6),
+                SWITCH_VARIABLE: props.switchVariable ?? 'RUNNER',
+                RUNNER_GROUP_ID: String(props.runnerGroupId ?? 1),
+                MAX_JOB_MINUTES: String((props.maxJobDuration ?? aws_cdk_lib_1.Duration.hours(2)).toMinutes()),
+                SWITCH_ID: name,
+                AMI_PARAMETER: this.amiParameterName,
+                LAUNCH_TEMPLATE_ID: template.launchTemplateId,
+                SECURITY_GROUP_ID: sg.securityGroupId,
+                SUBNET_IDS: subnets.subnetIds.join(','),
+            },
+        });
+        this.function = fn;
+        secret.grantRead(fn);
+        const { region, account } = aws_cdk_lib_1.Stack.of(this);
+        fn.addToRolePolicy(new iam.PolicyStatement({ actions: ['ssm:GetParameter'], resources: [`arn:aws:ssm:${region}:${account}:parameter${this.amiParameterName}`] }));
+        fn.addToRolePolicy(new iam.PolicyStatement({ actions: ['ec2:RunInstances', 'ec2:CreateTags', 'ec2:DescribeInstances'], resources: ['*'] }));
+        fn.addToRolePolicy(new iam.PolicyStatement({ actions: ['iam:PassRole'], resources: [instanceRole.roleArn] }));
+        this.webhookUrl = fn.addFunctionUrl({ authType: lambda.FunctionUrlAuthType.NONE }).url;
+        new events.Rule(this, 'UsageCheck', {
+            schedule: events.Schedule.rate(props.usageCheckInterval ?? aws_cdk_lib_1.Duration.minutes(30)),
+            targets: [new targets.LambdaFunction(fn, { event: events.RuleTargetInput.fromObject({ task: 'check-usage' }), retryAttempts: 1 })],
+        });
+        new events.Rule(this, 'Reconcile', {
+            schedule: events.Schedule.rate(props.reconcileInterval ?? aws_cdk_lib_1.Duration.minutes(5)),
+            targets: [new targets.LambdaFunction(fn, { event: events.RuleTargetInput.fromObject({ task: 'reconcile' }), retryAttempts: 0 })],
+        });
+    }
+}
+exports.GitHubRunnerSwitch = GitHubRunnerSwitch;
+/** Image Builder component (YAML). Step names: letters, digits, `-` and `_` only. */
+function runnerComponent(o) {
+    const list = (cmds) => cmds.map((c) => `            - ${JSON.stringify(c)}`).join('\n');
+    const steps = [`      - name: Packages
+        action: ExecuteBash
+        inputs:
+          commands:
+${list([
+            'export DEBIAN_FRONTEND=noninteractive',
+            'apt-get update',
+            'apt-get install -y ca-certificates curl git jq unzip zip build-essential python3 python3-pip docker.io',
+            'systemctl enable docker',
+            `curl -fsSL https://deb.nodesource.com/setup_${o.nodeMajorVersion}.x | bash -`,
+            'apt-get install -y nodejs',
+            'curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg -o /usr/share/keyrings/githubcli-archive-keyring.gpg',
+            'echo "deb [arch=arm64 signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" > /etc/apt/sources.list.d/github-cli.list',
+            'apt-get update && apt-get install -y gh',
+            'curl -fsSL https://awscli.amazonaws.com/awscli-exe-linux-aarch64.zip -o /tmp/awscli.zip && unzip -q /tmp/awscli.zip -d /tmp && /tmp/aws/install && rm -rf /tmp/aws /tmp/awscli.zip',
+        ])}`, `      - name: Runner
+        action: ExecuteBash
+        inputs:
+          commands:
+${list([
+            'id runner || useradd -m -s /bin/bash runner',
+            'usermod -aG docker runner',
+            'echo "runner ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/runner && chmod 440 /etc/sudoers.d/runner',
+            'V=$(curl -fsSL https://api.github.com/repos/actions/runner/releases/latest | jq -r .tag_name | sed "s/^v//")',
+            'mkdir -p /opt/actions-runner && cd /opt/actions-runner && curl -fsSL "https://github.com/actions/runner/releases/download/v$V/actions-runner-linux-arm64-$V.tar.gz" | tar xz',
+            '/opt/actions-runner/bin/installdependencies.sh',
+            'chown -R runner:runner /opt/actions-runner',
+        ])}`];
+    if (o.cachedImages.length)
+        steps.push(`      - name: CachedImages
+        action: ExecuteBash
+        inputs:
+          commands:
+${list(o.cachedImages.map((i) => `docker pull ${i}`))}`);
+    if (o.extraCommands.length)
+        steps.push(`      - name: Extra
+        action: ExecuteBash
+        inputs:
+          commands:
+${list(o.extraCommands)}`);
+    return `name: github-runner
+description: GitHub Actions runner (cdk-github-runner-switch)
+schemaVersion: 1.0
+phases:
+  - name: build
+    steps:
+${steps.join('\n')}
+`;
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "cdk-github-runner-switch",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "AWS CDK construct: GitHub Actions runners that switch from GitHub-hosted free minutes to disposable EC2 Spot (Graviton) machines when the monthly minutes run out — and back when the month resets.",
+  "license": "Apache-2.0",
+  "author": "uarch-solutions",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/uarch-solutions/cdk-github-runner-switch.git"
+  },
+  "homepage": "https://github.com/uarch-solutions/cdk-github-runner-switch#readme",
+  "bugs": {
+    "url": "https://github.com/uarch-solutions/cdk-github-runner-switch/issues"
+  },
+  "keywords": [
+    "aws-cdk",
+    "cdk",
+    "construct",
+    "github-actions",
+    "self-hosted-runner",
+    "github-runner",
+    "ec2-spot",
+    "graviton",
+    "arm64",
+    "ci",
+    "cost-optimization"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "files": [
+    "lib",
+    "lambda",
+    "scripts",
+    "README.md",
+    "README.pt-BR.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.180.0",
+    "constructs": "^10.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "aws-cdk-lib": "^2.271.0",
+    "constructs": "^10.4.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.2.0"
+  }
+}

package/scripts/setup-github-app.sh

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+# Connects the GitHub App to a deployed GitHubRunnerSwitch without the private key going through chat, shell history
+# or git. Run it in your own terminal, with AWS credentials for the account of the stack.
+#
+#   scripts/setup-github-app.sh <stack-name> [region]
+#
+# The stack must export the construct values as outputs named WebhookUrl and SecretArn (see examples/app.ts).
+set -euo pipefail
+STACK="${1:?usage: setup-github-app.sh <stack-name> [region]}"
+REGION="${2:-${AWS_REGION:-${AWS_DEFAULT_REGION:-}}}"
+[ -n "$REGION" ] || { echo "Set the region (second argument or AWS_REGION)." >&2; exit 2; }
+export AWS_REGION="$REGION" AWS_DEFAULT_REGION="$REGION"
+out() { aws cloudformation describe-stacks --stack-name "$STACK" --query "Stacks[0].Outputs[?OutputKey=='$1'].OutputValue" --output text; }
+URL="$(out WebhookUrl)"; SECRET="$(out SecretArn)"
+[ -n "$URL" ] && [ "$URL" != None ] && [ -n "$SECRET" ] && [ "$SECRET" != None ] || { echo "Outputs WebhookUrl/SecretArn not found in $STACK." >&2; exit 2; }
+CURRENT="$(aws secretsmanager get-secret-value --secret-id "$SECRET" --query SecretString --output text)"
+WEBHOOK_SECRET="$(printf '%s' "$CURRENT" | python3 -c 'import json,sys; print(json.load(sys.stdin)["webhookSecret"])')"
+
+cat <<MSG
+
+1) Create a GitHub App (organization: Settings → Developer settings → GitHub Apps → New GitHub App)
+   - Webhook: active · URL: $URL
+     Webhook secret: $WEBHOOK_SECRET
+   - Repository permissions: Administration (read & write), Actions (read & write), Variables (read & write), Metadata (read)
+   - Organization permissions: Administration (read)   ← billing usage report
+   - Subscribe to events: Workflow job · Where can it be installed: Only on this account
+2) Generate a private key (.pem) and install the App on the repository only.
+
+MSG
+read -rp "App ID: " APP_ID
+read -rp "Path to the downloaded .pem: " PEM
+read -rp "Personal account only — fine-grained token with 'Plan: read' (leave empty for organizations): " -s BILLING_TOKEN; echo
+[[ "$APP_ID" =~ ^[0-9]+$ ]] && [ -f "$PEM" ] || { echo "Invalid App ID or file; nothing changed." >&2; exit 2; }
+
+TMP="$(mktemp)"; trap 'shred -u "$TMP" 2>/dev/null || rm -f "$TMP"' EXIT
+APP_ID="$APP_ID" PEM="$PEM" BILLING_TOKEN="$BILLING_TOKEN" CURRENT="$CURRENT" python3 -c '
+import json, os
+s = json.loads(os.environ["CURRENT"])
+s.update(appId=os.environ["APP_ID"], privateKey=open(os.environ["PEM"]).read())
+if os.environ["BILLING_TOKEN"]: s["billingToken"] = os.environ["BILLING_TOKEN"]
+print(json.dumps(s))' > "$TMP"
+aws secretsmanager put-secret-value --secret-id "$SECRET" --secret-string "file://$TMP" --query VersionId --output text >/dev/null
+echo "Done: the function picks it up within 5 minutes. You can delete the .pem ($PEM)."