Install & Compatibility
Where this runs
tested against v2.4.73 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.000s · 359.4MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 18.0s · import 0.000s · 360MB
397MB installed
● package 397MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
GitlabContainerRunner
✓ from cdk_gitlab_runner import GitlabContainerRunner
BlockDuration
✓ from cdk_gitlab_runner import BlockDuration
This quickstart deploys a GitLab Container Runner on an EC2 instance within your default VPC using AWS CDK. It retrieves the GitLab Runner token from an environment variable (recommended for security) and configures the runner with a specific GitLab Runner version, EC2 instance type, and Docker image. Remember to set the `GITLAB_RUNNER_TOKEN` environment variable or replace the placeholder.
import os
from aws_cdk import App, Stack
from cdk_gitlab_runner import GitlabContainerRunner
from aws_cdk.aws_ec2 import Vpc
class MyGitlabRunnerStack(Stack):
def __init__(self, scope: App, id: str, **kwargs) -> None:
super().__init__(scope, id, **kwargs)
# Retrieve an existing VPC by ID or create a new one
# For simplicity, a default VPC lookup is used. In production, provide a specific vpc_id.
# Ensure your AWS account is bootstrapped and CDK context is up-to-date for VPC lookup.
vpc = Vpc.from_lookup(self, "VPC", is_default=True)
# Get GitLab Token from environment variable (secure practice)
gitlab_token = os.environ.get('GITLAB_RUNNER_TOKEN', 'glrt-YOUR_GITLAB_TOKEN_HERE')
if gitlab_token == 'glrt-YOUR_GITLAB_TOKEN_HERE':
print("WARNING: Replace 'glrt-YOUR_GITLAB_TOKEN_HERE' with a real GitLab Runner Token or set GITLAB_RUNNER_TOKEN env var.")
# Create a GitLab Container Runner
runner = GitlabContainerRunner(
self,
'MyGitlabRunner',
vpc=vpc,
gitlab_token=gitlab_token,
gitlab_runner_version='16.9.1', # Specify a compatible GitLab Runner version
ec2_type='t3.micro', # Instance type for the runner
docker_image_name='python:3.9-slim-buster', # Docker image for jobs
runner_tags=['aws', 'cdk', 'python'], # Tags for matching jobs
)
app = App()
MyGitlabRunnerStack(app, "MyGitlabRunnerStack")
app.synth()
Debug
Known issues
gotchaHardcoding GitLab Runner Tokens is a security risk. Always use AWS Secrets Manager or SSM Parameter Store to manage and retrieve sensitive tokens.fixStore your GitLab token in AWS Secrets Manager or SSM Parameter Store and retrieve it at runtime, e.g., `ssm.StringParameter.value_from_lookup(self, '/gitlab/runner/token')`.
affects: All versions
breakingGitLab Runner versions have compatibility requirements with GitLab server versions and features. Using an incompatible runner version can lead to unexpected behavior or features not working.fixRefer to the official GitLab Runner documentation for compatibility matrices. Ensure the `gitlab_runner_version` parameter in `GitlabContainerRunner` is compatible with your GitLab instance and desired features.
affects: GitLab Runner versions pre-15.10 (for new registration process) and others.
gotchaIf your CDK application involves building Docker images locally or within the CI/CD pipeline, the Docker daemon must be accessible in the environment where `cdk deploy` or `cdk synth` is executed.fixEnsure Docker is installed and running on the machine or CI runner performing CDK operations. For Docker-in-Docker (DinD) scenarios, consider the security implications of privileged containers.
affects: All versions
gotchaFor features like Docker-in-Docker (DinD), the GitLab Runner container often requires 'privileged' mode. This grants extensive capabilities to the container and poses a significant security risk if untrusted code is executed.fixOnly use privileged mode if absolutely necessary and fully understand the security implications. Limit the scope of jobs running in privileged containers and implement strict access controls.
affects: All versions when using DinD
gotchaJobs may stall or not be picked up by runners if the `runner_tags` defined in your `cdk-gitlab-runner` stack do not match the tags specified in your `.gitlab-ci.yml` jobs.fixCarefully define and verify that the `runner_tags` in your `GitlabContainerRunner` configuration precisely match the `tags` specified in your GitLab CI/CD job definitions.
affects: All versions
Errors
Common errors & fixes
Error: spawnSync docker ENOENT
The `docker` command is not found in the execution environment of the CDK deployment or synth process, usually when the CDK app attempts to build a Docker image.
fixInstall Docker on the machine or CI/CD runner executing the CDK commands. For CI environments, ensure the Docker service is running and accessible to the user running the pipeline.
Deployment Failure Due to Missing Permissions
The IAM role used by the AWS CDK deployment (or the CloudFormation execution role) lacks the necessary permissions to create, update, or delete AWS resources defined in your stack.
fixReview the IAM permissions attached to the role used for CDK deployments. Ensure it has permissions for all AWS services and actions required by your `cdk-gitlab-runner` stack (e.g., EC2, VPC, IAM, S3, Secrets Manager).
context value not found for key 'vpc-provider:account=...'
CDK's context (e.g., for VPC lookups) is outdated or missing, preventing it from resolving environment-specific information.
fixRun `cdk context --reset` to clear cached context values, then re-run `cdk synth` or `cdk deploy` to refresh the context. Alternatively, provide explicit VPC IDs and other resources instead of relying on lookups.
Job stalls and doesn't want to start even though your runner is available
The GitLab CI job's `tags` do not match any of the `runner_tags` configured for your `cdk-gitlab-runner` instance.
fixVerify that the `tags` array in your `.gitlab-ci.yml` for the failing job includes at least one tag present in the `runner_tags` array passed to `GitlabContainerRunner`.
No URL provided, cache will not be download / uploaded
This error in GitLab Runner logs indicates an issue with cache configuration, where the runner helper cannot get valid pre-signed URLs to access the remote cache (e.g., S3).
fixReview your GitLab Runner's `config.toml` (managed by `cdk-gitlab-runner`) and ensure the cache section is correctly configured, including S3 bucket details and IAM permissions for the runner to access the cache bucket. Ensure the helper image is up-to-date.
Upgrade
Version history
2.4.73latest on PyPI · released Jun 13, 2026
Audit
Dependencies
pythonrequiredRequires Python 3.9 or later.
aws-cdk-librequiredCore dependency for AWS CDK constructs. AWS CDK CLI (version >= 2.0.0) is a prerequisite for deployment.