CI Operations Playbook
Scope
This playbook defines operational standards for GitHub Actions in ClaudeSec:
- Single CodeQL operating model
- Required local docs validation before PR
- Retry policy for transient external action failures (
401)
- Dependabot conflict handling policy
1) CodeQL Operating Model
- Use repository default setup as the only CodeQL model.
- Do not add or reintroduce duplicate repo-level CodeQL workflow files (for example
.github/workflows/codeql.yml) unless an explicit migration plan is approved.
- If duplicate CodeQL workflows appear and conflict with default setup, remove the duplicate workflow and keep default setup.
2) Pre-PR Docs Validation (Required)
Before opening a PR that changes Markdown docs, run:
markdownlint "**/*.md"
lychee "**/*.md"
If either command fails, fix issues before pushing.
3) Transient 401 Action Download Failures
Trigger
When a workflow fails with action download errors like 401 (Unauthorized) from GitHub API tarball fetch.
Response
- Rerun the failed workflow.
- If it fails again with the same transient signature, rerun one more time.
- If it still fails after 2 reruns, move to manual triage.
Manual Triage Checklist
- Confirm the referenced action/revision still exists.
- Confirm workflow token/permissions are not over-restricted for checkout and action download.
- Check GitHub Status for platform incidents.
- If needed, pin to a currently available action release and open a follow-up PR.
4) Dependabot Action PR Conflict Policy
When Dependabot PRs for GitHub Actions conflict with current main:
- Apply the required action-version updates directly to
main.
- Verify CI passes on
main.
- Close duplicate/conflicting Dependabot PRs.
- Add a closing rationale comment that links to the commit on
main.
This keeps the PR queue clean and avoids repeated conflict churn.
References