1. Introduction
2. Prerequisites
3. Setup the Configuration File
4. Setup the Jobs
5. Setup the Necessary CI Variables
6. Extra Information Regarding Our Predefined Scripts

Introduction

This page will show you how to utilize the available predefined scripts to set up your first Gitlab-CI jobs with ease. Setting up the development environment for CET for the first time could be tricky. Especially, if you are not familiar with the necessary requirements to run CET. Luckily, CET Developer or Operator does all this for us when we set up our development environment for the first time. But when it comes to running jobs on runners, we need to set up the whole environment before each job. This way we can ensure that the jobs like builds and tests always give accurate results.

Luckily, you do not have to create your own setup script as long as you use our predefined setup scripts. The scripts also provide you a cleanup script and it uploads the log-files after the script finishes. Please note that our predefined scripts only works with powerShell. This means that if you like to use our scripts you have to use powerShell syntax in your jobs.

Prerequisites

• Maintainer access to the repository you will be setting up the runner for.
• Already setup runner(s) for your Gitlab repository. Otherwise, please read the Installing GitLab Runner on Windows section here.
• Administrator access to the runner computer.
• CET Developer version on the runner computer should be the latest available and logged into CET Developer with the same Email as Windows.

Setup the Configuration File

First, you need to create a file named .gitlab-ci.yml where you put the following code:

The defined stages are just for demo purposes. You can name them exactly as you would like to. All jobs within a stage can run in parallel as long as there are available runners that can pick them up. A job stage will not start until all the jobs in the previous stage are finished.

Please note that stages are not needed if you just want to run a single job or would like to run all jobs in parallel with no jobs dependent on the success/failure state of the previous one.

The code also includes the generalSimpleQuickStart.yml file from the master branch in the cet/external/ci repository. This will give us all the predefined scripts like the script to setup the CET development environment. If you have any issues including this file, please contact us.

Setup the Jobs

Jobs can be anything you would like your runners to do. In this example, we are demonstrating how to run a test. 

First, we need to choose a job name. In this example, we chose Test Bill of Material. Next, we need to fill in the keywords: stage, extends, script and only. Only the keyword script is mandatory and the stage keyword becomes mandatory if you have defined any stages. These are the keywords you might need in the beginning but there are a lot of other keywords that you may find useful. You can find them here.

stage: The stage this job will be included in.

extends: Inherit from other script(s).

script: The job itself, like build, test, etc. Anything you can run in the PowerShell terminal, you can also run here.

only: Limit the job to the specific event. For example, only in merge requests.

To use our predefined setup script, it is important that you inherit your job from the SimpleQuickStartAllStages job. In the script section, we choose to run the csXmlTests via cop.exe. Cop.exe will be available in ci\cop\ if you use our predefined script. It is a command-line version of our beloved CET Developer or Operator. This means you can run any tests or builds defined in your customBuildItems.xml that you used to run via Build Central in CET Developer or Operator. You can read more about customBuildItems.xml here.

The corresponding buildItem in customBuildItems.xml:

Setup the Necessary CI Variables

To run our predefined setup script these variables need to be setup in your CI variables. You can find the CI variables on your Git repository settings page:

CI_GITLAB_TOKEN: A Gitlab token with at least read access to base.

CI_BASE_BRANCH: The base branch you would like to use. For example: version10.0 or version10.5.

Congratulations! You should have your first Gitlab CI job-ready to run. To try it out. Please push the .gitlab-ci.yml file to the git server and you should see a pipeline started in the pipeline page of your git repository page at git.configura.com. If you choose to only run on merge requests, you also have to create a merge request to see any results.

Extra Information Regarding Our Predefined Scripts

Our predefined scripts have some extra features if you choose to run on merge requests. The script will first simulate the merged result of the merge request locally and then run the build or test. This is normally a Gitlab premium feature offered by Gitlab but our script does this for you. Without our script, the pipeline is first running on the source branch, and then after the merge request has been merged it will run on the target branch. This means that errors and bugs that are a result of a merge can get through the pipeline as long as the source branch were fine. You do not need to worry about this if you use our scripts!