GitLab避坑指南

Rules Gotchas

• - rules: and only:/except: can't mix — use one or the other per job
• First matching rule wins — put specific rules before general ones
• Missing when: defaults to on_success — rules: - if: $CI_COMMIT_TAG runs on tag
• Empty rules array rules: [] means never run — different from no rules at all
• Add - when: never at end to prevent fallthrough — otherwise unmatched conditions may run

Silent Failures

• - Protected variables missing on non-protected branches — job runs but variable is empty
• Runner tag mismatch — job stays pending forever with no error
• INLINECODE7 on non-privileged runner — fails with cryptic Docker errors
• Masked variable format invalid — variable exposed in logs anyway

YAML Merge Traps

• - extends: doesn't deep merge arrays — scripts, variables arrays get replaced, not appended
• Use !reference [.job, script] to reuse — INLINECODE10
• INLINECODE11 files can override each other — last one wins for same keys
• Anchors &/* don't work across files — use extends: for cross-file reuse

Artifacts vs Cache

• - Cache not guaranteed between runs — treat as optimization, not requirement
• Artifacts auto-download by stage — add dependencies: [] to skip if not needed
• INLINECODE16 downloads artifacts by default — needs: [{job: x, artifacts: false}] to skip

Docker-in-Docker

• - Shared runners usually don't support privileged — need self-hosted or special config
• INLINECODE18 required — job uses wrong Docker otherwise
• INLINECODE19 or configure TLS properly — half-configured TLS breaks builds

Pipeline Triggers

• - CI_PIPELINE_SOURCE differs by trigger — push, merge_request_event, schedule, api, INLINECODE25
• MR pipelines need rules: - if: $CI_MERGE_REQUEST_IID — not just branch rules
• Detached vs merged result pipelines — detached tests source, merged tests result of merge