ci: bulletproof pipeline (phase 1) — docs advisory, toolchain retries, dependabot auto-approve, main-health, DCO auto-signoff#179
Merged
Conversation
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
Comment on lines
+29
to
+63
| runs-on: ubuntu-latest | ||
| timeout-minutes: 10 | ||
| steps: | ||
| - uses: actions/checkout@v6 | ||
|
|
||
| - name: Install uv | ||
| uses: astral-sh/setup-uv@v7 | ||
| with: | ||
| python-version: "3.13" | ||
|
|
||
| - name: Install Python deps | ||
| run: uv sync --extra docs --extra server --extra mcp | ||
|
|
||
| - name: Version sync | ||
| run: uv run python scripts/check_version_sync.py | ||
|
|
||
| # Builds against the committed generated artifacts. Staleness of those | ||
| # artifacts is advisory (see docs-quality), not a build failure — a | ||
| # strict build validates nav, internal links, and rendering, which is | ||
| # what "the docs build" means. | ||
| - name: Build (strict) | ||
| run: uv run mkdocs build --strict | ||
|
|
||
| - name: Docstring coverage | ||
| run: uv run python scripts/check_docstrings.py | ||
|
|
||
| - name: SDK coverage | ||
| run: uv run python scripts/check_sdk_coverage.py | ||
|
|
||
| - name: Tutorial snippet verification | ||
| if: hashFiles('docs/tutorials/*.md') != '' | ||
| run: uv run python scripts/verify_tutorial_snippets.py docs/tutorials | ||
|
|
||
| # ---- ADVISORY: quality signals, never block a merge ------------------ | ||
| docs-quality: |
…t auto-approve, main-health canary, DCO auto-signoff
Phase 1 of the CI-fragility remediation. Root cause of the recurring red
checks: required gates that are nondeterministic (history-keyed doc-drift
across the squash-merge boundary; transient toolchain-install flake),
cosmetic checks wired as blocking, and automation defeated by its own
rails. This retiers the pipeline so only "does the code/docs build" blocks
a merge, and makes the remaining required installs survive network blips.
docs.yml — split into two jobs:
* docs (REQUIRED): deterministic + fast — version-sync, mkdocs build
--strict, docstring/SDK coverage, tutorial snippets. No regeneration,
no git-history walk, no network. Cannot flake across a squash.
* docs-quality (ADVISORY, every step continue-on-error): regenerate +
drift / freshness (check_doc_sources) / spelling / markdownlint / link
check, all as warnings. A doc typo or stale-artifact no longer blocks
an unrelated PR. Release-PR artifact drift is still auto-fixed by
release-please-docs.yml.
ci.yml — retry the raw-network installs in the REQUIRED test job (minisign
apt, protoc + protoc-gen-doc downloads). 3 attempts with backoff; the
SHA256 verify stays AFTER the retries so a partial/failed download still
fails loud and unverified binaries never install. Preserves the issue-#16
skip-guard (a genuinely-missing tool still fails the final `command -v` /
sha256 check). Kills transient-flake merge blocks without losing coverage.
dependabot-auto-approve.yml (new) — github-actions[bot] approves only
dependabot[bot] patch/minor PRs so they satisfy the "1 review" rule and
auto-merge completes hands-free. Human PRs still require a manual review.
main-health.yml (new) — opens/updates a tracking issue when a required
workflow fails on a push to main, so a red main can't sit unnoticed.
scripts/dco_signoff.sh + pre-commit prepare-commit-msg hook + `make init`
— auto-append a DCO Signed-off-by trailer so your own commits never trip
DCO, regardless of whether your git email maps to org membership.
Verified locally: required docs job passes against committed content with
no regen/foreign toolchain (mkdocs --strict 4s; coverage checks rc=0); the
original freshness-gate poison now downgrades to an advisory warning while
the required docs job stays green; retry logic tested (success / transient
/ all-fail-loud); DCO hook idempotent; all workflow YAMLs parse.
Signed-off-by: Sean Mauk <seanmauk@krakennetworks.com>
se-jo-ma
force-pushed
the
ci/bulletproof-phase1
branch
from
July 13, 2026 22:03
c3f2d83 to
c6da401
Compare
se-jo-ma
changed the title
se-jo-ma
enabled auto-merge (squash)
July 16, 2026 14:45
krakennetworks
approved these changes
Jul 16, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Phase 1 of the CI-fragility remediation. Companion to #178 (immediate unblock). Follows the RCA: the pipeline kept burning because required gates were nondeterministic or cosmetic, and dependabot automation was cancelled by its own rails.
Principle: block only on "does the code/docs build." Everything else auto-fixes or advises — never gates. And the required gates that remain must survive transient flake.
docs.yml— split by severitydocsmkdocs build --strict· docstring + SDK coverage · tutorial snippets — deterministic, fast, no regeneration / no git-history / no networkdocs-qualitycontinue-on-error)check_doc_sourcesfreshness · spelling · markdownlint · link-check — all as warningsThe freshness gate keyed on commit SHAs/dates, which squash-merge rewrites → green-on-PR, red-on-main (what broke #178's target). Advisory kills the whole class. Reproduced: the original poison (stale
last_verifiedvs a newerpyproject.tomlcommit) now exits 1 inside the advisory job (warning) while the requireddocsjob stays green.ci.yml— harden required toolchain installs (folded in)The required
testjob installs minisign/protoc/protoc-gen-doc via raw apt+curl — a transient network/apt blip would fail a required job for no real reason. Each is now retried (3× w/ backoff). The SHA256 verify stays after the retries, so a partial/failed download still fails loud and no unverified binary installs. The issue-#16 skip-guard is preserved (a genuinely-missing tool still fails). Retry logic unit-tested for success / transient-then-success / all-fail-loud.dependabot-auto-approve.yml(new)github-actions[bot]approves onlydependabot[bot]patch/minor PRs → satisfies the "1 review" rule → existing auto-merge completes with zero clicks. Human PRs (incl. write-collaborators) still require a manual review.main-health.yml(new)A required workflow failing a push to
mainopens/updates amain-healthtracking issue. Main once sat red 6 days unnoticed.DCO auto-signoff
scripts/dco_signoff.sh+ pre-commitprepare-commit-msghook (installed bymake init) auto-appendSigned-off-bymatching the author — your own commits never trip DCO even when your git email isn't the org-mapped one.Verified locally
docsjob green against committed content, no regen/toolchain:mkdocs --strict4s; version-sync/docstring/SDK coverage rc=0.docsstill green (reproduced both directions).Not in this PR (by design)
docsstays required;docs-qualityis never added to required..github/dco.ymluntouched (already remediation-friendly, non-required). Open question: keep DCO vs drop the ceremony.Phase 2 (separate): lift this pipeline into
kraken-dotgithubreusable workflows for nautilus + stargraph.🤖 Generated with Claude Code
https://claude.ai/code/session_01WwWcjyxBybBxWxLEue99YY