Skip to content

Getting Started ​

Use this CDK construct to create ephemeral self-hosted GitHub runners on-demand inside your AWS account.

  • 🧩 Easy to configure GitHub integration with a web-based interface
  • 🧠 Customizable runners with decent defaults
  • 🏃🏻 Multiple runner configurations controlled by labels
  • 🔐 Everything fully hosted in your account
  • 🔃 Automatically updated build environment with latest runner version

Self-hosted runners in AWS are useful when:

  • You need easy access to internal resources in your actions
  • You want to pre-install some software for your actions
  • You want to provide some basic AWS API access (but aws-actions/configure-aws-credentials has more security controls)
  • You are using GitHub Enterprise Server (3.10 or newer, as runners are registered with just-in-time configurations)

Ephemeral (or on-demand) runners are the recommended way by GitHub for auto-scaling, and they make sure all jobs run with a clean image. Runners are started on-demand. You don't pay unless a job is running.

Installation ​

  1. Install the package for your language

    Available on npm.

    bash
    npm i @cloudsnorkel/cdk-github-runners

    Available on PyPI.

    bash
    pip install cloudsnorkel.cdk-github-runners

    Available on Maven.

    xml
    <dependency>
       <groupId>com.cloudsnorkel</groupId>
       <artifactId>cdk.github.runners</artifactId>
    </dependency>

    Available on NuGet.

    bash
    dotnet add package CloudSnorkel.Cdk.Github.Runners

    Available on GitHub.

    bash
    go get github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners
  2. Use GitHubRunners construct in your code (starting with default arguments is fine)

    ts
    import { App, Stack } from 'aws-cdk-lib';
    import { GitHubRunners } from '@cloudsnorkel/cdk-github-runners';
    
    const app = new App();
    const stack = new Stack(app, 'github-runners');
    new GitHubRunners(stack, 'runners');
    
    app.synth();
    python
    from aws_cdk import App, Stack
    from cloudsnorkel.cdk_github_runners import GitHubRunners
    
    
    app = App()
    stack = Stack(app, "github-runners")
    GitHubRunners(stack, "runners")
    
    app.synth()
    java
    import software.amazon.awscdk.App;
    import software.amazon.awscdk.Stack;
    import com.cloudsnorkel.cdk.github.runners.GitHubRunners;
    
    
    App app = new App();
    Stack stack = new Stack(app, "github-runners");
    new GitHubRunners(stack, "runners");
    
    app.synth();
    csharp
    using Amazon.CDK;
    using CloudSnorkel;
    
    
    var app = new App();
    var stack = new Stack(app, "github-runners");
    new GitHubRunners(stack, "runners");
    
    app.Synth();
    go
    import "github.com/aws/aws-cdk-go/awscdk"
    import "github.com/CloudSnorkel/cdk-github-runners-go/cloudsnorkelcdkgithubrunners"
    
    
    app := awscdk.NewApp()
    stack := awscdk.NewStack(app, jsii.String("github-runners"))
    cloudsnorkelcdkgithubrunners.NewGitHubRunners(stack, jsii.String("runners"))
    
    app.Synth()
  3. Deploy your stack

  4. Look for the status command output similar to aws --region us-east-1 lambda invoke --function-name status-XYZ123 status.json

     ✅  github-runners-test
    
    ✨  Deployment time: 260.01s
    
    Outputs:
    github-runners-test.runnersstatuscommand4A30F0F5 = aws --region us-east-1 lambda invoke --function-name github-runners-test-runnersstatus1A5771C0-mvttg8oPQnQS status.json
  5. Execute the status command (you may need to specify --profile too) and open the resulting status.json file

  6. Open the URL in github.setup.url from status.json or manually setup GitHub integration as an app or with personal access token

  7. Run status command again to confirm github.auth.status and github.webhook.status are OK

  8. Trigger a GitHub action that has a self-hosted label with runs-on: [self-hosted, codebuild] (or non-default labels you set in step 2)

  9. If the action is not successful, see troubleshooting

Released under the Apache-2.0 License.