# gitlabci-local
<!-- markdownlint-disable no-inline-html -->
[](https://gitlab.com/AdrianDC/gitlabci-local/-/commits/master/)
[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)
[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)
[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)
[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)
[](https://sonarcloud.io/dashboard?id=AdrianDC_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
---
## Examples
<!-- prettier-ignore-start -->
```bash
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
```
<!-- prettier-ignore-end -->
---
## Usage
<!-- prettier-ignore-start -->
```yaml
usage: 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 path
debugging 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 entrypoint
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
--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,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 is supported unless --no-regex is used
```
<!-- prettier-ignore-end -->
---
## 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](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/configurations/.gitlab-ci.yml)
---
## Additional features in '.local'
`gitlabci-local` implements further support of most parameters
inside a `.local` node to ease default parameters definitions.
Supported local values for a `.local` node are:
<!-- prettier-ignore-start -->
```yaml
.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 `entrypoint
include: dict # Map `include: project:` names to local paths
manual: 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 jobs
version: str # Define a minimum version for `gitlabci-local` recommended for this file
volumes: bool # Mount `VOLUME` or `HOST:TARGET` in containers (see `-v`)
workdir: bool # Override the container's working path (see `-w`)
```
<!-- prettier-ignore-end -->
Examples for each of these can be found in the `local` unit tests: [tests/local](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/local/.gitlab-ci.yml)
and [tests/includes](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/includes/.gitlab-ci.project.yml)
---
## 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](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/.gitlab-ci.yml)
---
## Environment variables
<details>
<summary>Expand environment variables documentation</summary>
<div style="padding-left: 30px">
<br />
`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 variable `CI_LOCAL_HOST` is automatically defined to `true` by `gitlabci-local`
if running the job natively on the host (for example wiht `--host`)
The following variables are also defined by `gitlabci-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 value
- `CI_LOCAL_USER_HOST_UID`: The host user's user ID value
- `CI_LOCAL_USER_HOST_USERNAME`: The host user's username value
</div>
</details>
---
## 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 systems
<details>
<summary>Supported Linux systems</summary>
<div style="padding-left: 30px">
| Engines | Linux Mint, Ubuntu | CentOS | Others |
| :-------------------: | :----------------: | :----: | :----: |
| Native (shell) | **✓** | **✓** | **?** |
| Docker (as user) | **✓** | **✓** | **?** |
| Docker (as root) | **✓** | **✓** | **?** |
| Podman (as user) | **~** | **~** | **?** |
| Podman (as root) | **✓** | **✓** | **?** |
</div>
</details>
<details>
<summary>Supported macOS systems</summary>
<div style="padding-left: 30px">
| Engines | macOS (10.14, 10.15, 11.0, ...) |
| :-------------------: | :-----------------------------: |
| Native (shell) | **✓** |
| Docker (as user) | **?** |
</div>
</details>
<details>
<summary>Supported Windows systems</summary>
<div style="padding-left: 30px">
| Engines | Windows 10 (1909, 2004, 20H2) | Others |
| :---------------------: | :---------------------------: | :----: |
| Native (Command Prompt) | **~** | **?** |
| Native (Git Bash) | **✓** | **?** |
| Docker (Hyper‑V) | **✓** | **?** |
| Docker (WSL 2) | **✓** | **?** |
</div>
</details>
<details>
<summary>Supported Android systems</summary>
<div style="padding-left: 30px">
| Engines | Android (7.0, 7.1, 8.0, 8.1, 9.0, 10, 11, ...) |
| :-------------: | :--------------------------------------------: |
| Native (Termux) | **✓** |
</div>
</details>
---
## 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:
```bash
gitlabci-local --settings
```
---
## Environment available configurations
`gitlabci-local` uses `colored` for colors outputs and `questionary` for interactive menus.
If colors of both outputs types do not match the terminal's theme,
an environment variable `NO_COLOR=1` can be defined to disable colors.
---
## Upgrade issues and hints
<details>
<summary>Expand upgrade issues and hints documentation</summary>
<div style="padding-left: 30px">
<br />
- Versions before `4.6.0` used the now deprecated `PyInquirer` dependency,
and due to its own old dependency to the `prompt-toolkit` package,
you shoud uninstall both packages first before updating
</div>
</details>
---
## Supported .gitlab-ci.yml features
<details>
<summary>Expand .gitlab-ci.yml template documentation</summary>
<div style="padding-left: 30px">
```yaml
# Global configurations
include: FILE_PATH
include:
local: FILE_PATH
include:
- local: FILE_PATH
include:
- project: PROJECT_URL
file: FILE_PATH
include:
- project: PROJECT_URL
file:
- FILE_PATH_1
- FILE_PATH_2
image: IMAGE_NAME
image:
name: IMAGE_NAME
entrypoint: ['COMMANDS']
services:
- ...docker:dind
- SERVICE_NAME
- name: SERVICE_NAME
alias: SERVICE_ALIAS
stages:
- STAGE_NAMES
variables:
- VARIABLES: VALUES
- !reference [.path, to, YAML, node, variables]
# Global scripts
before_script:
- COMMANDS
- !reference [.path, to, YAML, node, before_script]
after_script:
- COMMANDS
- !reference [.path, to, YAML, node, after_script]
# Templates nodes
.TEMPLATES: &TEMPLATES
KEYS: VALUES
# Job nodes
JOB_NAME:
# Job configurations
stage: STAGE_NAME
image: IMAGE_NAME
image:
name: IMAGE_NAME
entrypoint: ['COMMANDS']
services:
- ...docker:dind
- SERVICE_NAME
- name: SERVICE_NAME
alias: SERVICE_ALIAS
variables:
VARIABLES: VALUES
VARIABLE_PREFILLED:
value: VALUE
description: DESCRIPTION
VARIABLE_REFERENCED: !reference [.path, to, YAML, node, variables, VARIABLE]
variables: !reference [.path, to, YAML, node, variables]
# Job templates
<<: *TEMPLATES
extends: TEMPLATE
extends:
- TEMPLATES
# Job scripts
before_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 executions
parallel:
matrix:
- VARIABLE1: VALUES
VARIABLE2: VALUES
- VARIABLE1: VALUES
VARIABLE3: VALUES
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
```
</div>
</details>
---
## Dependencies
- [colored](https://pypi.org/project/colored/): Terminal colors and styles
- [docker](https://pypi.org/project/docker/): Docker Engine API
- [python-dotenv](https://pypi.org/project/python-dotenv/): Support for .env files parsing
- [PyYAML](https://pypi.org/project/PyYAML/): YAML parser and emitter for Python
- [questionary](https://pypi.org/project/questionary/): Interactive terminal user interfaces
- [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages
- [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI
---
## References
- [.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/): GitLab CI/CD Pipeline Configuration Reference
- [git-chglog](https://github.com/git-chglog/git-chglog): CHANGELOG generator
- [gitlab-release](https://pypi.org/project/gitlab-release/): Utility for publishing on GitLab
- [OCI](https://opencontainers.org): Open Container Initiative
- [mypy](https://pypi.org/project/mypy/): Optional static typing for Python
- [pexpect-executor](https://pypi.org/project/pexpect-executor/): Automate interactive CLI tools actions
- [PyPI](https://pypi.org/): The Python Package Index
- [termtosvg](https://pypi.org/project/termtosvg/): Record terminal sessions as SVG animations
- [Termux](https://termux.com): Linux terminal emulator on Android
- [twine](https://pypi.org/project/twine/): Utility for publishing on PyPI
- [winpty](https://github.com/rprichard/winpty): Windows PTY interface wrapper
Raw data
{
"_id": null,
"home_page": "https://gitlab.com/AdrianDC/gitlabci-local",
"name": "gitlabci-local",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"maintainer_email": "",
"keywords": "gitlab-ci local gcil pipeline",
"author": "Adrian DC",
"author_email": "radian.dc@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/c5/60/bd04fe4249b8bec570cc768571047b63fd422cc95a8ecaa531745da73453/gitlabci-local-9.1.0.tar.gz",
"platform": null,
"description": "# gitlabci-local\n\n<!-- markdownlint-disable no-inline-html -->\n\n[](https://gitlab.com/AdrianDC/gitlabci-local/-/commits/master/)\n[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)\n[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)\n[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)\n[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)\n[](https://sonarcloud.io/dashboard?id=AdrianDC_gitlabci-local)\n\nLaunch .gitlab-ci.yml jobs locally, wrapped inside the specific images, \nwith inplace project volume mounts and adaptive user selections.\n\n---\n\n## Purpose\n\nThe main purpose of this project is to unify and enhance reliability \nof builds, tests or releases running on GitLab CI in a similar local context, \nby providing the simplicity of an interactive and automated terminal tool \nand avoiding code duplication (Makefile, Shell scripts, docker run, ...).\n\nRather than creating yet another standard, the .gitlab-ci.yml specification \nis the common and unique interface between GitLab CI and `gitlabci-local`.\n\n---\n\n## Preview\n\n\n\n---\n\n## Examples\n\n<!-- prettier-ignore-start -->\n\n```bash\ngitlabci-local # Launch the jobs choices interactive menu\ngitlabci-local -p # Launch the jobs pipeline automatically\ngitlabci-local -l # Launch the job selection interactive menu\ngitlabci-local 'Dev' # Launch jobs where the name contains a given string\ngitlabci-local 'Job 1' --debug # Hold a finishing specific job for debugging\ngitlabci-local 'Job 1' --bash # Prepare a bash environment for a specific job\ngcil # Shortcut alias to gitlabci-local\n```\n\n<!-- prettier-ignore-end -->\n\n---\n\n## Usage\n\n<!-- prettier-ignore-start -->\n\n```yaml\nusage: 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]\n [-H] [--notify] [-r] [-S] [--ssh [SSH_USER]] [-v VOLUME] [-w WORKDIR] [--bash | --debug] [--display] [--shell SHELL] [--all] [--defaults] [-f] [-i] [-m]\n [--no-color] [--no-console] [--no-git-safeties] [--no-script-fail] [-R] [--no-verbose] [--scripts] [-t TAGS] [-d | -s | -l | --pull | --rmi]\n [names ...]\n\ngitlabci-local: Launch .gitlab-ci.yml jobs locally (aliases: gcil)\n\ninternal arguments:\n -h, --help # Show this help message\n --version # Show the current version\n --update-check # Check for newer package updates\n --settings # Show the current settings path and contents\n --set GROUP KEY VAL # Set settings specific 'VAL' value to [GROUP] > KEY\n # or unset by using 'UNSET' as 'VAL'\n\npipeline arguments:\n -p, --pipeline # Automatically run pipeline stages rather than jobs\n -q, --quiet # Hide jobs execution context\n -c CONFIGURATION # Path to the .gitlab-ci.yml configuration file or folder\n -B, --no-before # Disable before_script executions\n -A, --no-after # Disable after_script executions\n -C COMMANDS # Run specific commands instead of \"scripts\" commands\n -n NETWORK # Configure the network mode used (or define CI_LOCAL_NETWORK)\n # Choices: bridge, host, none. Default: bridge\n -e ENV # Define VARIABLE=value, pass VARIABLE or ENV file\n -E ENGINE # Force a specific engine (or define CI_LOCAL_ENGINE)\n # Default list: auto,docker,podman\n -H, --host # Run all jobs on the host rather than containers\n --notify # Enable host notifications of pipeline and jobs results\n -r, --real-paths # Mount real folder paths in the container (Linux / macOS only)\n -S, --sockets # Mount engine sockets for nested containers\n # (Enabled by default with services: docker:*dind)\n --ssh [SSH_USER] # Bind SSH credentials to a container's user\n -v VOLUME # Mount VOLUME or HOST:TARGET in containers\n -w WORKDIR # Override the container's working path\n\ndebugging arguments:\n --bash # Prepare runners for manual bash purposes\n --debug # Keep runners active for debugging purposes\n --display # Enable host DISPLAY forwarding features\n --shell SHELL # Configure the default bash/debug shell entrypoint\n\njobs arguments:\n --all # Enable all jobs by default in selections\n --defaults # Use default variables for .local:configurations\n -f, --force # Force the action (use with --pull)\n -i, --ignore-case # Ignore case when searching for names\n -m, --manual # Allow manual jobs to be used\n --no-color # Disable colors outputs with 'NO_COLOR=1'\n # (or default settings: [themes] > no_color)\n --no-console # Disable console launch in bash/debug modes\n # (or default settings: [runner] > no_console)\n --no-git-safeties # Disable automated Git safeties configuration\n # (or default settings: [runner] > no_git_safeties)\n --no-script-fail # Fail on missing 'script' nodes of jobs\n # (or default settings: [runner] > no_script_fail)\n -R, --no-regex # Disable regex search of names\n --no-verbose # Hide jobs verbose outputs\n --scripts # Dump parsed jobs entrypoint scripts\n -t TAGS # Handle listed tags as manual jobs\n # Default list: deploy,local,publish\n\nfeatures arguments:\n -d, --dump # Dump parsed .gitlab-ci.yml configuration\n -s, --select # Force jobs selection from enumerated names\n -l, --list # Select one job to run (implies --manual)\n --pull # Pull container images from all jobs\n --rmi # Delete container images from all jobs\n\npositional arguments:\n names # Names of specific jobs (or stages with --pipeline)\n # Regex names is supported unless --no-regex is used\n```\n\n<!-- prettier-ignore-end -->\n\n---\n\n## User configurations with '.local:configurations'\n\n`gitlabci-local` implements support for specific user configurations \nallowing simple and interactive local pipeline configurations.\n\nSupported user configurations include `boolean`, `choice`, `input`, `yaml` and `json`.\n\nExamples for each of these can be found in the `configurations` unit tests: [tests/configurations](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/configurations/.gitlab-ci.yml)\n\n---\n\n## Additional features in '.local'\n\n`gitlabci-local` implements further support of most parameters \ninside a `.local` node to ease default parameters definitions.\n\nSupported local values for a `.local` node are:\n\n<!-- prettier-ignore-start -->\n\n```yaml\n.local:\n after: bool # Enable or disable `after_script` executions (see `-A`)\n all: bool # Enable all jobs by default in selections (see `--all`)\n bash: bool # Prepare runners for manual bash purposes (see `--bash`)\n before: bool # Enable or disable `before_script` executions (see `-B`)\n configurations: dict # See [User configurations with '.local:configurations'](#user-configurations-with-localconfigurations)\n debug: bool # Keep runners active for debugging purposes (see `--debug`)\n defaults: bool # Use default variables for `.local:configurations` (see `--defaults`)\n display: bool # Enable host `DISPLAY` forwarding features (see `--display`)\n engine: str # Force a specific engine (see `-E`)\n env: list[str] # Define `VARIABLE=value`, pass `VARIABLE` or `ENV` file (see `-e`)\n image: dict|str # Override container image's `name` and/or `entrypoint\n include: dict # Map `include: project:` names to local paths\n manual: bool # Allow manual jobs to be used (see `--manual`)\n names: list[str] # Names of specific jobs (or stages with `--pipeline`) (see `names`)\n network: str # Configure the network mode used (see `--network`)\n no_console: bool # Disable console launch in bash/debug modes (see `--no-console`)\n no_regex: bool # Disable regex search of names (see `--no-regex`)\n no_verbose: bool # Hide jobs verbose outputs (see `--no-verbose`)\n notify: bool # Enable host notifications of pipeline and jobs results (see `--notify`)\n pipeline: bool # Automatically run pipeline stages rather than jobs (see `-p`)\n quiet: bool # Hide jobs execution context (see `-q`)\n real_paths: bool # Mount real folder paths in the container (see `-r`)\n shell: str # Configure the default bash/debug shell entrypoint (see `--shell`)\n sockets: bool # Mount engine sockets for nested containers (see `-S`)\n ssh: bool|str # Bind SSH credentials to a container's user (see `--ssh`)\n tags: list[str] # Handle listed tags as manual jobs (see `--tags`)\n variables: dict[str] # Define `KEY: VALUE` variables for local jobs\n version: str # Define a minimum version for `gitlabci-local` recommended for this file\n volumes: bool # Mount `VOLUME` or `HOST:TARGET` in containers (see `-v`)\n workdir: bool # Override the container's working path (see `-w`)\n```\n\n<!-- prettier-ignore-end -->\n\nExamples for each of these can be found in the `local` unit tests: [tests/local](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/local/.gitlab-ci.yml)\nand [tests/includes](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/tests/includes/.gitlab-ci.project.yml)\n\n---\n\n## Job execution in native context\n\n`gitlabci-local` runs every jobs in the specified container image.\n\nFor specific local purposes where the native host context is wished, \nwhere the host tools, folders or credentials are required, \n`image: local` can be used to run the scripts natively.\n\nFor specific purposes, the `image: local:quiet` variant \ncan be used to enable the `quiet` option for specific jobs.\n\nThe `image: local:silent` variant extends the `quiet` option \nby also disabling the verbose script `set -x` line entry.\n\nAn example usage can be found in the local `Changelog` job: [.gitlab-ci.yml](https://gitlab.com/AdrianDC/gitlabci-local/blob/master/.gitlab-ci.yml)\n\n---\n\n## Environment variables\n\n<details>\n <summary>Expand environment variables documentation</summary>\n <div style=\"padding-left: 30px\">\n <br />\n\n`gitlabci-local` uses the variables defined in .gitlab-ci.yml, \nparses the simple environment variables file named `.env` \nand the configurations selected through `.local:configurations`.\n\nIf specific environment variables are to be used in the job's container:\n\n- `-e VARIABLE`: pass an environment variable\n- `-e VARIABLE=value`: set a variable to a specific value\n- `-e ENVIRONMENT_FILE`: parse a file as default variables\n\nFor example, `-e TERM=ansi` may enable colored terminal outputs.\n\nThe variable `CI_LOCAL` is automatically defined to `true` by `gitlabci-local` \nto allow specific conditions for local purposes in jobs' scripts.\n\nThe variable `CI_LOCAL_HOST` is automatically defined to `true` by `gitlabci-local` \nif running the job natively on the host (for example wiht `--host`)\n\nThe following variables are also defined by `gitlabci-local`:\n\n- `CI_COMMIT_REF_NAME`: The branch or tag name for which project is built (GitLab CI)\n- `CI_COMMIT_REF_SLUG`: CI_COMMIT_REF_NAME in lowercase, shortened to 63 bytes, \n and with everything except 0-9 and a-z replaced with -. No leading / trailing - (GitLab CI)\n- `CI_COMMIT_SHA`: The commit revision for which project is built (GitLab CI)\n- `CI_COMMIT_SHORT_SHA`: The first eight characters of CI_COMMIT_SHA (GitLab CI)\n- `CI_PROJECT_NAME`: The name of the directory for the project (GitLab CI)\n- `CI_PROJECT_NAMESPACE`: The project namespace (username or group name) of the job (GitLab CI)\n- `CI_LOCAL_USER_HOST_GID`: The host user's group ID value\n- `CI_LOCAL_USER_HOST_UID`: The host user's user ID value\n- `CI_LOCAL_USER_HOST_USERNAME`: The host user's username value\n\n </div>\n\n</details>\n\n---\n\n## Supported container engines\n\n`gitlabci-local` currently supports these container engines:\n\n- **Docker :** <https://docs.docker.com/get-docker/> (root daemon, as user or sudoer)\n- **Podman :** <https://podman.io/getting-started/> (rootless or root CLI)\n\n---\n\n## Supported systems\n\n<details>\n <summary>Supported Linux systems</summary>\n <div style=\"padding-left: 30px\">\n\n| Engines | Linux Mint, Ubuntu | CentOS | Others |\n| :-------------------: | :----------------: | :----: | :----: |\n| Native (shell) | **\u2713** | **\u2713** | **?** |\n| Docker (as user) | **\u2713** | **\u2713** | **?** |\n| Docker (as root) | **\u2713** | **\u2713** | **?** |\n| Podman (as user) | **~** | **~** | **?** |\n| Podman (as root) | **\u2713** | **\u2713** | **?** |\n\n </div>\n</details>\n\n<details>\n <summary>Supported macOS systems</summary>\n <div style=\"padding-left: 30px\">\n\n| Engines | macOS (10.14, 10.15, 11.0, ...) |\n| :-------------------: | :-----------------------------: |\n| Native (shell) | **\u2713** |\n| Docker (as user) | **?** |\n\n </div>\n</details>\n\n<details>\n <summary>Supported Windows systems</summary>\n <div style=\"padding-left: 30px\">\n\n| Engines | Windows 10 (1909, 2004, 20H2) | Others |\n| :---------------------: | :---------------------------: | :----: |\n| Native (Command Prompt) | **~** | **?** |\n| Native (Git Bash) | **\u2713** | **?** |\n| Docker (Hyper‑V) | **\u2713** | **?** |\n| Docker (WSL 2) | **\u2713** | **?** |\n\n </div>\n</details>\n\n<details>\n <summary>Supported Android systems</summary>\n <div style=\"padding-left: 30px\">\n\n| Engines | Android (7.0, 7.1, 8.0, 8.1, 9.0, 10, 11, ...) |\n| :-------------: | :--------------------------------------------: |\n| Native (Termux) | **\u2713** |\n\n </div>\n</details>\n\n---\n\n## Userspace available settings\n\n`gitlabci-local` creates a `settings.ini` configuration file in a userspace folder.\n\nFor example, it allows to change the default engines priority (`[engines] > engine`), \nor to disable the automated updates daily check (`[updates] > enabled`)\n\nThe `settings.ini` file location and contents can be shown with the following command:\n\n```bash\ngitlabci-local --settings\n```\n\n---\n\n## Environment available configurations\n\n`gitlabci-local` uses `colored` for colors outputs and `questionary` for interactive menus.\n\nIf colors of both outputs types do not match the terminal's theme, \nan environment variable `NO_COLOR=1` can be defined to disable colors.\n\n---\n\n## Upgrade issues and hints\n\n<details>\n <summary>Expand upgrade issues and hints documentation</summary>\n <div style=\"padding-left: 30px\">\n <br />\n\n- Versions before `4.6.0` used the now deprecated `PyInquirer` dependency, \nand due to its own old dependency to the `prompt-toolkit` package, \nyou shoud uninstall both packages first before updating\n\n </div>\n\n</details>\n\n---\n\n## Supported .gitlab-ci.yml features\n\n<details>\n <summary>Expand .gitlab-ci.yml template documentation</summary>\n <div style=\"padding-left: 30px\">\n\n```yaml\n# Global configurations\n\ninclude: FILE_PATH\ninclude:\n local: FILE_PATH\ninclude:\n - local: FILE_PATH\ninclude:\n - project: PROJECT_URL\n file: FILE_PATH\ninclude:\n - project: PROJECT_URL\n file:\n - FILE_PATH_1\n - FILE_PATH_2\n\nimage: IMAGE_NAME\nimage:\n name: IMAGE_NAME\n entrypoint: ['COMMANDS']\n\nservices:\n - ...docker:dind\n - SERVICE_NAME\n - name: SERVICE_NAME\n alias: SERVICE_ALIAS\n\nstages:\n - STAGE_NAMES\n\nvariables:\n - VARIABLES: VALUES\n - !reference [.path, to, YAML, node, variables]\n\n# Global scripts\n\nbefore_script:\n - COMMANDS\n - !reference [.path, to, YAML, node, before_script]\n\nafter_script:\n - COMMANDS\n - !reference [.path, to, YAML, node, after_script]\n\n# Templates nodes\n\n.TEMPLATES: &TEMPLATES\n KEYS: VALUES\n\n# Job nodes\n\nJOB_NAME:\n\n # Job configurations\n\n stage: STAGE_NAME\n\n image: IMAGE_NAME\n image:\n name: IMAGE_NAME\n entrypoint: ['COMMANDS']\n\n services:\n - ...docker:dind\n - SERVICE_NAME\n - name: SERVICE_NAME\n alias: SERVICE_ALIAS\n\n variables:\n VARIABLES: VALUES\n VARIABLE_PREFILLED:\n value: VALUE\n description: DESCRIPTION\n VARIABLE_REFERENCED: !reference [.path, to, YAML, node, variables, VARIABLE]\n variables: !reference [.path, to, YAML, node, variables]\n\n # Job templates\n\n <<: *TEMPLATES\n extends: TEMPLATE\n extends:\n - TEMPLATES\n\n # Job scripts\n\n before_script:\n - COMMANDS\n - !reference [.path, to, YAML, node, after_script]\n\n script:\n - COMMANDS\n - !reference [.path, to, YAML, node, script]\n\n after_script:\n - COMMANDS\n - !reference [.path, to, YAML, node, after_script]\n\n # Job executions\n\n parallel:\n matrix:\n - VARIABLE1: VALUES\n VARIABLE2: VALUES\n - VARIABLE1: VALUES\n VARIABLE3: VALUES\n\n retry: RETRY_COUNT\n retry:\n max: RETRY_COUNT\n\n tags:\n - MANUAL_TAGS\n\n trigger: SIMPLE_TRIGGER (ignored)\n trigger:\n COMPLEX_TRIGGER (ignored)\n\n when: on_success / manual / on_failure / always\n\n allow_failure: true / false\n```\n\n </div>\n</details>\n\n---\n\n## Dependencies\n\n- [colored](https://pypi.org/project/colored/): Terminal colors and styles\n- [docker](https://pypi.org/project/docker/): Docker Engine API\n- [python-dotenv](https://pypi.org/project/python-dotenv/): Support for .env files parsing\n- [PyYAML](https://pypi.org/project/PyYAML/): YAML parser and emitter for Python\n- [questionary](https://pypi.org/project/questionary/): Interactive terminal user interfaces\n- [setuptools](https://pypi.org/project/setuptools/): Build and manage Python packages\n- [update-checker](https://pypi.org/project/update-checker/): Check for package updates on PyPI\n\n---\n\n## References\n\n- [.gitlab-ci.yml](https://docs.gitlab.com/ee/ci/yaml/): GitLab CI/CD Pipeline Configuration Reference\n- [git-chglog](https://github.com/git-chglog/git-chglog): CHANGELOG generator\n- [gitlab-release](https://pypi.org/project/gitlab-release/): Utility for publishing on GitLab\n- [OCI](https://opencontainers.org): Open Container Initiative\n- [mypy](https://pypi.org/project/mypy/): Optional static typing for Python\n- [pexpect-executor](https://pypi.org/project/pexpect-executor/): Automate interactive CLI tools actions\n- [PyPI](https://pypi.org/): The Python Package Index\n- [termtosvg](https://pypi.org/project/termtosvg/): Record terminal sessions as SVG animations\n- [Termux](https://termux.com): Linux terminal emulator on Android\n- [twine](https://pypi.org/project/twine/): Utility for publishing on PyPI\n- [winpty](https://github.com/rprichard/winpty): Windows PTY interface wrapper\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Launch .gitlab-ci.yml jobs locally",
"version": "9.1.0",
"project_urls": {
"Bug Reports": "https://gitlab.com/AdrianDC/gitlabci-local/-/issues",
"Changelog": "https://gitlab.com/AdrianDC/gitlabci-local/blob/master/CHANGELOG.md",
"Documentation": "https://gitlab.com/AdrianDC/gitlabci-local#gitlabci-local",
"Homepage": "https://gitlab.com/AdrianDC/gitlabci-local",
"Source": "https://gitlab.com/AdrianDC/gitlabci-local",
"Statistics": "https://pypistats.org/packages/{PROJECT_PACKAGE}"
},
"split_keywords": [
"gitlab-ci",
"local",
"gcil",
"pipeline"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "bbae2524aa0cad6c6d31acfc484e0fbe0d5ca8c0b69844e092f71334ace30c8f",
"md5": "fedbf93b93cdaf18570859f535bbf726",
"sha256": "0eb0c1d703d0360e6bbfcee8add9fd94f98e6fa7d9f42a6a93174e05c9fa8e5e"
},
"downloads": -1,
"filename": "gitlabci_local-9.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fedbf93b93cdaf18570859f535bbf726",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"size": 70077,
"upload_time": "2023-12-10T15:49:19",
"upload_time_iso_8601": "2023-12-10T15:49:19.203457Z",
"url": "https://files.pythonhosted.org/packages/bb/ae/2524aa0cad6c6d31acfc484e0fbe0d5ca8c0b69844e092f71334ace30c8f/gitlabci_local-9.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "c560bd04fe4249b8bec570cc768571047b63fd422cc95a8ecaa531745da73453",
"md5": "e85131ad5dc63b1c9ceea31f5e4d9e10",
"sha256": "2b44499a601fce2a42d428902f0d7ab4dcb24b9d9a6b1ee217ed8b0bd2a36b3b"
},
"downloads": -1,
"filename": "gitlabci-local-9.1.0.tar.gz",
"has_sig": false,
"md5_digest": "e85131ad5dc63b1c9ceea31f5e4d9e10",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*, !=3.4.*, !=3.5.*",
"size": 138740,
"upload_time": "2023-12-10T15:49:21",
"upload_time_iso_8601": "2023-12-10T15:49:21.456425Z",
"url": "https://files.pythonhosted.org/packages/c5/60/bd04fe4249b8bec570cc768571047b63fd422cc95a8ecaa531745da73453/gitlabci-local-9.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-10 15:49:21",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "AdrianDC",
"gitlab_project": "gitlabci-local",
"lcname": "gitlabci-local"
}
JSON