Git integration (GitHub, GitLab, Bitbucket)

Your Read the Docs account can be connected to your Git provider’s account. Connecting your account provides the following features:

🔑️ Easy login

Log in to Read the Docs with your GitHub, Bitbucket, or GitLab account.

🔁️ List your projects

Select a project to automatically import from all your Git repositories and organizations. See: Adding a documentation project.

⚙️ Automatic configuration

Have your Git repository automatically configured with your Read the Docs webhook, which allows Read the Docs to build your docs on every change to your repository.

🚥️ Commit status

See your documentation build status as a commit status indicator on pull request builds.

See also

Manually add your project

Using a different provider? You can configure it manually. Read the Docs still supports other providers such as Gitea or GitHub Enterprise.

Getting started

✅️ Signed up with your Git provider?

If you signed up or logged in to Read the Docs with your GitHub, Bitbucket, or GitLab credentials, you’re all done. Your account is connected.

The rest of this guide explains how the automatic configuration works.

⏩️️ Signed up with your email address?

If you have signed up to Read the Docs with your email address, you can add the connection to the Git provider afterwards. You can also add a connection to an additional Git provider this way.

Please follow How to connect your Read the Docs account to your Git provider in this case.

Once you have your account connected, you can follow the Adding a documentation project guide to actually add your project to Read the Docs.

How automatic configuration works

When your Read the Docs account is connected to GitHub, Bitbucket, or GitLab and you add a new Read the Docs project:

  • Read the Docs automatically creates a Read the Docs Integration that matches your Git provider,

  • Read the Docs creates an incoming webhook with your Git provider, which is automatically added to your Git repository’s settings using the account connection.

After project creation, you can continue to configure the project. All settings can be modified, including the ones that were automatically created.

Tip

A single Read the Docs account can connect to many different Git providers. This allows you to have a single login for all your various identities.

Read the Docs incoming webhook

Accounts with GitHub, Bitbucket, and GitLab integration automatically have Read the Docs’ incoming webhook configured on all Git repositories that are imported. Other setups can setup the webhook through manual configuration.

When an incoming webhook notification is received, Read the Docs ensures that it matches an existing project. Once the webhook is validated, an action is taken based on the information inside of the webhook.

Possible webhook actions outcomes are:

Screenshot of the Dashboard view for the incoming webhook

All calls to the incoming webhook are logged. Each call can trigger builds and version synchronization.

On Read the Docs for Business, Git integration makes it possible for us to synchronize your Git repository’s access rights from your Git provider. That way, the same access rights are effective on Read the Docs and you don’t have to configure access in two places. See more in our Single Sign-on with GitHub, Bitbucket, or GitLab.

How does the connection work?

Read the Docs uses OAuth to connect to your account at GitHub, Bitbucket, or GitLab, You are asked to grant permissions for Read the Docs to perform a number of actions on your behalf.

At the same time, we use this process for authentication (login) since we trust that GitHub, Bitbucket, or GitLab have verified your user account and email address.

By granting Read the Docs the requested permissions, we are issued a secret OAuth token from your Git provider. Using the secret token, we can automatically configure repositories during project creation. We also use the token to send back build statuses and preview URLs for pull requests.

Note

Access granted to Read the Docs can always be revoked. This is a function offered by all Git providers.

Git provider integrations

If your project is using Organizations (Read the Docs for Business) or maintainers (Read the Docs Community), then you need to be aware of who is setting up the integration for the project.

The Read the Docs user who sets up the project through the automatic import should also have admin rights to the Git repository.

A Git provider integration is active through the authentication of the user that creates the integration. If this user is removed, make sure to verify and potentially recreate all Git integrations for the project.

Permissions for connected accounts

Read the Docs does not generally ask for write permission to your repository code (with one exception detailed below). However, we do need permissions for authorizing your account so that you can login to Read the Docs with your connected account credentials.

Read the Docs requests the following permissions (more precisely, OAuth scopes) when connecting your Read the Docs account to GitHub.

Read access to your email address (user:email)

We ask for this so you can create a Read the Docs account and login with your GitHub credentials.

Administering webhooks (admin:repo_hook)

We ask for this so we can create webhooks on your repositories when you import them into Read the Docs. This allows us to build the docs when you push new commits.

Read access to your organizations (read:org)

We ask for this so we know which organizations you have access to. This allows you to filter repositories by organization when importing repositories.

Repository status (repo:status)

Repository statuses allow Read the Docs to report the status (eg. passed, failed, pending) of pull requests to GitHub.

Note

Read the Docs for Business asks for one additional permission (repo) to allow access to private repositories and to allow us to setup SSH keys to clone your private repositories. Unfortunately, this is the permission for read/write control of the repository but there isn’t a more granular permission that only allows setting up SSH keys for read access.

GitHub permission troubleshooting

Repositories not in your list to import.

Many organizations require approval for each OAuth application that is used, or you might have disabled it in the past for your personal account. This can happen at the personal or organization level, depending on where the project you are trying to access has permissions from.

You need to make sure that you have granted access to the Read the Docs OAuth App to your personal GitHub account. If you do not see Read the Docs in the OAuth App settings, you might need to disconnect and reconnect the GitHub service.

See also

GitHub docs on requesting access to your personal OAuth for step-by-step instructions.