-
-
Notifications
You must be signed in to change notification settings - Fork 3.6k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add webhook modeling to projects (#2764)
* Add start of work to add webhook modeling for each integration * Lint cleanup * Add authentication to generic webhook * Add tests, docs, and lint fixes * Fix bitbucket operations for webhook create/update * Doc updates * Update integration token generator and make service debug logging more permissive * Redirect user to integration detail page on create * Add information for details page, drop automatic webhook mention
- Loading branch information
Showing
25 changed files
with
1,327 additions
and
251 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,78 +1,135 @@ | ||
| Webhooks | ||
| ======== | ||
|
|
||
| Webhooks are pretty amazing, and help to turn the web into a push instead of | ||
| pull platform. We have support for hitting a URL whenever you commit to your | ||
| project and we will try and rebuild your docs. This only rebuilds them if | ||
| something has changed, so it is cheap on the server side. As anyone who has | ||
| worked with push knows, pushing a doc update to your repo and watching it get | ||
| updated within seconds is an awesome feeling. | ||
| The primary method that Read the Docs uses to detect changes to your | ||
| documentation is through the use of *webhooks*. Webhooks are configured with | ||
| your repository provider, such as GitHub or Bitbucket, and with each commit, | ||
| merge, or other change to your repository, Read the Docs is notified. When we | ||
| receive a webhook notification, we determine if the change is related to an | ||
| active version for your project, and if it is, a build is triggered for that | ||
| version. | ||
|
|
||
| GitHub | ||
| --------- | ||
| .. _integration-detail: | ||
|
|
||
| If your project is hosted on GitHub, you can easily add a hook that will rebuild | ||
| your docs whenever you push updates: | ||
| Webhook Integrations | ||
| -------------------- | ||
|
|
||
| * Go to the "Settings" page for your project | ||
| * Click "Integrations & Services" | ||
| * In the "Services" section, click "Add service" | ||
| * In the list of available services, click "ReadTheDocs" | ||
| * Leave "Active" checked | ||
| * Click "Add service" | ||
| You'll find a list of configured webhook integrations on your project's admin | ||
| dashboard, under **Integrations**. You can select any of these integrations to | ||
| see the *integration detail page*. This page has additional configuration | ||
| details and a list of HTTP exchanges that have taken place for the integration. | ||
|
|
||
| .. note:: The GitHub URL in your Read the Docs project must match the URL on GitHub. The URL is case-sensitive. | ||
| .. _webhook-creation: | ||
|
|
||
| If you ever need to manually set the webhook on GitHub, | ||
| you can point it at ``https://readthedocs.org/github``. | ||
| Webhook creation | ||
| ---------------- | ||
|
|
||
| Bitbucket | ||
| ----------- | ||
| If you import a project using a :ref:`connected account <connect-account>`, a | ||
| webhook will be set up automatically for your repository. However, if your | ||
| project was not imported through a connected account, you may need to | ||
| manually configure a webhook for your project. | ||
|
|
||
| To manually set up a webhook, click **Add integration** on your project's | ||
| **Integrations** admin dashboard page and select the integration type you'd like | ||
| to add. After you have added the integration, you'll see a URL for the | ||
| integration on the :ref:`integration detail page <integration-detail>`. Use this | ||
| URL when setting up a new webhook with your provider -- these steps vary | ||
| depending on the provider: | ||
|
|
||
| GitHub | ||
| ~~~~~~ | ||
|
|
||
| * Go to the **Settings** page for your project | ||
| * Click **Webhooks** and then **Add webhook** | ||
| * For **Payload URL**, use the URL of the integration on Read the Docs, found on | ||
| the :ref:`integration detail page <integration-detail>` page | ||
| * For **Content type**, both *application/json* and | ||
| *application/x-www-form-urlencoded* work | ||
| * Select **Just the push event** | ||
| * Finish by clicking **Add webhook** | ||
|
|
||
| If your project is hosted on Bitbucket, you can easily add a hook that will rebuild | ||
| your docs whenever you push updates: | ||
| .. note:: The webhook secret is not yet respected | ||
|
|
||
| * Go to the "admin" page for your project | ||
| * Click "Services" | ||
| * In the available service hooks, select "Read the Docs" | ||
| * Click "Add service" | ||
| Bitbucket | ||
| ~~~~~~~~~ | ||
|
|
||
| If you ever need to manually set the webhook on Bitbucket, | ||
| you can point it at ``https://readthedocs.org/bitbucket``. | ||
| * Go to the **Settings** page for your project | ||
| * Click **Webhooks** and then **Add webhook** | ||
| * For **URL**, use the URL of the integration on Read the Docs, found on the | ||
| :ref:`integration detail page <integration-detail>` page | ||
| * Under **Triggers**, **Repository push** should be selected | ||
| * Finish by clicking **Save** | ||
|
|
||
| GitLab | ||
| --------- | ||
| ~~~~~~ | ||
|
|
||
| * Go to the **Settings** page for your project | ||
| * Click **Integrations** | ||
| * For **URL**, use the URL of the integration on Read the Docs, found on the | ||
| :ref:`integration detail page <integration-detail>` page | ||
| * Leave the default **Push events** selected | ||
| * Finish by clicking **Add Webhook** | ||
|
|
||
| If your project is hosted on GitLab, you can easily add a hook that will rebuild | ||
| your docs whenever you push updates. | ||
| Using the generic API integration | ||
| --------------------------------- | ||
|
|
||
| * Go to the "Settings" page for your project | ||
| * Click "Integrations" | ||
| * In the "URL" section, enter ``https://readthedocs.org/gitlab`` | ||
| * Leave the default "Push events" selected | ||
| * Click "Add Webhook" | ||
| 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, found on the | ||
| :ref:`integration detail page <integration-detail>`. | ||
|
|
||
| Others | ||
| ------ | ||
| 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. | ||
|
|
||
| Your ReadTheDocs project detail page has your post-commit hook on it; it will | ||
| look something along the lines of ``http://readthedocs.org/build/<project_name>``. | ||
| Regardless of which revision control system you use, you can just hit this URL | ||
| to kick off a rebuild. | ||
| Parameters | ||
| ~~~~~~~~~~ | ||
|
|
||
| The following parameters available to customize the behavior of custom webhooks: | ||
| This endpoint accepts the following arguments during an HTTP POST: | ||
|
|
||
| * ``'version_slug'``: The build version to trigger build for (defaults to ``'latest'``) | ||
| 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. | ||
|
|
||
| Example:: | ||
| Default: **latest** | ||
|
|
||
| $ curl -X POST --data "version_slug=$VERSION" https://readthedocs.org/build/$PROJECT_NAME | ||
| token | ||
| The integration token. You'll find this value on the | ||
| :ref:`integration detail page <integration-detail>` page. | ||
|
|
||
| You could make this part of a hook using Git_, Subversion_, Mercurial_, or | ||
| Bazaar_, perhaps through a simple script that accesses the build URL using | ||
| ``wget`` or ``curl``. | ||
| 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" 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_. | ||
|
|
||
| .. _Git: http://www.kernel.org/pub/software/scm/git/docs/githooks.html | ||
| .. _Subversion: http://mikewest.org/2006/06/subversion-post-commit-hooks-101 | ||
| .. _Mercurial: http://hgbook.red-bean.com/read/handling-repository-events-with-hooks.html | ||
| .. _Bazaar: http://wiki.bazaar.canonical.com/BzrHooks | ||
|
|
||
| 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. | ||
|
|
||
| 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. | ||
|
|
||
| Resyncing webhooks | ||
| ------------------ | ||
|
|
||
| It might be necessary to re-establish a webhook if you are noticing problems. | ||
| To resync a webhook from Read the Docs, visit the integration detail page and | ||
| follow the directions for re-syncing your repository webhook. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| """Shared model fields and defaults""" | ||
|
|
||
| import binascii | ||
| import os | ||
|
|
||
|
|
||
| def default_token(): | ||
| """Generate default value for token field""" | ||
| return binascii.hexlify(os.urandom(20)).decode() |
Oops, something went wrong.