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

# Connecting GitHub

> Connect Platinur to GitHub using the GitHub App (recommended) or a Personal Access Token.

GitHub is Platinur's version-control and promotion backbone. Generated dbt models and Evidence code are committed to a configured repository; staged changes reach production through a pull request from the staging branch to the production branch.

There are two ways to authenticate with GitHub:

* **GitHub App (recommended)** — Install the Platinur GitHub App on your repository. No personal token is needed; Platinur mints short-lived tokens itself from the App installation.
* **Personal Access Token (fallback)** — Paste a classic or fine-grained PAT with the required scopes. Use this if the GitHub App option is not available for your workspace.

If an App installation exists for the account it is used in preference to any stored PAT.

## Option 1: GitHub App

### Install flow

1. Open **Configuration** in the portal.
2. Click **Install on GitHub**. (If this button is not shown, the App connection option is not available for your workspace — use a Personal Access Token instead.)
3. GitHub opens the App installation page. Select the repository that holds the Platinur project and confirm.
4. GitHub redirects back to the portal automatically.
5. The portal shows a **GitHub App connected** confirmation. Platinur stores the `installation_id` for the account and no personal token is needed from this point on.

### How it works

Platinur mints short-lived **installation access tokens** scoped to your account's installation whenever it needs to interact with GitHub — pushing commits, opening PRs, reading branches. Tokens are cached in-process and refreshed automatically near expiry; you never handle or store them.

Per-account state is limited to the `installation_id`, a non-secret numeric identifier issued by GitHub at install time.

## Option 2: Personal Access Token

If the **Install on GitHub** button does not appear, or you prefer the token path, enter a PAT in the **Access Token** field in Configuration alongside the repository URL.

Token requirements:

* **Classic PAT** — `repo` scope.
* **Fine-grained PAT** — **Contents** (read and write) and **Pull requests** (read and write) permissions on the target repository.

Click **Save and test** after entering the token. Platinur verifies the credentials by resolving the repository.

## Security notes

* Per-account state is only the `installation_id` (App connections) or the encrypted token reference (PAT connections); neither is ever shown back in the portal after saving.
* Installation tokens are minted on demand, cached briefly, and never persisted to disk.
* Generated dbt and Evidence code committed to your repository is the only code Platinur writes there — Platinur never pushes to branches outside the configured staging/production pair.