Self-hosted GitLab Runner

By default the GitLab Custom Runner is hosted by vHaaS. You can instead run the custom executor yourself — for example, to register it against a specific GitLab group or project. vHaaS publishes the runner image and Helm chart to registry.code.vector.cloud.

Once the runner is running, jobs use it exactly as they use the vHaaS-hosted runner — see Basic CI Integration.

Prerequisites

A GitLab project or group where you can register a runner
A panel-issued vHaaS runner token
Docker with Docker Compose, or a Kubernetes cluster with Helm

Onboarding

The vHaaS runner token lets the runner open the secured tunnel to the VM. Contact us via the support page to onboard a self-hosted runner.

Steps

1. Register a GitLab runner

In the target GitLab project or group, go to Settings → CI/CD → Runners (docs) and create a runner with the vHaaS tag. Note its authentication token.

2. Write the runner configuration

Create config.toml and paste the runner authentication token as token:

```toml concurrent = 4 check_interval = 0

[[runners]] name = "veHaaS Custom Runner" url = "https://code.vector.cloud" token = "glrt-your-runner-token" executor = "custom" builds_dir = "builds" cache_dir = "cache" shell = "powershell"

[runners.custom] config_exec = "/opt/vehaas-driver/01-config.sh" config_exec_timeout = 86400 prepare_exec = "/opt/vehaas-driver/02-prepare.sh" prepare_exec_timeout = 86400 run_exec = "/opt/vehaas-driver/03-run.sh" cleanup_exec = "/opt/vehaas-driver/04-cleanup.sh" cleanup_exec_timeout = 86400 ```

3. Provide the runtime secrets

Create .env with the vHaaS API host and the runner token:

bash
VEHAAS_HOST=https://vhaas.vector.cloud
VEHAAS_RUNNER_TOKEN=your-vehaas-runner-token

Static tunnel tokens (legacy)

A static tunnel service-token pair, TUNNEL_SERVICE_TOKEN_ID and TUNNEL_SERVICE_TOKEN_SECRET, may be provided instead of VEHAAS_RUNNER_TOKEN. VEHAAS_RUNNER_TOKEN is preferred, so that rotation and revocation happen server-side.

4. Start the runner

Create docker-compose.yml, referencing a released image tag:

yaml
services:
  vehaas-runner:
    image: registry.code.vector.cloud/vhaas/vhaas-gitlab-custom-executor:<version>
    restart: unless-stopped
    env_file: .env
    volumes:
      - ./config.toml:/etc/gitlab-runner/config.toml:ro

Start it with docker compose up -d.

On Kubernetes

The same runner is published as a Helm chart at oci://registry.code.vector.cloud/vhaas/vhaas-gitlab-custom-executor for cluster deployments. Configure the runner authentication token, VEHAAS_HOST and the vHaaS runner token through the chart values.

Troubleshooting

Symptom	Likely cause	Solution
Jobs stay in `pending`	The runner is not registered with the `vHaaS` tag, or the token is wrong	Confirm the runner shows as online in GitLab and the job tag matches
Job fails opening the tunnel to the VM	`VEHAAS_RUNNER_TOKEN` is missing or revoked	Set a valid runner token in `.env`; request a new one via support
Runner cannot reach the vHaaS API	`VEHAAS_HOST` is wrong or unreachable from the runner host	Verify `VEHAAS_HOST` and outbound network access