Integrate with gitlab-ci

GitLab is a platform where you can create and build applications. You can use your own instance or an existing one.

In the following guide, you will update a GitLab project with its own OpenTestFactory workflow that will run whenever you push changes in your project.

You need to have access to a project on a GitLab instance, and you need to be able to start a GitLab pipeline on that project.

You also need to have access to a deployed OpenTestFactory orchestrator instance, with a corresponding token, that is accessible from the GitLab instance.

You will use the opentf-ctl tool.

Preparation

You need to define two environment variables. You can do this at your group level or at your project level.

If you define them at group level, all your projects in the group will be able to use them. That can be quite handy if you use many projects. If you define them at project level, only this project will see them. If you define a variable at group and project level, the definition at project level wins.

One variable, OPENTF_CONFIG, is typically shared. It references your OpenTestFactory orchestrator instance.

Depending on your preferences and security requirements, you can share the other variable, OPENTF_TOKEN, between your projects or define one per project.

Information

If you do not want to give those variables those names, you can freely change them, but then you will have to specify them explicitly in your GitLab pipeline, using the --opentfconfig= and --token=command line options below.

OPENTF_CONFIG

The OPENTF_CONFIG variable should contain your orchestrator configuration file, that is, the information needed to reach your orchestrator instance.

Local deployment

If you are using a local deployment, on your workstation, as for example described in Docker compose deployment, it will probably look something like the following:

apiVersion: opentestfactory.org/v1alpha1
contexts:
- context:
    orchestrator: my_orchestrator
    user: me
  name: my_orchestrator
current-context: my_orchestrator
kind: CtlConfig
orchestrators:
- name: my_orchestrator
  orchestrator:
    insecure-skip-tls-verify: false
    services:
      receptionist:
        port: 7774
      agentchannel: 
        port: 24368
      eventbus: 
        port: 38368
      killswitch: 
        port: 7776
      observer: 
        port: 7775
      qualitygate: 
        port: 12312
    server: http://127.0.0.1
users:
- name: me
  user:
    token: aa

Non-local deployment

If you are using a non-local deployment, on your intranet or open to the internet, as for example described in Kubernetes deployment, it will probably look something like the following.

(In the example below, the HTTP protocol is used. If your deployment is using the HTTPS protocol, which is strongly recommended, replace the port values with 443.)

apiVersion: opentestfactory.org/v1alpha1
contexts:
- context:
    orchestrator: my_orchestrator
    user: me
  name: my_orchestrator
current-context: my_orchestrator
kind: CtlConfig
orchestrators:
- name: my_orchestrator
  orchestrator:
    insecure-skip-tls-verify: false
    services:
      receptionist:
        port: 80
      agentchannel: 
        port: 80
      eventbus:
        port: 80
      killswitch:
        port: 80
      observer:
        port: 80
      qualitygate:
        port: 80
    server: http://example.com
users:
- name: me
  user:
    token: aa

Testing your configuration file

If you have not tested your configuration file before, it is a good idea to test it now.

On your workstation, install the opentf-tools package, using the following command:

pip install --upgrade opentf-tools

Then, copy your configuration in a config file in your current directory, and use the following command:

opentf-ctl get workflows --opentfconfig=config --token=YOURTOKEN

You should get something like:

WORKFLOWID
6c223f7b-3f79-4c51-b200-68eaa33c1325
31b5e665-819c-4e92-862a-f05d1993c096

Please refer to “Tools configuration” for more information on making your configuration file if needed.

Defining the variable

Go to your project (or group) Settings/CI/CD panel and search for the Variables section.

In this section, add a new variable OPENTF_CONFIG with the value above. It should be of type File.

OPENTF_TOKEN

The OPENTF_TOKEN variable should contain the token you want to use to communicate with the orchestrator.

Defining the variable

Add a new variable OPENTF_TOKEN with the value of your token. It should be of type Variable.

The two environment variables, OPENTF_CONFIG and OPENTF_TOKEN, will be available for use in your pipeline jobs.

Security

In the screenshots above, the variables have been flagged as “Protected variables”. It means they will only be usable from protected branches and tags, which is a good practice: you do not expose your token to everybody with access to your project, and you prevent possible undesired code execution in your execution environments.

Integration

Now that your two environment variables are defined, you are ready to integrate your OpenTestFactory orchestrator within your GitLab CI/CD.

This section assumes a basic knowledge of GitLab CI/CD. See “Getting started with GitLab CI/CD” for more information.

Note

There is no required location for your project’s workflows, but it is a good practice to put them in a single location. .opentf/workflows is a good candidate.

Running a workflow

If you have a .opentf/workflows/workflow.yaml orchestrator workflow in your project, you can use the following .gitlab-ci.yml file to run it each time you make changes to your project.

# A very simple pipeline with a single "test" stage made of a single workflow "job"

default:
  image: python:3.8

stages:            # List of stages for jobs, and their order of execution
  - test

opentf-workflow:   # This job runs in the build stage, which runs first.
  stage: test
  script:
    - pip install --upgrade opentf-tools
    - RESULT=$(opentf-ctl run workflow .opentf/workflows/workflow.yaml)
    - echo $RESULT
    - WORKFLOW_ID=$(echo $RESULT | awk -F ' ' '{print $2}')
    - opentf-ctl get workflow $WORKFLOW_ID --watch
    - opentf-ctl get qualitygate $WORKFLOW_ID --mode=strict

The pip install ... part ensures that the most recent version of opentf-ctl is available on the runner, and the opentf-ctl run ... part runs the workflow.

We are storing the ID of the launched workflow (retrieved from the run workflow’s output) in the $WORKFLOW_ID variable.

The opentf-ctl get workflow $WORKFLOW_ID --watch command is used to follow the workflow’s execution.

The opentf-ctl get qualitygate $WORKFLOW_ID --mode=strict command is used to check the test results. This is not a mandatory step but it’s highly recommended. With the mode set to strict, if one of the tests failed then the command will exit with a return code of 102, failing the pipeline. Without calling the quality gate, the pipeline will be in success regardless of the test results. See “Running commands (get qualitygate)” for more information.

Sharing files and variables

Sometimes, you need to share information—variables or files—for your workflow to work.

For variables, you can do it through the variables statement in your .gitlab-ci.yml file, prefixing them with OPENTF_RUN_, or pass them using the -e command line option (without the OPENTF_RUN_ prefix).

For files, you pass them using the -f my_file=my_file_path command line option.

You can use those options more than once. For variables, if a variable is defined both in the variables section and using the -e command line option, the command line option definition wins. (And if you have multiple definitions of a given variable using the -e command line options, the last definition wins.)

The following example will run a .opentf/workflows/my_workflow_2.yaml workflow, providing it with a file file (which content will be the one of my_data/file.xml) and two environment variables: FOO and TARGET.

default:
  image: python:3.8

stages:            # List of stages for jobs, and their order of execution
  - test

opentf-workflow:   # This job runs in the build stage, which runs first.
  stage: test
  script:
    - pip install --upgrade opentf-tools
    - RESULT=$(opentf-ctl run workflow .opentf/workflows/my_workflow_2.yaml -f file=my_data/file.xml -e FOO=12)
    - echo $RESULT
    - WORKFLOW_ID=$(echo $RESULT | awk -F ' ' '{print $2}')
    - opentf-ctl get workflow $WORKFLOW_ID --watch
    - opentf-ctl get qualitygate $WORKFLOW_ID
  variables:
    OPENTF_RUN_TARGET: "https://example.com/target"

Next steps

The opentf-ctl tool you just used offers additional options that can be useful in some contexts.

• “Running workflows“