diff --git a/README.md b/README.md index 0aec69a..9ffd501 100644 --- a/README.md +++ b/README.md @@ -19,9 +19,9 @@ github-scout shows you what is waiting for you across all your repositories, in ## Who it is for -github-scout is built for people with many GitHub repositories, private ones included, who already run Grafana and Loki. It checks each repository every 15 minutes. It covers up to 500 repositories of your own github.com account, not organization repositories or Dependabot alerts. +github-scout is built for people with many GitHub repositories, private ones included. It checks each repository every 15 minutes. It covers up to 500 repositories of your own github.com account, not organization repositories or Dependabot alerts. -You need Grafana, Loki, a log collector such as Grafana Alloy, and a read-only GitHub personal access token. +github-scout reports through its log, so its dashboard and alerts come from your Grafana, Loki and Alertmanager, which the [monitoring guide](https://github.com/cplieger/docs/blob/main/docs/monitoring.md#the-smallest-stack-sends-notifications-only) sets up. You also need a read-only GitHub personal access token. Other tools suit other needs: @@ -60,8 +60,8 @@ services: ``` 4. Run `docker compose up -d`. -5. Have your log collector send the container's logs to Loki with the label `container="github-scout"`, which every dashboard panel selects on. -6. In Grafana, import [`grafana-dashboard.json`](grafana-dashboard.json). It reads from your default Loki data source. +5. Have your log collector [send the container's logs to Loki](https://github.com/cplieger/docs/blob/main/docs/monitoring.md#the-smallest-stack-sends-notifications-only) with the label `container="github-scout"`, which every dashboard panel selects on. +6. In Grafana, [import](https://github.com/cplieger/docs/blob/main/docs/monitoring.md#importing-an-apps-dashboard) [`grafana-dashboard.json`](grafana-dashboard.json). It reads from your default Loki data source. Run `docker logs github-scout`. You should see a line with `"msg":"scan complete"`. If you see `"msg":"repo discovery failed"` instead, GitHub rejected the token or could not be reached. Check the `GITHUB_TOKEN` line of `.env`. @@ -101,7 +101,7 @@ The healthcheck runs `/github-scout health`, which checks that the scan loop ref ## Monitoring -github-scout writes one JSON log line for each open pull request, issue, alert and finished run, plus a `scan complete` summary after each scan. The bundled dashboard reads those lines from Loki, and two Loki alert rules fire when scans go blind or stop. [Monitoring and alerts](docs/monitoring.md) lists the log fields, the dashboard and the rules. +github-scout writes one JSON log line for each open pull request, issue, alert and finished run, plus a `scan complete` summary after each scan. Two Loki alert rules fire when scans go blind or stop. [Monitoring and alerts](docs/monitoring.md) lists the log fields, the dashboard and the rules. ## Documentation diff --git a/docs/hardening.md b/docs/hardening.md index 6e69e2b..58ad8aa 100644 --- a/docs/hardening.md +++ b/docs/hardening.md @@ -13,7 +13,7 @@ Because github-scout only reads, a read-only token is all it needs. [Configurati ## Hardened deployment -To lock the container down further, pin the image by digest and add these settings to the quick start service: +[Pin the image by digest](https://github.com/cplieger/docs/blob/main/docs/images.md#pinning-a-digest) and add these lines to the quick start service. [Hardening a compose file](https://github.com/cplieger/docs/blob/main/docs/hardening.md) explains each setting. ```yaml read_only: true diff --git a/docs/monitoring.md b/docs/monitoring.md index b9095bd..474639a 100644 --- a/docs/monitoring.md +++ b/docs/monitoring.md @@ -61,7 +61,7 @@ A single 401 beside successful reads only marks the scan degraded, because GitHu ## Grafana dashboard -Ship the container's logs to Loki with a `container` label that holds the container name, then import [`grafana-dashboard.json`](../grafana-dashboard.json) or drop it into a file-based dashboard provider. With Grafana Alloy's [`loki.source.docker`](https://grafana.com/docs/alloy/latest/reference/components/loki/loki.source.docker/), that label comes from a relabel rule that copies `__meta_docker_container_name` without its leading `/`. The dashboard reads from your default Loki data source and needs no plugin. Its rows follow the order you ask questions: +The dashboard needs the container's log in Loki with a `container` label that holds the container name, which the Alloy config in the [monitoring guide](https://github.com/cplieger/docs/blob/main/docs/monitoring.md#the-smallest-stack-sends-notifications-only) sets. [Importing an app's dashboard](https://github.com/cplieger/docs/blob/main/docs/monitoring.md#importing-an-apps-dashboard) shows how to load [`grafana-dashboard.json`](../grafana-dashboard.json). The dashboard reads from your default Loki data source and needs no plugin. Its rows follow the order you ask questions: 1. At a glance holds four count tiles, for open pull requests, open issues, code-scanning alerts and failed CI runs in the selected time range. 2. Open work holds linked tables of the open pull requests, issues and code-scanning alerts from the latest scan. @@ -104,7 +104,7 @@ spec: ## Alerting -github-scout has no metrics endpoint, so its state is in its logs. Ship the container's logs to Loki as above and evaluate these rules with [Loki's ruler](https://grafana.com/docs/loki/latest/alert/). Firing alerts go through your Alertmanager like any Prometheus alert. The first rule catches scans that ran but went blind. The second fires when no scan completes at all. +github-scout has no metrics endpoint, so its state is in its logs. These rules are for Loki's ruler. Save the block below as a file in Loki's rules folder, as [Loading an app's alert rules](https://github.com/cplieger/docs/blob/main/docs/monitoring.md#loading-an-apps-alert-rules) shows. The first rule catches scans that ran but went blind. The second fires when no scan completes at all. ```yaml groups: