From ef653304c7b5fb4e52ea0a681755d7b2fc37bfcb Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Fri, 12 Jun 2026 16:35:16 +0800 Subject: [PATCH 1/2] docs: Update github-runner-operator to Mature home page milestone --- docs/index.md | 139 ++++++++++++++++++++++++++++---------------------- 1 file changed, 79 insertions(+), 60 deletions(-) diff --git a/docs/index.md b/docs/index.md index e228c899e8..1b27208c7d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -2,10 +2,11 @@ # GitHub runner operator -A [Juju](https://juju.is/) [charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/) for deploying and managing [GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on virtual machines. The charm maintains a set of self-hosted runners, each isolated in a single-use virtual machine instance. +A [Juju](https://juju.is/) [charm](https://documentation.ubuntu.com/juju/3.6/reference/charm/) for deploying and managing [GitHub self-hosted runners](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners) on virtual machines. The charm maintains a set of self-hosted runners, each isolated in a single-use virtual machine instance. + +Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. +For the GitHub runner operator, this includes: -Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. -For the github-runner-operator charm, this includes: * Stateless operation. * Configurable resource limits. * Ability to redeploy without losing any data (no need to back up). @@ -23,13 +24,22 @@ The charm enforces a set of GitHub repository settings as best practice. This is | | | |--|--| -| [Overview](https://charmhub.io/github-runner)
Overview of the charm
| [How-to guides](https://charmhub.io/github-runner/docs/how-to-openstack-runner)
Step-by-step guides covering key operations and common tasks | -| [Reference](https://charmhub.io/github-runner/docs/reference-actions)
Technical information - specifications, APIs, architecture | [Explanation](https://charmhub.io/github-runner/docs/explanation-charm-architecture)
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) | +| 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) | - -If you want to use ephemeral LXD virtual machines spawned by charm, you can refer to the section [Track local-lxd](https://charmhub.io/github-runner). - +## How this documentation is organized +This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/): + +* **Tutorials** — hands-on introductions for newcomers. +* **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. ## Contributing to this documentation @@ -39,65 +49,74 @@ If there's a particular area of documentation that you'd like to see that's miss ## Project and community -The GitHub runner charm is a member of the Ubuntu family. It's an open-source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback. +The GitHub runner operator is a member of the Ubuntu family. It's an open-source project that warmly welcomes community projects, contributions, suggestions, fixes, and constructive feedback. + +### Governance and policies -- [Code of conduct](https://ubuntu.com/community/code-of-conduct) -- [Get support](https://discourse.charmhub.io/) -- [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) -- [Contribute](https://github.com/canonical/github-runner-operator/blob/main/CONTRIBUTING.md) +* [Code of conduct](https://ubuntu.com/community/code-of-conduct) -Thinking about using the GitHub runner charm for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! +### Get involved + +* [Get support](https://discourse.charmhub.io/) +* [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com) +* [Contribute](https://github.com/canonical/github-runner-operator/blob/main/CONTRIBUTING.md) + +### Releases + +* [Changelog](changelog.md) + +Thinking about using the GitHub runner operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! # Contents 1. [How to](how-to) - 1. [Change repository or organization](how-to/change-path.md) - 1. [Change GitHub personal access token](how-to/change-token.md) - 1. [Add custom labels](how-to/add-custom-labels.md) - 1. [Debug with SSH](how-to/debug-with-ssh.md) - 1. [Integrate with COS](how-to/integrate-with-cos.md) - 1. [Spawn OpenStack runner](how-to/openstack-runner.md) - 1. [Comply with security requirements](how-to/comply-security.md) - 1. [Upgrade](how-to/upgrade.md) - 1. [Contribute](how-to/contribute.md) + 1. [Change repository or organization](how-to/change-path.md) + 1. [Change GitHub personal access token](how-to/change-token.md) + 1. [Add custom labels](how-to/add-custom-labels.md) + 1. [Debug with SSH](how-to/debug-with-ssh.md) + 1. [Integrate with COS](how-to/integrate-with-cos.md) + 1. [Spawn OpenStack runner](how-to/openstack-runner.md) + 1. [Comply with security requirements](how-to/comply-security.md) + 1. [Upgrade](how-to/upgrade.md) + 1. [Contribute](how-to/contribute.md) 1. [Reference](reference) - 1. [Actions](reference/actions.md) - 1. [Charm architecture](reference/charm-architecture.md) - 1. [Configurations](reference/configurations.md) - 1. [COS Integration](reference/cos.md) - 1. [GitHub runner cryptographic overview](reference/cryptographic-overview.md) - 1. [External Access](reference/external-access.md) - 1. [Integrations](reference/integrations.md) - 1. [Token scopes](reference/token-scopes.md) + 1. [Actions](reference/actions.md) + 1. [Charm architecture](reference/charm-architecture.md) + 1. [Configurations](reference/configurations.md) + 1. [COS Integration](reference/cos.md) + 1. [GitHub runner cryptographic overview](reference/cryptographic-overview.md) + 1. [External Access](reference/external-access.md) + 1. [Integrations](reference/integrations.md) + 1. [Token scopes](reference/token-scopes.md) 1. [Explanation](explanation) - 1. [SSH Debug](explanation/ssh-debug.md) + 1. [SSH Debug](explanation/ssh-debug.md) 1. [Changelog](changelog.md) 1. [Track local-lxd](local-lxd) - 1. [Tutorial](local-lxd/tutorial) - 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) - 1. [Quick start](local-lxd/tutorial/quick-start.md) - 1. [How to](local-lxd/how-to) - 1. [Add custom labels](local-lxd/how-to/add-custom-labels.md) - 1. [Change repository or organization](local-lxd/how-to/change-path.md) - 1. [Change GitHub personal access token](local-lxd/how-to/change-token.md) - 1. [Comply with security requirements](local-lxd/how-to/comply-security.md) - 1. [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) - 1. [Debug with SSH](local-lxd/how-to/debug-with-ssh.md) - 1. [Deploy on ARM64](local-lxd/how-to/deploy-on-arm64.md) - 1. [Integrate with COS](local-lxd/how-to/integrate-with-cos.md) - 1. [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) - 1. [Set base image](local-lxd/how-to/set-base-image.md) - 1. [Reference](local-lxd/reference) - 1. [Actions](local-lxd/reference/actions.md) - 1. [Charm architecture](local-lxd/reference/charm-architecture.md) - 1. [Configurations](local-lxd/reference/configurations.md) - 1. [COS Integration](local-lxd/reference/cos.md) - 1. [GitHub runner cryptographic overview](local-lxd/reference/cryptographic-overview.md) - 1. [External Access](local-lxd/reference/external-access.md) - 1. [Integrations](local-lxd/reference/integrations.md) - 1. [Token scopes](local-lxd/reference/token-scopes.md) - 1. [Explanation](local-lxd/explanation) - 1. [ARM64](local-lxd/explanation/arm64.md) - 1. [Security](explanation/security.md) - 1. [SSH Debug](local-lxd/explanation/ssh-debug.md) - \ No newline at end of file + 1. [Tutorial](local-lxd/tutorial) + 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) + 1. [Quick start](local-lxd/tutorial/quick-start.md) + 1. [How to](local-lxd/how-to) + 1. [Add custom labels](local-lxd/how-to/add-custom-labels.md) + 1. [Change repository or organization](local-lxd/how-to/change-path.md) + 1. [Change GitHub personal access token](local-lxd/how-to/change-token.md) + 1. [Comply with security requirements](local-lxd/how-to/comply-security.md) + 1. [Configure runner storage](local-lxd/how-to/configure-runner-storage.md) + 1. [Debug with SSH](local-lxd/how-to/debug-with-ssh.md) + 1. [Deploy on ARM64](local-lxd/how-to/deploy-on-arm64.md) + 1. [Integrate with COS](local-lxd/how-to/integrate-with-cos.md) + 1. [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) + 1. [Set base image](local-lxd/how-to/set-base-image.md) + 1. [Reference](local-lxd/reference) + 1. [Actions](local-lxd/reference/actions.md) + 1. [Charm architecture](local-lxd/reference/charm-architecture.md) + 1. [Configurations](local-lxd/reference/configurations.md) + 1. [COS Integration](local-lxd/reference/cos.md) + 1. [GitHub runner cryptographic overview](local-lxd/reference/cryptographic-overview.md) + 1. [External Access](local-lxd/reference/external-access.md) + 1. [Integrations](local-lxd/reference/integrations.md) + 1. [Token scopes](local-lxd/reference/token-scopes.md) + 1. [Explanation](local-lxd/explanation) + 1. [ARM64](local-lxd/explanation/arm64.md) + 1. [Security](explanation/security.md) + 1. [SSH Debug](local-lxd/explanation/ssh-debug.md) + From 35caa5f19dfd439f09f83b83904d41fb24077743 Mon Sep 17 00:00:00 2001 From: charlie4284 Date: Mon, 29 Jun 2026 16:27:16 +0800 Subject: [PATCH 2/2] docs: Address PR review comments for home page table - 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 --- docs/index.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/docs/index.md b/docs/index.md index 1b27208c7d..a2317d4dcb 100644 --- a/docs/index.md +++ b/docs/index.md @@ -24,12 +24,12 @@ The charm enforces a set of GitHub repository settings as best practice. This is | | | |--|--| -| 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) | +| 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) | +| Design | [Charm architecture](reference/charm-architecture.md) • [Integrations](reference/integrations.md) • [ARM64](local-lxd/explanation/arm64.md) | +| Security | [Security overview](explanation/security.md) • [Cryptographic overview](reference/cryptographic-overview.md) • [Token scopes](reference/token-scopes.md) • [External Access](reference/external-access.md) • [Comply with security requirements](how-to/comply-security.md) • [Manage external contributors](how-to/manage-external-contributors.md) | ## How this documentation is organized @@ -39,7 +39,6 @@ This documentation uses the [Diátaxis documentation structure](https://diataxis * **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. ## Contributing to this documentation @@ -90,10 +89,10 @@ Thinking about using the GitHub runner operator for your next project? [Get in t 1. [Token scopes](reference/token-scopes.md) 1. [Explanation](explanation) 1. [SSH Debug](explanation/ssh-debug.md) -1. [Changelog](changelog.md) + 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) + 1. [Security](explanation/security.md) 1. [Track local-lxd](local-lxd) 1. [Tutorial](local-lxd/tutorial) - 1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md) 1. [Quick start](local-lxd/tutorial/quick-start.md) 1. [How to](local-lxd/how-to) 1. [Add custom labels](local-lxd/how-to/add-custom-labels.md) @@ -117,6 +116,5 @@ Thinking about using the GitHub runner operator for your next project? [Get in t 1. [Token scopes](local-lxd/reference/token-scopes.md) 1. [Explanation](local-lxd/explanation) 1. [ARM64](local-lxd/explanation/arm64.md) - 1. [Security](explanation/security.md) 1. [SSH Debug](local-lxd/explanation/ssh-debug.md)