docs(cicd): add self-hosted runner reliability requirements#28
docs(cicd): add self-hosted runner reliability requirements#28JacobPEvans wants to merge 2 commits into
Conversation
|
Preview deployment for your docs. Learn more about Mintlify Previews.
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces comprehensive documentation for the organization's GitHub Actions runner topology, including a new dedicated MDX file, an entry in the navigation configuration, and a descriptive card in the infrastructure overview. The documentation covers the three runner tiers (RunsOn, GitHub-hosted, and on-prem), label usage, and strict requirements for self-hosted instances. Review feedback focuses on correcting an invalid AWS instance type in the examples, ensuring consistent markdown formatting for commands and labels, and aligning the documentation card order with the project's navigation structure.
The CI/CD overview documented the four runner tiers but didn't say what a self-hosted runner has to actually be. The recurring token-refresh failure in orbstack-kubernetes (JacobPEvans/orbstack-kubernetes#234, #237) shows the cost of leaving this implicit. Adds a single subsection between "Runner tiers" and "The shape of every IaC pipeline" listing the five non-negotiables for any self-hosted runner: GitHub App auth (not PAT), digest-pinned image, process healthcheck, dead-man's-switch heartbeat, pre-flight secret check. Links to the orbstack-kubernetes runner as the reference implementation. Companion PRs codify the same rules at the AI-agent layer: - JacobPEvans/ai-assistant-instructions#654 (org-wide ci-cd-policy rule) - JacobPEvans/claude-code-plugins#321 (self-hosted-runners skill) Supersedes the earlier standalone runner-topology-page draft in this PR's history — the four-tier CI/CD section landed in #23 in the meantime, making a separate topology page redundant. Assisted-by: Claude <noreply@anthropic.com>
JacobPEvans
force-pushed
the
chore/runner-topology-page
branch
from
0240311 to
96d4136
Compare
JacobPEvans
changed the title
Restate the reliability requirements as policy rather than as "things we learned the hard way". Each rule now reads as the current standard; the historical incident link and the consequence-narrative trailers are removed. Assisted-by: Claude <noreply@anthropic.com>
|
Closing — superseded by #32 (merged). The five-item self-hosted runner reliability section this PR adds to Where to look now: https://docs.jacobpevans.com/infrastructure/cicd/policy#on-prem-runner-requirements #32 also added a CardGroup link from The cross-references this PR cited ( Reopen if you want a different framing on the overview page itself (e.g. a short teaser pointing at the detail page); for now the redirect via the existing CardGroup is sufficient. |
1 participant
Summary
The CI/CD overview added in #23 documented the four runner tiers but didn't say what a self-hosted runner has to actually be — and the recurring token-refresh failure in orbstack-kubernetes (JacobPEvans/orbstack-kubernetes#234, #237) shows the cost of leaving this implicit.
This PR adds a single subsection between "Runner tiers" and "The shape of every IaC pipeline" listing the five non-negotiables for any self-hosted runner: GitHub App auth (not PAT), digest-pinned image, process healthcheck, dead-man's-switch heartbeat, pre-flight secret check.
Reference implementation: `orbstack-kubernetes/docker/actions-runner/`.
Companion PRs
The same rules at the AI-agent layer:
What changed since the initial PR
The initial draft of this PR added a standalone `infrastructure/github-actions-runners.mdx` topology page. PR #23 landed in the meantime adding the full four-tier CI/CD section, making a separate topology page redundant. This PR was reworked down to just the reliability-requirements enrichment on the existing CI/CD overview.
Test plan