From 5e49a5a1c6a3592d893b05c5c3c79049ee18a4d0 Mon Sep 17 00:00:00 2001 From: Carlos Panato Date: Fri, 9 Oct 2026 17:57:39 +0200 Subject: [PATCH] Refresh the README: metrics, flags, webhook events and Docker usage - document the workflow metrics and the flags/env vars - webhook events are Workflow jobs and Workflow runs, not Check Run - mention the separate ingress/metrics ports - fix the Docker image name and tag, use go install, mention the Helm chart - use relative links and main instead of master Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Carlos Panato --- CONTRIBUTING.md | 4 +-- README.md | 66 +++++++++++++++++++++++++++++++++++++------------ 2 files changed, 52 insertions(+), 18 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 83f3f486..7c0e1781 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,9 +14,9 @@ This project uses GitHub to manage reviews of pull requests. ## Pull Request Checklist -* Start by forking the project, and then create a feature branch from the master branch for your feature. +* Start by forking the project, and then create a feature branch from the main branch for your feature. -* If needed, rebase to the current master branch before submitting your pull request. If it doesn't merge cleanly with master you may be asked to rebase your changes. +* If needed, rebase to the current main branch before submitting your pull request. If it doesn't merge cleanly with main you may be asked to rebase your changes. * Commits should be as small as possible, while ensuring that each commit is correct independently (i.e., each commit should compile and pass tests). diff --git a/README.md b/README.md index 8d1a7435..142e28cf 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,21 @@ # GitHub Actions Exporter -Prometheus exporter exposing [GitHub Actions](https://github.com/features/actions) metrics. +Prometheus exporter exposing [GitHub Actions](https://github.com/features/actions) metrics: -Right now this exporter only expose the one metric which is the WorkFlow execution -time. - -Other metrics can be added in the future. +- workflow job and workflow run metrics (durations, queue time, status counts), built from GitHub webhook events +- GitHub Actions billing metrics (minutes used, paid and per runner type), polled from the GitHub API ## Getting Started This exporter receives webhook events from GitHub. -If you want to collect metrics from a GitHub repository you will need to create a webhook -in your GitHub repo. +If you want to collect metrics from a GitHub repository or organization you will need to create a webhook +in GitHub. -You need just to select the `Check Run` event and the set your secret (that you start your exporter, see below) +You need to select the `Workflow jobs` and `Workflow runs` events and set your secret (the same one you start your exporter with, see below). -The webhook will call `/gh_event` path on your endpoint by default. You can change this with the `--web.gh-webhook-path` option. +The exporter listens on two addresses: the webhook is received on `--web.listen-address-ingress` (`:8065` by default) and the metrics are exposed on `--web.listen-address` (`:9101` by default). +The webhook will call the `/gh_event` path on your ingress endpoint by default. You can change this with the `--web.gh-webhook-path` option. ![gh_webook](./assets/gh_webhook.png) @@ -31,6 +30,18 @@ The metrics are built from the GitHub [billing usage report](https://docs.github When configuring for an organization, the Access token must belong to an administrator of the organization and the organization must be on the enhanced billing platform. When configuring for an user, the token must belong to that user. +### Metrics + +Webhook metrics: + +| Metric | Type | Labels | Description | +|--------|------|--------|-------------| +| `workflow_job_duration_seconds` | histogram | `org`, `repo`, `branch`, `state`, `runner_group`, `workflow_name`, `job_name` | Time that a workflow job took to reach a given state (`queued`, `in_progress`). | +| `workflow_job_duration_seconds_total` | counter | `org`, `repo`, `branch`, `status`, `conclusion`, `runner_group`, `workflow_name`, `job_name` | The total duration of jobs. | +| `workflow_job_status_count` | counter | `org`, `repo`, `branch`, `status`, `conclusion`, `runner_group`, `workflow_name`, `job_name` | Count of workflow job events. | +| `workflow_execution_time_seconds` | histogram | `org`, `repo`, `branch`, `workflow_name`, `conclusion` | Time that a workflow took to run. | +| `workflow_status_count` | counter | `org`, `repo`, `branch`, `status`, `conclusion`, `workflow_name` | Count of the occurrences of different workflow states. | + ### Example queries Time a job waits for a runner (queued until started) per runner group, useful to compare how fast runner groups pick up jobs: @@ -47,6 +58,23 @@ sum by (runner_group) (rate(workflow_job_duration_seconds_count{state="queued"}[ histogram_quantile(0.95, sum by (le, runner_group) (rate(workflow_job_duration_seconds_bucket{state="queued"}[5m]))) ``` +### Flags + +| Flag | Environment variable | Default | Description | +|------|----------------------|---------|-------------| +| `--web.listen-address` | | `:9101` | Address to listen on for metrics. | +| `--web.listen-address-ingress` | | `:8065` | Address to listen on for the webhook and the web interface. | +| `--web.telemetry-path` | | `/metrics` | Path under which to expose metrics. | +| `--web.gh-webhook-path` | | `/gh_event` | Path that will be called by the GitHub webhook. | +| `--gh.github-webhook-token` | `GITHUB_WEBHOOK_TOKEN` | | GitHub webhook secret (required). | +| `--gh.github-api-token` | `GITHUB_API_TOKEN` | | GitHub API token, only needed for the billing metrics. | +| `--gh.github-org` | `GITHUB_ORG` | | GitHub organization to collect the billing metrics for. | +| `--gh.github-user` | | | GitHub user to collect the billing metrics for. | +| `--gh.billing-poll-seconds` | `BILLING_POLL_SECONDS` | `5` | Frequency at which to poll the billing API. | +| `--log.level` | | `info` | Only log messages with the given severity or above (`debug`, `info`, `warn`, `error`). | +| `--log.format` | | `logfmt` | Output format of log messages (`logfmt`, `json`). | + +Run `github_actions_exporter --help` for the complete list. ### Prerequisites @@ -55,7 +83,7 @@ To run this project, you will need a [working Go environment](https://golang.org ### Installing ```bash -go get -u github.com/cpanato/github_actions_exporter +go install github.com/cpanato/github_actions_exporter@latest ``` ## Building @@ -74,15 +102,21 @@ make build ## Docker -You can deploy this exporter using the [ghcr.io/cpanato/github_actions_exporter-linux-amd64](https://github.com/users/cpanato/packages/container/package/github_actions_exporter-linux-amd64) Docker image. +You can deploy this exporter using the [ghcr.io/cpanato/github_actions_exporter](https://github.com/users/cpanato/packages/container/package/github_actions_exporter) Docker image. -For example: +For example (replace `` with a [release](https://github.com/cpanato/github_actions_exporter/releases) tag, e.g. `v0.10.1`): ```bash -docker pull ghcr.io/cpanato/github_actions_exporter-linux-amd64:v0.2.0 -docker run -d -p 9101:9101 ghcr.io/cpanato/github_actions_exporter-linux-amd64:v0.2.0 --gh.github-webhook-token="1234567890token" --gh.github-api-token="Accesstoken" --gh.github-org="honk_org" +docker pull ghcr.io/cpanato/github_actions_exporter: +docker run -d -p 9101:9101 -p 8065:8065 ghcr.io/cpanato/github_actions_exporter: --gh.github-webhook-token="1234567890token" --gh.github-api-token="Accesstoken" --gh.github-org="honk_org" ``` +Port `9101` serves the metrics and port `8065` receives the GitHub webhooks. + +## Helm chart + +A Helm chart is available in [charts/github-exporter](./charts/github-exporter). + ## Testing ### Running unit tests @@ -105,8 +139,8 @@ Open Prometheus at http://localhost:9090 and explore the available metrics. ## Contributing -Refer to [CONTRIBUTING.md](https://github.com/cpanato/github_actions_exporter/blob/master/CONTRIBUTING.md). +Refer to [CONTRIBUTING.md](./CONTRIBUTING.md). ## License -Apache License 2.0, see [LICENSE](https://github.com/cpanato/github_actions_exporter/blob/master/LICENSE). +Apache License 2.0, see [LICENSE](./LICENSE).