Skip to content

Refresh the README: metrics, flags, webhook events and Docker usage #299

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

Merged
cpanato merged 1 commit into from
Oct 9, 2026
Merged

Refresh the README: metrics, flags, webhook events and Docker usage #299

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down
66 changes: 50 additions & 16 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)

Expand All @@ -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:
Expand All @@ -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

Expand All @@ -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
Expand All @@ -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 `<version>` 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:<version>
docker run -d -p 9101:9101 -p 8065:8065 ghcr.io/cpanato/github_actions_exporter:<version> --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
Expand All @@ -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).
Loading