# GitHub

> Install the planpage GitHub app to link pull requests to plans, keep a progress comment on each pull request, and require an approved plan before merging.

With the GitHub app installed, a pull request that belongs to a plan shows the plan's state on GitHub, and the plan shows the pull request.

## Install the app

Owners and admins install it, once per workspace.

1. Go to **Workspace settings → Integrations**.
2. Click **Install on GitHub** and choose the account and repositories.
3. GitHub sends you back to planpage, which shows "GitHub connected".

Each installation covers one GitHub account: your personal account or one organisation. To connect another, click **Install on another account or organisation** and pick it on GitHub; a workspace can have as many installations as you need, and **New project** lists the repositories from all of them. An installation belongs to one planpage workspace at a time. To move it to another workspace, disconnect it in the workspace that has it first. When you install, planpage checks that you belong to the GitHub account you installed on: if it can't tell, link your GitHub login under **Account → Logins** with the account that installed the app, then try again.

To change which repositories an existing installation covers, edit it in the installation's settings on GitHub. Each installation is listed with its GitHub account and a **Linked** status, or **Suspended on GitHub** if it's been suspended there.

## Repository suggestions

Installing the app also fills the repository list in **New project**, so people can pick a repository instead of typing its URL; see [Projects and folders](https://planpage.dev/docs/projects-and-folders.md). Agents get the same list from `list_repositories`.

The list covers the repositories you chose when installing. When you add or remove repositories in the installation's settings on GitHub, planpage updates the list straight away. Other changes, such as renames and recent pushes, are fetched when someone opens **Projects** and the list is more than an hour old. Everyone in the workspace who can create projects sees the list, including the names of private repositories.

If you started the installation from **New project**, GitHub sends you back to that form instead of to Integrations. Once one account is connected, owners and admins see **Add another GitHub account** under the list there too.

## Link a pull request to a plan

There are two ways:

- **Mention the plan in the pull request.** Put the plan's URL, for example `https://app.planpa.ge/d/…`, in the pull request's title or description. planpage picks it up when the pull request is opened or updated.
- **Have the agent link it.** An agent with Publish and run access calls `link_ref` with the pull request URL, optionally against a step.

A pull request can only link to plans in a project whose **Repository URL** matches the pull request's repository, and the app must be installed for the same workspace as the project.

Linked pull requests appear under their step, or on the plan, with their state: open, closed or merged.

## The plan comment

planpage keeps one comment on each linked pull request and updates it whenever the plan changes. It shows:

- the plan's number and title, linked to the document,
- its status and what the status check says,
- progress, such as "Progress: 3/5 steps",
- each step as a checklist, marked in progress or blocked where that applies.

## The status check

planpage reports a commit status named `planpage/approved` on the pull request's latest commit.

| State | When |
| --- | --- |
| Pending | The plan is waiting for approval, or an amendment is waiting ("Plan v3 amendment awaiting approval"). |
| Success | The plan has an approved version and no amendment is pending ("Plan approved (v2)"). |
| Failure | Changes were requested before any approval, or the plan was abandoned. |

planpage learns a pull request's latest commit from GitHub's pull request events, which it only reads for pull requests that mention the plan's URL. A pull request linked only through `link_ref` gets the comment but not the status check, so put the plan's URL in the description of any pull request you want to gate.

To stop pull requests merging without an approved plan, make `planpage/approved` a required status check in the repository's branch protection settings on GitHub.

## Disconnect

In **Workspace settings → Integrations**, click **Disconnect** next to the installation. planpage stops updating pull requests and status checks for that workspace. Links already made stay on the plans. The app stays installed on GitHub until you uninstall it there.