Launch .gitlab-ci.yml jobs locally
Project description
gitlabci-local
Launch .gitlab-ci.yml jobs locally, wrapped inside the specific images,
with inplace project volume mounts and adaptive user selections.
Purpose
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.
Preview
Usage
usage: gitlabci-local [-h] [--version] [-q] [-c CONFIGURATION] [-B] [-A] [-m] [-n NETWORK]
[-p] [-e ENV] [-E ENGINE] [-H] [-R] [-t TAGS] [-r] [-S] [-v VOLUME]
[-w WORKDIR] [--all] [--defaults] [--bash | --debug]
[-d | -s | -l | --pull]
[names [names ...]]
gitlabci-local: Launch .gitlab-ci.yml jobs locally (aliases: gcil)
positional arguments | |
---|---|
names | Names of specific jobs (or stages with --pipeline) Regex names is supported unless --no-regex is used |
optional arguments | |
---|---|
-h, --help | Show this help message |
--version | Show the current version |
-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 |
-m, --manual | Allow manual jobs to be used |
-n NETWORK | Configure the network mode used Choices: bridge, host, none. Default: bridge |
-p, --pipeline | Run complete stages rather than jobs |
-e ENV | Define VARIABLE=value, pass VARIABLE or ENV file |
-E ENGINE | Force a specific engine (or define CI_LOCAL_ENGINE) Available engines: auto, docker, podman |
-H, --host | Run all jobs on the host rather than containers |
-R, --no-regex | Disable regex search of names |
-t TAGS | Handle listed tags as manual jobs Default list: ['deploy', 'local', 'publish'] |
-r, --real-paths | Mount real folder paths in the container (Linux only) |
-S, --sockets | Mount engine sockets for nested containers |
-v VOLUME | Mount VOLUME or HOST:TARGET in containers |
-w WORKDIR | Override the container's working path |
--all | Enable all jobs by default in selections |
--defaults | Use default variables for .local:configurations |
--bash | Prepare runners for manual bash purposes |
--debug | Keep runners active for debugging purposes |
-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 |
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.
Supported container engines
gitlabci-local currently 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 operating systems
- Linux systems :
Engines | Linux Mint, Ubuntu | CentOS | Others |
---|---|---|---|
Docker (as user) | ✓ | ✓ | ? |
Docker (as root) | ✓ | ✓ | ? |
Podman (as user) | ~ | ~ | ? |
Podman (as root) | ✓ | ✓ | ? |
- Windows systems :
Engines | Windows 10 (2004, 20H2) | Others |
---|---|---|
Docker (Hyper-V) | ✓ | ? |
Docker (WSL 2) | ✓ | ? |
Supported .gitlab-ci.yml features
- image: IMAGE_NAME
- image:
- name: IMAGE_NAME
- entrypoint: ['COMMANDS']
- include:
- local: FILE_PATHS
- variables:
- VARIABLES: VALUES
- .TEMPLATES: &TEMPLATES
- stages:
- STAGE_NAMES
- before_script:
- COMMANDS
- after_script:
- COMMANDS
- JOB_NAME:
- stage: STAGE_NAME
- image: IMAGE_NAME
- image:
- name: IMAGE_NAME
- entrypoint: ['COMMANDS']
- <<: *TEMPLATES
- extends: TEMPLATE
- extends:
- TEMPLATES
- variables:
- VARIABLES: VALUES
- before_script:
- COMMANDS
- script:
- COMMANDS
- after_script:
- COMMANDS
- retry: RETRY_COUNT
- retry:
- max: RETRY_COUNT
- tags:
- MANUAL_TAGS
- trigger: SIMPLE_TRIGGER (ignored)
- trigger:
- COMPLEX_TRIGGER (ignored)
- when: on_success/manual/on_failure/always
- allow_failure: true/false
Dependencies
- colored: Terminal colors and styles
- docker: Docker Engine API
- oyaml: Ordered YAML dictionnaries
- PyInquirer: Interactive terminal user interfaces
- python-dotenv: Support for .env files parsing
References
- .gitlab-ci.yml: GitLab CI/CD Pipeline Configuration Reference
- git-chglog: CHANGELOG generator
- OCI: Open Container Initiative
- peek: Simple GIF screen recorder
- pexpect: Interactive console applications controller
- PyPI: The Python Package Index
- winpty: Windows PTY interface wrapper
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for gitlabci_local-2.0.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | daa994c150ad847feab9b857a205d73514a7bd7d314439b4c2764b1ac141909d |
|
MD5 | 4aeb683ec2626da110d8933e497a0bdb |
|
BLAKE2b-256 | 5b0f804c4df2235ed9926ed88f42f510532952c993944be570c2e7e796f2e07c |