Cross-Project Pipelines

glci supports both child pipelines (trigger: include:) and cross-project pipelines (trigger: project:) locally. Child pipelines share the parent’s Docker infrastructure. Cross-project triggers resolve the target project from a local directory or by cloning it from GitLab.

Child pipelines (trigger: include:)#

Child pipelines work the same as production GitLab CI parent-child pipelines. All include formats (string shorthand, local: map, artifact-sourced includes (artifact:/job:, see below), forward:, and per-include inputs:) are supported. A trigger: include: may list up to 3 files, which are merged into the child pipeline (matching GitLab).

A child pipeline’s config is ordinary CI YAML, so it may carry its own include: block — and those includes resolve exactly as they do in a top-level .gitlab-ci.yml, include: project: and include: component: included. A child that pulls shared job templates out of a central templates project therefore runs locally with no changes:

# child.yml
include:
  - project: my-group/my-templates
    ref: v1.0.0
    file: templates.yml

job:
  extends: .template-job

The remote fetch uses the same GitLab token as the top-level parse (see What requires a GitLab token) and the same on-disk include cache, so a template fetched once is reused by every child pipeline in the run.

When no token is available the include is skipped, and glci says so twice: in the trigger job’s output (glci log <pipeline-id> <trigger-job>, and inline during glci run) and in the daemon log. Look for:

skipping project include my-group/my-templates: no GitLab token configured

What happens next depends on whether anything referenced the skipped file:

• If a job extends: a definition the include would have provided, the parse fails and the trigger job fails with extends target ".template-job" not found — matching GitLab, which rejects a config whose extends: target is missing.
• If nothing references it, the child pipeline runs without the jobs that file defined. The warning above is the only sign, so treat it as an error in disguise.

Note that downstream parsing is stricter than glci lint/glci jobs here: those warn about a missing extends: target and carry on, because a top-level parse is often run deliberately offline. A downstream parse cannot afford that — a job stripped of its extends: keeps no script:, so it is dropped from the pipeline and the trigger job passes with nothing to show for it. So glci lint -f child.yml may succeed on a file the child parse rejects; the parse error names the target it could not find.

Where include paths resolve from#

trigger: include: paths — and any include: local: inside the child’s own config — resolve from the repository root, exactly as GitLab reads them out of the repository. Leading slashes are stripped, so ci/child.yml and /ci/child.yml name the same file.

Include resolution does not depend on which directory you invoke glci from, so a CI file in a subdirectory names paths the way GitLab reads them:

# apps/web/.gitlab-ci.yml, run as: glci run --file apps/web/.gitlab-ci.yml
child:
  trigger:
    include: ci/child.yml   # <repo-root>/ci/child.yml, as on GitLab

A path that climbs out of the repository (../outside.yml) is rejected. An absolute filesystem path is not a special case: its leading slash is stripped like any other, so /etc/passwd is looked up as <repo-root>/etc/passwd and simply isn’t found — a path outside the repository can never be read, because GitLab could not read one either.

