cplieger/forge-scout repository overview

⁠forge-scout

forge-scout puts the open pull requests, open issues and failing CI workflows across your repositories on GitHub, GitLab, Gitea and Forgejo on one Grafana dashboard, with a link on every row, and adds code-scanning alerts on GitHub. It only reads from your forges.

⁠What it does

forge-scout shows you what is waiting for you across all your repositories and forges, in one place:

• Lists open pull requests and issues, idlest first, with who opened them, how old they are and whether a pull request's checks fail.
• Lists the workflows whose latest run on the default branch failed, how many runs in a row, since when and when they last ran.
• Logs every finished CI run, the slowest workflows and the workflows GitHub disabled.
• Lists open GitHub code-scanning alerts, colored by severity.
• Adds a new repository or workflow on the next scan, with nothing to configure.
• Marks the counts a scan could not read whole, and the signals a forge does not have, so the dashboard never shows an unchecked count as 0.

⁠Who it is for

forge-scout is built for people with repositories on one or more forges, private ones included: github.com or GitHub Enterprise Server, gitlab.com or a self-managed GitLab, and Gitea or Forgejo instances. It checks every repository of the owners you name every 15 minutes.

forge-scout reports through its log, so its dashboard and alerts come from your Grafana, Loki and Alertmanager, which the monitoring guide⁠ sets up. You also need an access token for each forge, read-only where the forge allows it.

Other tools suit other needs:

• Consider the Grafana GitHub data source⁠ if you want Grafana panels that query the GitHub API directly for your repositories and projects.
• Consider gh-dash⁠ if you want to work through GitHub pull requests and issues from a terminal, with diff, comment and checkout built in.

forge-scout is free software under the GPL-3.0-or-later license.

⁠Pull

docker pull cplieger/forge-scout:latest

Also published to ghcr.io/cplieger/forge-scout with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for forge-scout. See the README for all configuration options and hardening.
services:
  forge-scout:
    image: ghcr.io/cplieger/forge-scout:latest
    container_name: forge-scout
    restart: unless-stopped
    # Must own the ./data host folder. If .env sets PUID and PGID, those numbers are used.
    user: "${PUID:-1000}:${PGID:-1000}"

    environment:
      # Every token the config file names as ${...}. Put each in a .env file beside this file.
      # The github connection in config.example.yaml reads this token. Delete this line when you remove that connection.
      GITHUB_TOKEN: "${GITHUB_TOKEN:-}"
      # The forgejo connection in config.example.yaml reads this token. Delete this line when you remove that connection.
      FORGEJO_TOKEN: "${FORGEJO_TOKEN:-}"

    volumes:
      # Run "mkdir -p config && cp config.example.yaml config/config.yaml", then edit
      # config/config.yaml before the first start.
      - "./config:/config:ro"
      # The run state. Run "mkdir -p data && sudo chown 1000:1000 data" before the first start.
      # If .env sets PUID and PGID, use those numbers.
      - "./data:/data"

⁠Documentation

• Full documentation⁠: setup, settings, troubleshooting and security
• Configuration⁠
• Security⁠
• How forge-scout works⁠
• Monitoring and alerts⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

GPL-3.0-or-later. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.

Third-party attributions are in THIRD_PARTY_NOTICES.md⁠.