Understand / AWS runner guide
GitHub Actions runners on AWS, without Kubernetes
Gondola runs its controller on ECS Fargate and your GitHub Actions jobs on disposable EC2 instances. You do not need a Kubernetes cluster. You do need a team willing to own the AWS network, runner images, access policy, costs, and operational response.
This guide is for an initial architecture decision. Use the architecture reference for component details and the guided install when you are ready to review a deployment plan.
Is this the right operating model?
| Your requirement | What it means with Gondola |
|---|---|
| Builds in your AWS account | You choose the VPC, subnets, AMI, instance types, and runner IAM policy. |
| No Kubernetes dependency | ECS Fargate hosts the controller; EC2 hosts jobs. You still operate an AWS deployment. |
| A fresh machine for each job | One-job runners avoid carrying a previous job’s local workspace forward. Shared services and remote caches need separate controls. |
| No infrastructure ownership | This is not that model. Gondola supplies installed software, not hosted runner capacity. |
| Other operating systems or clouds | The current scope is GitHub.com and Linux x64/ARM64 in AWS. Windows, macOS, other clouds, and GitHub Enterprise Server are not supported. |
What runs where?
- GitHub holds the job queue. A workflow selects a configured fleet through its
runs-onlabel. - Your ECS controller receives assignments. It long-polls GitHub over outbound HTTPS. A DynamoDB lease coordinates one active listener; the default second controller is a standby, not a second active scheduler.
- Your EC2 runner executes the job. Gondola resolves the label to a reviewed fleet and supplies a short-lived just-in-time runner configuration. The instance is retired after its job, with reconciliation and a hard lifetime limit as additional cleanup paths.
The versioned Terraform/OpenTofu module describes the infrastructure. The controller is a proprietary, digest-pinned container. Its entitlement signature is verified locally; a vendor licensing request is not part of job scheduling. Renewal still requires an updated signed token and the documented operator renewal procedure.
AWS describes ECS task definitions and capacity; Gondola’s component and trust-boundary map explains how this deployment uses them. The software opens no inbound internet listener, but it is not an offline build environment: GitHub, AWS APIs, image registries, and workflow dependencies need appropriate outbound connectivity.
The trade-offs to evaluate
Scale-to-zero is not a zero-cost control plane
Setting a fleet’s min_runners to zero removes its deliberate idle EC2 capacity. Controller tasks, coordination, secrets, logs, and your network can still incur charges. Warm runners trade idle EC2/EBS cost for avoiding some provisioning delay. They are unused one-job machines, not reused workspaces. Start with the AWS cost model, including software cost and operator time, before making a savings claim.
A fresh instance does not mean every cache is cold
An AMI can contain tools or dependencies; a workflow can restore remote caches. Record capacity state separately from package, compiler, test, and Docker cache state. Compare the same application revision and workload. Measure waiting, execution, and cleanup separately, and keep failures and retries in the record. A tiny successful build establishes compatibility, not representative performance.
Spot capacity needs an interruption plan
Fleets can use On-Demand, Spot, or configured Spot-to-On-Demand fallback. Fallback handles supported launch-capacity failures; it does not promise that a job already running on Spot will finish or be resumed. Establish the first working baseline on On-Demand, then evaluate interruption and retry behavior for suitable workloads. Review fleet policy and the operations runbook together.
Disposable compute still needs security and diagnostics
Job code can use the credentials and network reach available to that job. Ephemeral runners do not make untrusted code safe. Start with a private, non-critical repository, restrict runner access, minimize permissions, and review workflow triggers and third-party Actions. GitHub’s self-hosted runner security guidance covers this boundary; Gondola’s security overview defines its product-specific controls and limits.
Gondola’s current runner diagnostics are not automatically exported durably before termination. Controller logs are not a substitute for the runner’s diagnostic files. GitHub recommends preserving ephemeral runner logs externally before production use. Resolve this operational gap for your workload; see logging and diagnostics.
A bounded first evaluation
- Write down the boundary. Choose an isolated pilot scope, one AWS account and region, an existing VPC with reviewed egress, one private repository, a spend cap, and a cleanup owner. Review the release evidence and its limits.
- Prepare access and a reviewed plan. Follow Install on AWS for the GitHub App, AWS secrets, runner image, exact versions, and Terraform/OpenTofu configuration. Keep credentials out of source and support requests.
- Run one real build. Use the Node, Go, or Docker workflow recipe with your configured label and compatible image. Check the output, GitHub job result, runner deregistration, and final EC2 termination.
- Test how you will recover. In the same approved scope, qualify a failed job, cancellation, renewal, and a rollback. A successful build alone does not prove these paths. Record untested steps explicitly.
- Measure, then decide. Use the downloadable evaluation worksheet to record observations and your acceptance criteria. Confirm cleanup of pilot resources through the decommissioning procedure. Scale beyond the pilot only after the evidence meets your own gates.
Gondola is a new product. Published release checks describe a particular test scope; they are not customer adoption data, a workload benchmark, or an availability guarantee. Keep that distinction in your evaluation.