How to Set Up a Katalon CI/CD Pipeline with GitHub Actions

If you are a Test Automation Engineer working with Katalon Studio, writing reliable test scripts is only half the battle. The real magic happens when you integrate those tests into a CI/CD pipeline, ensuring your suites run automatically on every code push or pull request.

Integrating the Katalon Runtime Engine (KRE) with GitHub Actions is one of the most powerful setups for QA teams. However, finding clear documentation on how to handle dynamic environments, test suite collections, and—most importantly—securely passing protected variables can be a nightmare.

In this comprehensive guide, I will walk you through exactly how to set up Katalon in GitHub Actions from scratch, explain the hidden trap of protected variables, and share a custom tool I built to automate the entire configuration process.

How Katalon Integrates with GitHub Actions

GitHub Actions provides cloud-based runners (like Ubuntu or Windows VMs) that can execute your code. Katalon provides an official GitHub Action (katalon-studio/katalon-studio-github-action) that automatically downloads the Katalon Runtime Engine, authenticates your license, and runs your project.

A basic workflow file (.github/workflows/katalon.yml) looks like this:

name: Basic Katalon Execution
on:
  push:
    branches: [ main ]

jobs:
  run-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Run Katalon KRE
        uses: katalon-studio/katalon-studio-github-action@v3
        with:
          version: '10.4.3'
          projectPath: '${{ github.workspace }}'
          args: '-noSplash -retry=0 -testSuiteCollectionPath="Test Suites/My_Collection" -apiKey="${{ secrets.KATALON_API_KEY }}"'

While this looks simple, it immediately breaks as soon as your tests require secure credentials like passwords, APIs, or database tokens. Here is why.

The Trap: Protected Variables in CI/CD

In Katalon Studio, best practice dictates that you mark sensitive Global Variables as <protected>true</protected> in your execution profile (e.g., Sandbox.glbl). When you run tests locally, Katalon decrypts these seamlessly.

But when you push your code to GitHub, Katalon intentionally strips out the actual values of protected variables to prevent hardcoded secrets from leaking into your Git history.

If you run the basic YAML script above, your cloud runner will try to log in to your portal or BrowserStack using empty strings (""). Your tests will fail immediately with errors like MalformedURLException or Invalid Credentials.

The Manual Fix: The -g_ Parameter

To fix this, you must store your actual secrets securely in GitHub Secrets (Settings > Secrets and variables > Actions) and explicitly pass them into the KRE command line using the -g_ prefix.

For example, if you have a protected Katalon variable named super_password, you must append this to your KRE arguments:

-g_super_password="${{ secrets.MY_GITHUB_SECRET }}"

When KRE sees the -g_ prefix, it knows to take the secure value from GitHub and inject it directly into your running test profile, masking it in the console logs.

The Solution: Automating the YAML Creation

Passing one variable manually is fine. But what if you are running a Test Suite Collection that tests both a Web Portal (Chrome Headless) and a Mobile App (BrowserStack)? You might have 15 to 20 protected variables: OTPs, Jira API keys, Jira tokens, technician numbers, and BrowserStack access keys.

Hand-typing 20 -g_ parameters into a YAML file is incredibly tedious. One typo, and the whole pipeline crashes. I got tired of doing this manually, so I built a web-based Katalon KRE YAML Generator to solve it permanently.

Step-by-Step: The Ultimate CI/CD Workflow

Here is my exact, optimized workflow for taking a Katalon project from local development to a fully automated, secure cloud pipeline.

Step 1: Optimize Your Katalon Execution Profile

In Katalon Studio, open your execution profile (e.g., Sandbox.glbl). Do not protect every single variable! Unprotect non-sensitive data like base URLs, timeouts, device names, or OS versions. If they are unprotected, Katalon will read them natively from your Git repository without any extra YAML configuration.

Only check the Protected box for actual secrets (Passwords, API Keys, Auth Tokens).

Step 2: Add Your GitHub Secrets

Go to your GitHub repository (Settings > Secrets and variables > Actions). Click New repository secret. Add your KATALON_API_KEY (required for the KRE license), and then add all the corresponding secure values for the variables you protected in Step 1.

Step 3: Generate the Pipeline File

Open the YAML Generator. Input your Katalon version, trigger branch, and Test Suite Collection path.

Under Variables Mapping, simply type your Katalon variable name on the left, and your GitHub Secret name on the right. Click Generate. The tool instantly writes the flawless, syntax-perfect katalon-run.yml file. Click "Download" and place it in the .github/workflows/ folder of your repository.

Step 4: Save Your Execution Reports

By default, GitHub Actions destroys the Ubuntu cloud runner as soon as the tests finish, which means your HTML/PDF reports would disappear. My generator automatically includes an actions/upload-artifact step at the end of the YAML file.

To view your results after a run, go to the Actions tab in GitHub, click on the completed run, and scroll down to the Artifacts section. Click Katalon-Reports to download your full execution history.

Common Challenges & Troubleshooting

Setting up CI/CD is rarely perfect on the first try. During my own setup process, I ran into a few frustrating roadblocks. Here is what to look out for if your pipeline fails:

1. The Dreaded MalformedURLException: no protocol

If your build fails instantly with this error, it usually means a URL variable (like a BrowserStack Hub URL or your testing Portal URL) is being read as a completely blank string. This happens if you accidentally set the URL as <protected>true</protected> in Katalon but forget to pass it in your YAML file.
Fix: Either unprotect the URL in your profile (if it contains no actual passwords) or ensure you are passing it properly via the GitHub Actions UI.

2. Silent Failures (Empty Strings in Inputs)

If you watch your test execution logs and see something like Text '' has been set to element 'Input_PhoneNumber', GitHub Actions is passing a blank value. This almost always means there is a typo between your YAML file (e.g., ${{ secrets.TECH_NUMBER }}) and the actual name you typed into the GitHub Secrets UI (e.g., TECH_NUMBER_VAR). They must match exactly; otherwise, GitHub silently ignores it.

3. Web Driver Mismatches on Cloud Runners

When running Chrome Headless tests on ubuntu-latest, the runner's installed Chrome browser might update faster than the ChromeDriver bundled in your Katalon project, causing immediate session failures.
Fix: Always include --config -webui.autoUpdateDrivers=true in your KRE arguments. My generator tool automatically appends this for you!

Conclusion

By standardizing your Katalon CI/CD pipeline and automating the generation of the YAML file, you eliminate syntax errors, speed up onboarding for other QA engineers, and enforce strict security standards for your automation framework.

I hope this guide helps you untangle the complexities of Katalon and GitHub Actions. Have you built any custom workflows or tools to help with your test automation infrastructure? Let me know your thoughts or connect with me below!