GitLab: CI/CD

How to use GitLab CI/CD

👋 Welcome to the Stackhero documentation!

Stackhero offers a ready-to-use GitLab cloud solution designed for teams seeking a fast, secure, and scalable environment:

• Unlimited users, repositories, data transfers, and CI/CD processing time for complete flexibility.
• Effortless updates with a single click, keeping your environment up to date with no downtime.
• Custom domain name secured with HTTPS (for example, https://git.your-company.com) for a professional image and enhanced security.
• Consistent performance and robust security on your own private, dedicated infrastructure. No noisy neighbours and full isolation guaranteed.
• Choice of hosting location: 🇪🇺 Europe or 🇺🇸 USA to meet your compliance or latency requirements.

Get started quickly and focus on your code. Stackhero's GitLab cloud hosting solution is up and running in about 5 minutes.

Introduction

GitLab CI/CD is a powerful, integrated feature of GitLab, a widely used open-source platform for version control and collaboration. This tool enables you to automate and optimise the key stages of building, testing, and deploying your applications, ensuring faster and more reliable delivery of quality software.

For example, with GitLab CI/CD, you can configure automated unit tests that are triggered each time a new commit is pushed to a GitLab repository. Once these tests pass, your code can be built and deployed to a staging environment for further checks. After all staging tests are validated, the system can promote the code to production, making it available to end users.

One of the main advantages of GitLab CI/CD is its native integration within GitLab. This allows you to define and manage your CI/CD pipelines directly in your project repositories, simplifying the orchestration and monitoring of your entire workflow.

GitLab CI/CD supports a wide range of languages, frameworks, and tools, making it versatile enough to adapt to different types of projects. Its customisable pipeline system lets you tailor each stage of the CI/CD process to your requirements, whether for building, testing, or deploying to multiple environments.

In summary, GitLab CI/CD is a comprehensive solution designed to automate and improve software delivery processes. It enables developers to focus on writing and improving code, while the platform efficiently handles operational tasks.

How to build Docker images in your GitLab CI

If your project repository contains Dockerfile files, you can automate the building, running, and, if needed, publishing of your Docker images to a registry.

Step 1: Enable Docker in Docker (DinD) support

To begin, enable "Docker in Docker" (DinD) support from your Stackhero dashboard.

Enabling DinD support presents a security risk, especially if you want to isolate your users and prevent them from accessing each other's projects.

Step 2: Configure the GitLab CI pipeline

Next, update your gitlab-ci.yml file to include a pipeline configuration that builds your Dockerfile using DinD. Here is an example configuration:

image: docker:29

build:
  stage: build
  services:
    - name: docker:29-dind
      alias: docker
  variables:
    # Point the Docker CLI at the Docker-in-Docker service, via its plain
    # (non-TLS) port. See the note below about why DOCKER_HOST matters.
    DOCKER_HOST: "tcp://docker:2375"
    DOCKER_TLS_CERTDIR: ""
  before_script:
    - docker info
  script:
    # Replace "my-docker-image" with the name of your desired image:
    - docker build -t my-docker-image .
    # Optionally, test the Docker image:
    # - docker run my-docker-image /script/to/run/tests

The docker:29-dind service starts a Docker daemon alongside your job, and DOCKER_HOST tells the docker CLI to use it. Always set DOCKER_HOST when you declare a docker:dind service: if you omit it, the CLI silently connects to a different daemon, and your build may succeed even if the service is misconfigured, masking real issues. DOCKER_TLS_CERTDIR: "" allows the use of the plain, non-TLS port 2375 on the internal job network.

As a simpler alternative, you can remove the services block and both variables entirely: Stackhero's runner already exposes a ready-to-use Docker daemon via a mounted socket, so a simple docker build command works immediately.

For more information on building Docker images with GitLab CI, refer to the official GitLab documentation.

Running your tests with Testcontainers

If your test suite uses Testcontainers, a library that launches real services (databases, message brokers, etc.) as disposable Docker containers during test execution, the configuration above is already suitable. Keep the docker:29-dind service and both variables: Testcontainers uses DOCKER_HOST to access the Docker daemon and connect to the containers it starts, so no further configuration is required.

Omitting DOCKER_HOST is the most common cause of Testcontainers failures in CI. The library then falls back to the Docker socket mounted by the runner and cannot access its own test containers, which usually results in a timeout of the Ryuk helper container.