GitLab CI/CD

Automate build, test, and deployment of your WSO2 Integrator projects using GitLab CI/CD pipelines.

Overview

GitLab CI/CD uses a .gitlab-ci.yml file at the root of your repository to define pipeline stages. For WSO2 Integrator projects, the pipeline typically includes stages for building the Ballerina package, running tests, building a Docker image, pushing it to a container registry, and deploying to a target environment.

Prerequisites

• A GitLab project with your WSO2 Integrator (Ballerina) source code
• A container registry (GitLab Container Registry, Docker Hub, or a cloud provider registry)
• GitLab Runner available (shared or project-specific)
• Deployment target configured (Kubernetes cluster, VM, or cloud service)

Pipeline configuration

Create a .gitlab-ci.yml file at the root of your repository:

# .gitlab-ci.yml
image: ubuntu:22.04

variables:
  BAL_VERSION: "2201.10.0"
  DOCKER_IMAGE: "${CI_REGISTRY_IMAGE}/wso2-integrator-app"
  JAVA_HOME: "/usr/lib/jvm/java-17-openjdk-amd64"

stages:
  - build
  - test
  - docker
  - deploy

before_script:
  - apt-get update && apt-get install -y wget openjdk-17-jdk
  - wget -q https://dist.ballerina.io/downloads/${BAL_VERSION}/ballerina-${BAL_VERSION}-swan-lake-linux-x64.deb
  - dpkg -i ballerina-${BAL_VERSION}-swan-lake-linux-x64.deb

build:
  stage: build
  script:
    - bal build
  artifacts:
    paths:
      - target/
    expire_in: 1 hour

test:
  stage: test
  script:
    - bal test --code-coverage
  artifacts:
    when: always
    paths:
      - target/report/
    reports:
      junit: target/report/**/TEST-*.xml

docker-build:
  stage: docker
  image: docker:24
  services:
    - docker:24-dind
  variables:
    DOCKER_TLS_CERTDIR: "/certs"
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  script:
    - docker build -t "$DOCKER_IMAGE:$CI_COMMIT_SHA" -t "$DOCKER_IMAGE:latest" -f target/docker/wso2-integrator-app/Dockerfile .
    - docker push "$DOCKER_IMAGE:$CI_COMMIT_SHA"
    - docker push "$DOCKER_IMAGE:latest"
  only:
    - main
    - tags

deploy-staging:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl config use-context "$KUBE_CONTEXT"
    - kubectl set image deployment/wso2-integrator-app app="$DOCKER_IMAGE:$CI_COMMIT_SHA" -n staging
    - kubectl rollout status deployment/wso2-integrator-app -n staging --timeout=300s
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - main

deploy-production:
  stage: deploy
  image: bitnami/kubectl:latest
  script:
    - kubectl config use-context "$KUBE_CONTEXT"
    - kubectl set image deployment/wso2-integrator-app app="$DOCKER_IMAGE:$CI_COMMIT_SHA" -n production
    - kubectl rollout status deployment/wso2-integrator-app -n production --timeout=300s
  environment:
    name: production
    url: https://api.example.com
  when: manual
  only:
    - main

Build stage

The build stage compiles the Ballerina project and produces artifacts in the target/ directory. These artifacts are passed to subsequent stages.

build:
  stage: build
  script:
    - bal build
  artifacts:
    paths:
      - target/
    expire_in: 1 hour

When your project includes a Cloud.toml configuration, bal build generates Docker and Kubernetes artifacts alongside the executable JAR.

Test stage

The test stage runs all test functions and generates JUnit-compatible reports that GitLab displays in the merge request and pipeline views.

test:
  stage: test
  script:
    - bal test --code-coverage
  artifacts:
    when: always
    reports:
      junit: target/report/**/TEST-*.xml

Use when: always to ensure test reports are collected even when tests fail, making failures visible in the GitLab UI.

Docker build and push

The docker stage uses Docker-in-Docker (dind) to build the container image from the Dockerfile generated by bal build. The image is tagged with both the commit SHA (for traceability) and latest.

docker-build:
  stage: docker
  image: docker:24
  services:
    - docker:24-dind
  before_script:
    - docker login -u "$CI_REGISTRY_USER" -p "$CI_REGISTRY_PASSWORD" $CI_REGISTRY
  script:
    - docker build -t "$DOCKER_IMAGE:$CI_COMMIT_SHA" -f target/docker/wso2-integrator-app/Dockerfile .
    - docker push "$DOCKER_IMAGE:$CI_COMMIT_SHA"

Deploy stage

The deploy stage updates the Kubernetes deployment with the new image. For production, the when: manual flag requires a manual click in the GitLab UI to promote the build.

To use GitLab's Kubernetes integration, register your cluster under Settings > Kubernetes and reference the context via $KUBE_CONTEXT.

Secrets management

Store sensitive values as GitLab CI/CD variables under Settings > CI/CD > Variables. Mark them as Protected and Masked to limit exposure.

Variable	Description	Masked
CI_REGISTRY_PASSWORD	Container registry password	Yes
DB_PASSWORD	Database connection password	Yes
KUBE_CONTEXT	Kubernetes cluster context	No
API_KEY	External service API key	Yes

Reference these variables in your pipeline scripts or pass them to Config.toml via environment variables:

deploy-staging:
  stage: deploy
  variables:
    BAL_CONFIG_FILES: "config/staging-Config.toml"
  script:
    - export DB_PASSWORD="$DB_PASSWORD"
    - kubectl apply -f k8s/staging/

Merge request pipelines

Configure pipelines to run automatically on merge requests for early feedback:

test:
  stage: test
  script:
    - bal test
  rules:
    - if: $CI_MERGE_REQUEST_IID
    - if: $CI_COMMIT_BRANCH == "main"

What's next

• GitHub Actions -- CI/CD with GitHub-hosted runners
• Azure DevOps -- Pipeline configuration for Azure DevOps
• Jenkins -- Pipeline configuration for Jenkins