Starting a GitLab Runner using the veHaaS CI Template

Since starting a GitLab Runner on a veHaaS assembly und triggering a child pipeline on it is a very common task, we created the veHaaS CI template that gets you going quickly. By including the template you can make session booking and child pipeline initiation work just by passing some inputs to it.

Video Tutorial and Examples

We strongly advise to have a look at our Video Tutorial which includes the access token setup as well as the template integration into a GitLab project. It goes into a lot more depth about different use-cases and features of the CI template. Additionally you can always have a look at our Example Repositories that also demonstrate different features of our CI template.

Creating a veHaaS token

Our CI template uses the veHaaS CLI client for interacting with the API which in turn requires a veHaaS access token that has a GitLab token linked to it. To create such a token you can follow chapters Create a Technical User and Pairing the GitLab Runner.

Including the CI template

Once you have a veHaaS access token you can include the template inside of your .gitlab-ci.yaml like so:

include:
  - project: "templates/pes-pipeline-templates"
    file: "/.vehaas-gitlab-ci.yml"
    inputs:
      sessionDurationMinutes: 10
      vehaasToken: $VEHAAS_TOKEN
      assemblyRef:
        - ASSEMBLY-0
      pipelinePath: ".vehaas/pipelines/build-pipeline.yml"

The CI template takes inputs. Some of them are required while others are optional and only required for some use-cases:

Input Name	Required	Type	Default Value	Description
vehaasToken		string		A veHaaS access token used for creating a session request. The veHaaS token is used to book an assembly, so please make sure that the token has sufficient permissions to view and book the assembly. More details on veHaaS access tokens can be found here Access tokens documentation
sessionDurationMinutes		number		The duration in minutes for the veHaaS session. This is the time the allocated veHaaS session is available for the pipeline execution. After this time execution on the veHaaS runner will be stopped and you will be logged off from the veHaaS VM.
pipelinePath		string		The path to the CI/CD YAML file containing the jobs that should be executed on the allocated veHaaS session.
requestProfilePath		string		The path to the veHaaS request profile json file. The content must follow the RequestProfile schema which can be found in our API Documentation
assemblyRef		array	[]	A list of assembly references that should be used for the veHaaS session. If multiple assembly references are given, the first available one will be used. This input is ignored if the requestProfilePath is set.
jobName		string	default	The name of the template instance. This input is only necessary if you need to use this template multiple times in the same project. The jobName also determines the location of the child pipeline artifacts. All artifacts will be placed under $[[inputs.jobName]]/{childPipelineJobName}/. If for example you are generating an artifact called test.txt in a pipeline job called childJob of the child pipeline and passed testName for this input, the resulting artifact can be accessed in later stages of the pipeline under /testName/childJob/test.txt.
gitlabToken		string		A GitLab project token which is used in order to retrieve child pipeline artifacts and environment variables. The token needs to have the api scope and at least the Developer role. You can use the GitLab Token that is used for the veHaaS token configuration. If no token is provided, the artifact collection step is skipped and therefore no artifacts or environment variables of child pipelines are available in the main pipeline.
vehaasUrl		string	https://vehaas.vi.vector.int	The URL of the veHaaS instance. This should normally not be changed except you want to test against staging. Defaults to https://vehaas.vi.vector.int.
timeoutMinutes		number	10	The maximum time in minutes to wait for the veHaaS session to be allocated. If no session is available after this duration the allocate job fails and no pipeline is executed on the veHaaS VMs. Defaults to 10 minutes.
stage		string	test	The stage in which the veHaaS CI template steps should be executed. Defaults to test.
rules		array	[if: $CI_MERGE_REQUEST_ID]	The rules for the veHaaS CI template jobs. Defaults to merge requests.

Example Repositories

Example repositories demonstrating different features of the CI template are available on request via the support page.

Video Tutorial

For a full tutorial on setting up a repository with the veHaaS CI template, please contact us via the support page.