ci-pipeline-debugging
Skill0 starsChanged 5 months agoMITView on GitHub
Diagnose a failing GitLab CI/CD pipeline or Ansible job without leaking masked variables: read job logs/traces safely, reproduce the execution environment locally, and recognize common Molecule/ansible-lint/idempotence/runner-tag failure signatures. Triggers on: pipeline failed, red pipeline, job failed, CI failure, debug pipeline, molecule failure, runner tag, ansible error, check-mode failure.
In this repository24 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ansible-patternsSkill
- ansible-testingSkill
- change-documentationSkill
- drift-detectionSkill
- gitlab-cicd-pipelineSkill
- hsa-infrastructureSkill
- iac-sast-scanningSkill
- iac-tooling-selectionSkill
- incident-responseSkill
- instinct-promotionSkill
- instinct-rollbackSkill
- knowledge-curationSkill
- multi-env-promotionSkill
- octopus-releaseSkill
- pci-cp-complianceSkill
- pci-dss-complianceSkill
- pci-pin-awarenessSkill
- perso-change-controlSkill
- perso-complianceSkill
- pre-commit-and-secret-scanningSkill
- rollback-and-runbooksSkill
- secrets-vaultSkill
- supply-chain-and-sbomSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 16
Use when a GitLab CI job or an Ansible run has failed and you need to find the root cause.
- Distinctive: line 31
Confirm semantics with Context7: before blaming syntax (modules/keywords are version-specific).
- Very specific: line 67
Read-only / reproduction-only.
- Distinctive: line 68
Never print masked variables or secret values from logs.
- Distinctive: line 98
Never extract secrets from job logs.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CI Pipeline Debugging Skill
When to Use
Use when a GitLab CI job or an Ansible run has failed and you need to find the root
cause. This is the playbook the iac-debugger agent leans on. It is read-only and
reproduction-only — diagnose and propose, never apply or rerun against prod.
How It Works
- Read the failure safely — pull the job log/trace read-only (
glab ci trace/get, or a read-only GitLab MCP if configured). Never echo masked CI variables; do not enableCI_DEBUG_TRACEon protected jobs (it can expose secrets). Find the first error, not the downstream cascade. - Classify the failure (see signatures) — code defect, drift, environment/runner, secret-connectivity, or trust-boundary.
- Reproduce minimally — re-run the narrowest read-only command in the same
execution environment (EE) image:
ansible-lint,--syntax-check,--check --diff --tags <x>. Pin the EE by digest so the repro matches CI. - Confirm semantics with Context7 before blaming syntax (modules/keywords are version-specific).
- Propose the minimal fix + verification command — hand authoring to
iac-author.
Common failure signatures → cause
| Signature in the log | Likely cause | First check |
changed=N on a re-run / Molecule idempotence step fails | non-idempotent task (missing creates:/changed_when:) | the task reported changed on 2nd converge |
couldn't resolve module/action / FQCN error | collection not installed in the EE, or short module name | requirements.yml / EE contents |
This job is stuck / no runner | runner tag mismatch or no runner for the tag | job tags: vs registered runner tags |
ansible-lint non-zero, production profile | rule violation (FQCN, risky command/shell, no_log) | the named rule id |
Vault permission denied / 403 on lookup | JWT/OIDC aud mismatch or missing role binding | bound_audiences vs CI id_tokens aud |
Permission denied (publickey) to a host | SSH key/known_hosts in the job, not a playbook bug | before_script key setup |
| WinRM/psrp timeout on Windows hosts | transport/credential/firewall, not the role logic | connectivity, not the task |
Examples
Reproduce a Molecule idempotence failure locally
# Same EE image (digest-pinned), narrowest scope:
molecule converge -s default
molecule idempotence -s default # second converge must report no changes
# A task that shows changed here is the non-idempotent culprit — cite it.Read a failing job without leaking secrets
glab ci trace <job-id> # read-only; do NOT set CI_DEBUG_TRACE on protected jobs
# Identify the FIRST failing line; ignore the downstream cascade.Trust boundary
- Read-only / reproduction-only; never apply, never run without
--check, never prod. - Never print masked variables or secret values from logs; redact and cite location.
- A PAN/key/secret surfaced in a log → route to
incident-response+ flag; stop. - HSA failures → in-zone local lane.
Deep Reference
Failure Signature Table
| Error | Likely cause | First check |
ERROR! the role 'X' was not found | Missing collection or wrong path | ansible-galaxy collection list |
fatal: [host]: FAILED! => changed: false with no message | Handler not notified | Check notify: chain |
UNREACHABLE! => SSH Error: Permission denied | Wrong SSH key or user | Check ansible_user and key in group_vars |
WinRM connection failed | WinRM not enabled or firewall | Test-WSMan from target, check port 5985/5986 |
No module named 'X' in CI | Missing Python dependency | Add to requirements.txt or CI image |
yaml.scanner.ScannerError | Indentation or tab in YAML | yamllint -d default <file> |
| Pipeline timeout | Job exceeded timeout: value | Increase timeout or split job |
Reading a Failed ansible-lint Report
Focus on [rule-name] tags. Suppressable: [yaml[line-length]]. Never suppress: [fqcn], [no-changed-when], [risky-file-permissions].
Safe Job Log Access
# Via GitLab API (read-only)
curl --header "PRIVATE-TOKEN: $GITLAB_TOKEN" \
"https://gitlab.example.com/api/v4/projects/<id>/jobs/<job_id>/trace"Never extract secrets from job logs. If a job log contains a masked variable value, report it to the security team immediately.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.