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.