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

# Setup

> Step-by-step guide to installing the Prizm Pulse GitHub App, configuring its webhook, and registering repositories and branches in Prizm.

<script type="application/ld+json">
  {`{
            "@context": "https://schema.org",
            "@type": "TechArticle",
            "headline": "GitHub App Setup",
            "description": "Step-by-step guide to installing the Prizm Pulse GitHub App, configuring its webhook, and registering repositories and branches in Prizm.",
            "url": "https://docs.dqlabs.ai/integrations/githubapp/setup",
            "publisher": {
              "@type": "Organization",
              "name": "DQLabs Inc",
              "logo": "https://media.brand.dev/332adc35-5bc4-4d2b-bf78-256aa4a5e414.svg"
            }
            }`}
</script>

## Connecting GitHub to Prizm

Setting up the GitHub App integration takes four steps: installing Prizm Pulse from the GitHub Marketplace, configuring the webhook so GitHub notifies Prizm of PR events, obtaining the Installation ID, and entering the repository and branch details in Prizm.

### Prerequisites

* GitHub Organization administrator access
* Repository administrator permissions for repositories to be monitored
* Admin or privileged user access in Prizm to configure integrations

***

## Step 1: Install Prizm Pulse from the GitHub Marketplace

1. Navigate to [**Prizm Pulse**](https://github.com/marketplace/prizm-pulse) in the GitHub Marketplace.
2. Click **Install** and select the GitHub Organization to install the app on.
3. Choose repository access:
   * **All repositories** — recommended for organization-wide monitoring
   * **Selected repositories** — grant access only to the dbt repositories Prizm should monitor
4. Review the requested permissions and approve the installation.

### Permissions required (read-only)

* Pull Requests
* Repository Metadata
* Branch Information
* Commit Metadata

***

## Step 2: Configure the webhook URL

<Steps>
  <Step title="Open GitHub App settings">
    In GitHub, navigate to **Organization Settings** → **Developer Settings** → **GitHub Apps** → **Prizm Pulse**.
  </Step>

  <Step title="Set the webhook URL">
    Open the **Webhook** section and enter:

    ```text theme={null}
    https://<your-prizm-domain>/api/v1/integration/webhook/github
    ```

    Replace `<your-prizm-domain>` with your Prizm instance hostname (e.g., `benchmark.qa.prizmdata.ai`).
  </Step>

  <Step title="Enable the webhook and save">
    Toggle the webhook on and save. GitHub will now deliver PR open, merge, and close events to Prizm in real time.
  </Step>
</Steps>

***

## Step 3: Obtain the Installation ID

After installation, GitHub redirects to a URL in this format:

```text theme={null}
https://github.com/organizations/<org>/settings/installations/12345678
```

The number at the end is your **Installation ID**. Copy and save it.

***

## Step 4: Configure the GitHub App in Prizm

<Steps>
  <Step title="Open Integration settings">
    Navigate to **Organization** → **Integration** and click the pencil icon on the **GitHub App** row.
  </Step>

  <Step title="Enter the Installation ID">
    Paste the numeric Installation ID obtained in Step 3.
  </Step>

  <Step title="Add repositories and branches">
    In the **GitHub details** section, enter the repository identifier in **Repo Name** (e.g., `my-org/dbt-project`). In **Branch Names**, type each target branch and press **Enter** to add it as a tag (e.g., `main`, `develop`, `prod`). Add a new row for each additional repository.
  </Step>

  <Step title="Save">
    Click **Update Integration**. Prizm validates the Installation ID and begins monitoring the configured repositories.
  </Step>
</Steps>

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/dqlabs/images/integrations/github-app/setup-panel.png" alt="GitHub App configuration panel showing Installation ID field and GitHub details table with repo name and branch name columns" />
</Frame>

***

## Configuration reference

| Field               | Required | Description                                                                                                              |
| ------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Installation ID** | Yes      | Numeric ID from the GitHub App installation URL on GitHub.                                                               |
| **Repo Name**       | Yes      | Repository in `org/repo` format (e.g., `my-org/dbt-project`). One row per repository.                                    |
| **Branch Names**    | Yes      | Target branches Prizm monitors for merged PR events. Multiple branches per repository are supported — add each as a tag. |

***

## Updating repository access

To add a new repository after the initial setup:

1. In GitHub, go to **Organization Settings** → **Installed GitHub Apps** → **Prizm Pulse** and add the new repository to the app's access list.
2. In Prizm, navigate to **Organization** → **Integration** → **GitHub App** and add a new row with the repository name and target branches.

<Note>
  Both steps are required. If the app does not have access to a repository listed in Prizm, monitoring for that repository will fail silently.
</Note>