Skip to content

gitlab-ci-local: run the pipeline before push

CI/CD · Local checks
Not studied

Added 2026-10-29.

Problem

"Tired of pushing to test your .gitlab-ci.yml?" — every edit is a separate "fix ci" commit, a wait for the runner, and another error. Actionlint only checks GitHub Actions.

Solution

gitlab-ci-local runs GitLab pipelines locally "as shell executor or docker executor". It supports include, needs, inputs and CI components. The final check still stays in GitLab: server-side variables and protected branches are not reproduced locally.

Example

gitlab-ci-local --list            # which jobs end up in the pipeline
gitlab-ci-local build-site        # run a single job by name
gitlab-ci-local --needs deploy    # a job together with its needs

CI variables for local runs go in .gitlab-ci-local-variables.yml at the project root. Add the file to .gitignore: it may end up containing secrets.

Things to know:

  • isolated jobs only see files tracked by Git — run git add first;
  • the shell executor writes artifacts into the working directory; --shell-isolation is closer to a real runner.

When to use

Before every push that changes .gitlab-ci.yml or pipeline scripts.

Source

How to apply it yourself

  1. Install it and run --list on the devops-kb pipeline.
  2. Run the site build locally through the docker executor.
  3. Break a job on purpose and make sure the error shows up locally.
  4. Mark it "Studied" once a local run before push has become a habit.