Connecting GitHub

Docup reads your code from GitHub. There are two ways to connect, and the choice decides whether private repositories work and whether your docs update on their own.

	GitHub App	Public link
Public repositories	Yes	Yes
Private repositories	Yes	No
You choose which repositories Docup can see	Yes	Not applicable
Docs update on every push	Yes	No

The Docup GitHub App#

The GitHub App is the recommended way to connect. To use it:

1. Choose Connect GitHub on the welcome screen.
2. On GitHub, install the Docup app on your user account or on an organization, and choose which repositories it may access.
3. You return to Docup, where the repositories you allowed appear in a list. Pick one.

Docup checks, right after you install, that the GitHub account you signed in with can actually see the installation. A workspace can connect more than one GitHub account, such as your personal account and an organization.

Docup only reads. It downloads files and compares commits. It does not push, open pull requests or change anything in your repository.

If you remove the app from GitHub, Docup forgets the installation. To change which repositories it can see, use the app's settings on GitHub.

A public repository link#

If the repository is public, you can paste its link instead. Docup reads it with its own read-only token for public data. This is the quickest way to try Docup, with one limit: a project made from a link does not update on push. Its Settings show Public link as the connection and note that docs will not update until you connect GitHub.

A private repository looks the same as one that does not exist when you paste its link. If you see "We cannot see github.com/owner/repo. If it is private, connect GitHub first. Otherwise check the URL.", either the link has a typo or the repository is private and needs the GitHub App.

Which branch Docup follows#

Docup always follows the repository's default branch. Pushes to other branches, and deleted branches, are ignored. The branch is shown in General settings and cannot be changed there. Additionally, push updates are ignored if the project is still writing its first docs, as the initial setup run reads the latest commit when it starts.

Published docs are public#

Fixing connection problems#

Message	What to do
"Paste a link like github.com/owner/repo."	The text is not a GitHub repository link. Check for typos.
"We cannot see github.com/owner/repo. If it is private, connect GitHub first. Otherwise check the URL."	Install the GitHub App and allow this repository.
"The GitHub App cannot read github.com/owner/repo. Give it access to this repository on GitHub."	The app is installed but this repository is not in its list. Add it in the app's settings on GitHub.
"GitHub is limiting requests right now. Try again in a minute."	Wait a minute and try again.
"Too many repository lookups. Try again in a few minutes."	A workspace can look up 60 repositories per hour. Try again in a few minutes.
"... is already one of your projects."	A repository can be a project once per workspace. Open the existing project.

If a connection attempt fails on the way back from GitHub, Docup shows one of these status messages:

• Expired: The connection took too long or was started in another session. Choose Connect GitHub again to restart it.
• Requested: You requested installation on an organization repository, but you are not an owner. An owner must approve the request before you can connect.
• Failed: GitHub did not confirm the connection. Try connecting again.