# Git integrations

> Connect GitHub, GitLab or Bitbucket so every push, tag and release becomes an event marker on your charts and ApiTraffic knows which commit was running.

Source: https://www.apitraffic.io/docs/git-integrations/overview

Link a repository to a bucket and ApiTraffic turns every push, tag and release on it into an [event marker](https://www.apitraffic.io/docs/events), with no CI changes. You see which change lines up with a jump in errors or latency, and ApiTraffic knows which commit was running when a request was captured. That commit is what links APM spans to the code that ran, and what fix prompts and AI assistants use to name the change behind a failure.

## Supported providers

| Provider | How it connects | Hosting |
| --- | --- | --- |
| [GitHub](https://www.apitraffic.io/docs/git-integrations/github) | Installs the ApiTraffic GitHub App on the repositories you choose. | github.com |
| [GitLab](https://www.apitraffic.io/docs/git-integrations/gitlab) | OAuth; ApiTraffic adds a webhook to each project you link. | gitlab.com only (not self-managed) |
| [Bitbucket](https://www.apitraffic.io/docs/git-integrations/bitbucket) | OAuth; ApiTraffic adds a webhook to each repository you link. | Bitbucket Cloud only (not Server or Data Center) |

## How it works

**Connect a provider**

An owner or admin connects the account to GitHub, GitLab or Bitbucket once.

**Link a repository to a bucket**

Pick a repository and the bucket whose traffic that code serves. Each linked repository sends events to one bucket.

**Map branches to environments**

For example `main` to Production and `release/*` to Staging. Pushes to branches that match no mapping are ignored.

**Push code**

The provider notifies ApiTraffic, and a marker appears on the bucket's charts in the mapped environment.

## Before you begin

- **Plan.** Git integrations need a plan that includes **Git integration**. Your plan can also limit how many repositories are linked. If the plan stops including it, linked repositories stop producing markers and new connections and links are refused; you can still unlink and disconnect. Markers also need **Deploy & incident markers** on your plan.
- **Role.** Connecting and disconnecting a provider is for account owners and admins. Once a provider is connected, any member can link repositories and edit branch mappings.
- **On the provider side,** you need enough access to install an app or add webhooks; each provider page says what.
- **In ApiTraffic,** the bucket and environments you want to map to must exist.

## What gets tracked

| Provider event | Marker type | Marker name |
| --- | --- | --- |
| Push to a mapped branch | `git.push` | `acme/store-api@main: 3 commits` |
| Each commit in a push, when **Per-commit markers** is on | `git.commit` | `acme/store-api@main: Fix tax rounding` (first line of the commit message) |
| New tag | `git.tag` | `acme/store-api: tag v1.4.0` |
| Release published | `git.release` | `acme/store-api: release 1.4.0` |

A push marker carries the commit list in its metadata, and its popover links to the commit. Commit author emails are never stored.

Tags and releases don't belong to a branch, so they go to the environment of the mapping marked **Fallback**, or, without one, the environment that the repository's default branch maps to. If neither exists, they are dropped.

> **Tip:** By default each push creates one `git.push` marker, so a large push doesn't crowd your charts. Turn on **Per-commit markers** for a repository to get one `git.commit` marker per commit instead.

## Open Git Integration

Open the account menu, choose **Account**, then select **Git** under **Integration**. The **Git Integration** page has a **Connect a Provider** card, then one card per connected provider with its **Linked Repositories**.

A bucket's **Events** page (under **Automate**) also shows which repositories send deploys to it, or offers **Connect a Repository** when none do.

## Link a repository

**Add a repository**

On the provider's card, select **Add Repository**.

**Choose the repository and bucket**

In **Link a repository**, choose the **Repository** and the **Bucket**. Under **Subscribed events**, keep `push`, `tag` and `release`, or clear the ones you don't want. Turn on **Create a marker per commit (default: one per push)** if you want per-commit markers. Select **Link Repository**.

**Map branches to environments**

Under **Branch → Environment mappings**, enter a branch or pattern, choose how it matches, pick the environment, and select **Add**. Add a row for each branch that deploys.

## Branch mappings

Each mapping has:

| Field | Meaning |
| --- | --- |
| Pattern | A branch name or pattern, such as `main` or `release/*`. |
| Match | `exact`, `glob` or `regex`. In a glob, `*` matches within one path segment and `**` matches across `/`. A regex must match the whole branch name. |
| Environment | Where markers for matching pushes go. |
| Priority | Mappings are tried from the lowest number up; the first match wins. |
| Fallback | Used when no pattern matches, and for tags and releases. Mark at most one. |

With no mappings at all, the table says **No mappings - events on unmapped branches are dropped.**

## Check a repository's health

Each linked repository shows a health badge, checked every time you open the page: **Healthy**, **Needs attention** or **Not receiving events**. Select **Diagnose** to see each check a push goes through and which one fails: the provider connection, repository access, the webhook (or, for GitHub, the app installation and its webhook), the deliveries the provider sent, event processing, and branch mappings. It also lists recent deliveries with when they were **Received**, the **Event**, its **Status** and the **Detail**.

Where ApiTraffic can fix a problem, the failing check has a button: **Redeliver failed** asks GitHub to resend deliveries that were refused, and **Re-register webhook** replaces a missing GitLab or Bitbucket webhook. Checks that need a change on the provider link to the right settings page.

## Unlink or disconnect

- **Unlink** on a repository stops its markers. For GitLab and Bitbucket, ApiTraffic also removes the webhook it added.
- **Disconnect** on a provider card removes the connection and unlinks all of its repositories.

Markers already created stay on your charts. Delete them from **Account** → **Events** if you need to.

## Troubleshooting

**I pushed but no marker appeared**

Select **Diagnose** on the repository. The most common cause is a branch that matches no mapping; the diagnostics name the branch that was skipped. Also check that `push` is in the repository's subscribed events and that your plan includes **Deploy & incident markers**.

**Tags and releases don't show up**

Mark one mapping as **Fallback**, or make sure the repository's default branch is mapped. Tags and releases have no branch of their own.

**A connection shows error**

The provider's access was revoked or could not be refreshed. Connect the provider again with **Connect GitHub**, **Connect GitLab** or **Connect Bitbucket**, link the repositories under the new connection, then disconnect the old one.

**There are too many markers on my charts**

Turn off **Per-commit markers** so each push produces one marker, or clear `tag` from the subscribed events.

**I see Repositories Without a Provider**

These repositories were linked through a connection that no longer exists. Unlink them and link them again under an active connection.

## Related

- [GitHub](https://www.apitraffic.io/docs/git-integrations/github):
    Install the ApiTraffic GitHub App.

- [GitLab](https://www.apitraffic.io/docs/git-integrations/gitlab):
    Connect gitlab.com with OAuth.

- [Bitbucket](https://www.apitraffic.io/docs/git-integrations/bitbucket):
    Connect Bitbucket Cloud with OAuth.

- [Event markers](https://www.apitraffic.io/docs/events):
    How markers appear on charts, and other ways to create them.