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

# Install the LoopIQ GitHub App

> Connect selected GitHub repositories and synchronize pull-request references to LoopIQ work items.

# Install the LoopIQ GitHub App

The LoopIQ GitHub App replaces organization-managed GitHub OAuth App credentials. A LoopIQ organization admin starts the installation, and a GitHub owner chooses which repositories LoopIQ can access.

The GitHub Marketplace listing is not required to start an installation from LoopIQ. Until the public listing is approved, begin from the GitHub integration card in LoopIQ; it opens the same GitHub App installation and repository-selection flow.

## Before you begin

You need:

* LoopIQ organization admin access.
* Permission to install GitHub Apps for the target GitHub account or organization.
* The LoopIQ story or task identifiers that contributors should mention in pull requests, such as `STORY-4242` or `TASK-108`.

Repository access remains scoped to the repositories selected during installation. Installing the app for one LoopIQ organization does not grant another organization access to its data.

## Install the app

1. In LoopIQ, open `Organization` > `Integrations`. If your navigation labels this area `External Connections`, open it and then select the GitHub integration.
2. Find `GitHub` and select `Install GitHub App`.
3. In GitHub, select the personal account or organization that owns the repositories.
4. Choose `Only select repositories` and select the repositories LoopIQ should synchronize. Select all repositories only when that broader access is intended.
5. Complete the installation. GitHub returns you to the LoopIQ `Integrations` page.
6. Confirm that LoopIQ shows the GitHub account and selected repository count.

Use `Manage repositories` on the GitHub integration card to add or remove repository access later. LoopIQ updates its repository catalog when GitHub sends an installation change event.

## Link pull requests to LoopIQ work

Include an exact LoopIQ story or task identifier in the pull-request title or description. For example:

```text theme={null}
Implements STORY-4242 and completes TASK-108.
```

LoopIQ validates the identifier within the organization connected to the GitHub App installation. A matching identifier from another organization is not linked. The pull request then appears in the work item's `GitHub References` section with its repository, author, state and link.

When a contributor edits a pull request and removes an identifier, LoopIQ removes that active reference. Replayed GitHub deliveries do not create duplicates.

## Manage access and lifecycle changes

From `Organization` > `Integrations`:

1. Select `Manage repositories` to open the installation settings in GitHub.
2. Add or remove repositories as needed.
3. Return to LoopIQ and refresh the page to confirm the selected repository count.

Suspending or uninstalling the app stops new synchronization. Removing one repository stops events from that repository without affecting the others.

## GitHub App permissions

For pull-request reference synchronization and the existing GitHub capabilities, the LoopIQ GitHub App uses these read permissions:

* Repository metadata, pull requests and contents.
* Actions and checks for workflow and build signals.
* Code-scanning and secret-scanning alerts for security evidence.
* Organization members for LoopIQ-to-GitHub identity mapping.

The app subscribes only to the corresponding installation, repository-selection, pull-request, push, workflow, check and security-alert events. Additional permissions should be introduced only when a LoopIQ feature needs them.

LoopIQ verifies every webhook using GitHub's SHA-256 signature, rejects deliveries without GitHub event and delivery identifiers, and suppresses duplicate deliveries.

## Move from the legacy OAuth connection

1. Install the LoopIQ GitHub App and confirm the repository count.
2. Open or edit a pull request with a LoopIQ story or task identifier and confirm the reference appears in LoopIQ.
3. Disconnect the legacy OAuth integration only after the GitHub App path is verified.

The legacy connection remains available during migration, but new organizations should use the GitHub App.

## Troubleshoot missing references

Check the following:

1. The repository is selected in the GitHub App installation.
2. The installation is active rather than suspended.
3. The pull-request title or description contains the exact LoopIQ identifier.
4. The story or task belongs to the same LoopIQ organization as the installation.
5. The GitHub integration card shows the expected GitHub account and repository count.

If the reference is still missing, ask a LoopIQ administrator to review the GitHub webhook delivery history for the repository.