The Complete Production SOP: How to Deploy and Run GitLab CI Multi-Stage Pipelines & Artifact Passing in Autonomous AI Agents
Production guide: Configure GitLab CI multi-stage pipelines and artifact passing in Codex, Claude Code, and Cursor with deterministic SKILL.md SOPs.
Technical Overview & Architectural Context
Autonomous coding agents frequently generate brittle or invalid GitLab CI/CD configurations due to conflicting structural paradigms. Common agent failures include conflating sequential stages with Directed Acyclic Graphs (DAGs), misconfiguring ephemeral artifact expiration paths, improperly nesting GitLab rules clauses (such as mixing 'only/except' with modern 'rules:if'), and omitting artifact dependency specifications across asynchronous jobs. When an agent creates a multi-stage pipeline without deterministic boundary guards, downstream deploy jobs fail because artifacts from intermediate build stages are silently missing or expired. The 'gitlab-ci-yaml-stages-artifacts' skill injects strict procedural standards into Codex, Claude Code, Cursor, and Windsurf runtimes. By establishing declarative stage hierarchies, explicit DAG 'needs' relationships, granular artifact path scoping, and predictable cache keys, this skill prevents non-deterministic CI configurations and ensures zero-defect pipeline executions across merge requests and production deployments.
Prerequisites & Environment Requirements
Verified Search Intents & Long-Tail Queries Solved
This operational tutorial is engineered to provide deterministic solutions for these developer search queries:
Step-by-Step Execution Playbook
Local Environment Setup & SKILL.md Mounting
Mount the skill manifest into your target agent runtime's global or workspace skill registry.
Autonomous agent runtimes scan standardized local paths to register available SOPs. For Claude Code CLI, skills reside in ~/.claude/skills/ or workspace .claude/skills/. For Cursor and Windsurf, skills map to .cursor/rules/ or .windsurf/skills/. For OpenAI Codex, skills reside in the runtime manifest directory. Injecting SKILL.md ensures that prompt intents containing CI pipeline requests immediately trigger strict GitLab syntax compliance.
mkdir -p ~/.agents/skills/gitlab-ci-yaml-stages-artifacts && cat << 'EOF' > ~/.agents/skills/gitlab-ci-yaml-stages-artifacts/SKILL.md
---
name: "gitlab-ci-yaml-stages-artifacts"
description: "Construct complex GitLab CI pipelines with stages, dependencies, and ephemeral job artifacts."
metadata:
author: "GitLab"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "write .gitlab-ci.yml"
- "pass artifacts gitlab ci"
- "gitlab ci rules changes"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---
# GitLab CI Multi-Stage Pipelines & Artifact Passing
Configures .gitlab-ci.yml: defining stages (lint, test, build, deploy), artifacts (paths, expire_in, reports:junit), caching across jobs, rules conditionals (if, changes), and runner tags.
## When to Invoke
Invoke this skill whenever you need to:
- write .gitlab-ci.yml
- pass artifacts gitlab ci
- gitlab ci rules changes
## Execution SOP & Rules
1. Declare stages: [lint, test, build, deploy] at the root of .gitlab-ci.yml.
2. Use artifacts: { paths: [dist/], expire_in: '1 day' } to pass compiled assets downstream.
3. Configure rules: - if: '$CI_PIPELINE_SOURCE == "merge_request_event"' for MR-only pipelines.
4. Use needs: [build_job] to enable DAG execution and run dependent jobs without waiting for entire stage.
## Verification Checklist
- Run local linting, syntax validation, and type-checks before reporting completion.
- Ensure all created or modified files adhere to workspace boundaries and avoid uncommitted secrets.
- Verify tests or build commands exit cleanly with return code 0.
EOF---
name: "gitlab-ci-yaml-stages-artifacts"
description: "Construct complex GitLab CI pipelines with stages, dependencies, and ephemeral job artifacts."
metadata:
author: "GitLab"
version: "1.0.0"
runtime_compatibility:
- "codex"
- "claude-code"
- "cursor"
- "windsurf"
triggers:
- "write .gitlab-ci.yml"
- "pass artifacts gitlab ci"
- "gitlab ci rules changes"
permissions:
fs_read: true
fs_write: "workspace"
shell_exec: false
net_access: false
---To save up to 45% LLM context tokens, mount the skill in the global runtime path (~/.agents/skills) rather than duplicating full text prompts into every prompt session.
Ensure directory permissions match your workspace user (chmod 755). Sandboxed agents like Claude Code CLI will halt if an unreadable skill manifest fails the initial manifest discovery pass.
Local Validator & Linter Dependency Validation
Set up offline schema verification tools to allow the agent to test its pipeline yaml locally.
Because gitlab-ci-yaml-stages-artifacts operates with shell_exec: false and net_access: false, the agent writes valid configuration files directly to the workspace. You must provide the local environment with validation hooks such as 'gitlab-ci-lint' or the official 'glab ci lint' CLI utility. This ensures local quality gates can execute immediately after code emission.
which glab >/dev/null 2>&1 || (echo "Warning: glab CLI not detected. Install via brew install glab or curl binary for local syntax checks.")Set up a git pre-commit hook that runs 'glab ci lint .gitlab-ci.yml' automatically so agent commits are pre-screened before pushing to remote branches.
Never place real GitLab project tokens (CI_JOB_TOKEN or personal access tokens) in your working repository or agent prompts; rely entirely on predefined GitLab CI runtime environment variables.
Intent Matching & Trigger Invocation
Prompt the agent using validated triggers to engage deterministic pipeline construction.
The skill runtime binds to specific phrase triggers: 'write .gitlab-ci.yml', 'pass artifacts gitlab ci', and 'gitlab ci rules changes'. When structuring prompts, using these explicit verbs instructs the agent to invoke the SOP rules, enforcing DAG dependencies ('needs'), structured artifact retention policies ('expire_in'), and modular staging.
Structure prompts with distinct operational boundaries: specify the upstream producer job, downstream consumer job, artifact paths, and cache boundaries.
Avoid ambiguous legacy phrasing like 'gitlab only/except rules' as it triggers outdated syntax models instead of modern 'rules:if' logic.
Verification, Linting & Output Quality Gate
Perform schema validation and artifact path verification against the generated .gitlab-ci.yml file.
Once the agent completes the file generation, verify that stages, jobs, and artifact dependencies are structurally sound. Use the GitLab CI schema validator to confirm that all 'needs' references point to defined jobs within earlier or concurrent stages, and verify that artifact paths match output directory targets.
glab ci lint .gitlab-ci.yml || python3 -c "import yaml; yaml.safe_load(open('.gitlab-ci.yml')) and print('.gitlab-ci.yml is valid YAML')"Review 'git diff .gitlab-ci.yml' to verify that artifact paths (e.g., 'build/', 'coverage/') are explicitly relative to the project root and do not reference absolute OS paths.
Real-World Scenario: Multi-Stage Monorepo Pipeline with DAG Artifact Passing & Conditional Deployments
“write .gitlab-ci.yml for a Node.js monorepo with stages lint, test, build, and deploy. Ensure the build job creates 'dist/' and passes artifacts to deploy. Use needs: [build] on deploy to pass artifacts gitlab ci without waiting for test completion. Add gitlab ci rules changes so deploy only runs on main branch.”
Runtime Troubleshooting & Failure Modes
Root Cause: The downstream job specified in 'needs:' or 'dependencies:' references a job name that does not expose an 'artifacts:paths' definition, or the upstream job is not declared in a prior stage in sequential mode.
# Add artifacts block to upstream build job
build:
stage: build
script:
- npm run build
artifacts:
paths:
- dist/
expire_in: 1 day
deploy:
stage: deploy
needs: [build]
script:
- ./deploy.sh dist/Root Cause: The agent introduced legacy 'only: [main]' along with modern 'rules: - if: ...' or improperly structured file change paths within the rules array.
# Standardize exclusively on modern GitLab CI rules syntax
deploy:
stage: deploy
rules:
- if: '$CI_COMMIT_BRANCH == "main"'
changes:
- dist/**/*
- src/**/*
script:
- ./deploy.shFrequently Asked Questions (GitLab CI Multi-Stage Pipelines & Artifact Passing SOP)
Q:Can I use GitLab CI Multi-Stage Pipelines & Artifact Passing across Codex, Claude Code, and Cursor simultaneously?
Yes. This skill adheres strictly to the open SKILL.md specification. Runtimes including OpenAI Codex, Claude Code CLI, Cursor, and Windsurf parse the triggers and boundaries identically, ensuring unified cross-agent behavior.
Q:How does GitLab CI Multi-Stage Pipelines & Artifact Passing prevent context window overflow during long agent sessions?
The skill enforces focused procedural boundaries directly at the prompt interpretation layer. Instead of prompting the agent with hundreds of lines of reference CI/CD configurations, the skill provides 4 targeted SOP directives, keeping token consumption minimal while eliminating hallucinated syntax.
Q:Does this skill require escalated root or container permissions?
No. It is audited with a security score of 98/100. It requires only workspace file-system read/write permissions to create and edit .gitlab-ci.yml. It explicitly disables shell execution and external network access during execution.
Ready to equip your autonomous agent with GitLab CI Multi-Stage Pipelines & Artifact Passing?
Copy the complete audited SKILL.md specification or download the 1-click zip bundle directly from our verified registry.