GitLab Custom Runner

The vHaaS GitLab Custom Runner integrates hardware assemblies directly into GitLab CI/CD pipelines. A job tagged vHaaS is picked up by the runner, which books an assembly, connects to its virtual machine, runs the job script on that VM with hardware access, and releases the assembly when the job finishes.

The runner is hosted by vHaaS, so no installation is required. The executor can also be run in a self-managed environment; see Self-hosted GitLab Runner.

Setting up your first pipeline?

For a step-by-step walkthrough, see Basic CI Integration. For a conceptual overview of how the runner books, connects, runs and releases, see CI Integration.

Job routing

The runner only picks up jobs that carry the vHaaS tag:

tags:
  - vHaaS

Jobs without this tag are ignored by the vHaaS runner and handled by the project's other runners as usual.

CI/CD variables

Set these as CI/CD variables on the project/group or under the job's variables:. The names are matched exactly.

Variable	Required	Description
`VEHAAS_TOKEN`	✓	A vHaaS access token used to book the assembly and read the VM credentials. Store it as a masked, protected CI/CD variable. Needs at least the `group_user` role on the assembly.
`ASSEMBLY_REF`	✓	One assembly ref, or several as a comma-separated list. The refs are tried in order and the first available one is used (e.g. `"ASSEMBLY-1004"` or `"ASSEMBLY-1, ASSEMBLY-2"`).
`SESSION_DURATION`	✓	Booking duration in minutes. The session is force-ended after this time.
`SESSION_TIMEOUT`	✓	Maximum time in minutes to wait for a free assembly before the job fails.
`VEHAAS_ORGANIZATION_ID`	✓	The vHaaS organization ID.
`VEHAAS_HOST`	—	Base URL of the vHaaS service. Defaults to `https://vhaas.vector.cloud` and does not normally need to be set.

Token security

Never commit VEHAAS_TOKEN to the repository. Always use a masked and protected GitLab CI/CD variable.

Job environment

In addition to the standard GitLab CI/CD predefined variables and any user-defined variables, the runner exposes the booked VM to the job script:

Variable	Description
`SESSION_ID`	ID of the vHaaS session backing this job.
`VM_ID`	ID of the VM the job is running on.
`VM_HOSTNAME`	DNS name of the VM.
`VM_USERNAME`	Username the job script runs as.
`VM_PASSWORD`	Password for that user. Treat as a secret — do not print it.
`VM_IP`	IP address of the VM. Empty when the VM is reached through a tunnel.
`VM_SSH_HOSTNAME`	Public SSH hostname of the VM when it is reached through a tunnel.

Execution environment

The repository is checked out on the VM and the script runs from the checkout directory, so artifacts are collected from there as usual. Hardware interfaces are available as configured in the assembly profile.

PowerShell semantics

The assembly's default GitLab-runner VM runs Windows, so each line of the script, before_script and after_script sections executes in PowerShell on that VM. Commands must use PowerShell syntax — Bash/POSIX constructs will not work — and variables are referenced the PowerShell way, e.g. $env:VM_HOSTNAME:

script:
  - Write-Host "Running on $env:VM_HOSTNAME (session $env:SESSION_ID)"
  - Get-Location

Troubleshooting

Symptom	Likely cause	Solution
Job stays in `pending`	No runner with the `vHaaS` tag is available to the project	Confirm the project can reach the vHaaS runner; for external projects contact support
Job fails asking for `VEHAAS_ORGANIZATION_ID`	The variable is unset	Set `VEHAAS_ORGANIZATION_ID` to the organization ID
"Assembly not available"	The assembly is in use or access is missing	Check availability in the web UI; add fallback refs (`"ASSEMBLY-1, ASSEMBLY-2"`); raise `SESSION_TIMEOUT`
Authentication failed	Invalid or expired `VEHAAS_TOKEN`	Verify the variable is set, not expired, and has at least the `group_user` role
Job fails mid-run	`SESSION_DURATION` elapsed before the job finished	Increase `SESSION_DURATION` or shorten the job
Commands fail with syntax errors	Script written for Bash, not PowerShell	Rewrite the `script` in PowerShell syntax (see PowerShell semantics)