GitHub

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, so installing the same account from another workspace moves it there.

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. 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.

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.