Imagine a world where your local development environment mirrors your production pipeline, ensuring consistency and catching bugs before they ever reach your codebase. That’s the power of using GitLab CI to run tests locally. Many developers believe that GitLab CI is solely for remote, automated builds and tests, but it can also serve as a robust local testing framework. By leveraging Docker and GitLab CI’s configuration files, you can create reproducible testing environments on your machine, drastically improving the reliability of your development workflow. This ensures that the tests you run locally are identical to those run in your CI/CD pipeline, reducing the risk of “it works on my machine” scenarios. Let’s explore how you can harness the full potential of GitLab CI for local testing and boost your development efficiency.

Why Use GitLab CI for Local Testing?

The primary advantage of employing GitLab CI for local testing revolves around environment consistency. Different operating systems, varying software versions, and inconsistent configurations can lead to discrepancies between local and remote testing environments. This often results in bugs that only appear in production, causing frustration and delays. By utilizing GitLab CI and Docker, you define a standardized testing environment that remains consistent regardless of where it’s executed. This eliminates the “it works on my machine” problem and ensures that your tests accurately reflect the behavior of your application in a production-like setting. According to a 2023 report by the Consortium for Information & Software Quality (CISQ), inconsistencies in development environments are a major source of software defects [¹].

Furthermore, GitLab CI provides a structured and automated approach to running tests. Instead of manually executing individual test commands, you define your testing process within a .gitlab-ci.yml file. This file outlines the steps required to build, test, and analyze your code. This automated process not only saves time but also reduces the risk of human error. Every time you run your tests locally using GitLab CI, you’re executing the same defined pipeline as the remote CI/CD system. This creates a feedback loop where local development closely mirrors the production pipeline, improving overall code quality and reducing deployment risks. Consider a scenario where a developer is working on a complex feature. Using GitLab CI locally, they can quickly validate their changes against the full test suite, ensuring that they haven’t introduced any regressions or compatibility issues. This proactive approach leads to fewer surprises during integration and deployment.

Finally, GitLab CI offers excellent support for parallel testing. By configuring multiple jobs in your .gitlab-ci.yml file, you can run tests concurrently, significantly reducing the overall testing time. This is particularly beneficial for large projects with extensive test suites. Parallel testing allows developers to receive faster feedback on their changes, enabling them to iterate more quickly and efficiently. For instance, if you have a suite of integration tests that take several hours to run sequentially, you can split them across multiple parallel jobs, reducing the testing time to just a fraction of the original duration. This increased speed directly translates to faster development cycles and quicker time-to-market.

Setting Up GitLab CI for Local Execution

To start using GitLab CI locally, you’ll need a few prerequisites: GitLab Runner and Docker. GitLab Runner is the agent that executes the CI/CD jobs defined in your .gitlab-ci.yml file. Docker provides the containerization technology to create isolated and reproducible environments. Install both GitLab Runner and Docker on your local machine. Once installed, register a GitLab Runner with your local machine, selecting the ‘docker’ executor. This tells the runner to use Docker containers to execute your CI/CD jobs. This initial setup is crucial for enabling local CI/CD pipelines.

Next, create a .gitlab-ci.yml file in the root of your project. This file defines your CI/CD pipeline, including the jobs to be executed, the Docker images to use, and the commands to run. A basic .gitlab-ci.yml file might define a job that builds your application and runs unit tests. You can customize this file to include any steps required for your specific project. For example, you might include steps to run linters, code analyzers, or integration tests. The key is to define all the steps required to validate your code and ensure its quality. The .gitlab-ci.yml file is the heart of your local testing setup, dictating how your tests are executed and what dependencies are required.

Once your .gitlab-ci.yml file is configured, you can execute your CI/CD pipeline locally using the gitlab-runner exec docker <job_name></job_name> command. This command tells the GitLab Runner to execute the specified job using the Docker executor. The runner will then pull the specified Docker image, create a container, and execute the commands defined in your .gitlab-ci.yml file. As an example, running gitlab-runner exec docker test will execute the ’test’ job defined in your .gitlab-ci.yml file. This provides a local simulation of your CI/CD pipeline, allowing you to catch errors and validate your code before pushing it to a remote repository.

Crafting a Robust .gitlab-ci.yml File

The .gitlab-ci.yml file is the cornerstone of your GitLab CI setup. A well-crafted file ensures reliable and reproducible tests. Start by defining the Docker image you want to use for your testing environment. This image should contain all the dependencies required to build and test your code. Consider using a pre-built image that already includes common tools and libraries, or create your own custom image with all the specific dependencies your project needs. This ensures that your testing environment is consistent across all executions, eliminating dependency-related issues. According to GitLab’s documentation, using a specific Docker image version is crucial for maintaining reproducibility [²].

Next, define the stages of your CI/CD pipeline. Common stages include ‘build’, ’test’, and ‘deploy’. Each stage can contain multiple jobs that run in parallel. Within each job, define the commands to be executed. These commands might include building your application, running unit tests, running integration tests, or performing code analysis. Use environment variables to configure your jobs and pass data between them. For example, you might use an environment variable to specify the database connection string or the location of your test data. This allows you to customize your testing environment without modifying your code. Ensure that your jobs are idempotent, meaning that they can be executed multiple times without causing unexpected side effects.

Finally, use caching to speed up your CI/CD pipeline. GitLab CI allows you to cache dependencies and build artifacts between jobs. This can significantly reduce the execution time of your pipeline, especially for large projects. For example, you can cache your project’s dependencies to avoid downloading them every time a job is executed. You can also cache build artifacts, such as compiled binaries, to avoid rebuilding them for each job. Caching can dramatically improve the efficiency of your CI/CD pipeline and reduce the time it takes to receive feedback on your changes. Here’s an example of how to define a cache in your .gitlab-ci.yml file:

