v3.0.0

Promoted from v3.0.0-dev.22

forge-scout v3 is the project formerly called github-scout, rebuilt to read more than one forge. It puts the open pull requests, open issues, failing CI workflows and finished CI runs of your repositories on GitHub, GitLab, Gitea and Forgejo on one Grafana dashboard, and adds code-scanning alerts on GitHub. Each forge is a connection in one YAML config file, and connections are read side by side. The dashboard has five tabs: Overview, CI runs, Open work, Code scanning and Scout health. This is a major release, so a v2 deployment needs the steps below before it upgrades.

Upgrade checklist

1. Pull ghcr.io/cplieger/forge-scout:v3.0.0 or docker.io/cplieger/forge-scout:v3.0.0. The github-scout images get no new releases. (#488)
2. Copy config.example.yaml to /config/config.yaml, add one connection for each forge with its url, owners and token, and mount the file read-only. Move each old environment variable to its key as the first breaking change below lists. (#426)
3. Write the old PR_EXCLUDE_QUERY and ISSUE_EXCLUDE_QUERY filters as exclude rules, such as - author: "renovate[bot]" or - label: renovate. The exclude_authors and exclude_labels keys that the first breaking change names were removed before this release, and the config file now refuses them as unknown keys. (#443)
4. With a fine-grained GitHub token, add read-only Contents to its permissions. (#437)
5. Mount a /data volume that the container user owns, so the run state survives a restart. (#426)
6. Point every Loki query and alert rule at {container="forge-scout"}, and replace the old rules with ForgeScoutScanDegraded and ForgeScoutScanStalled from docs/monitoring.md. (#426)
7. Import the new grafana-dashboard.json, then delete the old "GitHub Scout" dashboard. (#488)
8. Change any Renovate rule or download URL that names cplieger/github-scout to cplieger/forge-scout. (#488)

Breaking changes

Scan GitHub, GitLab, Gitea and Forgejo from one config file (#426)

Change the deployment as follows before upgrading.

• The binary is now /forge-scout, and the example container name is forge-scout. Update any entrypoint, health check or container name that names /github-scout or github-scout.
• Settings now come from one YAML file at /config/config.yaml, mounted read-only, or the path in CONFIG_PATH. Copy config.example.yaml to start.
• forge-scout no longer reads GITHUB_OWNER, GITHUB_TOKEN, SCAN_INTERVAL, LOOKBACK_HOURS, EXCLUDE_REPOS, CODE_SCANNING_EXCLUDE_REPOS, CODE_SCANNING_EXCLUDE_FORKS, PR_EXCLUDE_QUERY, ISSUE_EXCLUDE_QUERY or LOG_LEVEL.
• Each connection names its url, owners and token. The token must be exactly one ${NAME} reference to an environment variable whose name ends in _TOKEN or starts with FORGE_SCOUT_.
• The old settings map as follows: SCAN_INTERVAL to scan_interval, LOOKBACK_HOURS to lookback, a Go duration that must be at least 4.2 times scan_interval, EXCLUDE_REPOS to exclude_repos, CODE_SCANNING_EXCLUDE_REPOS to security.skip_repos, CODE_SCANNING_EXCLUDE_FORKS to security.skip_forks, and LOG_LEVEL to log_level.
• The two search-query settings are replaced by exclude_authors and exclude_labels.
• Code scanning on private repositories is off unless security.include_private is true.
• A container that still sets GITHUB_OWNER or GITHUB_TOKEN without a config file stops at start with an error naming the file.
• The run state now lives on a /data volume. Mount a folder the container user owns, uid 1000 or your PUID and PGID. Without it, each restart starts cold.
• Every log line carries forge and connection, and repo is the path the forge shows.
• workflow run is now ci run. conclusion is replaced by state (passing, failing or neutral), and event by trigger (push, pull_request, schedule, manual, other or unknown).
• code scanning alert is now security alert, with source.
• scan complete is logged once per connection. code_alerts is now security_alerts, duration is now duration_ms, scanned is gone (repos_discovered and skipped count the repositories), failed_signals names security_alerts instead of code_scanning, and every signal has a <signal>_read field.
• New log lines: scan stopped, failing workflow, slow workflow, ci day, disabled workflow, top security alert, security tool, runs coverage gap and owner lists no repository.
• A finished run's line can repeat after a crash. Count runs by connection, repo, run_id, state and updated_at.
• The Loki selector is now {container="forge-scout"}. Update any query or rule that reads {container="github-scout"}.
• The example alert rules are renamed and retuned. GithubScoutScanDegraded is now ForgeScoutScanDegraded, grouped by connection, with a 100m window. GithubScoutScanStalled is now ForgeScoutScanStalled, which counts scan complete or scan stopped over 55m. Replace the old rules with the ones in docs/monitoring.md.
• The dashboard's UID is now forge-scout (it was github-scout), with the title Forge Scout and a new tab layout. Import the new grafana-dashboard.json and delete the old "GitHub Scout" dashboard, because importing over it creates a second dashboard.

Rename github-scout to forge-scout (#488)

The project is renamed from github-scout to forge-scout. Change these before upgrading.

• Pull the image as ghcr.io/cplieger/forge-scout or docker.io/cplieger/forge-scout, in place of ghcr.io/cplieger/github-scout and docker.io/cplieger/github-scout, which get no new releases.
• Use the repository URL https://github.com/cplieger/forge-scout, including in any Renovate rule or dashboard download URL that names cplieger/github-scout.
• The dashboard's UID is forge-scout and its title is Forge Scout. Import the new grafana-dashboard.json and delete the old "GitHub Scout" dashboard.

Added

• One config file reads GitHub, GitLab, Gitea and Forgejo connections side by side, each with its own owners and token. A signal a forge does not have, such as code scanning on Gitea and Forgejo, shows as not available instead of 0. (#426)
• A new exclude list leaves out open pull requests and issues that match a rule, set at the top level for every connection or on one connection. A rule can match on kind, author, label, title as a Go regular expression, repository and draft state, and the Overview shows how many items the rules left out. (#443)
• forge-scout keeps each connection open between scans and answers an unchanged page from memory after a conditional request, so an unchanged run list costs no request on GitHub. The Scout health tab shows the requests each connection spends per hour, split by read, and how the read cache answered. (#480)
• The dashboard shows only what needs action. Outside Scout health, a tile that reads 0 and an empty table are hidden, and the Overview shows All clear when nothing needs you. The Code scanning tab hides when no connection reads code scanning. (#481)
• The Overview's table of pull requests is now "Pull requests needing attention" and shows why each one is listed. (#483)

Fixed

• With a fine-grained token, one pull request whose checks GitHub refuses no longer hides every open pull request or degrades the scan. That pull request's checks show as not available with this token, and one warning names the remedy, a classic token with repo. A repository with more than 500 open code-scanning alerts now reads complete, up to 10,000 alerts per repository. (#437)
• Every dashboard panel counts open pull requests and issues apart, so a list of pull requests read in part no longer hides the issue counts. An alert with no security severity shows its problem severity, and a GitHub App author such as renovate[bot] counts as a bot on every route, so an exclude rule on it matches everywhere. (#460)
• When a scan stops on the API budget, the dashboard keeps each connection's last complete scan of the past 7 days instead of going blank, and dates older values with As of. (#465)
• Rows that held a single panel no longer collapse, and the tables on the CI runs and Open work tabs are shorter and scroll. (#483)
• forge-scout now builds on the stable forgeapi v1.3.0 release. (#491)

Performance

• On GitHub, an unchanged code-scanning or workflows page is answered from memory after a free conditional request, and the run list request stays the same for a whole UTC day. None of those reads costs a REST request while its answer is unchanged, and every run count still covers exactly lookback. (#482)

Full changelog: v2.5.0...v3.0.0

Dependencies: 11 changes (github.com/cplieger/atomicfile/v4, github.com/cplieger/envx/v2, github.com/cplieger/envx/yamlenv/v2)

• Added github.com/cplieger/atomicfile/v4 v4.1.0 (Go)
• Removed github.com/cplieger/envx/v2 v2.0.7 (Go)
• Added github.com/cplieger/envx/yamlenv/v2 v2.0.3 (Go)
• Added github.com/cplieger/forgeapi v1.3.0 (Go)
• Added github.com/cplieger/jsoncap/v2 v2.0.3 (Go)
• Removed github.com/cplieger/runesafe/v2 v2.1.1 (Go)
• Added github.com/cplieger/runesafe/v3 v3.0.0 (Go)
• Added github.com/cplieger/ssrf/v4 v4.4.0 (Go)
• Added go.yaml.in/yaml/v3 v3.0.5 (Go)
• Transitive changes: 2 Go modules

v2.5.0

Promoted from v2.5.0-dev.3

Changed

• Drop unread repo fields and narrow config defaults (#413)

Full changelog: v2.4.2...v2.5.0

v2.4.2

Built from main for dependency and system-package updates

Full changelog: v2.4.1...v2.4.2

Dependencies: 8 changes (github.com/cplieger/envx/v2, github.com/cplieger/health, github.com/cplieger/httpx/v5)

• github.com/cplieger/envx/v2 v2.0.3 to v2.0.7 (Go)
• github.com/cplieger/health v1.8.0 to v1.8.2 (Go)
• github.com/cplieger/httpx/v5 v5.0.3 to v5.0.5 (Go)
• github.com/cplieger/runesafe/v2 v2.1.0 to v2.1.1 (Go)
• github.com/cplieger/scheduler/v4 v4.2.1 to v4.2.3 (Go)
• github.com/cplieger/slogx v1.6.5 to v1.6.7 (Go)
• go 1.27.1 to 1.27.2 (Go)
• Transitive changes: 1 Go module

System packages: 8 changes (github.com/cplieger/envx/v2, github.com/cplieger/health, github.com/cplieger/httpx/v5)

• github.com/cplieger/envx/v2 v2.0.3 to v2.0.7
• github.com/cplieger/health v1.8.0 to v1.8.2
• github.com/cplieger/httpx/v5 v5.0.3 to v5.0.5
• github.com/cplieger/pathinside/v2 v2.0.1 to v2.0.3
• github.com/cplieger/runesafe/v2 v2.1.0 to v2.1.1
• github.com/cplieger/scheduler/v4 v4.2.1 to v4.2.3
• github.com/cplieger/slogx v1.6.5 to v1.6.7
• stdlib go1.27.1 to go1.27.2

v2.4.1

Fixed

• Remove the failures by repository panel (#393)

v2.4.0

Added

• Move to Grafana schema v2, add failures per repo

v2.3.0

Added

• Ship the license text of every bundled component in the image

v2.2.17

Fixed

• Retry GitHub search timeouts instead of degrading the scan

v2.2.16

Dependencies

• Update gcr.io/distroless/static-debian13:nonroot docker digest to e2e927e (#345)

v2.2.15

Fixed

• Update module github.com/cplieger/scheduler/v4 to v4.2.1 (#343)

v2.2.14

Fixed

• Keep the health deadline armed when the configured cadence is absurd

Dependencies

• Update github.com/cplieger/health to v1.8.0