Testing your GitLab Pipeline locally

CI/CD pipelines are an integral part of professional software development setups nowadays. For instance, they run tests, build containers and push them. When developing complex pipeline configurations, debugging variables, or testing new CI/CD features, changes to the pipeline are often evaluated directly on the CI-Server by pushing and waiting for the result. This might work but can significantly slow down the iteration cycle. Why not run these pipelines locally, like you would run your test suite before?

Enter gitlab-ci-local: a practical tool that enables you to validate and debug GitLab CI pipelines directly on your local machine before deploying changes to your GitLab instance.

Requirements

gitlab-ci-local executes pipeline jobs in containers, so you’ll need to have Docker installed and running on your system before getting started.

Installation

Installing gitlab-ci-local is pretty straight forward. You can install it from the package manager for most operating systems or install it via npm.

Usage

After installation, you can run a GitLab pipeline configuation with:

gitlab-ci-local --cwd ./

The cwd option uses the current folder as starting point. It will then look for the pipeline configuration in .gitlab-ci.yml.

Some other useful command line options:

• --list output a list of all pipeline steps
• --timestamps in case you are trying to improve the performance, logging timestamps and job durations might be relevant
• --manual triggers a defined manual pipeline step

Debugging

gitlab-ci-local features some useful decorators, with which you can enhance your pipeline development experience. For example, the @Interactive decorator might come in handy for debugging. You can pause the pipeline after a certain step and look around in a shell.

Example for interrupting the pipeline and to start a shell:

# @Interactive
interactive-shell:
  needs: [npm-install]
  rules:
    - if: $GITLAB_CI == 'false'
      when: manual
  script:
    - sh

Note: As this requires a manual step, keep in mind to start it with the --manual option, e.g.: gitlab-ci-local --cwd ./examples/docker-compose-nodejs --manual interactive-shell

Alternatives

What are possible alternatives if you want to avoid installing another tool? Well, other options I can think of, but which might need even more installation and configuration work:

• Setup a self hosted GitLab runner and connect it to your GitLab instance. You can configure a local runner on your machine and actually connect it to GitLab.com.
• Install GitLab locally including GitLab runner: With this you have your private GitLab environment which gives you a lot of room for testing. However, setting up a whole GitLab instance locally seems a bit overkill.

Do you have questions or suggestion? Don’t hesitate to contact us!