How to manually configure a Git repositoryï
In this guide, you will find the simple steps to manually integrating your Read the Docs project with all Git providers that support our generic API. This includes most Git providers, for example GitHub, Bitbucket, and GitLab.
See also
- How to automatically configure a Git repository
You are now reading the guide to configuring a Git repository manually. If your Read the Docs account is connected to the Git provider, we can setup the integration automatically.
Provider-specific instructionsï
You need to configure your Git provider to call a webhook on Read the Docs. This will make Read the Docs build your documentation when a new commit, branch or tag is pushed to your repository.
Go to the Settings page for your GitHub project
Click Webhooks > Add webhook
For Payload URL, use the URL of the integration on your Read the Docs project, found on the projectâs Admin > Integrations page. You may need to prepend https:// to the URL.
For Content type, both application/json and application/x-www-form-urlencoded work
Leave the Secrets field blank
Select Let me select individual events, and mark Branch or tag creation, Branch or tag deletion, Pull requests and Pushes events
Ensure Active is enabled; it is by default
Finish by clicking Add webhook. You may be prompted to enter your GitHub password to confirm your action.
You can verify if the webhook is working at the bottom of the GitHub page under Recent Deliveries. If you see a Response 200, then the webhook is correctly configured. For a 403 error, itâs likely that the Payload URL is incorrect.
Note
The webhook token, intended for the GitHub Secret field, is not yet implemented.
Go to the Settings > Webhooks > Add webhook page for your project
For URL, use the URL of the integration on Read the Docs, found on the Admin > Integrations page
Under Triggers, Repository push should be selected
Finish by clicking Save
Go to the Settings > Webhooks page for your GitLab project
For URL, use the URL of the integration on Read the Docs project, found on the Admin > Integrations page
Leave the default Push events selected, additionally mark Tag push events and Merge request events.
Finish by clicking Add Webhook
These instructions apply to any Gitea instance.
Warning
This isnât officially supported, but using the âGitHub webhookâ is an effective workaround, because Gitea uses the same payload as GitHub. The generic webhook is not compatible with Gitea. See issue #8364 for more details. Official support may be implemented in the future.
On Read the Docs:
Manually create a âGitHub webhookâ integration (this will show a warning about the webhook not being correctly set up, that will go away when the webhook is configured in Gitea)
On your Gitea instance:
Go to the Settings > Webhooks page for your project on your Gitea instance
Create a new webhook of type âGiteaâ
For URL, use the URL of the integration on Read the Docs, found on the Admin > Integrations page
Leave the default HTTP Method as POST
For Content type, both application/json and application/x-www-form-urlencoded work
Leave the Secret field blank
Select Choose events, and mark Branch or tag creation, Branch or tag deletion and Push events
Ensure Active is enabled; it is by default
Finish by clicking Add Webhook
Test the webhook with Delivery test
Finally, on Read the Docs, check that the warnings have disappeared and the delivery test triggered a build.
Other providers are supported through a generic webhook, see Using the generic API integration.
Additional integrationï
You can configure multiple incoming webhooks.
To manually set up an integration, go to Admin > Integrations > Add integration dashboard page and select the integration type youâd like to add. After you have added the integration, youâll see a link to information about the integration.
As an example, the URL pattern looks like this: https://readthedocs.org/api/v2/webhook/<project-name>/<id>/*.
Use this URL when setting up a new integration with your provider ^^ these steps vary depending on the provider.
Warning
Git repositories that are imported manually do not have the required setup to send back a commit status. If you need this integration, you have to configure the repository automatically.
See also
- How to setup email notifications
Quickly enable email notifications.
- How to setup build status webhooks
Learn how to add custom webhook notifications.
Using the generic API integrationï
For repositories that are not hosted with a supported provider, we also offer a generic API endpoint for triggering project builds. Similar to webhook integrations, this integration has a specific URL, which can be found on the projectâs Integrations dashboard page (Admin > Integrations).
Token authentication is required to use the generic endpoint, you will find this token on the integration details page. The token should be passed in as a request parameter, either as form data or as part of JSON data input.
Parametersï
This endpoint accepts the following arguments during an HTTP POST:
- branches
The names of the branches to trigger builds for. This can either be an array of branch name strings, or just a single branch name string.
Default: latest
- token
The integration token found on the projectâs Integrations dashboard page (Admin > Integrations).
- default_branch
This is the default branch of the repository (ie. the one checked out when cloning the repository without arguments)
Optional
For example, the cURL command to build the dev branch, using the token
1234, would be:
curl -X POST -d "branches=dev" -d "token=1234" -d "default_branch=main"
https://readthedocs.org/api/v2/webhook/example-project/1/
A command like the one above could be called from a cron job or from a hook inside Git, Subversion, Mercurial, or Bazaar.
Authenticationï
This endpoint requires authentication. If authenticating with an integration token, a check will determine if the token is valid and matches the given project. If instead an authenticated user is used to make this request, a check will be performed to ensure the authenticated user is an owner of the project.
Payload validationï
If your project was imported through a connected account, we create a secret for every integration that offers a way to verify that a webhook request is legitimate. Currently, GitHub and GitLab offer a way to check this.
Troubleshootingï
Debugging webhooksï
If you are experiencing problems with an existing webhook, you may be able to use the integration detail page to help debug the issue. Each project integration, such as a webhook or the generic API endpoint, stores the HTTP exchange that takes place between Read the Docs and the external source. Youâll find a list of these exchanges in any of the integration detail pages.
Webhook activation failed. Make sure you have the necessary permissionsï
If you find this error, make sure your user has permissions over the repository. In case of GitHub, check that you have granted access to the Read the Docs OAuth App to your organization.
My project isnât automatically buildingï
If your project isnât automatically building, you can check your integration on Read the Docs to see the payload sent to our servers. If there is no recent activity on your Read the Docs project webhook integration, then itâs likely that your VCS provider is not configured correctly. If there is payload information on your Read the Docs project, you might need to verify that your versions are configured to build correctly.