> ## Documentation Index
> Fetch the complete documentation index at: https://docs.periscope.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# GitHub integration

> Connect your GitHub organization to capture PR merge events and enable SPACE metrics, service health, and contributor analytics.

The GitHub integration is the foundation of Periscope's PR analytics. By installing the Periscope GitHub App on your organization, you enable automatic capture of pull request merge events, which powers SPACE metrics, service health tracking, and contributor activity analysis.

## What it captures

When a pull request is merged in a monitored repository, Periscope records:

| Data                  | Description                                        |
| --------------------- | -------------------------------------------------- |
| **PR metadata**       | Number, title, URL, branch                         |
| **Author and merger** | GitHub login and display name for both             |
| **Timestamps**        | Created at, merged at (for cycle time calculation) |
| **Size**              | Additions, deletions, changed files                |
| **Merge commit SHA**  | Used to link PRs to deployments for lead time      |

<Info>
  Periscope only captures PR merge events going forward from the moment you connect. Historical PR data is not backfilled.
</Info>

## Setup

<Steps>
  <Step title="Install the GitHub App">
    Go to **Settings > Connections** in the Periscope dashboard and click **Connect GitHub**. This redirects you to GitHub to install the Periscope GitHub App on your organization.

    You can install it with access to:

    * **All repositories** — Periscope can see all repos (you still choose which to monitor)
    * **Selected repositories** — limit access to specific repos
  </Step>

  <Step title="Select repositories to monitor">
    After installation, go to **Settings > Repositories**. You will see all repositories the GitHub App has access to. Toggle the **Monitored** switch for each repository you want Periscope to track.

    Only monitored repositories contribute to your metrics. You can change this at any time.
  </Step>

  <Step title="Verify the connection">
    Merge a pull request in one of your monitored repositories. Within seconds, it should appear in the **Insights** dashboard. If you do not see it, check that:

    * The repository is toggled on in **Settings > Repositories**
    * The GitHub App has access to the repository
    * The PR was actually merged (not just closed)
  </Step>
</Steps>

## Permissions

The Periscope GitHub App requests these permissions:

* **Pull requests** (read) — to receive PR merge events
* **Contents** (read) — to access commit SHAs for deployment linking
* **Metadata** (read) — to list repositories

## Service matching

When deployment events include a `service` field, Periscope automatically matches it against your repositories to correlate deployment data with PR activity. Using the repository name as your service name provides the most reliable matching.

## What the integration enables

| Feature               | Requires GitHub | Requires deployments |
| --------------------- | --------------- | -------------------- |
| PR cycle time         | Yes             | No                   |
| Throughput            | Yes             | No                   |
| Contributor activity  | Yes             | No                   |
| Service health        | Yes             | No                   |
| Risk signals          | Yes             | No                   |
| Deployment frequency  | No              | Yes                  |
| Lead time for changes | Yes             | Yes                  |
| Change failure rate   | No              | Yes                  |
| Mean time to recovery | No              | Yes                  |

GitHub alone gives you the full SPACE metrics suite. Adding deployment data unlocks DORA metrics and the connection between PR activity and production delivery.

## Managing the installation

### Adding or removing repositories

Go to your GitHub organization's **Installed GitHub Apps** settings to change which repositories the Periscope app can access. Then go to **Settings > Repositories** in Periscope to toggle monitoring on or off.

### Disconnecting

To remove the integration entirely, uninstall the Periscope GitHub App from your GitHub organization settings. This stops all webhook events. Existing data in Periscope is retained.

<CardGroup cols={2}>
  <Card title="Deployment webhook" icon="webhook" href="/integrations/deployment-webhook">
    Add deployment data to unlock DORA metrics alongside your GitHub PR data.
  </Card>

  <Card title="SPACE metrics" icon="users" href="/concepts/space-metrics">
    Learn what GitHub data powers in the SPACE framework.
  </Card>
</CardGroup>