diff --git a/docs/user/build-notifications.rst b/docs/user/build-notifications.rst index 10a368a6723..a6b0171ea5a 100644 --- a/docs/user/build-notifications.rst +++ b/docs/user/build-notifications.rst @@ -1,12 +1,13 @@ -Build Notifications and Webhooks -================================ +Build notifications via webhooks and email +========================================== -Read the Docs features a number of build notification mechanisms. -Build notifications can alert you when your builds fail so you can take immediate action. +Build notifications can alert you when your documentation builds fail so you can take immediate action. +We offer the following methods for being notified: Email notifications: - Read the Docs allows you to configure emails that can be sent on failing builds. - This makes sure you know when your builds have failed. + Read the Docs allows you to configure build notifications via email. + When builds fail, + configured email addresses are notified. Build Status Webhooks: Build notifications can happen via :term:`webhooks `. @@ -16,9 +17,15 @@ Build Status Webhooks: Webhooks can be customized through your own template and a variety of variable substitutions. +.. note:: + + We don't trigger email notifications or build status webhooks on :doc:`builds from pull requests `. + .. seealso:: - :doc:`/guides/build-notifications` - All the practical steps for setting up build notifications + :doc:`/guides/build/email-notifications` + Enable email notifications on failed builds, + so you always know that your docs are deploying successfully. - :doc:`pull-requests` - Similarly to build notifications, you can also configure automated feedback for your pull requests. + :doc:`/guides/build/webhooks` + Steps for setting up build notifications via webhooks, + including examples for popular platforms like Slack and Discord. diff --git a/docs/user/guides/build/email-notifications.rst b/docs/user/guides/build/email-notifications.rst new file mode 100644 index 00000000000..9e347908385 --- /dev/null +++ b/docs/user/guides/build/email-notifications.rst @@ -0,0 +1,33 @@ +How to setup email notifications +================================ + +In this brief guide, +you can learn how to setup a simple build notification via email. + +Read the Docs allows you to configure emails that will be notified on failing builds. +This makes sure that you are aware of failures happening in an otherwise automated process. + +.. seealso:: + + :doc:`/guides/build/webhooks` + How to use webhooks to be notified about builds on popular platforms like Slack and Discord. + + :doc:`/pull-requests` + Configure automated feedback and documentation site previews for your pull requests. + + +Email notifications +------------------- + +Follow these steps to add an email address to be notified about build failures: + +* Go to :menuselection:`Admin --> Notifications` in your project. +* Fill in the **Email** field under the **New Email Notifications** heading +* Press :guilabel:`Add` and the email is saved and will be displayed in the list of **Existing notifications**. + +The newly added email address will be notified once a build fails. + + +.. note:: + + We don't send email notifications on :doc:`builds from pull requests `. diff --git a/docs/user/guides/build/index.rst b/docs/user/guides/build/index.rst index 1b7ff73230c..b607710457c 100644 --- a/docs/user/guides/build/index.rst +++ b/docs/user/guides/build/index.rst @@ -1,11 +1,14 @@ How-to guides: build process ============================ -⏩️ :doc:`Setup build notifications and webhooks ` - Build notifications can alert you when your builds fail so you can take immediate action. - In this guide, - you will learn how to get notified through various available channel integrations, - including email and chat. +⏩️ :doc:`Setup email notifications ` + Email notifications can alert you when your builds fail. + This is the most simple way to monitor your documentation builds, + it only requires you to switch it on. + +⏩️ :doc:`Setup webhook notifications ` + Webhook notifications can alert you when your builds fail so you can take immediate action. + We show examples of how to use the webhooks on popular platforms like Slack and Discord. ⏩️ :doc:`Configuring pull request builds ` Have your documentation built and access a preview for every :doc:`pull request builds `. @@ -28,7 +31,8 @@ How-to guides: build process :maxdepth: 1 :hidden: - Setup build notifications and webhooks + Setup email notifications + Setup webhook notifications Configuring pull request builds Using custom environment variables Managing versions automatically diff --git a/docs/user/guides/build-notifications.rst b/docs/user/guides/build/webhooks.rst similarity index 60% rename from docs/user/guides/build-notifications.rst rename to docs/user/guides/build/webhooks.rst index 72a6b4c7cae..fa537f51de4 100644 --- a/docs/user/guides/build-notifications.rst +++ b/docs/user/guides/build/webhooks.rst @@ -1,46 +1,29 @@ -How to setup build notifications and webhooks -============================================= +How to setup build status webhooks +================================== -In this guide, you can learn how to setup a number of build notification mechanisms. -Build notifications can alert you when your builds fail so you can take immediate action. +In this guide, +you can learn how to setup build notifications via webhooks. -.. note:: +When a documentation build is *triggered*, *successful* or *failed*, +Read the Docs can notify external APIs using :term:`webhooks `. +In that way, +you can receive build notifications in your own monitoring channels and be alerted you when your builds fail so you can take immediate action. - Currently we don't send notifications or trigger :term:`webhooks ` - on :doc:`builds from pull requests `. +.. seealso:: + :doc:`/guides/build/email-notifications` + Setup basic email notifications for build failures. -.. tip:: :doc:`/pull-requests` - Similarly to build notifications, you can also configure automated feedback for your pull requests. - - -.. contents:: Contents - :local: - - -Email notifications -------------------- - -Read the Docs allows you to configure emails that can be sent on failing builds. -This makes sure you know when your builds have failed. - -Take these steps to enable build notifications using email: + Configure automated feedback and documentation site previews for your pull requests. -* Go to :guilabel:`Admin` > :guilabel:`Notifications` in your project. -* Fill in the **Email** field under the **New Email Notifications** heading -* Submit the form - -You should now get notified by email when your builds fail! Build status webhooks --------------------- -Read the Docs can also send webhooks when builds are triggered, successful or failed. - Take these steps to enable build notifications using a webhook: -* Go to :guilabel:`Admin` > :guilabel:`Webhooks` in your project. +* Go to :menuselection:`Admin --> Webhooks` in your project. * Fill in the **URL** field and select what events will trigger the webhook * Modify the payload or leave the default (see below) * Click on :guilabel:`Save` @@ -79,6 +62,11 @@ you will see the server response, the webhook request, and the payload. Activity of a webhook +.. note:: + + We don't trigger :term:`webhooks ` on :doc:`builds from pull requests `. + + Custom payload examples ~~~~~~~~~~~~~~~~~~~~~~~ @@ -93,81 +81,81 @@ and in the following section you will find all the available variables. Custom payload -Slack -+++++ - -.. code-block:: json - - { - "attachments": [ - { - "color": "#db3238", - "blocks": [ - { - "type": "section", - "text": { - "type": "mrkdwn", - "text": "*Read the Docs build failed*" +.. tabs:: + + .. tab:: Slack + + .. code-block:: json + + { + "attachments": [ + { + "color": "#db3238", + "blocks": [ + { + "type": "section", + "text": { + "type": "mrkdwn", + "text": "*Read the Docs build failed*" + } + }, + { + "type": "section", + "fields": [ + { + "type": "mrkdwn", + "text": "*Project*: <{{ project.url }}|{{ project.name }}>" + }, + { + "type": "mrkdwn", + "text": "*Version*: {{ version.name }} ({{ build.commit }})" + }, + { + "type": "mrkdwn", + "text": "*Build*: <{{ build.url }}|{{ build.id }}>" + } + ] + } + ] } - }, - { - "type": "section", - "fields": [ - { - "type": "mrkdwn", - "text": "*Project*: <{{ project.url }}|{{ project.name }}>" - }, - { - "type": "mrkdwn", - "text": "*Version*: {{ version.name }} ({{ build.commit }})" - }, - { - "type": "mrkdwn", - "text": "*Build*: <{{ build.url }}|{{ build.id }}>" - } - ] - } - ] - } - ] - } - -More information on `the Slack Incoming Webhooks documentation `_. - -Discord -+++++++ - -.. code-block:: json - - { - "username": "Read the Docs", - "content": "Read the Docs build failed", - "embeds": [ - { - "title": "Build logs", - "url": "{{ build.url }}", - "color": 15258703, - "fields": [ - { - "name": "*Project*", - "value": "{{ project.url }}", - "inline": true - }, - { - "name": "*Version*", - "value": "{{ version.name }} ({{ build.commit }})", - "inline": true - }, - { - "name": "*Build*", - "value": "{{ build.url }}" - } - ] - } - ] - } + ] + } + + More information on `the Slack Incoming Webhooks documentation `_. + + .. tab:: Discord + + .. code-block:: json + + { + "username": "Read the Docs", + "content": "Read the Docs build failed", + "embeds": [ + { + "title": "Build logs", + "url": "{{ build.url }}", + "color": 15258703, + "fields": [ + { + "name": "*Project*", + "value": "{{ project.url }}", + "inline": true + }, + { + "name": "*Version*", + "value": "{{ version.name }} ({{ build.commit }})", + "inline": true + }, + { + "name": "*Build*", + "value": "{{ build.url }}" + } + ] + } + ] + } -More information on `the Discord webhooks documentation `_. + More information on `the Discord webhooks documentation `_. Variable substitutions reference ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -213,7 +201,7 @@ Variable substitutions reference Version name. Validating the payload -~~~~~~~~~~~~~~~~~~~~~~ +---------------------- After you add a new webhook, Read the Docs will generate a secret key for it and uses it to generate a hash signature (HMAC-SHA256) for each payload @@ -255,7 +243,7 @@ like this: ) Legacy webhooks -~~~~~~~~~~~~~~~ +--------------- Webhooks created before the custom payloads functionality was added to Read the Docs send a payload with the following structure: diff --git a/docs/user/guides/setup/git-repo-manual.rst b/docs/user/guides/setup/git-repo-manual.rst index 6b5f3c8baad..89385018a63 100644 --- a/docs/user/guides/setup/git-repo-manual.rst +++ b/docs/user/guides/setup/git-repo-manual.rst @@ -139,8 +139,11 @@ Use this URL when setting up a new integration with your provider ^^ these steps .. seealso:: - :doc:`/guides/build-notifications` - Learn how to add custom build notifications. + :doc:`/guides/build/email-notifications` + Quickly enable email notifications. + + :doc:`/guides/build/webhooks` + Learn how to add custom webhook notifications. .. _webhook-integration-generic: