Running GitLab CI Builds Locally with Docker

If you have a GitLab project configured with a .gitlab-ci.yml file, you can run your builds locally using Docker. This approach allows you to maintain consistency between your local environment and the CI environment, ensuring that tests run in the same conditions.

Prerequisites

To get started, make sure you have the following installed on your machine:

  • Docker
  • GitLab Runner

Steps to Run Builds Locally

  1. Install GitLab Runner: Follow the official installation guide for your operating system.

  2. Use the GitLab Runner Command: You can execute your CI jobs locally by using the following command:

    gitlab-runner exec docker <job-name>

    Replace <job-name> with the name of the job defined in your .gitlab-ci.yml file.

  3. Configure Docker Volumes (if necessary): If your job requires specific files or configurations, you can mount volumes. For example:

    gitlab-runner exec docker <job-name> --docker-volumes "/path/to/local/file:/path/in/container"

    This command allows you to share files between your local machine and the Docker container.

Example Command

Here’s a sample command that runs a job named test while mounting an SSH key:

gitlab-runner exec docker test --docker-volumes "/home/user/.ssh/id_rsa:/root/.ssh/id_rsa:ro"

Additional Options

To explore more options available with gitlab-runner exec, you can run:

gitlab-runner exec docker --help

This will provide you with details on available flags and configurations.

By following these steps, you can effectively run your GitLab CI jobs locally, leveraging Docker to replicate your CI environment without the need for a dedicated CI runner.