cdk-github-runners

This project provides AWS CDK constructs to create ephemeral, on-demand self-hosted GitHub runners within your AWS account. These runners are started only when a job is running, ensuring you only pay for active compute time.

Key features include:

• Web-based interface for easy GitHub integration.
• Customizable runner environments with sensible defaults.
• Support for multiple runner configurations via labels.
• Fully hosted within your own AWS account.
• Automatic updates to the latest runner versions.

Ephemeral runners are recommended by GitHub for auto-scaling and ensuring every job runs in a clean, isolated environment.

GitHub Actions self-hosted runners support running scripts before or after every job via environment variables. This is a portable mechanism supported across all providers (EC2, ECS, Fargate, CodeBuild, Lambda).

Supported Hooks

• Before a job: Set the ACTIONS_RUNNER_HOOK_JOB_STARTED environment variable to the path of your script.
• After a job: Set the ACTIONS_RUNNER_HOOK_JOB_COMPLETED environment variable to the path of your script.

Use Cases

Use hooks for tasks that must occur once per job, such as:

• Logging job metadata.
• Sending notifications.
• Preparing or cleaning the workspace.
• Gating jobs.

Note: If you need to install software or run a persistent service on the runner itself, do not use hooks. Instead, bake the software into the runner image or configure a systemd unit during the image build.

The LinuxUbuntuComponents class provides various software components for Ubuntu Linux that can be used with AWS Image Builder-based builders.

Note: These components cannot be used with CodeBuildImageBuilder.

In JavaScript environments where multiple copies of the constructs library might exist (e.g., due to manual symlinking or certain monorepo tool configurations), instanceof checks against the Construct class may fail even if the object is a valid construct.

To ensure reliability, avoid using instanceof and instead use the project's provided type-testing methods (like isConstruct) to verify objects.

When configuring EC2 runners, you can choose between different EBS volume types to balance cost and performance:

• GP3: General purpose SSD. Offers configurable IOPS and throughput; provides the best price/performance.
• GP2: General purpose SSD. Provides baseline performance.
• IO1: Provisioned IOPS SSD. Designed for the highest performance in I/O-intensive workloads.

The CodeBuildImageBuilder is an implementation of IRunnerImageBuilder that uses AWS CodeBuild to build Docker images pre-baked with GitHub Actions runner requirements. These builders can be passed to runner providers to customize the runner's environment. Builders automatically re-run at a specified rebuildInterval to keep images up to date.

const builder = new CodeBuildImageBuilder(this, 'Builder', {
    dockerfilePath: FargateRunnerProvider.LINUX_X64_DOCKERFILE_PATH,
    runnerVersion: RunnerVersion.specific('2.293.0'),
    rebuildInterval: Duration.days(14),
});
builder.setBuildArg('EXTRA_PACKAGES', 'nginx xz-utils');
new FargateRunnerProvider(this, 'Fargate provider', {
    labels: ['customized-fargate'],
    imageBuilder: builder,
});

The Ec2RunnerProvider is a GitHub Actions runner provider that uses EC2 instances to execute jobs.

Important: This construct is not intended to be used in isolation. It must be passed into the providers property of a GitHubRunners construct.

It implements the IRunnerProvider interface and provides the necessary logic to generate Step Function tasks for starting new runners.

import { Ec2RunnerProvider } from '@cloudsnorkel/cdk-github-runners'

// Note: This must be passed to GitHubRunners providers property
new Ec2RunnerProvider(scope, id, props);

The registration level determines where on-demand runners are dynamically registered during provisioning. This is independent of where the GitHub App is installed.

• Repository-level (Recommended): Runners are registered to specific repositories. This provides better isolation and reduces the risk of jobs being assigned to the wrong runners. Requires the administration permission.
• Organization-level: Runners are registered to the entire organization and are available to all repositories in the organization, regardless of app installation. This requires the organization_self_hosted_runners permission but carries a higher risk of accidental job routing.

Decision Guide:

• Use Repository-level for better security, isolation, and control.
• Use Organization-level if you want to minimize permissions and fully trust all repositories in your organization.