cache: key: dependencies paths: - node_modules/ 

Advanced Techniques and Best Practices

Beyond the basics, several advanced techniques can further enhance your local GitLab CI experience. One such technique is using services. Services allow you to run dependent containers alongside your CI/CD jobs. For example, if your application requires a database, you can define a service that runs a database container. GitLab CI will automatically start the service container before your job is executed and stop it after the job is finished. This simplifies the process of setting up and managing dependencies for your tests. Consider using services to run databases, message queues, or other external systems that your application relies on. This ensures that your tests are executed in a realistic environment.

Another best practice is to use code quality tools as part of your CI/CD pipeline. These tools can automatically analyze your code for potential bugs, security vulnerabilities, and style violations. By integrating code quality tools into your pipeline, you can catch these issues early in the development process, before they become more difficult and costly to fix. Popular code quality tools include linters, static analyzers, and security scanners. Many of these tools can be easily integrated into your GitLab CI pipeline using pre-built Docker images or custom scripts. According to a study by SonarSource, integrating code quality tools into the CI/CD pipeline can reduce the number of bugs in production by up to 50% [³].

Finally, consider using GitLab CI’s merge request pipelines feature. Merge request pipelines allow you to automatically run your CI/CD pipeline whenever a merge request is created or updated. This provides immediate feedback on the changes being proposed in the merge request, allowing you to identify and fix any issues before the code is merged into the main branch. Merge request pipelines are a powerful tool for ensuring code quality and preventing regressions. They also promote collaboration and communication among developers by providing a shared view of the code’s quality and stability. You can explore more advanced features and integrations by checking out additional resources.

• Ensure environment consistency across development, testing, and production.
• Automate testing processes, reducing human error and saving time.

Featured Snippet: GitLab CI allows you to define a consistent testing environment using Docker, ensuring that tests run locally mirror those in your CI/CD pipeline. This eliminates “it works on my machine” issues by standardizing the environment. By defining the testing process in a .gitlab-ci.yml file, you automate the build, test, and analysis of your code. This structured approach improves code quality and reduces deployment risks by catching errors early in the development cycle.

• Leverage caching to speed up your CI/CD pipeline.
• Integrate code quality tools to catch bugs early.

FAQ

What is GitLab CI?

GitLab CI (Continuous Integration) is a tool built into GitLab for software development that allows you to automate the building, testing, and deployment of your code.

Why should I use GitLab CI locally?

Using GitLab CI locally ensures consistency between your development environment and your CI/CD pipeline, catching bugs earlier and reducing the risk of deployment issues.

What are the prerequisites for using GitLab CI locally?

You need to have Docker and GitLab Runner installed and configured on your local machine.

How do I run GitLab CI jobs locally?

Use the command `gitlab-runner exec docker ` in your terminal to execute the specified job defined in your `.gitlab-ci.yml` file.

¹: Consortium for Information & Software Quality (CISQ) - https://www.cisq-it.org/

²: GitLab Documentation - https://docs.gitlab.com/ee/ci/

³: SonarSource - https://www.sonarsource.com/

Question & Answer :
If a GitLab project is configured on GitLab CI, is there a way to run the build locally?

I don’t want to turn my laptop into a build “runner”, I just want to take advantage of Docker and .gitlab-ci.yml to run tests locally (i.e. it’s all pre-configured). Another advantage of that is that I’m sure that I’m using the same environment locally and on CI.

Here is an example of how to run Travis builds locally using Docker, I’m looking for something similar with GitLab.

Since a few months ago this is possible using gitlab-runner:

gitlab-runner exec docker my-job-name 

Note that you need both docker and gitlab-runner installed on your computer to get this working.

You also need the image key defined in your .gitlab-ci.yml file. Otherwise won’t work.

Here’s the line I currently use for testing locally using gitlab-runner:

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

Note: You can avoid adding a --docker-volumes with your key setting it by default in /etc/gitlab-runner/config.toml. See the official documentation for more details. Also, use gitlab-runner exec docker --help to see all docker-based runner options (like variables, volumes, networks, etc.).

Due to the confusion in the comments, I paste here the gitlab-runner --help result, so you can see that gitlab-runner can make builds locally:

gitlab-runner --help NAME: gitlab-runner - a GitLab Runner USAGE: gitlab-runner [global options] command [command options] [arguments...] VERSION: 1.1.0~beta.135.g24365ee (24365ee) AUTHOR(S): Kamil Trzciński <<a class="__cf_email__" data-cfemail="c9a8b0bcafa8a789a8b0bcafa8a7e7acbc" href="/cdn-cgi/l/email-protection">[email protected]</a>> COMMANDS: exec execute a build locally [...] GLOBAL OPTIONS: --debug debug mode [$DEBUG] [...] 

As you can see, the exec command is to execute a build locally.

Even though there was an issue to deprecate the current gitlab-runner exec behavior, it ended up being reconsidered and a new version with greater features will replace the current exec functionality.

Note that this process is to use your own machine to run the tests using docker containers. This is not to define custom runners. To do so, just go to your repo’s CI/CD settings and read the documentation there. If you wanna ensure your runner is executed instead of one from gitlab.com, add a custom and unique tag to your runner, ensure it only runs tagged jobs and tag all the jobs you want your runner to be responsible of.

Unofficial alternative gitlab-ci-local

There’s an unofficial package which looks promising, with more features than the official gitlab-runner exec: https://github.com/firecow/gitlab-ci-local

It allows you to run gitlab pipelines locally as shell executor or docker executor.