GitLab Pipeline Integration With Subject7

Overview 

In this comprehensive guide, we will walk you through the process of integrating Subject7 with Gitlab Pipelines. It is assumed that you are well-acquainted with Gitlab and possess a fundamental understanding of programming, particularly in Python.

Whether you're a seasoned developer or just starting, this document will provide you with clear, step-by-step instructions to successfully set up the integration between Subject7 and Gitlab, ensuring a seamless workflow for your projects.

GitLab pipelines are a powerful tool for automating your software development and deployment workflows. One common use case is to call a REST API as part of your pipeline. In this article, we'll walk you through the process of creating a GitLab pipeline stage named 'daily-run' using Python to call a REST API. We'll break down each section of the GitLab CI/CD configuration file to explain its purpose.

In this guide, we will walk you through the process of setting up a GitLab pipeline named "daily_run." This pipeline consists of several crucial stages, including "build," "deploy," and "execute tests." The "build" and "deploy" stages are responsible for building and deploying the app on the target server. However, the real integration happens when we reach the "test" stage. Here, we leverage the Subject7 REST API to initiate the execution of a predefined test set (i.e. Execution Set), which essentially comprises a collection of test cases. Based on the outcomes of this execution, we gain the flexibility to make informed decisions, essentially to fail the build or promote the build to the next stages of the pipeline. Main Subject7 REST API functions: 

1. Start an Execution 

2. Query the results of an execution 

3. Get the artifacts of an execution (video, logs, etc.) 

Setting up the 'daily-run' Stage

Here's an example GitLab CI/CD configuration for a 'daily-run' stage with comments explaining each section:

start daily run (prod):
# Set up the environment before running the script
before_script:
- before_running_the_script.sh && the_environment_you_must_set_up.sh

# Set a timeout for the stage
timeout: 2h 30m

# Define when the stage should run based on pipeline source
rules:
- if: $CI_PIPELINE_SOURCE == "push"
when: manual

# Specify the dependencies of this stage
needs:
- build
- build docker
- deploy to server

# Define the Docker image for this stage
image: python

# Specify the stage name
stage: daily-run

# Define the script to run in this stage
script:
# SSH into a remote server and perform Docker-related tasks within an environment
- docker_related_tasks_within_an_environment.sh && perform_you.shall
# Install Python dependencies, and run tests with provided variables
- cd ci/tests && pip3 --disable-pip-version-check install -r ./requirements.txt && python3 ./run_tests.py $HOST_TEST $S7_API_KEY $EXECUTION_SETS

before_script

The before_script section contains commands that run before the main script.

timeout

The timeout specifies the maximum amount of time the stage is allowed to run. In this case, it's set to 2 hours and 30 minutes to allow for long-running tasks.

rules

The rules section defines when the stage should be executed. In this example:

• If the pipeline source is a 'push' (manual trigger), the stage will be executed manually.

needs

The needs section lists dependencies for the stage. This means the 'daily-run' stage will only run if the specified previous stages ('build', 'build docker', 'deploy to server') are successful.

image

The image section specifies the Docker image to use for this stage. In this case, it's using the 'python' image.

stage

The stage section defines the name of the stage. Here, it's named 'daily-run.'

script

The script section contains the actual commands to execute in this stage. In this example:

• Runs tests with the provided variables.

By following these guidelines, you can create a 'daily-run' stage in your GitLab pipeline that efficiently calls a REST API using Python. This automation can help streamline your development and deployment processes, ensuring consistent and reliable results.

Setting up environment variables

Setting up environment variables in GitLab CI/CD for your project is a straightforward process. Environment variables can be used to store sensitive or configuration information that your CI/CD jobs require. Here's how you can set up the $HOST_TEST, $S7_API_KEY, and $EXECUTION_SETS variables in GitLab:

1. Navigate to Your Project:

   Log in to your GitLab account, and go to the project for which you want to set up these variables.

2. Access CI/CD Settings:

   • In your project, click on "Settings" in the left sidebar.

   • Under "General," select "CI/CD."

3. Expand the "Variables" Section:

   Scroll down to find the "Variables" section. This is where you can define and manage environment variables for your CI/CD jobs.

4. Define the Environmental Variables:

   • Click on the "Add Variable" button to create a new environment variable.

     • For $HOST_TEST:

       • Variable Key: HOST_TEST

       • Variable Value: The value you want to set as the host for testing.

     • For $S7_API_KEY:

       • Variable Key: S7_API_KEY

       • Variable Value: The API key or secret that you want to set.

     • For $EXECUTION_SETS:

       • Variable Key: EXECUTION_SETS

       • Variable Value: The value or data you want to set for EXECUTION_SETS.

   • You can also mark variables as protected if they contain sensitive information that should not be exposed in the logs.

5. Save the Variables:

   After entering the variable details, click the "Add Variable" button to save them.

6. Usage in GitLab CI/CD Pipeline:

   Now that you've defined these variables, you can reference them in your GitLab CI/CD pipeline configuration (.gitlab-ci.yml) as shown in your previous example:

script:
- cd ci/tests && pip3 --disable-pip-version-check install -r ./requirements.txt && python3 ./run_tests.py $HOST_TEST $S7_API_KEY $EXECUTION_SETS

The pipeline will automatically substitute the values you defined in the CI/CD variables when executing this script during the pipeline run.

By setting up these environment variables, you can keep sensitive information and configuration separate from your code, making it easier to manage and secure your CI/CD process.

Python Script for Managing Test Executions via REST API

This script interacts with a REST API and continuously checks the status of test executions.

import time
import requests
import sys
import datetime

# Function to log the current time
def log_time():
current_time = datetime.datetime.now()
print("Time now at Greenwich Meridian is:", current_time)

# Display a starting message
print("Starting test ...")
log_time()

# Define the final states for test executions
FINAL_STATES = ['COMPLETED', 'ERROR', 'CANCELLED', 'NONE', 'GATEWAY DENIED']

# Extract command-line arguments
host = sys.argv[1]
header = sys.argv[2]
execution_sets = sys.argv[3].split(',')
ids = []

# Loop through each execution set and initiate test runs
for es in execution_sets:
print("Running for the next test suite: {execution_set}".format(execution_set=es))
# Make a POST request to create a new test execution
resp = requests.post("{host}/api/v2/executions".format(host=host), json={'name': es},
headers={'X-API-KEY': header, 'Content-Type': 'application/json'})
print("Got response: \n {resp}".format(resp=resp))
e_id = resp.json()['id']
ids.append(e_id)

log_time()

# Continuous loop to check the status of test executions
while True:
time.sleep(20)
ids_to_rm = []
log_time()

# Check the status of each test execution
for e_id in ids:
resp = requests.get("{host}/api/v2/executions/{e_id}".format(host=host, e_id=e_id),
headers={'X-API-KEY': header})
state = resp.json()['executionState']
print("Status {status} for execution {execution}".format(status=state, execution=e_id))

# If the test execution is in a final state, mark it for removal
if state.upper() in FINAL_STATES:
ids_to_rm.append(e_id)

# Remove completed test executions from the list
for rm_id in ids_to_rm:
ids.remove(rm_id)

# If all test executions are completed, exit the loop
if len(ids) == 0:
break

This script should provide better clarity and readability. This is just one way to implement such functionality, and users are free to adapt it to their specific needs and preferences.