Skip to content

Basic CI integration

The vHaaS custom GitLab runner integrates hardware assemblies directly into your CI/CD pipelines, handling booking, connection, and script execution automatically.

Currently only GitLab is supported. Integration with GitHub and other platforms will be added in the future.

For advanced patterns — choosing assemblies at run time, parallel runs, and API booking — see Advanced CI Integration.

vHaaS custom GitLab runner

The runner is operated and hosted by vHaaS — there is nothing for you to install. Ask support to make it available to your GitLab project, then tag a job with vHaaS and the runner takes over from there:

  • Monitors GitLab projects for jobs tagged with vHaaS
  • Automatically books assemblies using your vHaaS token
  • Establishes SSH connections to the assembly's VM
  • Executes your CI scripts directly on the VM with hardware access
  • Releases the assembly when the job completes

Running the executor in your own environment is also supported — see Self-hosted GitLab Runner.

Integrate vHaaS to your GitLab CI pipelines

Prerequisites

  • GitLab Project Access: At least Developer role in your GitLab project
  • vHaaS custom GitLab runner is set up and available for your project (contact the support for onboarding of your project)
  • vHaaS Organization Membership: You must be a member of a vHaaS organization
  • Assembly Access: You need access to at least one assembly through your organization or a group you are part of

Steps

1. Create and copy the vHaaS Access Token

This is a vHaaS access token, not a GitLab one. In vHaaS, open the Group page and go to its Access Tokens tab, then create a group-level token with the following settings:

  • Name: gitlab-ci-token (or descriptive name for your project)
  • Role: At minimum group_user role (to book assemblies)
  • Expiration: Set according to your security policy

Copy the token value before leaving the page — it cannot be viewed again afterwards. See Manage Scoped Access Tokens for the full creation steps and Access Tokens for the available token levels.

Token Security

Never commit your vHaaS token to your repository. Always use GitLab CI/CD variables (protected and masked).

2. Configure GitLab CI Variables

In your GitLab project, go to Settings → CI/CD → Variables and add a new variable:

Key Value
VEHAAS_TOKEN Value of your vHaaS Access Token
VEHAAS_ORGANIZATION_ID ID of your vHaaS organization. It appears in the address bar as .../organizations/<id>/... while you browse the organization in the Explorer, or look it up with GET /api/v3/self/organizations.

Use these exact names

The runner looks up VEHAAS_TOKEN and VEHAAS_ORGANIZATION_ID by name. A variable named anything else is ignored, and the job fails with Error: VEHAAS_TOKEN is not set.

3. Find Your Assembly ID

  1. Open vHaaS and navigate to the Overview page
  2. Assemblies you have access to are listed with their IDs (e.g., ASSEMBLY-100)
  3. Note the assembly IDs you want to use in your pipeline

Alternatively, use the vHaaS API endpoint directly or a CLI command:

GET /api/v3/organizations/{org_id}/assemblies

vHaaS-cli get assemblies

4. Configure Your CI Job

Add the following configuration to your .gitlab-ci.yml file:

your-job-name:
  tags:
    - vHaaS # This tag routes the job to the vHaaS runner
  variables:
    ASSEMBLY_REF: "YOUR-ASSEMBLY-ID"
    SESSION_DURATION: 30
    SESSION_TIMEOUT: 10
  script:
    -  # Your test commands here

Configuration Variables

The job sets ASSEMBLY_REF, SESSION_DURATION, SESSION_TIMEOUT and VEHAAS_ORGANIZATION_ID, plus the masked VEHAAS_TOKEN configured above. For the full list with valid ranges, defaults and the optional VEHAAS_HOST, see the CI/CD variables reference.

Examples

Verification Example

Test your configuration with this minimal job:

test-vHaaS-connection:
  tags:
    - vHaaS
  variables:
    SESSION_DURATION: 10
    SESSION_TIMEOUT: 5
    ASSEMBLY_REF: "YOUR-ASSEMBLY-ID"  # Replace with your assembly
  script:
    - echo "Connected to vHaaS VM"
    - hostname
    - whoami
  only:
    - branches

Expected output:

  • Job should complete successfully
  • Hostname shows the vHaaS VM
  • Directory shows the VM's workspace path

If this fails, check the logs of job and the troubleshooting.

Basic Example

test:
  tags:
    - vHaaS
  variables:
    SESSION_DURATION: 30
    SESSION_TIMEOUT: 10
    ASSEMBLY_REF: "ASSEMBLY-1004"
  script:
    - echo "Test running on assembly $ASSEMBLY_REF"
    - sleep 60
  rules:
    - if: $CI_COMMIT_SHA

Advanced Example with multiple assemblies

Job scripts run in PowerShell on the assembly's Windows VM.

hardware-test:
  tags:
    - vHaaS
  variables:
    SESSION_DURATION: 45
    SESSION_TIMEOUT: 15
    ASSEMBLY_REF: "ASSEMBLY-1004, ASSEMBLY-1005, ASSEMBLY-1006"
  script:
    - Write-Host "Running on VM $env:VM_HOSTNAME"
    - python -m pip install -r requirements.txt
    - python -m pytest tests/ --junit-xml=report.xml
  artifacts:
    when: always
    paths:
      - report.xml
    reports:
      junit: report.xml
    expire_in: 1 week
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Available Environment

When your job runs on a vHaaS VM, these environment variables are available:

  • Standard GitLab CI variables: $CI_PROJECT_NAME, $CI_COMMIT_SHA, etc.
  • Custom variables: Any variables you define in your .gitlab-ci.yml
  • VM details: VM_HOSTNAME, SESSION_ID and the other VM variables — see the job environment reference
  • Assembly context: The VM is connected to the booked assembly hardware

Working Directory:

  • Your repository is cloned to the VM's workspace
  • Scripts execute from the repository root
  • Artifacts are collected from this directory

Hardware Access:

  • Hardware interfaces are available as configured in the assembly profile
  • Network devices accessible via their configured IPs
  • Refer to the assembly's specific documentation for device details

Troubleshooting

Symptom Likely cause Solution
Job stays in "pending" state No runner with the vHaaS tag is available to your project Verify your project can access the vHaaS runner; for external projects contact support
"Assembly not available" error The specified assembly is in use or you don't have access Check availability in the vHaaS web interface; add fallback assemblies: ASSEMBLY_REF: "ASSEMBLY-1, ASSEMBLY-2"; increase SESSION_TIMEOUT
"Authentication failed" error Invalid or expired vHaaS token Verify VEHAAS_TOKEN is set in GitLab CI/CD settings; check the token hasn't expired; ensure it has at least group_user role
Job fails mid-execution SESSION_DURATION expired before the job finished Increase SESSION_DURATION; optimize test scripts for faster execution
SSH connection error Network issue or VM startup problem Retry the job; contact support if the issue persists

Next Steps