docs: Update github-runner-operator to Mature home page milestone#801
Open
yanksyoon wants to merge 4 commits into
Open
docs: Update github-runner-operator to Mature home page milestone#801yanksyoon wants to merge 4 commits into
yanksyoon wants to merge 4 commits into
Conversation
yanksyoon
requested review from
cbartz,
florentianayuwono,
javierdelapuente,
weiiwang01 and
yhaliaw
as code owners
erinecon
reviewed
Jun 27, 2026
erinecon
left a comment
erinecon
left a comment
Contributor
There was a problem hiding this comment.
Thank you so much for working on the home page 🎉 the great news for us is that we have a lot of pages and content to work with :D but this also means that the review will likely take a few rounds as I'll dig into the docs in greater detail. Thanks in advance for your patience!
I've limited this first round (mostly) to suggesting pages and categories for the table
Comment on lines
+27
to
+32
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | | ||
| | Design | [Charm architecture](reference/charm-architecture.md) | [Security](explanation/security.md) | | ||
| | Security | [Cryptographic overview](reference/cryptographic-overview.md) | [Token scopes](reference/token-scopes.md) | [External Access](reference/external-access.md) | |
Contributor
There was a problem hiding this comment.
The first thing I notice in the table's rendered output is that using the vertical lines | to separate the individual pages are causing issues in the table. So I think we should convert this to be {list-table} (see e.g. the HAProxy home page). It won't render nicely until we set up an RTD project though. So we could also use • as separators instead.
| |--|--| | ||
| | [Overview](https://charmhub.io/github-runner)</br> Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks | | ||
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | |
Contributor
There was a problem hiding this comment.
Two comments here:
- Quick start should come first in the list
- "Managing resource usage" does not feel like a tutorial to me. It's not end-to-end, there are no commands for users to run, etc. If the content is still correct and relevant, I think we should move this document into the Explanation section.
| | [Overview](https://charmhub.io/github-runner)</br> Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks | | ||
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | |
Contributor
There was a problem hiding this comment.
Other ideas for pages that we could include here: Change repository or organization, Change GitHub authentication
I also think that Configure runner storage might be a better fit in this row.
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | |
Contributor
There was a problem hiding this comment.
Other ideas for pages that we could include here: Add custom labels, Set base image, Troubleshoot
But if you think any of these pages fall more into "Deployment" (meaning Day 0/1 operations), please let me know!
| | Get started | [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | [Quick start](local-lxd/tutorial/quick-start.md) | | ||
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | |
Contributor
There was a problem hiding this comment.
Two comments here:
- "Product-specific feature" is a placeholder term -- we should update to something specific to the GH runner charm.
- I'm not sure what the product-specific feature you're trying to highlight with these pages. Maybe we should highlight the local-lxd track? Or perhaps the fact that LXD and OpenStack are both options? (I don't really know what "category" the LXD/OpenStack difference highlights -- maybe "runner types"? Let me know)
| | Deployment | [Spawn OpenStack runner](how-to/openstack-runner.md) | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) | | ||
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | | ||
| | Design | [Charm architecture](reference/charm-architecture.md) | [Security](explanation/security.md) | |
Contributor
There was a problem hiding this comment.
I think the Security page should go into the dedicated row
I also think we could add the ARM64 explanation page and maybe the Integrations page
| | Operations | [Integrate with COS](how-to/integrate-with-cos.md) | [Debug with SSH](how-to/debug-with-ssh.md) | [Upgrade](how-to/upgrade.md) | | ||
| | Product-specific feature | [Comply with security requirements](how-to/comply-security.md) | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) | | ||
| | Design | [Charm architecture](reference/charm-architecture.md) | [Security](explanation/security.md) | | ||
| | Security | [Cryptographic overview](reference/cryptographic-overview.md) | [Token scopes](reference/token-scopes.md) | [External Access](reference/external-access.md) | |
Contributor
There was a problem hiding this comment.
Other pages we could add to the Security row: Security overview, Comply with security requirements, Manage external contributors
| * **How-to guides** — step-by-step guides covering key operations and common tasks. | ||
| * **Reference** — technical information such as specifications, APIs, and configuration options. | ||
| * **Explanation** — background, concepts, and design discussion. | ||
| * **Release notes** — summaries of changes and upgrade notes. |
Contributor
There was a problem hiding this comment.
Since there are no release notes for the charm, I don't think we need to include it in this list
Comment on lines
+64
to
+66
| ### Releases | ||
|
|
||
| * [Changelog](changelog.md) |
Contributor
There was a problem hiding this comment.
this might be a little misleading since the changelog isn't really capturing releases -- I think we should remove
yanksyoon
added a commit
that referenced
this pull request
Jun 29, 2026
- Reorder Get started row with Quick start first - Move Managing resource usage from Tutorial to Explanation - Enhance Deployment row with Change repository/authentication pages - Add LXD runners row with custom labels, base image, troubleshoot - Rename 'Product-specific feature' to 'LXD runners' - Enhance Design row with Integrations and ARM64 pages - Expand Security row with all suggested security-related pages - Use bullet separators instead of pipes for better rendering - Remove Release notes from documentation organization section - Remove Changelog from Contents list - Move Managing resource usage and Security to Explanation section Addresses all comments from erinecon on PR #801
- Reorder Get started row with Quick start first - Move Managing resource usage from Tutorial to Explanation - Enhance Deployment row with Change repository/authentication pages - Add LXD runners row with custom labels, base image, troubleshoot - Rename 'Product-specific feature' to 'LXD runners' - Enhance Design row with Integrations and ARM64 pages - Expand Security row with all suggested security-related pages - Use bullet separators instead of pipes for better rendering - Remove Release notes from documentation organization section - Remove Changelog from Contents list - Move Managing resource usage and Security to Explanation section Addresses all comments from erinecon on PR #801
yanksyoon
force-pushed
the
docs/mature-home-milestone-isd-5894
branch
from
837b789 to
35caa5f
Compare
erinecon
reviewed
Jul 2, 2026
erinecon
left a comment
erinecon
left a comment
Contributor
There was a problem hiding this comment.
Some general questions (which would probably lead to follow-up issues or PRs) and a nit
| |--|--| | ||
| | [Overview](https://charmhub.io/github-runner)</br> Overview of the charm </br> | [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner) </br> Step-by-step guides covering key operations and common tasks | | ||
| | [Reference](https://charmhub.io/github-runner/docs/reference-actions) </br> Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture) </br> Concepts - discussion and clarification of key topics | | ||
| | Get started | [Quick start](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | |
Contributor
There was a problem hiding this comment.
Suggested change
| | Get started | [Quick start](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | | |
| | Get started | [Deploy the GitHub runner charm](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | |
Nit, "quick start" is ambiguous about what the user will do
| | Get started | [Quick start](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | | ||
| | Deployment | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) • [Change repository or organization](how-to/change-path.md) • [Change GitHub authentication](how-to/change-token.md) | | ||
| | Operations | [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) • [Integrate with COS](how-to/integrate-with-cos.md) • [Debug with SSH](how-to/debug-with-ssh.md) • [Upgrade](how-to/upgrade.md) | | ||
| | LXD runners | [Add custom labels](local-lxd/how-to/add-custom-labels.md) • [Set base image](local-lxd/how-to/set-base-image.md) | |
Contributor
There was a problem hiding this comment.
Question: Is there any documentation (reference or explanation) about the LXD runners, or the difference between LXD and OpenStack runners? I took a look through the documentation but didn't find anything.
Do you think it would benefit users to have this kind of document? (In a follow-up PR)
| 1. [SSH Debug](explanation/ssh-debug.md) | ||
| 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) | ||
| 1. [Security](explanation/security.md) | ||
| 1. [Track local-lxd](local-lxd) |
Contributor
There was a problem hiding this comment.
Some general questions about the local-lxd track:
- Is the long-term plan for this charm to support both LXD and OpenStack runners? If we're planning to drop support for one of the tracks, what would be the approximate time scale?
- Do you think it would benefit readers if the local-lxd documentation had a landing page? (Meaning
docs/local-lxd/index.md.) I think it might be good to have some formal introduction to this portion of the documentation.
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
2 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.
What this PR does
Update to latest home page milestone
Why we need it
Documentation quality sync
Checklist
docs/changelog.mdwith user-relevant changesterraform fmtpasses andtflintreports no errorsgithub-runner-manager/pyproject.toml.Only documentation change.