A * makes the path a wildcard, matched the way GitLab matches it. The 3-file limit counts include entries, before expansion — again as GitLab counts it — so one ci/*.yml entry may merge more than three files. Other characters (?, [) are literal parts of a filename, not wildcards.

Variables in a child’s include paths#

$VAR / ${VAR} references in a child’s include: entries (project:, ref:, file:, local:) expand against the variables the trigger job forwards downstream — the parent’s global variables: merged with the trigger job’s own variables: — the same set GitLab expands them against. So this picks up v2.0.0:

# .gitlab-ci.yml
child:
  variables:
    TEMPLATES_REF: v2.0.0
  trigger:
    include: child.yml

# child.yml
include:
  - project: my-group/my-templates
    ref: $TEMPLATES_REF
    file: templates.yml

Underneath the forwarded set sit the predefined CI_* variables and any API-fetched instance/group/project variables, so ref: $CI_DEFAULT_BRANCH resolves too. The forwarded set overrides the child’s own global variables: block, matching GitLab.

glci’s own layers (--env, --env-file, preset env:, .glci.env) sit on top of all of it and still override a forwarded value. Note they apply whatever forward: says — they are glci’s local override for a run, not a simulated GitLab variable source — so --env can steer which file a child includes even when forward: pipeline_variables is false and that variable is absent from the child’s runtime environment. Setting forward: yaml_variables: false withholds the forwarded set from the expansion, leaving the predefined and glci layers in place.

glci-specific behavior#

• The child shares the parent’s mock server and runner containers.
• The child’s submodules are served too: it inherits what the parent served, and glci walks the repository again when the child’s jobs ask for more.
• Child pipeline events are bridged to the parent’s event bus, so the TUI and glci log display them inline.
• Nesting is capped at 2 levels deep (matching GitLab). Exceeding this produces: child pipeline nesting depth 3 exceeds maximum 2.
• strategy: depend (or mirror) makes the trigger job fail if the child fails. Without a strategy the trigger job is fire-and-forget and passes once the child is created.
• allow_failure: true on a trigger job is honoured, so a failing child under strategy: depend need not sink the parent pipeline. A trigger job runs no script and so never reports an exit code, which means allow_failure:exit_codes never applies to one. See Tolerated failures.
• The child receives CI_PIPELINE_SOURCE=parent_pipeline and CI_PARENT_PIPELINE_ID, and its own freshly generated CI_PIPELINE_ID/CI_PIPELINE_IID/CI_PIPELINE_URL/CI_PIPELINE_CREATED_AT (not inherited from the parent).
• Stopping the parent pipeline (glci stop) automatically cancels in-flight child pipeline jobs via the Job-Status cancel protocol.

Variable forwarding#

forward: controls what the parent passes to the downstream pipeline. The defaults match GitLab’s FORWARD_DEFAULTS:

Because yaml_variables defaults to true, a trigger job with no forward: block still forwards the parent’s global variables and the trigger job’s own variables:. Set yaml_variables: false to suppress both.

Forwarded yaml_variables values are expanded in the context of the trigger job (the upstream pipeline) before being forwarded, so a value like SERVICE_PROJECT_URL: $CI_PROJECT_URL resolves to the parent project’s URL — matching GitLab. Use $$ to pass a literal dollar sign. If an expanded value references a masked variable, the forwarded copy stays masked.

Trigger inputs: are not forwarded as variables — like GitLab, they are used only for spec:inputs interpolation of the included config.

Dynamic child pipelines (trigger: include: artifact:)#

A child pipeline can be generated at runtime by a job and passed to the trigger as an artifact, matching GitLab’s dynamic child pipelines. A generator job writes the child pipeline YAML to a file and exposes it as an artifact; the trigger job references it with artifact: and job::

generate-child-pipeline:
  stage: generate
  script:
    - ./scripts/generate.sh > generated-pipeline.yml
  artifacts:
    paths:
      - generated-pipeline.yml

trigger-child-pipeline:
  stage: trigger
  needs:
    - job: generate-child-pipeline
      artifacts: true
  trigger:
    include:
      - artifact: generated-pipeline.yml
        job: generate-child-pipeline
    strategy: depend

glci resolves the artifact from the generator job’s output and runs it as the child pipeline, with full support for strategy: depend, variable forwarding, and per-include inputs: — the same as a static local: include. Notes:

• The generator job must run before the trigger job. Like GitLab, glci resolves it by name within the same pipeline, so put it in an earlier stage (as above) or add needs:. If it hasn’t produced the artifact yet, the trigger job fails with artifact include "…": job "…" produced no artifacts.
• The artifact: path is resolved inside the generator job’s artifact archive (the same path you listed under artifacts:paths:); nested paths like dir/child.yml work.
• artifact: requires a job:; omitting it is a config error.
• An empty artifact file, or one larger than 5 MiB, is rejected with a clear error.
• Artifact-sourced includes can be mixed with plain local: includes (still up to 3 files total).

Cross-project pipelines (trigger: project:)#

Cross-project triggers (trigger: project:) work the same as production GitLab CI, but glci needs to know where the target project’s source code lives locally.

Mapping projects to local directories#

Use --project-dir to map a project path to a local checkout:

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

Or configure the mapping permanently in .glciconfig.toml:

[projects."group/other-project"]
dir = "../other-project"
branch = "main"  # optional: override which branch to use

Relative paths in dir are resolved against the parent project’s working directory. The target directory must be a git repository.

Resolution order#

When glci encounters a trigger: project: job, it resolves the target in this order:

1. CLI --project-dir mapping – highest priority
2. Config [projects] section in .glciconfig.toml or ~/.glci/config.toml (project-level overrides global)
3. Git clone from GitLab – if a token is available, glci clones the target project as a bare repo (works for public repos without a token)
4. Error with instructions – if none of the above succeed, glci prints a message showing how to configure the mapping

Submodules in a triggered target#

The target’s own git submodules are served from the mock, read from the commit the target is running and resolved against the target’s project path — ../submod next to mygroup/target is mygroup/submod, not a sibling of the triggering project. A target resolved by cloning has no checkout to take objects from, so map its submodules with --project-dir when they cannot be cloned from your GitLab instance.

Includes in a cloned target#

A target resolved by cloning from GitLab has no local checkout, so glci extracts the target’s CI configuration out of the bare repo into a private directory and parses it there. The whole tree of .yml/.yaml files is extracted, not just .gitlab-ci.yml, so the target’s own include: local: entries resolve from its repository root the way GitLab resolves them:

# .gitlab-ci.yml in the target project
include:
  - local: ci/build.yml   # resolves — ci/build.yml is extracted too

Only YAML is extracted, because that is the only thing an include: can name (GitLab rejects an include whose path has any other extension). Two consequences:

• rules: exists: in a cloned target is evaluated against that extracted tree, so it only ever sees the target’s YAML files. Map the project locally (--project-dir, or [projects]) when a target’s job selection depends on non-YAML files.
• A target with more than 64 MiB of YAML is refused with a message pointing at --project-dir. Extraction runs per cross-project trigger job, and a repository that large belongs on disk rather than in a temp directory.

The target’s own .gitattributes is not applied: export-ignore hides files from git archive, but GitLab reads includes straight out of the repository, so glci does too.

The target’s config is read from its repository root as .gitlab-ci.yml; a target whose project settings point ci_config_path somewhere else needs a local mapping.

What requires a GitLab token#

Cross-project variables#

Cross-project pipelines get fresh CI variables derived from the target project’s git state rather than inheriting the parent’s. This means CI_PROJECT_NAME, CI_COMMIT_SHA, CI_COMMIT_REF_NAME, and other git-derived variables reflect the target project.

The target pipeline receives CI_PIPELINE_SOURCE=pipeline (distinct from child pipelines which use parent_pipeline).

The cross-project pipeline also gets CI_REGISTRY, CI_REGISTRY_USER, and CI_REGISTRY_IMAGE pointing at the shared embedded registry, so jobs in the triggered project can build and push images just like the parent. CI_REGISTRY_IMAGE reflects the target project’s path. CI_REGISTRY_PASSWORD is injected per job (the job token), the same way it works in the parent pipeline.

Variable forwarding uses the same forward: rules and defaults as child pipelines (see Variable forwarding above): yaml_variables (default true) forwards the parent’s global variables: merged with the trigger job’s own variables:; pipeline_variables (default false) forwards CLI/dotenv variables. The target’s own include: entries expand against that forwarded set too, exactly as a child pipeline’s do (see Variables in a child’s include paths). Forwarded values are expanded in the trigger job’s context ($CI_PROJECT_URL resolves to the parent project’s URL, not the target’s), and trigger inputs: are used only for spec interpolation, not forwarded as variables.

Dirty mode for cross-project targets#

When dirty mode is enabled (the default), glci overlays uncommitted and untracked files from local project directories onto the bare repo sent to the runner. This lets you test changes across multiple projects without committing first.

Multi-project setups#

For monorepos, standard child pipelines with different include paths work as expected. You can run a specific trigger job with glci run trigger-frontend.

For separate repositories that form a pipeline chain, map them all in .glciconfig.toml:

[projects."myorg/shared-lib"]
dir = "../shared-lib"

[projects."myorg/deploy-tools"]
dir = "../deploy-tools"
branch = "main"

include: project: in YAML#

include: project: works the same as production GitLab CI – it fetches YAML files from other projects via the GitLab Repository Files API at parse time. This always requires a GitLab token (see the token table above).

Nested includes within the fetched file that use local: are automatically rewritten to project: includes targeting the same remote project, matching GitLab’s behavior.

It applies to every config glci parses, not just the top-level .gitlab-ci.yml: a child pipeline’s config and a cross-project trigger’s target config resolve include: project: the same way, against the same GitLab instance and token. Fetched files are cached under ~/.glci/cache/includes and shared across all of them (refs naming a version tag are cached indefinitely; others for an hour).

include: component: in YAML#

include: component: fetches CI/CD components from GitLab via the API at parse time. This always requires a GitLab token.

Version selectors#

Components are referenced with a version suffix after @. In addition to exact tag references, glci supports version selectors that resolve to the latest matching semver release tag:

Pre-release tags (e.g. 1.0.0-rc1) are excluded from version selector resolution. Only stable semver tags are considered.

Version selectors query the GitLab Tags API, so they always require a GitLab token and network access. Exact tag references (e.g. @1.2.3) also require a token but skip the tag listing step.

Troubleshooting#

If a trigger job fails, check the daemon logs for resolution and parsing errors:

glci log <pipeline-id> trigger-job-name
tail -f ~/.glci/daemon.log