Skip to main content

Launch .gitlab-ci.yml jobs locally

Project description


Build Bugs Code Smells Coverage Lines of Code Quality Gate Status

Launch .gitlab-ci.yml jobs locally, wrapped inside the specific images,
with inplace project volume mounts and adaptive user selections.


The main purpose of this project is to unify and enhance reliability
of builds, tests or releases running on GitLab CI in a similar local context,
by providing the simplicity of an interactive and automated terminal tool
and avoiding code duplication (Makefile, Shell scripts, docker run, ...).

Rather than creating yet another standard, the .gitlab-ci.yml specification
is the common and unique interface between GitLab CI and gitlabci-local.




Commands Purpose
gitlabci-local Launch the jobs choices interactive menu
gitlabci-local -p Launch the jobs pipeline automatically
gitlabci-local -l Launch the job selection interactive menu
gitlabci-local 'Dev' Launch jobs where the name contains a given string
gitlabci-local 'Job 1' --debug Hold a finishing specific job for debugging
gitlabci-local 'Job 1' --bash Prepare a bash environment for a specific job
gcil Shortcut alias to gitlabci-local


gitlabci-local Main entrypoint to this project
gcil Shortcut entrypoint to this project
Internal arguments
-h, --help Show this help message
--version Show the current version
--update-check Check for newer package updates
--settings Show the current settings path and contents
Pipeline arguments
-p, --pipeline Automatically run pipeline stages rather than jobs
-q, --quiet Hide jobs execution context
-c CONFIGURATION Path to the .gitlab-ci.yml configuration file or folder
-B, --no-before Disable before_script executions
-A, --no-after Disable after_script executions
-n NETWORK Configure the network mode used
Choices: bridge, host, none. Default: bridge
-e ENV Define VARIABLE=value, pass VARIABLE or ENV file
-E ENGINE Force a specific engine (or define CI_LOCAL_ENGINE)
Default list: auto,podman,docker
-H, --host Run all jobs on the host rather than containers
-r, --real-paths Mount real folder paths in the container (Linux / macOS only)
-S, --sockets Mount engine sockets for nested containers
(Enabled by default with services: docker:*dind)
-v VOLUME Mount VOLUME or HOST:TARGET in containers
-w WORKDIR Override the container's working path
Debugging arguments
--bash Prepare runners for manual bash purposes
--debug Keep runners active for debugging purposes
Jobs arguments
--all Enable all jobs by default in selections
--defaults Use default variables for .local:configurations
-f, --force Force the action (use with --pull)
-i, --ignore-case Ignore case when searching for names
-m, --manual Allow manual jobs to be used
-R, --no-regex Disable regex search of names
-t TAGS Handle listed tags as manual jobs
Default list: deploy,local,publish
Features arguments
-d, --dump Dump parsed .gitlab-ci.yml configuration
-s, --select Force jobs selection from enumerated names
-l, --list Select one job to run (implies --manual)
--pull Pull container images from all jobs
--rmi Delete container images from all jobs
Positional arguments
names Names of specific jobs (or stages with --pipeline)
Regex names are supported unless --no-regex is used

User configurations with ".local:configurations"

gitlabci-local implements support for specific user configurations
allowing simple and interactive local pipeline configurations.

Supported user configurations include boolean, choice, input, yaml and json.

Examples for each of these can be found in the configurations unit tests: tests/configurations

Additional features in ".local"

gitlabci-local implements further support of most parameters
inside the .local to ease default parameters definitions.

Supported local values include after, all, bash, before, configurations,
debug, defaults, engine, env, image, manual, names, network,
pipeline, quiet, real_paths, sockets, tags, volumes, workdir.

Examples for each of these can be found in the local unit tests: tests/local

Job execution in native context

gitlabci-local runs every jobs in the specified container image.

For specific local purposes where the native host context is wished,
where the host tools, folders or credentials are required,
image: local can be used to run the scripts natively.

For specific purposes, the image: local:quiet variant
can be used to enable the quiet option for specific jobs.

The image: local:silent variant extends the quiet option
by also disabling the verbose script set -x line entry.

An example usage can be found in the local Changelog job: .gitlab-ci.yml

Environment variables

gitlabci-local uses the variables defined in .gitlab-ci.yml,
parses the simple environment variables file named .env
and the configurations selected through .local:configurations.

If specific environment variables are to be used in the job's container:

  • -e VARIABLE: pass an environment variable
  • -e VARIABLE=value: set a variable to a specific value
  • -e ENVIRONMENT_FILE: parse a file as default variables

For example, -e TERM=ansi may enable colored terminal outputs.

The variable CI_LOCAL is automatically defined to true by gitlabci-local
to allow specific conditions for local purposes in jobs' scripts.

The following variables are also defined by gitlabci-local:

  • CI_COMMIT_SHA: The commit revision for which project is built (GitLab CI)
  • CI_COMMIT_SHORT_SHA: The first eight characters of CI_COMMIT_SHA (GitLab CI)

Supported container engines

gitlabci-local currently supports these container engines:

Supported Linux systems

Engines Linux Mint, Ubuntu CentOS Others
Native (shell) ?
Docker (as user) ?
Docker (as root) ?
Podman (as user) ~ ~ ?
Podman (as root) ?

Supported macOS systems

Engines macOS (10.14, 10.15, 11.0, ...)
Native (shell)
Docker (as user) ?

Supported Windows systems

Engines Windows 10 (1909, 2004, 20H2) Others
Native (shell) ?
Docker (Hyper‑V) ?
Docker (WSL 2) ?

Supported Android systems

Engines Android (7.0, 7.1, 8.0, 8.1, 9.0, 10, 11, ...)
Native (Termux)

Userspace available settings

gitlabci-local creates a settings.ini configuration file in a userspace folder.

For example, it allows to change the default engines priority ([engines] > engine),
or to disable the automated updates daily check ([updates] > enabled)

The settings.ini file location and contents can be shown with the following command:

gitlabci-local --settings

Supported .gitlab-ci.yml features

# Global configurations

include: FILE_PATH
  local: FILE_PATH
  - local: FILE_PATH

  name: IMAGE_NAME
  entrypoint: ['COMMANDS']

  - ...docker:dind
  - name: SERVICE_NAME
    alias: SERVICE_ALIAS



# Global scripts



# Templates nodes


# Job nodes


  # Job configurations

  stage: STAGE_NAME

  image: IMAGE_NAME
    name: IMAGE_NAME
    entrypoint: ['COMMANDS']

    - ...docker:dind
    - name: SERVICE_NAME
      alias: SERVICE_ALIAS


  # Job templates

  extends: TEMPLATE

  # Job scripts




  # Job executions

  retry: RETRY_COUNT
    max: RETRY_COUNT


  trigger: SIMPLE_TRIGGER (ignored)
    COMPLEX_TRIGGER (ignored)

  when: on_success / manual / on_failure / always

  allow_failure: true / false



  • .gitlab-ci.yml: GitLab CI/CD Pipeline Configuration Reference
  • git-chglog: CHANGELOG generator
  • gitlab-release: Utility for publishing on GitLab
  • OCI: Open Container Initiative
  • pexpect-executor: Automate interactive CLI tools actions
  • PyPI: The Python Package Index
  • termtosvg: Record terminal sessions as SVG animations
  • Termux: Linux terminal emulator on Android
  • twine: Utility for publishing on PyPI
  • winpty: Windows PTY interface wrapper

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for gitlabci-local, version 4.0.0
Filename, size File type Python version Upload date Hashes
Filename, size gitlabci_local-4.0.0-py3-none-any.whl (51.3 kB) File type Wheel Python version py3 Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page