Debugging & Inspection

Variable precedence debugging#

When a job behaves unexpectedly, the variable stack is often the cause. See Variables & Secrets for the full precedence table.

To isolate which variable source is causing a problem:

glci run --secrets none my-job       # run without remote variables
glci run --secrets project my-job    # project-level only (skip group)
glci run --env MY_VAR=debug my-job   # override a specific variable
glci run --refresh-secrets my-job    # force refresh cached API variables

Debugging rule evaluation#

Rules evaluation works the same as production GitLab CI (docs). glci supports if:, changes: (with compare_to:), and exists: conditions.

Compare the pipeline across contexts to understand which rules matched:

glci jobs --context merge_request
glci jobs --context branch=main
diff <(glci show --json --context merge_request) \
     <(glci show --json --context branch=main)

If glci show returns no jobs, workflow: rules: may be rejecting the entire pipeline. Try a different context.

Daemon logs#

The glci daemon writes logs to ~/.glci/daemon.log with details not visible in job output: mock server requests, runner container lifecycle, child pipeline events, cross-project trigger resolution, and scheduler decisions.

tail -f ~/.glci/daemon.log     # follow in real time
glci system logs info          # check file size
glci system logs clean         # clear the log file (safe while daemon runs)

Log lines are prefixed with their source: daemon: (orchestration), mock-server: (API handling), runner: (gitlab-runner output).

Job logs#

glci log                       # all logs from latest pipeline
glci log 5 build-job           # specific job from pipeline #5
glci history                   # find child pipeline IDs
glci log 7 child-job-name      # child pipeline job log

glci log streams live output for running jobs and reads from disk for completed jobs.

Common issues#

Job is unexpectedly skipped#

Check which context is active (default is merge_request). Compare glci jobs --context merge_request vs glci jobs --context branch=main. If the job appears in one but not the other, the issue is in rules:. Also check workflow: rules: which can reject the entire pipeline.

Job fails with “variable not found”#

Isolate the source: glci run --secrets none my-job (remove remote vars), then glci run --secrets all my-job (add them back). Override with --env MISSING_VAR=value to confirm.

Trigger job fails immediately#

• Child pipelines: verify the include file exists on disk.
• Cross-project triggers: ensure --project-dir group/project=../project is set.
• Check tail -20 ~/.glci/daemon.log for resolution errors.

Include resolution fails#

• include: project: requires a GitLab token – run glci doctor to verify.
• include: component: with version selectors (@~latest, @~N, @~N.M) requires a GitLab token to query the Tags API. If the token is missing or lacks read access, you will see errors like failed to resolve version selector: unauthorized or no matching tags found for selector ~latest.
• Max nesting depth is 10 levels.

Tips#

• Quick validation loop: glci show --watch re-renders the pipeline graph on every save.
• Environment health check: glci doctor checks Docker, daemon, token, CI config, and git.
• Simulation mode: glci run --simulate replaces scripts with echo commands and produces dummy artifacts.
• Effective config: glci config, glci config --network, glci config --gitlab.