Skip to content

docs: update the readme #195

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
cbartz wants to merge 7 commits into
base: main
Choose a base branch
from
Open

docs: update the readme #195

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
25c7dae
docs: Add readme intro
cbartz Apr 30, 2026
107e1db
docs: update repository layout and remove observability section
cbartz Apr 30, 2026
5fdfb77
docs: move Grafana dashboard reference to docs/reference
cbartz Apr 30, 2026
9daeb09
docs: fix review comments - capitalize Juju and replace e.g.
cbartz Apr 30, 2026
31595c4
docs: fix spelling and broken link in grafana-dashboards reference
cbartz Apr 30, 2026
8c5952b
docs: fix host metrics receiver link to point to correct source
cbartz Apr 30, 2026
f3da639
Merge branch 'main' into docs/update-readme-ISD-5404
cbartz Apr 30, 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
37 changes: 14 additions & 23 deletions README.md
View file
Open in desktop
Copy link
Copy Markdown
Contributor

@erinecon erinecon Apr 30, 2026

Choose a reason for hiding this comment

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

WDYT about adding a link to the RTD site somewhere in the README, or a dedicated section about the documentation? Currently we use this template section for most of our repos with RTD projects:

## Documentation

Our documentation is stored in the `docs` directory.
It is based on the Canonical starter pack
and hosted on [Read the Docs](LINK TO RTD). In structuring,
the documentation employs the [Diátaxis](https://diataxis.fr/) approach.

You may open a pull request with your documentation changes, or you can
[file a bug](LINK TO ISSUES) to provide constructive feedback or suggestions.

To run the documentation locally before submitting your changes:

```bash
cd docs
make run
```

GitHub runs automatic checks on the documentation
to verify spelling, validate links and style guide compliance.

You can (and should) run the same checks locally:

```bash
make spelling
make linkcheck
make vale
make lint-md
```

Original file line number Diff line number Diff line change
@@ -1,41 +1,32 @@
# GitHub runner operators

![WIP](https://img.shields.io/badge/status-WIP-yellow)
This repository contains applications, Juju charms, Grafana dashboards and actions related to operating and using
self-hosted GitHub Actions runners.

A monorepo containing charms to operate Self-Hosted GitHub Action Runners.

## Repository layout

```
actions/
enable-log-forwarding/ # GitHub Action: enable log forwarding on runners

charms/
planner-operator/ # Juju charm: GitHub runner planner
cos_custom/
grafana_dashboards/ # Grafana dashboards for the planner charm
# (served via cos-configuration-k8s, path: charms/planner-operator/cos_custom/grafana_dashboards)
webhook-gateway-operator/ # Juju charm: GitHub webhook gateway
Comment on lines 13 to 17
Copy link
Copy Markdown
Contributor

@erinecon erinecon Apr 30, 2026

Choose a reason for hiding this comment

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

Do you think the README should provide any descriptions or high-level overview of the roles/responsibilities fulfilled by the charms? I think that the layout block is already clear about the structure, but consider adding a new section after the layout (maybe something like ## Charms or ## Repository charms) with some brief details about the purpose of the charms.


runner_grafana_dashboards/ # Grafana dashboards for runner VM host metrics
# (served via cos-configuration-k8s, path: runner_grafana_dashboards)
```
cmd/
planner/ # Application entry point: planner
webhook-gateway/ # Application entry point: webhook gateway

## Observability: Grafana dashboards
internal/ # Shared Go packages
Copy link
Copy Markdown
Contributor

@erinecon erinecon Apr 30, 2026

Choose a reason for hiding this comment

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

I ran the README draft through Gemini and asked for feedback about how digestable the README is for LLMs. Gemini said that it's not clear what the internal folder actually holds -- what kind of logic exists in this folder? Perhaps clarifying the purpose in this block may help, something like:

Suggested change
internal/ # Shared Go packages
internal/ # Shared Go packages to <fulfill this specific purpose>

That way you don't need to provide more details or an explicit section


Dashboards in this repo are delivered to Grafana through
[`cos-configuration-k8s`](https://charmhub.io/cos-configuration-k8s), which syncs
JSON files from this Git repository and provisions them via the `grafana-dashboard`
relation. Provisioned dashboards are **immutable** in Grafana regardless of user
role — they cannot be edited or deleted through the UI.
docs/ # Documentation
Copy link
Copy Markdown
Collaborator Author

@cbartz cbartz Apr 30, 2026

Choose a reason for hiding this comment

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

I have removed this, because I do not think we should mention deployment details here.


### Conventions
runner_grafana_dashboards/ # Grafana dashboards for runner VM host metrics
Comment thread
cbartz marked this conversation as resolved.
```

| Directory | Purpose | `grafana_dashboards_path` config value |
|---|---|---|
| `charms/<charm>/cos_custom/grafana_dashboards/` | Dashboards for a specific charm's workload metrics | `charms/<charm>/cos_custom/grafana_dashboards` |
| `runner_grafana_dashboards/` | Dashboards for runner VM host-level metrics (CPU, memory, disk, network) | `runner_grafana_dashboards` |
## Further information

Dashboard JSON files should use `__inputs` to declare the datasource (type `prometheus`).
Setting `"editable": false` is recommended for clarity, but is not strictly required:
dashboards delivered through `cos-configuration-k8s` are filesystem-provisioned and
therefore read-only in Grafana regardless of the JSON flag. Metric names follow the
[OpenTelemetry hostmetrics receiver](https://opentelemetry.io/docs/collector/components/#receiver)
Prometheus naming convention (e.g. `system_cpu_time_seconds_total`).
Further information can be found in the `docs/` directory.
Comment on lines +30 to +32
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

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

A new doc page is being added under docs/reference/, but docs/changelog.md wasn’t updated. Please add a short changelog entry noting the new reference page so documentation consumers can track user-facing doc changes.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator Author

@cbartz cbartz Apr 30, 2026

Choose a reason for hiding this comment

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

the changelog currently only refers to planner and webhook-gateway charm. should we change the changelog to reflect everything user-facing in this repo? @erinecon

Copy link
Copy Markdown
Contributor

@erinecon erinecon Apr 30, 2026

Choose a reason for hiding this comment

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

Yes, I think so -- the changelog should cover everything relevant to users

Comment thread
cbartz marked this conversation as resolved.
Comment thread
cbartz marked this conversation as resolved.
Comment thread
cbartz marked this conversation as resolved.
15 changes: 15 additions & 0 deletions docs/reference/grafana-dashboards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
# Grafana dashboards

## Dashboard directories

| Directory | Purpose |
|---|---|
| `charms/<charm>/cos_custom/grafana_dashboards/` | Dashboards for a specific charm's workload metrics |
| `runner_grafana_dashboards/` | Dashboards for runner VM host-level metrics (CPU, memory, disk, network) |

Comment thread
cbartz marked this conversation as resolved.
## Conventions

Dashboard JSON files should use `__inputs` to declare the data source (type `prometheus`).
Setting `"editable": false` is recommended for clarity. Metric names follow the
[OpenTelemetry host metrics receiver](https://github.com/open-telemetry/opentelemetry-collector-contrib/tree/main/receiver/hostmetricsreceiver)
Prometheus naming convention (for example, `system_cpu_time_seconds_total`).
3 changes: 2 additions & 1 deletion docs/reference/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,5 @@ Contents
:maxdepth: 1

architecture
charms
charms
grafana-dashboards
Loading