{"id":27638,"library":"cdktf-gitlab-runner","title":"CDKTF GitLab Runner","description":"A CDK for Terraform (CDKTF) construct to deploy GitLab Runner on Google Cloud Platform (GCP). Version 0.0.1463, pre-1.0 with rapid releases. Supports Python 3.9+ and CDKTF 0.12+.","status":"active","version":"0.0.1463","language":"python","source_language":"en","source_url":"https://github.com/neilkuan/cdktf-gitlab-runner","tags":["cdktf","terraform","gitlab-runner","gcp","iac"],"install":[{"cmd":"npm install cdktf-cli@latest","lang":"bash","label":"Install CDKTF CLI"},{"cmd":"pip install cdktf-gitlab-runner","lang":"bash","label":"Install library"}],"dependencies":[{"reason":"Core CDKTF library required to synthesize Terraform configs","package":"cdktf","optional":false},{"reason":"Required by CDKTF for construct base classes","package":"constructs","optional":false}],"imports":[{"note":"Hyphens are invalid in Python imports; use underscores.","wrong":"from cdktf-gitlab-runner import GitlabRunner","symbol":"GitlabRunner","correct":"from cdktf_gitlab_runner import GitlabRunner"}],"quickstart":{"code":"from cdktf import App, TerraformStack\nfrom cdktf_gitlab_runner import GitlabRunner\nimport os\nstack = TerraformStack(App(), 'gitlab-runner-example')\n# Minimal required config; adjust values as needed.\n# WARNING: Some attributes may require additional usage specifics.\nGitlabRunner(\n    stack,\n    id='my-runner',\n    gitlab_url='https://gitlab.com',\n    registration_token=os.environ.get('GITLAB_REG_TOKEN', 'your-default-token'),\n    runner_name='my-runner',\n    runner_count=1,\n    machine_type='e2-medium',\n    zone='us-central1-a',\n    project_id=os.environ.get('GCP_PROJECT', 'my-project'),\n    service_account_email=os.environ.get('SA_EMAIL', 'default@project.iam.gserviceaccount.com'),\n)\nApp().synth()","lang":"python","description":"Creates a basic GitLab Runner stack using CDKTF. Replace placeholders with actual GCP project and service account email."},"warnings":[{"fix":"Use `pip install cdktf-gitlab-runner==0.0.1463` to pin version.","message":"Version 0.0.x is pre-release; breaking changes may occur without major version bump. Always pin exact version in requirements.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Ensure VPC, subnetwork, and firewall rules (allow SSH and GitLab Runner traffic) exist in the specified project and region.","message":"The construct requires existing GCP resources: a VPC network, subnetwork, and firewall rules. It does not create them. Missing resources cause deployment failures.","severity":"gotcha","affected_versions":"all"},{"fix":"Grant the service account the necessary IAM roles before deploying.","message":"The runner uses a service account with roles/compute.instanceAdmin.v1 and roles/iam.serviceAccountUser. The user must grant these roles; construct does not do so.","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Use 'from cdktf_gitlab_runner import GitlabRunner'","cause":"Incorrect import using hyphen 'cdktf-gitlab-runner' instead of underscore.","error":"ModuleNotFoundError: No module named 'cdktf_gitlab_runner'"},{"fix":"Check that the registration token is correct and the GitLab URL is accessible from the runner machine.","cause":"The registration token may be incorrectly passed or the runner fails to register.","error":"Error: Invalid Terraform output: missing 'gitlab_runner_token'"},{"fix":"Grant roles/compute.instanceAdmin.v1 and roles/iam.serviceAccountUser to the service account.","cause":"The service account used by the runner lacks compute.instanceAdmin.v1 or iam.serviceAccountUser roles.","error":"Error: Service account does not have required permissions"}],"ecosystem":"pypi","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}