CI/CD Runners¶

This guide explains how continuous integration and continuous delivery (CI/CD) works on the Synderys GitLab instance, including how to use the available runners and write pipeline configurations.

What Is CI/CD?¶

CI/CD automates the process of building, testing, and deploying your code. When you push changes to a GitLab repository, a pipeline runs automatically to verify your code. Pipelines are defined by a .gitlab-ci.yml file in the root of your repository.

A pipeline consists of stages (such as build, test, and deploy), and each stage contains one or more jobs. Jobs run on runners — dedicated servers that execute your pipeline commands inside containers.

Available Runners¶

Synderys provides 3 shared runners available to all projects:

Runner	Type	Description
Runner 1	Docker executor	General-purpose runner for build and test jobs
Runner 2	Docker executor	General-purpose runner for build and test jobs
Runner 3	Docker executor	General-purpose runner for build and test jobs

All runners use the Docker executor, which means each job runs inside an isolated container. You specify the container image in your .gitlab-ci.yml file.

What to expect

When you push code, GitLab assigns your pipeline jobs to an available runner automatically. You do not need to select a runner — the system handles scheduling and load balancing across all three runners.

Writing a Pipeline Configuration¶

Create a file named .gitlab-ci.yml in the root of your repository. Here is a minimal example:

stages:
  - build
  - test

build-job:
  stage: build
  image: node:20
  script:
    - npm ci
    - npm run build

test-job:
  stage: test
  image: node:20
  script:
    - npm ci
    - npm test

Key Concepts¶

stages — defines the order of execution. Jobs in the same stage run in parallel; stages run sequentially.
image — the Docker image used for the job. Choose an image that has the tools your project needs.
script — the commands to run inside the container. These are your build, test, or deploy commands.

Viewing Pipeline Results¶

In your project, click Build > Pipelines in the left sidebar.
You will see a list of recent pipelines with their status (passed, failed, or running).
Click on a pipeline to see its stages and jobs.
Click on an individual job to see its console output and any error messages.

What to expect

A green checkmark means the pipeline passed. A red X means one or more jobs failed. Click into the failed job to read the error output and diagnose the issue.

Pipeline Triggers¶

Pipelines run automatically when you:

Push commits to any branch
Create or update a merge request
Trigger a pipeline manually from the GitLab UI

You can control which branches trigger pipelines using rules in your .gitlab-ci.yml file:

deploy-job:
  stage: deploy
  script:
    - echo "Deploying..."
  rules:
    - if: $CI_COMMIT_BRANCH == "main"

This job only runs when changes are pushed to the main branch.

Using the Container Registry in Pipelines¶

Pipelines can push and pull images from the Synderys container registry without additional authentication. GitLab provides a built-in CI/CD token automatically:

build-image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
    - docker build -t $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA

Troubleshooting FAQ¶

Q: My pipeline is stuck in "pending" status. : All runners may be busy with other jobs. Wait a few minutes for a runner to become available. If the pipeline stays pending for more than 15 minutes, contact IT.

Q: My job fails with "image not found" or "pull access denied". : Check that the Docker image name in your .gitlab-ci.yml is correct and publicly available (or stored in the Synderys container registry). Private images from external registries require authentication configuration.

Q: Where do I find the pipeline status badge for my project? : Go to your project > Settings > CI/CD > General pipelines. Copy the pipeline status badge URL to display it in your README.

Q: Can I run a pipeline manually without pushing code? : Yes. Go to Build > Pipelines, click Run pipeline, select the branch, and click Run pipeline again.

Q: My pipeline takes too long. How can I speed it up? : Use caching for dependencies (such as node_modules or Python virtualenvs), split large jobs into parallel jobs, and choose slim Docker images to reduce pull times.