Running Pipelines

glci run executes CI jobs locally via a background daemon that survives terminal disconnection.

Basic usage#

glci run                     # run everything
glci run lint test           # run specific jobs
glci run --stage build       # run all jobs in a stage
glci run -d build-job        # detached: start in background, exit immediately

Job selection#

# Glob patterns (only * is a metacharacter)
glci run 'qa:*'              # all qa: jobs
glci run 'static-analysis *' # all static-analysis shards
glci run rubocop 'lint-*'    # mix exact and glob

Skipping and manual jobs#

glci run --skip slow-integration    # skip a job (treated as success)
glci run --no-skip deploy-canary    # force-run a normally-skipped job
glci run --no-skip-all              # disable ALL skip rules
glci run --manual deploy-staging    # auto-run a specific manual job
glci run --manual-all               # auto-run ALL manual jobs
glci run --no-manual                # disable manual auto-run

Skip rules can be configured permanently in .glciconfig.toml:

[skip]
jobs = ["slow-integration"]
job_patterns = [".*windows.*"]
stages = ["deploy"]

Dirty mode#

By default, uncommitted and untracked files are included in the pipeline (respects .gitignore). Use --no-dirty to only use committed code.

Simulation mode#

Replace all scripts with echo commands. Produces dummy artifacts so you can validate pipeline structure and artifact flow in seconds:

glci run --simulate

Artifact reuse#

Skip upstream jobs when their artifacts exist from a prior run – useful for iterating on a single failing job:

glci run --reuse-artifacts test-job

Cross-project triggers#

Map trigger: project: targets to local directories:

glci run --project-dir group/other-project=../other-project

Or in .glciconfig.toml:

[projects."group/other-project"]
dir = "../other-project"
branch = "main"

Watch mode#

glci run --watch automatically re-runs the pipeline when source files change. The watcher monitors the entire project directory, respects .gitignore patterns, and debounces rapid edits.

glci run --watch                          # re-run full pipeline on changes
glci run --watch test-job                 # re-run specific job on changes
glci run --watch --debounce 1s            # custom debounce interval
glci run --watch --on-change 'make lint'  # run a hook before re-running

The --on-change flag runs a shell command each time changes are detected, before the pipeline re-executes. The command receives GLCI_CHANGED_FILES in its environment (newline-separated list of changed paths).

Watch mode is also available on glci show, glci lint, and glci jobs:

glci show --watch                 # live pipeline visualization
glci lint --watch                 # continuous validation
glci jobs --watch --json          # live job list as JSON

Concurrent runs#

If you start glci run while another pipeline is already being prepared for the same project directory, the new request automatically queues behind the in-progress preparation. The CLI and TUI display “Waiting for pipeline preparation to finish…” while queued. Up to 3 requests can queue per directory; additional requests are rejected. Press Ctrl+C to abort the wait at any time.

Ctrl+C behavior#

In attached mode (the default):

First Ctrl+C: detaches from the pipeline. Jobs continue in the background. Re-attach with glci log or cancel with glci stop.
Second Ctrl+C: cancels the pipeline immediately.

Flags reference#

Flag	Description
`-d, --detached`	Start pipeline in background and exit
`-e, --executor`	Executor: docker, kubernetes (default “docker”)
`-f, --file`	Path to CI config file (default “.gitlab-ci.yml”)
`--image`	Default Docker image (default “alpine:latest”)
`--stage`	Run only jobs in this stage
`--env KEY=VALUE`	Set variable (repeatable)
`--env-file`	Load variables from env file
`--secrets`	Fetch remote variables: all, project, or none (default “all”)
`--refresh-secrets`	Force refresh cached API variables
`--git-strategy`	Source code strategy: clone, fetch, none, remote (default “clone”)
`--context`	CI context: branch=NAME, merge_request, tag=NAME, env=NAME, or preset name
`--mr-source`	Source branch for merge_request context
`--mr-target`	Target branch for merge_request context
`--input KEY=VALUE`	Set pipeline input (repeatable)
`--inputs-file`	Load pipeline inputs from YAML file
`--dirty`	Include uncommitted files (default: true)
`--no-dirty`	Disable dirty mode
`--reuse-artifacts`	Skip upstream deps when their artifacts exist
`--simulate`	Echo commands without executing
`--timeout`	Override job timeout (e.g. 30m, 1h)
`--no-registry`	Disable embedded container registry
`--registry`	Custom container registry URL
`--registry-user`	Container registry username
`--registry-password`	Container registry password
`--push-through`	Mirror pushes to upstream registry
`--pull-policy`	Docker image pull policy: always, if-not-present, never (default “if-not-present”)
`--token`	GitLab private token
`--gitlab-url`	GitLab instance URL
`--project`	GitLab project path
`--no-token`	Disable forwarding host GitLab token as CI_JOB_TOKEN
`--skip`	Skip a job (treated as success; repeatable)
`--no-skip`	Force-run a normally-skipped job (repeatable)
`--no-skip-all`	Disable all skip rules
`--manual`	Auto-run a manual job (repeatable)
`--manual-all`	Auto-run ALL manual jobs
`--no-manual`	Disable manual auto-run
`--project-dir`	Map cross-project trigger to local dir (repeatable)
`-p, --pipeline`	Named pipeline preset from .glciconfig.toml
`-w, --watch`	Re-run on file changes
`--debounce`	Debounce interval for watch mode (default 500ms)
`--on-change`	Shell command to run when files change (requires –watch)

Edit on GitLab Report issue