CDKTF GitLab Runner

0.0.1463 verified Sat May 09 auth: no python

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+.

pip install cdktf-gitlab-runner

Common errors

error ModuleNotFoundError: No module named 'cdktf_gitlab_runner' ↓

cause Incorrect import using hyphen 'cdktf-gitlab-runner' instead of underscore.

fix

Use 'from cdktf_gitlab_runner import GitlabRunner'

error Error: Invalid Terraform output: missing 'gitlab_runner_token' ↓

cause The registration token may be incorrectly passed or the runner fails to register.

fix

Check that the registration token is correct and the GitLab URL is accessible from the runner machine.

error Error: Service account does not have required permissions ↓

cause The service account used by the runner lacks compute.instanceAdmin.v1 or iam.serviceAccountUser roles.

fix

Grant roles/compute.instanceAdmin.v1 and roles/iam.serviceAccountUser to the service account.

Warnings

breaking Version 0.0.x is pre-release; breaking changes may occur without major version bump. Always pin exact version in requirements. ↓

fix Use `pip install cdktf-gitlab-runner==0.0.1463` to pin version.

gotcha The construct requires existing GCP resources: a VPC network, subnetwork, and firewall rules. It does not create them. Missing resources cause deployment failures. ↓

fix Ensure VPC, subnetwork, and firewall rules (allow SSH and GitLab Runner traffic) exist in the specified project and region.

gotcha 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. ↓

fix Grant the service account the necessary IAM roles before deploying.

Install

npm install cdktf-cli@latest

Imports

GitlabRunner

wrong

from cdktf-gitlab-runner import GitlabRunner

correct

from cdktf_gitlab_runner import GitlabRunner

Hyphens are invalid in Python imports; use underscores.

Quickstart

Creates a basic GitLab Runner stack using CDKTF. Replace placeholders with actual GCP project and service account email.

from cdktf import App, TerraformStack
from cdktf_gitlab_runner import GitlabRunner
import os
stack = TerraformStack(App(), 'gitlab-runner-example')
# Minimal required config; adjust values as needed.
# WARNING: Some attributes may require additional usage specifics.
GitlabRunner(
    stack,
    id='my-runner',
    gitlab_url='https://gitlab.com',
    registration_token=os.environ.get('GITLAB_REG_TOKEN', 'your-default-token'),
    runner_name='my-runner',
    runner_count=1,
    machine_type='e2-medium',
    zone='us-central1-a',
    project_id=os.environ.get('GCP_PROJECT', 'my-project'),
    service_account_email=os.environ.get('SA_EMAIL', 'default@project.iam.gserviceaccount.com'),
)
App().synth()