Skip to content

docs: Update github-runner-operator to Mature home page milestone #801

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
yanksyoon wants to merge 6 commits into
base: main
Choose a base branch
from
+78 −61
Open

docs: Update github-runner-operator to Mature home page milestone #801

Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ef65330
docs: Update github-runner-operator to Mature home page milestone
yanksyoon Jun 12, 2026
fb77c45
Merge branch 'main' into docs/mature-home-milestone-isd-5894
yanksyoon Jun 24, 2026
35caa5f
docs: Address PR review comments for home page table
yanksyoon Jun 29, 2026
13d3ee5
Merge branch 'main' into docs/mature-home-milestone-isd-5894
yanksyoon Jul 2, 2026
c1d15cc
Merge branch 'main' into docs/mature-home-milestone-isd-5894
erinecon Jul 6, 2026
562f967
Merge branch 'main' into docs/mature-home-milestone-isd-5894
yanksyoon Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 78 additions & 61 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,11 @@
# GitHub runner operator
<!-- vale Canonical.007-Headings-sentence-case = YES -->

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).
Expand All @@ -23,13 +24,21 @@ The charm enforces a set of GitHub repository settings as best practice. This is

| | |
|--|--|
| [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) |

@erinecon erinecon Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

| 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) |

@erinecon erinecon Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

| 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) |

<!-- vale Canonical.004-Canonical-product-names = NO -->
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).
<!-- vale Canonical.004-Canonical-product-names = YES -->
## How this documentation is organized

This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/):

* **Tutorials** — hands-on introductions for newcomers.

@yhaliaw yhaliaw Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Diátaxis orientation section lists "Tutorials — hands-on introductions for newcomers" as one of four categories, but the main (OpenStack) Contents TOC has no top-level Tutorial section — tutorials currently live only under "Track local-lxd". A newcomer reading this description may look for a main Tutorial section that isn't there.

Consider adding a brief parenthetical noting that hands-on tutorials currently live under the local-lxd track, or surfacing a top-level entry (e.g., a Quick start) in the main TOC to fulfil the expectation the description sets.

🤖 AI-assisted

* **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.

## Contributing to this documentation

Expand All @@ -39,65 +48,73 @@ 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)
Comment on lines +63 to +65

@erinecon erinecon Jun 27, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this might be a little misleading since the changelog isn't really capturing releases -- I think we should remove


Thinking about using the GitHub runner operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!

# Contents
<!-- vale Canonical.004-Canonical-product-names = NO -->
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. [Changelog](changelog.md)
1. [SSH Debug](explanation/ssh-debug.md)
1. [Managing resource usage](local-lxd/tutorial/managing-resource-usage.md)

@yhaliaw yhaliaw Jul 8, 2026

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

local-lxd/tutorial/managing-resource-usage.md is listed under the top-level Explanation section of the Contents TOC, but its path places it in a tutorial/ directory, and every other local-lxd/* entry appears under the "Track local-lxd" section further down. The Diátaxis orientation section added in this same PR explicitly distinguishes Tutorials from Explanation, so this placement sits at odds with both the file's path and the model just described.

Either move this entry under "Track local-lxd" → Explanation (alongside the other local-lxd content) so path and category agree, or relocate the source file out of local-lxd/tutorial/ if classifying it as general explanation is the intent.

🤖 AI-assisted

1. [Security](explanation/security.md)
1. [Track local-lxd](local-lxd)

@erinecon erinecon Jul 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some general questions about the local-lxd track:

  1. 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?
  2. 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.

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)
<!-- vale Canonical.004-Canonical-product-names = YES -->
1. [Tutorial](local-lxd/tutorial)
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. [SSH Debug](local-lxd/explanation/ssh-debug.md)
<!-- vale Canonical.004-Canonical-product-names = YES -->
Loading