diff --git a/docs/index.md b/docs/index.md index e228c899e8..d0ea40757b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,35 +1,45 @@ -# 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. +# GitHub runner operator -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). -* Supported observability through the `cos-agent` integration. -* Scheduled dependencies upgrades to mitigate security risks. Furthermore, the Landscape Client charm can be deployed with this charm to ensure other dependencies are kept up to date. + -Operating a self-hosted runner comes with [certain security concerns according to GitHub](https://docs.github.com/en/actions/hosting-your-own-runners/managing-self-hosted-runners/about-self-hosted-runners#self-hosted-runner-security). -Just like GitHub's runners, the self-hosted runners managed by the charm are isolated in a single-use virtual machine. +A [Juju](https://juju.is/) [charm](https://canonical.com/juju/docs/juju-cli/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. -Metrics and logs about the runners and the charm itself are collected and sent to the [Canonical Observability Stack](https://charmhub.io/topics/canonical-observability-stack) for analysis and visualisation. +Like any Juju charm, this charm supports one-line deployment, configuration, integration, scaling, and more. +For the GitHub runner operator, this includes: -The charm enforces a set of GitHub repository settings as best practice. This is planned to be opt-in in the future. See [How to comply with security requirements](https://charmhub.io/github-runner/docs/how-to-comply-security). +- Stateless operation. +- Configurable resource limits. +- Ability to redeploy without losing any data (no need to back up). +- Supported observability through the `cos-agent` integration. +- Scheduled dependencies upgrades to mitigate security risks. Furthermore, the Landscape Client charm can be deployed with this charm to ensure other dependencies are kept up to date. ## In this documentation -| | | -|--|--| -| [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 | - -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). + +If you want to use ephemeral LXD virtual machines, see the [Track local-lxd](#track-local-lxd) section below. + +| | | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Get started | [Deploy the GitHub runner charm](local-lxd/tutorial/quick-start.md) • [Spawn OpenStack runner](how-to/openstack-runner.md) | +| Deployment | [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 | [Run on LXD cloud](local-lxd/how-to/run-on-lxd.md) • [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 + +This documentation uses the [Diátaxis documentation structure](https://diataxis.fr/): + +- **Tutorials** — hands-on introductions for newcomers using a local LXD controller. +- **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 @@ -39,65 +49,71 @@ 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 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) -Thinking about using the GitHub runner charm for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)! +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. [Changelog](changelog.md) + 1. [SSH Debug](explanation/ssh-debug.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) - 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. [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. [Managing resource usage](local-lxd/explanation/managing-resource-usage.md) + 1. [SSH Debug](local-lxd/explanation/ssh-debug.md) + diff --git a/docs/local-lxd/tutorial/managing-resource-usage.md b/docs/local-lxd/explanation/managing-resource-usage.md similarity index 100% rename from docs/local-lxd/tutorial/managing-resource-usage.md rename to docs/local-lxd/explanation/managing-resource-usage.md