PushMetrics can push your report configurations as YAML files to a GitHub repository. Once connected, every report can be published to Git, reviewed in GitHub like any other code change, and reverted from history if something goes wrong. This is the recommended way to keep an audit trail of how your reports evolve and to promote changes between environments.

Before you start

You will need:

  • A GitHub account with permission to create repositories (a personal account or an organization you belong to).
  • The Workspace Admin role in PushMetrics. The Git Integration panel is read-only for non-admin users.
  • About 5 minutes.

Create an empty GitHub repository

We recommend creating a brand-new, empty private repository dedicated to your PushMetrics reports. An empty repo is the easiest starting point — PushMetrics will create the first file the first time you publish a report.

  1. In GitHub, click the + menu in the top-right corner and choose New repository.
  2. Pick the Owner (yourself or your organization) and a Repository name (e.g. pushmetrics-workspace).
  3. Set visibility to Private.
  4. Leave "Add a README file" unchecked. Do not add a .gitignore or a license either — you want a fully empty repo.
  5. Click Create repository.

Official GitHub guide: Creating a new repository.

Create a Personal Access Token

PushMetrics authenticates to GitHub with a Personal Access Token (PAT) that you generate in your GitHub account. The token is stored encrypted on our servers and is only used to push and pull report YAML files for the workspace it is configured on.

GitHub offers two kinds of PATs. Either works with PushMetrics — pick the one that matches your security policy.

Common starting steps for both options:

  1. In GitHub, click your profile avatar (top-right) and choose Settings.
  2. Scroll all the way down the left sidebar to Developer settings.
  3. Click Personal access tokens.

Direct link: github.com/settings/tokens.

Option A — Fine-grained personal access token

A fine-grained token can be scoped to a single repository with only the permissions PushMetrics needs. This is the more secure option and is the right choice for most organizations.

  1. Choose Fine-grained tokens → Generate new token.
  2. Give it a descriptive name (e.g. pushmetrics-<workspace>) and an expiration date.
  3. Under Repository access, select Only select repositories and pick the repository you just created.
  4. Under Permissions → Repository permissions, set Contents to Read and write.
  5. Click Generate token and copy it immediately — GitHub only shows it once.

Official GitHub guide: Creating a fine-grained personal access token.

Option B — Classic personal access token

A classic token is quicker to create — a single checkbox covers everything — but the repo scope grants access to all of the repositories your account can see, not just the one you want PushMetrics to use.

  1. Choose Tokens (classic) → Generate new token (classic).
  2. Give it a descriptive name and an expiration date.
  3. Tick the repo scope (Full control of private repositories).
  4. Click Generate token and copy it immediately.

Official GitHub guide: Creating a personal access token (classic).

Configure the integration in PushMetrics

In PushMetrics, open the Account page and scroll to the Git Integration section.

Fill in the form:

  • GitHub Repository URL — the full URL of the repo you created, starting with https://github.com/ (e.g. https://github.com/acme-inc/pushmetrics-workspace).
  • Branch — leave blank to use the repository's default branch (usually main). Set this only if you want to publish to a specific branch.
  • Personal Access Token — paste the token you copied from GitHub.

Click Test Connection. PushMetrics will call the GitHub API and confirm that the repo and credentials work. On success you'll see a green confirmation with the repo name and default branch.

When the test passes, click Connect (or Save changes if you are updating an existing connection). Your token is encrypted on save and is never sent back to your browser. If you ever need to test the connection again later, you'll need to re-enter the token because the saved one cannot leave the server in plain text.

What changes once it's connected

Once Git Integration is configured, two new actions become available across the app.

On the report editor, a new Git button appears in the report header. Its menu has:

  • Publish to Git — pushes the current report's YAML as a commit to the configured branch. The first publish creates the file in the repo; later publishes update it. PushMetrics tracks the last published commit per report and will warn you if someone else pushed a newer version before letting you overwrite it.
  • Git History — opens a panel listing every commit that touched this report's YAML, so you can preview and revert to a past version.

On the report list, the bulk actions menu gains a Publish to Git item. Select multiple reports and publish them all in one go — PushMetrics runs the work in the background and shows you per-report results when it finishes.

Security notes

  • Tokens are stored encrypted server-side using the same pattern as other integration credentials. They are never returned to the browser after saving.
  • Prefer a fine-grained PAT scoped to a single repository. Revoking it in GitHub immediately cuts off PushMetrics' access without affecting your other repos.
  • Disconnecting does not delete anything in GitHub. The "Disconnect" action removes the saved repo URL and token from PushMetrics, but the YAML files already in your repository stay where they are.
  • Branch protection rules block direct publishes. If your default branch requires pull requests, configure PushMetrics to publish to an unprotected branch for now. A pull-request-based workflow is on the roadmap.

Troubleshooting

  • Test Connection fails with a 401 error — the token is wrong, has expired, or doesn't grant Contents: Read and write on the repository. Generate a new token and try again.
  • Publish fails with a "branch protected" error — the configured branch has GitHub branch-protection rules that prevent direct pushes. Switch PushMetrics to an unprotected branch, or relax the protection rules on the target branch.
  • Publish prompts "Someone else has published a newer version" — the file in the repo changed since PushMetrics last published it. Either choose Overwrite with mine to force-publish your version, or open Git History first and revert to the remote version before re-publishing.