How to use GitLab CI in Docker

TLDR

• When deploying GitLab using Docker Compose, be sure to set external_url to ensure SSH and HTTP links are correct.
• If you need to use the artifacts feature, be sure to use Docker Volume instead of Bind Mount to avoid permission issues.
• If the GitLab Runner uses the Docker Executor, you must mount /var/run/docker.sock to call the external Docker Engine from within the container.
• When registering a Runner, if GitLab does not have a correct external_url set, you must manually specify clone_url in config.toml.
• The network_mode in .gitlab-ci.yml should not be set to host; it is recommended to use gitlab_default to avoid network conflicts.
• If you need to operate Docker during the deployment stage, it is recommended to mount docker.sock (Docker-outside-of-Docker) rather than using DIND.

Installing GitLab on Docker

When deploying GitLab in a Docker environment, it is recommended to use Docker Compose for management.

version: '3.7'

services:
  GitLab-Server:
    image: 'gitlab/gitlab-ee:latest'
    container_name: GitLab-Server
    environment:
      GITLAB_OMNIBUS_CONFIG: |
        external_url 'http://127.0.0.1:5080/'
        nginx['listen_port'] = 80
        gitlab_rails['gitlab_shell_ssh_port'] = 5022
    ports:
      - 5080:80
      - 5443:443
      - '5022:22'
    privileged: true
    volumes:
      - .\Volumes\GitLab-Server\Config:/etc/gitlab
      - data:/var/opt/gitlab
      - .\Volumes\GitLab-Server\Logs:/var/log/gitlab
    shm_size: '256m'
    networks:
      default:
        ipv4_address: 172.20.0.2
    restart: always
volumes:
  data:
networks:
  default:
    driver: bridge
    ipam:
      driver: default
      config:
        - subnet: 172.20.0.0/16
          gateway: 172.20.0.1

TIP

• external_url must be set, otherwise the SSH and HTTP link URLs for repositories will appear abnormal.
• If you are using a port other than 80, you must also set nginx['listen_port'].
• If you encounter an "invalid port specification" error, change 5022:22 in the ports configuration to a string format (by adding quotes).
• It is recommended to use a Volume for /var/opt/gitlab. Using Bind Mount may cause the artifacts feature to fail due to insufficient permissions.

Installing and Registering GitLab Runner on Docker

To execute CI/CD tasks, you need to deploy an additional GitLab Runner. If you use the Docker Executor, you must mount the Docker Socket.

  GitLab-Runner:
    image: gitlab/gitlab-runner:latest
    container_name: GitLab-Runner
    privileged: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
      - .\Volumes\GitLab-Runner\Config:/etc/gitlab-runner
    networks:
      default:
        ipv4_address: 172.20.0.3
    restart: always

Registration Process

Execute the command: docker exec -it GitLab-Runner gitlab-runner register.

• When will you encounter issues: When GitLab does not have external_url set or is using 127.0.0.1, the Runner may not be able to connect correctly.
• Solution: Manually add clone_url = "http://172.20.0.2" in config.toml.
• Configuration Key Points: In config.toml, set privileged to true and ensure volumes includes /var/run/docker.sock.

WARNING

network_mode must not be set to host, otherwise it may cause the GitLab service to become busy and unresponsive.

GitLab CI Example (.NET 6)

Define the Build, List, and Deploy stages via .gitlab-ci.yml.

stages:
  - build
  - list
  - deploy

build-job:
  stage: build
  image: mcr.microsoft.com/dotnet/sdk:6.0
  tags: ['docker', 'linux']
  script:
    - cd src/TestCore
    - dotnet restore
    - dotnet build --configuration Release
    - dotnet publish --configuration Release --output ../../build/publish
  artifacts:
    paths:
      - ./build/publish/*

deploy-job:
  stage: deploy
  tags: ['docker', 'linux']
  script:
    - cd build
    - docker build --tag $CI_PROJECT_PATH_SLUG:latest .
    - docker stop $CI_PROJECT_NAME || true && docker rm $CI_PROJECT_NAME || true
    - docker run -d -p 9080:80 --name $CI_PROJECT_NAME $CI_PROJECT_PATH_SLUG:latest

Key Technical Analysis

• Artifacts Transfer: Since each Stage is an independent Container, you must use artifacts to pass compiled files from build-job to deploy-job.
• Docker-outside-of-Docker: By mounting docker.sock, the Runner can directly call the host's Docker Engine to build and run containers. This method is more stable and easier to manage than DIND.
• Environment Variables: Use $CI_PROJECT_PATH_SLUG to handle project names, as Docker Image names do not support uppercase letters.



Change Log

• 2022-10-24 Initial document creation.