Using Build Spec to install yarn

[truecolintracy]

I'm a little confused as to how to properly install yarn on the docker image. I don't properly understand how to extend this construct to implement something like:

aws_codebuild.BuildSpec.fromObject({
    version: '0.2',
    phases: {
      install: {
        'runtime-versions': {
          nodejs: 18,
        },
        commands: [
          'echo "Installing dependencies"',
          'npm install -g yarn',
          'yarn',
        ],
      },
    },
  });

[truecolintracy]

Understanding now that is only for use with the actual runner and I need to install yarn on the actual docker instance. Still a bit lost on how to accomplish this, I'm thinking it's pretty simple but I'm just not seeing it. :|

[kichik]

You would have to configure your runner image builder to build images with your additional requirements. If you are building AMI or a container image for Windows, it's pretty straightforward (and copied from README.md).

const myWindowsBuilder = new ContainerImageBuilder(this, 'Windows image builder', {
  architecture: Architecture.X86_64,
  os: Os.WINDOWS,
  runnerVersion: RunnerVersion.specific('2.291.0'),
  rebuildInterval: Duration.days(14),    
});
myWindowsBuilder.addComponent(new ImageBuilderComponent(this, 'Ninja Component',
  {
    displayName: 'Ninja',
    description: 'Download and install Ninja build system',
    platform: 'Windows',
    commands: [
      'Invoke-WebRequest -UseBasicParsing -Uri "https://github.com/ninja-build/ninja/releases/download/v1.11.1/ninja-win.zip" -OutFile ninja.zip',
      'Expand-Archive ninja.zip -DestinationPath C:\\actions',
      'del ninja.zip',
    ],
  }
));

const myProvider = new FargateRunnerProvider(this, 'fargate runner', {
  label: 'customized-windows-fargate',
  vpc: vpc,
  securityGroup: runnerSg,
  imageBuidler: myWindowsBuilder,
});

// create the runner infrastructure
new GitHubRunners(this, 'runners', {
  providers: [myProvider],
});

Linux would be almost identical (if you're building an AMI):

const myBuilder = new AmiBuilder(this, 'AMI builder', {
  architecture: Architecture.X86_64,
  os: Os.LINUX,
});
myBuilder.addComponent(new ImageBuilderComponent(this, 'Yarn',
  {
    displayName: 'Yarn',
    description: 'Download and install Yarn',
    platform: 'Linux',
    commands: [
      'npm install -g yarn',
    ],
  }
));

const myProvider = new Ec2RunnerProvider(this, 'ec2 runner with yarn', {
  labels: ['ec2-with-yarn'],
  imageBuidler: myBuilder,
});

// create the runner infrastructure
new GitHubRunners(this, 'runners', {
  providers: [myProvider],
});

If you want to build a runner image for Linux with a provider that needs a Docker image, it's a bit more complicated. First figure out which Dockerfile you want to modify. Each provider has two constants pointing to the paths of Dockerfiles it uses by default. CodeBuildRunnerProvider has one for Linux x64 and one for ARM64.

cdk-github-runners/src/providers/codebuild.ts

Lines 123 to 147 in a62cecf

	/**
	* Path to Dockerfile for Linux x64 with all the requirements for CodeBuild runner. Use this Dockerfile unless you need to customize it further than allowed by hooks.
	*
	* Available build arguments that can be set in the image builder:
	* * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image.
	* * `EXTRA_PACKAGES` can be used to install additional packages.
	* * `DOCKER_CHANNEL` overrides the channel from which Docker will be downloaded. Defaults to `"stable"`.
	* * `DIND_COMMIT` overrides the commit where dind is found.
	* * `DOCKER_VERSION` overrides the installed Docker version.
	* * `DOCKER_COMPOSE_VERSION` overrides the installed docker-compose version.
	*/
	public static readonly LINUX_X64_DOCKERFILE_PATH = path.join(__dirname, '..', '..', 'assets', 'docker-images', 'codebuild', 'linux-x64');
	/**
	* Path to Dockerfile for Linux ARM64 with all the requirements for CodeBuild runner. Use this Dockerfile unless you need to customize it further than allowed by hooks.
	*
	* Available build arguments that can be set in the image builder:
	* * `BASE_IMAGE` sets the `FROM` line. This should be an Ubuntu compatible image.
	* * `EXTRA_PACKAGES` can be used to install additional packages.
	* * `DOCKER_CHANNEL` overrides the channel from which Docker will be downloaded. Defaults to `"stable"`.
	* * `DIND_COMMIT` overrides the commit where dind is found.
	* * `DOCKER_VERSION` overrides the installed Docker version.
	* * `DOCKER_COMPOSE_VERSION` overrides the installed docker-compose version.
	*/
	public static readonly LINUX_ARM64_DOCKERFILE_PATH = path.join(__dirname, '..', '..', 'assets', 'docker-images', 'codebuild', 'linux-arm64');

All of the Dockerfiles are under the same folder. For example, if you're trying to create a CodeBuild runner provider on x64, it's here.

Most Dockerfiles have some arguments you can override. Those are also documented in the constants pointing to them from the provider as you can see above. If you just want to install an extra package, there is an argument to override for that.

cdk-github-runners/src/providers/docker-images/codebuild/linux-x64/Dockerfile

Lines 8 to 10 in e4ebc40

	ARG EXTRA_PACKAGES=""
	ARG DEBIAN_FRONTEND=noninteractive
	RUN apt-get update && apt-get upgrade -y && apt-get install -y curl sudo jq bash zip unzip iptables software-properties-common ca-certificates $EXTRA_PACKAGES && \

const builder = new CodeBuildImageBuilder(stack, 'codebuild image builder', {
  dockerfilePath: CodeBuildRunnerProvider.LINUX_X64_DOCKERFILE_PATH,
  architecture: Architecture.X86_64,
});
builder.setBuildArg('EXTRA_PACKAGES', 'yarnpkg');

new GitHubRunners(this, 'runners', {
  providers: [
    new CodeBuildRunnerProvider(this, 'provider', {
      imageBuilder: builder,
    });
  ],
});

If you want to add arbitrary commands, you will have to completely override the Dockerfile. This can be useful in your case if the version of Yarn that comes with Ubuntu is not new enough. In this case, you would make a copy of the relevant Dockerfile and modify it to your liking. You would then point the builder to your Dockerfile directory instead of CodeBuildRunnerProvider.LINUX_X64_DOCKERFILE_PATH.

In the future I plan to make a generic component that can be added to both Docker image builders and AMI builders. This should make this process easier. There will be no more need to hunt down and copy any Dockerfile.

[kichik]

With version 0.9.0 you can now use the following on all runner providers:

const builder = CodeBuildRunnerProvider.imageBuilder(stack, 'codebuild image builder');
builder.addComponent(
  RunnerImageComponent.custom({ commands: ['apt install -y yarnpkg'] })
);

new GitHubRunners(this, 'runners', {
  providers: [
    new CodeBuildRunnerProvider(this, 'provider', {
      imageBuilder: builder,
    });
  ],
});