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 on 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
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.
OPENTF_CONFIG, is typically shared. It references your OpenTestFactory
Depending on your preferences and security requirements, you can share the other variable,
OPENTF_TOKEN, between your projects or define one per project.
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
--token=command line options below.
OPENTF_CONFIG variable should contain your orchestrator configuration file, that
is, the information needed to reach your orchestrator instance.
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 ports: agentchannel: 24368 eventbus: 38368 killswitch: 7776 observer: 7775 receptionist: 7774 server: http://127.0.0.1 users: - name: me user: token: aa
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 ports: agentchannel: 80 eventbus: 80 killswitch: 80 observer: 80 receptionist: 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 on your current directory, and use the
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
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 your token. It should be of type
The two environment variables,
OPENTF_TOKEN, will be available for use
in your pipeline jobs.
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 on your execution environments.
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.
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
# 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 - opentf-ctl run workflow .opentf/workflows/workflow.yaml --wait
pip install ... part ensures that the most recent version of
available on the runner, and the
opentf-ctl run ... part runs the workflow and
shows its progress.
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
file, prefixing them with
OPENTF_RUN_, or pass them using the
-e command line
option (without the
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
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
command line options, the last definition wins.)
The following example will run a
.opentf/workflows/my_workflow_2.yaml workflow, providing it
file file (which content will be the one of
my_data/file.xml) and two environment variables:
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 - opentf-ctl run workflow .opentf/workflows/my_workflow_2.yaml -f file=my_data/file.xml -e FOO=12 --wait variables: OPENTF_RUN_TARGET: "https://example.com/target"
opentf-ctl tool you just used offers additional options that can be useful in some contexts.