From 3c732c9dbf1a874c7e4c97a4f984c0596a5cdb1f Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Thu, 27 Dec 2018 11:28:20 -0700 Subject: [PATCH 1/3] Updated copy on webhooks * Drop "deprecated webhook endpoint" copy, this is core team nomenclature, not user nomenclature. * Add small amount of docs to point to --- docs/webhooks.rst | 42 +++++++++++++++++++ readthedocs/projects/notifications.py | 2 +- .../deprecated_webhook_endpoint_email.html | 9 ++-- .../deprecated_webhook_endpoint_site.html | 2 +- 4 files changed, 49 insertions(+), 6 deletions(-) diff --git a/docs/webhooks.rst b/docs/webhooks.rst index ecf18611b50..31137f36f61 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -36,6 +36,8 @@ As an example, the URL pattern looks like this: *readthedocs.org/api/v2/webhook/ Use this URL when setting up a new webhook with your provider -- these steps vary depending on the provider: +.. _webhook-integration-github: + GitHub ~~~~~~ @@ -53,6 +55,8 @@ 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. +.. _webhook-integration-bitbucket: + Bitbucket ~~~~~~~~~ @@ -63,6 +67,8 @@ Bitbucket * Under **Triggers**, **Repository push** should be selected * Finish by clicking **Save** +.. _webhook-integration-gitlab: + GitLab ~~~~~~ @@ -73,6 +79,8 @@ GitLab * Leave the default **Push events** selected and mark **Tag push events** also * Finish by clicking **Add Webhook** +.. _webhook-integration-generic: + Using the generic API integration --------------------------------- @@ -136,3 +144,37 @@ 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. + +Troubleshooting +--------------- + +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. + +Either way, it may help to either resync your webhook intergration (see +`Resyncing webhooks`_ for information on this process), or set up an entirely +new webhook intergration. + +.. _webhook-github-services: + +Should I use GitHub Services? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Effective Jan 31st, GitHub Services will stop sending notifications to Read the +Docs. Your project has been configured on Read the Docs for a long time, you are +most likely using a GitHub Service to automatically build your project on Read +the Docs. + +In order for your project to continue automatically building, you will need to +configure your GitHub repository with a new webhook. You can use either a +connected GitHub account and a :ref:`GitHub webhook integration ` +on your Read the Docs project, or you can use a +:ref:`generic webhook integraiton ` without a connected +account. diff --git a/readthedocs/projects/notifications.py b/readthedocs/projects/notifications.py index c1fd9985aa6..d3b4af2e272 100644 --- a/readthedocs/projects/notifications.py +++ b/readthedocs/projects/notifications.py @@ -37,7 +37,7 @@ class DeprecatedWebhookEndpointNotification(Notification): name = 'deprecated_webhook_endpoint' context_object_name = 'project' - subject = 'Project {{ project.name }} is using a deprecated webhook' + subject = '{{ project.name }} project webhook needs to be updated' send_email = False email_period = timedelta(days=7) level = REQUIREMENT diff --git a/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_email.html b/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_email.html index c51862ea7fc..6ab3247fc21 100644 --- a/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_email.html +++ b/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_email.html @@ -1,7 +1,8 @@ -

Just a heads up, your project {{ project.name }} has configured a DEPRECATED webhook to trigger new builds and should be upgraded. Projects hitting these deprecated webhook will stop building on Jan 1, 2019. Please, update it soon!

+

Your project, {{ project.name }}, is currently using GitHub Services to trigger builds on Read the Docs. Effective January 31, 2019, GitHub will no longer process requests using the Services feature, and so Read the Docs will not receive notifications on updates to your repository.

-

To update the webhook your project is hitting, you need to go to the project's settings under your VCS service (GitHub, Bitbucket or GitLab) and remove the Read the Docs webhook from there.

+

To continue building your Read the Docs project on changes to your repository, you will need to add a new webhook on your GitHub repository. You can either connect your GitHub account and configure a GitHub webhook integration, or you can add a generic webhook integration.

-

Once you have done that, you need to go to your project's Integrations under Read the Docs project's Admin, click integration and then in "Resync webhook" button.

+

You can find more information on our webhook intergrations in our documentation, at:

-

Thanks!

+{% comment %}Plain text link because of text version of email{% endcomment %} +

https://docs.readthedocs.io/en/latest/webhooks.html

diff --git a/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html b/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html index 7d7276fb260..7588aa51bc6 100644 --- a/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html +++ b/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html @@ -1 +1 @@ -Your project {{ project.name }} has configured a DEPRECATED webhook to trigger new builds and should be upgraded. Projects hitting these deprecated webhooks will stop building on Jan 1, 2019. Please, update it soon! +Your project, {{ project.name }}, needs to be reconfigured in order to continue building automatically after Jan 31st. For more information, see our documentation on webhook integrations. From b50af5485355f1bec668dcbe1c654c376b53085f Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Wed, 2 Jan 2019 18:13:02 -0700 Subject: [PATCH 2/3] Update docs and point to docs in notification message --- docs/webhooks.rst | 15 +++++++++------ .../deprecated_webhook_endpoint_site.html | 2 +- 2 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 31137f36f61..8ab637a0340 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -164,13 +164,14 @@ new webhook intergration. .. _webhook-github-services: -Should I use GitHub Services? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +I was warned I shouldn't use GitHub Services +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Effective Jan 31st, GitHub Services will stop sending notifications to Read the -Docs. Your project has been configured on Read the Docs for a long time, you are -most likely using a GitHub Service to automatically build your project on Read -the Docs. +Last year, GitHub announced that effective Jan 31st, GitHub Services will stop +working [1]_. This means GitHub will stop sending notifications to Read the Docs +for projects configured with the ``ReadTheDocs`` GitHub Service. If your project +has been configured on Read the Docs for a long time, you are most likely still +using this service to automatically build your project on Read the Docs. In order for your project to continue automatically building, you will need to configure your GitHub repository with a new webhook. You can use either a @@ -178,3 +179,5 @@ connected GitHub account and a :ref:`GitHub webhook integration ` without a connected account. + +.. [1] https://developer.github.com/changes/2018-04-25-github-services-deprecation/ diff --git a/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html b/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html index 7588aa51bc6..5f1ada22295 100644 --- a/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html +++ b/readthedocs/templates/projects/notifications/deprecated_webhook_endpoint_site.html @@ -1 +1 @@ -Your project, {{ project.name }}, needs to be reconfigured in order to continue building automatically after Jan 31st. For more information, see our documentation on webhook integrations. +Your project, {{ project.name }}, needs to be reconfigured in order to continue building automatically after Jan 31st. For more information, see our documentation on webhook integrations. From f0594e5960f59b498634f7f0d8842f3db6f9bb35 Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Fri, 4 Jan 2019 13:03:52 -0700 Subject: [PATCH 3/3] Add year --- docs/webhooks.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/webhooks.rst b/docs/webhooks.rst index 8ab637a0340..584548d88ed 100644 --- a/docs/webhooks.rst +++ b/docs/webhooks.rst @@ -167,7 +167,7 @@ new webhook intergration. I was warned I shouldn't use GitHub Services ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Last year, GitHub announced that effective Jan 31st, GitHub Services will stop +Last year, GitHub announced that effective Jan 31st, 2019, GitHub Services will stop working [1]_. This means GitHub will stop sending notifications to Read the Docs for projects configured with the ``ReadTheDocs`` GitHub Service. If your project has been configured on Read the Docs for a long time, you are most likely still