{"id":8002,"library":"cdk-gitlab-runner","title":"cdk-gitlab-runner","description":"cdk-gitlab-runner is a Python library that leverages AWS CDK to provision and manage GitLab CI/CD runners within your AWS environment. It supports various configurations, including Fargate and EC2 instances, enabling users to quickly deploy self-hosted runners to execute GitLab pipeline jobs. The library is actively maintained, with frequent updates to support new AWS CDK and GitLab Runner features, and the current version is 2.4.18.","status":"active","version":"2.4.18","language":"en","source_language":"en","source_url":"https://github.com/neilkuan/cdk-gitlab-runner.git","tags":["aws-cdk","gitlab","ci-cd","runner","infrastructure-as-code","iac","fargate","ec2","cloud"],"install":[{"cmd":"pip install cdk-gitlab-runner","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Requires Python 3.9 or later.","package":"python","optional":false},{"reason":"Core dependency for AWS CDK constructs. AWS CDK CLI (version >= 2.0.0) is a prerequisite for deployment.","package":"aws-cdk-lib","optional":false}],"imports":[{"symbol":"GitlabContainerRunner","correct":"from cdk_gitlab_runner import GitlabContainerRunner"},{"symbol":"BlockDuration","correct":"from cdk_gitlab_runner import BlockDuration"}],"quickstart":{"code":"import os\nfrom aws_cdk import App, Stack\nfrom cdk_gitlab_runner import GitlabContainerRunner\nfrom aws_cdk.aws_ec2 import Vpc\n\n\nclass MyGitlabRunnerStack(Stack):\n    def __init__(self, scope: App, id: str, **kwargs) -> None:\n        super().__init__(scope, id, **kwargs)\n\n        # Retrieve an existing VPC by ID or create a new one\n        # For simplicity, a default VPC lookup is used. In production, provide a specific vpc_id.\n        # Ensure your AWS account is bootstrapped and CDK context is up-to-date for VPC lookup.\n        vpc = Vpc.from_lookup(self, \"VPC\", is_default=True)\n\n        # Get GitLab Token from environment variable (secure practice)\n        gitlab_token = os.environ.get('GITLAB_RUNNER_TOKEN', 'glrt-YOUR_GITLAB_TOKEN_HERE')\n\n        if gitlab_token == 'glrt-YOUR_GITLAB_TOKEN_HERE':\n            print(\"WARNING: Replace 'glrt-YOUR_GITLAB_TOKEN_HERE' with a real GitLab Runner Token or set GITLAB_RUNNER_TOKEN env var.\")\n\n        # Create a GitLab Container Runner\n        runner = GitlabContainerRunner(\n            self, \n            'MyGitlabRunner',\n            vpc=vpc,\n            gitlab_token=gitlab_token,\n            gitlab_runner_version='16.9.1', # Specify a compatible GitLab Runner version\n            ec2_type='t3.micro', # Instance type for the runner\n            docker_image_name='python:3.9-slim-buster', # Docker image for jobs\n            runner_tags=['aws', 'cdk', 'python'], # Tags for matching jobs\n        )\n\napp = App()\nMyGitlabRunnerStack(app, \"MyGitlabRunnerStack\")\napp.synth()","lang":"python","description":"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."},"warnings":[{"fix":"Store 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')`.","message":"Hardcoding GitLab Runner Tokens is a security risk. Always use AWS Secrets Manager or SSM Parameter Store to manage and retrieve sensitive tokens.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Refer 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.","message":"GitLab 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.","severity":"breaking","affected_versions":"GitLab Runner versions pre-15.10 (for new registration process) and others."},{"fix":"Ensure 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.","message":"If 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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Only 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.","message":"For 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.","severity":"gotcha","affected_versions":"All versions when using DinD"},{"fix":"Carefully define and verify that the `runner_tags` in your `GitlabContainerRunner` configuration precisely match the `tags` specified in your GitLab CI/CD job definitions.","message":"Jobs 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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install 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.","cause":"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.","error":"Error: spawnSync docker ENOENT"},{"fix":"Review 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).","cause":"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.","error":"Deployment Failure Due to Missing Permissions"},{"fix":"Run `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.","cause":"CDK's context (e.g., for VPC lookups) is outdated or missing, preventing it from resolving environment-specific information.","error":"context value not found for key 'vpc-provider:account=...'"},{"fix":"Verify 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`.","cause":"The GitLab CI job's `tags` do not match any of the `runner_tags` configured for your `cdk-gitlab-runner` instance.","error":"Job stalls and doesn't want to start even though your runner is available"},{"fix":"Review 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.","cause":"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).","error":"No URL provided, cache will not be download / uploaded"}]}