GitLab integration

If you use Katalon Studio for testing, you can integrate your tests into your GitLab CI/CD pipeline. This setup allows your tests to run automatically with each project update.

You can run your GitLab CI/CD jobs in a Docker container built from the Katalon Docker Image (KDI), which includes the latest versions of Google Chrome, Mozilla Firefox, and Katalon Studio. This Docker image is available on Docker Hub.

This tutorial shows you how to integrate your Katalon Studio project with GitLab CI/CD.

Important:

• A GitLab account.
• A Katalon Studio project in GitLab. You can clone or download the sample project on this GitHub repository: CI samples.
• GitLab Runners configured in your project. For more information about GitLab Runner, refer to this GitLab document: Ensure you have runners available.
• For self-hosted GitLab Runners, you need to install and run Docker. For installation instructions, see this Docker document: Get Docker.
• An active Katalon Runtime Engine floating license. See KRE floating license.

After preparing the sample GitLab project, you need to configure the essential components:

• The .gitlab-ci.yml file: A file containing CI/CD configurations.
• Katalon API key variable: A key representing your credentials for Katalon Studio and Katalon Runtime Engine.

Configure the .gitlab-ci.yml file

The .gitlab-ci.yml file contains settings that direct the GitLab CI/CD pipeline to execute Katalon Studio tests within a Docker environment.

To configure the .gitlab-ci.yml file, follow these steps:

1. Open the pipeline editor by selecting CI/CD > Editor on the left side bar.

   The editor will display the .gitlab-ci.yml file as follows:

   
   
   

2. Modify the file with your CI/CD configurations, including:

   • image: The Katalon Docker image that the job runs in. By default, katalonstudio/katalon uses the latest version of Katalon Studio. To use a specific version, input katalonstudio/katalon:<version_tag>, for example katalonstudio/katalon:8.1.2.

   • KATALON_PROJECT_DIR: Katalon Studio project directory. By default, it is stored under the root project folder.

   • script: Your desired katalonc commands. All of katalonc supported arguments can be found in Command syntax.

   # Requirements
   # A Katalon Studio project with the content saved in the root repository folder. If the project is under another location, you need to update KATALON_PROJECT_DIR with the corresponding value in the variable section
   # An active KRE license
   # A valid Katalon API key, which is stored as KATALON_API_KEY in Settings/CI/CD/Variables
   image: 'katalonstudio/katalon' # Use the latest version of Katalon Runtime Engine. We can also use other versions of Katalon Runtime Engine by specifying another tag, such as `katalonstudio/katalon:8.1.2` or `katalonstudio/katalon:8.3.0`
   services:
     - docker:dind
   variables:
     # Specify Katalon Studio project directory. By default, it is stored under the root project folder.
     KATALON_PROJECT_DIR: $CI_PROJECT_DIR
   stages:
     - test
   test_job:
     stage: test
     # Update your desired katalonc commands. All of katalonc supported arguments can be found in this document https://docs.katalon.com/katalon-studio/docs/console-mode-execution.html
     script:
       - katalonc.sh -projectPath=$KATALON_PROJECT_DIR -apiKey=$KATALON_API_KEY -browserType="Chrome" -retry=0 -statusDelay=20 -testSuitePath="Test Suites/TS_RegressionTest" 

   To learn more about configuration options, see Get started with GitLab CI/CD.

Configure the Katalon API Key variable

In the sample .gitlab-ci.yml file, we use the KATALON_API_KEY to represent the Katalon API key. You need to define this variable and specify its value in the project's settings.

To configure the Katalon API Key variable, follow these steps:

1. Go to Settings > CI/CD and expand the Variables section.
2. Select Add variable and specify these fields:
   • Key: KATALON_API_KEY.
   • Value: <Your Katalon API key>. For instructions on generating and viewing your API key, see Katalon API Key in Katalon TestOps.

   

3. Click Add variable.

Test the pipeline

After the configuration, you can start making changes to the project to test the CI/CD pipeline. GitLab CI/CD monitors the changes and runs the jobs specified in the .gitlab-ci.yml file.

To view the jobs running in your project, on the left sidebar, go to CI/CD > Jobs, and select a job.

GitLab displays our job log as follows:

The job log should display information about the Docker image in use and the output of the configured katalonc command.

To view test reports on TestOps, you can enable Katalon TestOps integration in your project. See TestOps integration.