Package: gitlabci-local
gitlabci-localLaunch .gitlab-ci.yml jobs locally, wrapped inside the specific images,with inplace project volume mounts and adaptive user selections.PurposeThe main purpose of this project is to unify and enhance reliabilityof builds, tests or releases running on GitLab CI in a similar local context,by providing the simplicity of an interactive and automated terminal tooland avoiding code duplication (Makefile, Shell scripts, docker run, ...).Rather than creating yet another standard, the .gitlab-ci.yml specificationis the common and unique interface between GitLab CI andgitlabci-local.PreviewExamplesgitlabci-local# Launch the jobs choices interactive menugitlabci-local-p# Launch the jobs pipeline automaticallygitlabci-local-l# Launch the job selection interactive menugitlabci-local'Dev'# Launch jobs where the name contains a given stringgitlabci-local'Job 1'--debug# Hold a finishing specific job for debugginggitlabci-local'Job 1'--bash# Prepare a bash environment for a specific jobgcil# Shortcut alias to gitlabci-localUsageusage:gitlabci-local [-h] [--version] [--update-check] [--settings] [--set GROUP KEY VAL] [-p] [-q] [-c CONFIGURATION] [-B] [-A] [-C COMMANDS] [-n NETWORK] [-e ENV] [-E ENGINE][-H] [--notify] [-r] [-S] [--ssh [SSH_USER]] [-v VOLUME] [-w WORKDIR] [--bash | --debug] [--display] [--shell SHELL] [--all] [--defaults] [-f] [-i] [-m][--no-color] [--no-console] [--no-git-safeties] [--no-script-fail] [-R] [--no-verbose] [--scripts] [-t TAGS] [-d | -s | -l | --pull | --rmi][names ...]gitlabci-local: Launch .gitlab-ci.yml jobs locally (aliases:gcil)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--set GROUP KEY VAL# Set settings specific 'VAL' value to [GROUP] > KEY# or unset by using 'UNSET' as 'VAL'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-C COMMANDS# Run specific commands instead of "scripts" commands-n NETWORK# Configure the network mode used (or define CI_LOCAL_NETWORK)# 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,docker,podman-H, --host# Run all jobs on the host rather than containers--notify# Enable host notifications of pipeline and jobs results-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)--ssh [SSH_USER]# Bind SSH credentials to a container's user-v VOLUME# Mount VOLUME or HOST:TARGET in containers-w WORKDIR# Override the container's working pathdebugging arguments:--bash# Prepare runners for manual bash purposes--debug# Keep runners active for debugging purposes--display# Enable host DISPLAY forwarding features--shell SHELL# Configure the default bash/debug shell entrypointjobs 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--no-color# Disable colors outputs with 'NO_COLOR=1'# (or default settings: [themes] > no_color)--no-console# Disable console launch in bash/debug modes# (or default settings: [runner] > no_console)--no-git-safeties# Disable automated Git safeties configuration# (or default settings: [runner] > no_git_safeties)--no-script-fail# Fail on missing 'script' nodes of jobs# (or default settings: [runner] > no_script_fail)-R, --no-regex# Disable regex search of names--no-verbose# Hide jobs verbose outputs--scripts# Dump parsed jobs entrypoint scripts-t TAGS# Handle listed tags as manual jobs# Default list: deploy,local,publishfeatures 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 jobspositional arguments:names# Names of specific jobs (or stages with --pipeline)# Regex names is supported unless --no-regex is usedUser configurations with '.local:configurations'gitlabci-localimplements support for specific user configurationsallowing simple and interactive local pipeline configurations.Supported user configurations includeboolean,choice,input,yamlandjson.Examples for each of these can be found in theconfigurationsunit tests:tests/configurationsAdditional features in '.local'gitlabci-localimplements further support of most parametersinside a.localnode to ease default parameters definitions.Supported local values for a.localnode are:.local:after:bool# Enable or disable `after_script` executions (see `-A`)all:bool# Enable all jobs by default in selections (see `--all`)bash:bool# Prepare runners for manual bash purposes (see `--bash`)before:bool# Enable or disable `before_script` executions (see `-B`)configurations:dict# See [User configurations with '.local:configurations'](#user-configurations-with-localconfigurations)debug:bool# Keep runners active for debugging purposes (see `--debug`)defaults:bool# Use default variables for `.local:configurations` (see `--defaults`)display:bool# Enable host `DISPLAY` forwarding features (see `--display`)engine:str# Force a specific engine (see `-E`)env:list[str]# Define `VARIABLE=value`, pass `VARIABLE` or `ENV` file (see `-e`)image:dict|str# Override container image's `name` and/or `entrypointinclude:dict# Map `include: project:` names to local pathsmanual:bool# Allow manual jobs to be used (see `--manual`)names:list[str]# Names of specific jobs (or stages with `--pipeline`) (see `names`)network:str# Configure the network mode used (see `--network`)no_console:bool# Disable console launch in bash/debug modes (see `--no-console`)no_regex:bool# Disable regex search of names (see `--no-regex`)no_verbose:bool# Hide jobs verbose outputs (see `--no-verbose`)notify:bool# Enable host notifications of pipeline and jobs results (see `--notify`)pipeline:bool# Automatically run pipeline stages rather than jobs (see `-p`)quiet:bool# Hide jobs execution context (see `-q`)real_paths:bool# Mount real folder paths in the container (see `-r`)shell:str# Configure the default bash/debug shell entrypoint (see `--shell`)sockets:bool# Mount engine sockets for nested containers (see `-S`)ssh:bool|str# Bind SSH credentials to a container's user (see `--ssh`)tags:list[str]# Handle listed tags as manual jobs (see `--tags`)variables:dict[str]# Define `KEY: VALUE` variables for local jobsversion:str# Define a minimum version for `gitlabci-local` recommended for this filevolumes:bool# Mount `VOLUME` or `HOST:TARGET` in containers (see `-v`)workdir:bool# Override the container's working path (see `-w`)Examples for each of these can be found in thelocalunit tests:tests/localandtests/includesJob execution in native contextgitlabci-localruns 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: localcan be used to run the scripts natively.For specific purposes, theimage: local:quietvariantcan be used to enable thequietoption for specific jobs.Theimage: local:silentvariant extends thequietoptionby also disabling the verbose scriptset -xline entry.An example usage can be found in the localChangelogjob:.gitlab-ci.ymlEnvironment variablesExpand environment variables documentationgitlabci-localuses the variables defined in .gitlab-ci.yml,parses the simple environment variables file named.envand 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 variablesFor example,-e TERM=ansimay enable colored terminal outputs.The variableCI_LOCALis automatically defined totruebygitlabci-localto allow specific conditions for local purposes in jobs' scripts.The variableCI_LOCAL_HOSTis automatically defined totruebygitlabci-localif running the job natively on the host (for example wiht--host)The following variables are also defined bygitlabci-local:CI_COMMIT_REF_NAME: The branch or tag name for which project is built (GitLab CI)CI_COMMIT_REF_SLUG: CI_COMMIT_REF_NAME in lowercase, shortened to 63 bytes,and with everything except 0-9 and a-z replaced with -. No leading / trailing - (GitLab CI)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)CI_PROJECT_NAME: The name of the directory for the project (GitLab CI)CI_PROJECT_NAMESPACE: The project namespace (username or group name) of the job (GitLab CI)CI_LOCAL_USER_HOST_GID: The host user's group ID valueCI_LOCAL_USER_HOST_UID: The host user's user ID valueCI_LOCAL_USER_HOST_USERNAME: The host user's username valueSupported container enginesgitlabci-localcurrently supports these container engines:Docker :https://docs.docker.com/get-docker/(root daemon, as user or sudoer)Podman :https://podman.io/getting-started/(rootless or root CLI)Supported systemsSupported Linux systemsEnginesLinux Mint, UbuntuCentOSOthersNative (shell)✓✓?Docker (as user)✓✓?Docker (as root)✓✓?Podman (as user)~~?Podman (as root)✓✓?Supported macOS systemsEnginesmacOS (10.14, 10.15, 11.0, ...)Native (shell)✓Docker (as user)?Supported Windows systemsEnginesWindows 10 (1909, 2004, 20H2)OthersNative (Command Prompt)~?Native (Git Bash)✓?Docker (Hyper‑V)✓?Docker (WSL 2)✓?Supported Android systemsEnginesAndroid (7.0, 7.1, 8.0, 8.1, 9.0, 10, 11, ...)Native (Termux)✓Userspace available settingsgitlabci-localcreates asettings.iniconfiguration 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)Thesettings.inifile location and contents can be shown with the following command:gitlabci-local--settingsEnvironment available configurationsgitlabci-localusescoloredfor colors outputs andquestionaryfor interactive menus.If colors of both outputs types do not match the terminal's theme,an environment variableNO_COLOR=1can be defined to disable colors.Upgrade issues and hintsExpand upgrade issues and hints documentationVersions before4.6.0used the now deprecatedPyInquirerdependency,and due to its own old dependency to theprompt-toolkitpackage,you shoud uninstall both packages first before updatingSupported .gitlab-ci.yml featuresExpand .gitlab-ci.yml template documentation# Global configurationsinclude:FILE_PATHinclude:local:FILE_PATHinclude:-local:FILE_PATHinclude:-project:PROJECT_URLfile:FILE_PATHinclude:-project:PROJECT_URLfile:-FILE_PATH_1-FILE_PATH_2image:IMAGE_NAMEimage:name:IMAGE_NAMEentrypoint:['COMMANDS']services:-...docker:dind-SERVICE_NAME-name:SERVICE_NAMEalias:SERVICE_ALIASstages:-STAGE_NAMESvariables:-VARIABLES:VALUES-!reference[.path,to,YAML,node,variables]# Global scriptsbefore_script:-COMMANDS-!reference[.path,to,YAML,node,before_script]after_script:-COMMANDS-!reference[.path,to,YAML,node,after_script]# Templates nodes.TEMPLATES:&TEMPLATESKEYS:VALUES# Job nodesJOB_NAME:# Job configurationsstage:STAGE_NAMEimage:IMAGE_NAMEimage:name:IMAGE_NAMEentrypoint:['COMMANDS']services:-...docker:dind-SERVICE_NAME-name:SERVICE_NAMEalias:SERVICE_ALIASvariables:VARIABLES:VALUESVARIABLE_PREFILLED:value:VALUEdescription:DESCRIPTIONVARIABLE_REFERENCED:!reference[.path,to,YAML,node,variables,VARIABLE]variables:!reference[.path,to,YAML,node,variables]# Job templates<<:*TEMPLATESextends:TEMPLATEextends:-TEMPLATES# Job scriptsbefore_script:-COMMANDS-!reference[.path,to,YAML,node,after_script]script:-COMMANDS-!reference[.path,to,YAML,node,script]after_script:-COMMANDS-!reference[.path,to,YAML,node,after_script]# Job executionsparallel:matrix:-VARIABLE1:VALUESVARIABLE2:VALUES-VARIABLE1:VALUESVARIABLE3:VALUESretry:RETRY_COUNTretry:max:RETRY_COUNTtags:-MANUAL_TAGStrigger:SIMPLE_TRIGGER (ignored)trigger:COMPLEX_TRIGGER (ignored)when:on_success / manual / on_failure / alwaysallow_failure:true / falseDependenciescolored: Terminal colors and stylesdocker: Docker Engine APIpython-dotenv: Support for .env files parsingPyYAML: YAML parser and emitter for Pythonquestionary: Interactive terminal user interfacessetuptools: Build and manage Python packagesupdate-checker: Check for package updates on PyPIReferences.gitlab-ci.yml: GitLab CI/CD Pipeline Configuration Referencegit-chglog: CHANGELOG generatorgitlab-release: Utility for publishing on GitLabOCI: Open Container Initiativemypy: Optional static typing for Pythonpexpect-executor: Automate interactive CLI tools actionsPyPI: The Python Package Indextermtosvg: Record terminal sessions as SVG animationsTermux: Linux terminal emulator on Androidtwine: Utility for publishing on PyPIwinpty: Windows PTY interface wrapper