Skip to content

Docs: Split email notifications and webhook notifications into separate howtos #10396

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 8 commits into from
Jun 9, 2023
Merged

Docs: Split email notifications and webhook notifications into separate howtos #10396

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
20c7e66
Split email notifications and webhook notifications into separate howtos
benjaoming Jun 6, 2023
5ddd445
Updates re: review @ericholscher
benjaoming Jun 7, 2023
fea3fc6
More review feedback addressed
benjaoming Jun 7, 2023
e60ca66
Update several parts of copy to adapt to the split
benjaoming Jun 7, 2023
33b3b9c
Dot the i's
benjaoming Jun 7, 2023
8df4c44
Adds a note about PR notifications being skipped
benjaoming Jun 8, 2023
1454899
prefer "documentation builds"
benjaoming Jun 8, 2023
3368ed9
Trim out a seealso to give the other two more prominence
benjaoming Jun 8, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 6 additions & 2 deletions docs/user/build-notifications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,8 +17,12 @@ Build Status Webhooks:
Webhooks can be customized through your own template and a variety of variable substitutions.

.. seealso::
:doc:`/guides/build-notifications`
All the practical steps for setting up build notifications
:doc:`/guides/build/email-notifications`
Enable email notifications in a second.

:doc:`/guides/build/webhooks`
Steps for setting up build notifications with webhooks,
including examples for popular platforms like Slack and Discord.

:doc:`pull-requests`
Similarly to build notifications, you can also configure automated feedback for your pull requests.
40 changes: 40 additions & 0 deletions docs/user/guides/build/email-notifications.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
How to enable email notifications
=================================

In this guide, you can learn how to setup build notification via email.

.. note::

Currently we don't send email notifications on :doc:`builds from pull requests </pull-requests>`.

.. tip::
:doc:`/pull-requests`
Similarly to email notifications,
you can also configure automated feedback for your pull requests.


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:

* Go to :menuselection:`Admin --> Notifications` in your project.
* Fill in the **Email** field under the **New Email Notifications** heading
* Submit the form

Who is notified?
----------------

If you are a single owner of a project,
*you* will get notified.

If your project has several members,
then the following are notified:

* All :term:`maintainers <maintainer>` (|org_brand|)
* All owners of an :doc:`organization </commercial/organizations>` (|com_brand|)
that owns the project,
or members of teams with admin access to the project.
16 changes: 10 additions & 6 deletions docs/user/guides/build/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,11 +1,14 @@
How-to guides: build process
============================

⏩️ :doc:`Setup build notifications and webhooks </guides/build-notifications>`
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:`Enable email notifications </guides/build/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 </guides/build/webhooks>`
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 </guides/pull-requests>`
Have your documentation built and access a preview for every :doc:`pull request builds </pull-requests>`.
Expand All @@ -28,7 +31,8 @@ How-to guides: build process
:maxdepth: 1
:hidden:

Setup build notifications and webhooks </guides/build-notifications>
Enable email notifications </guides/build/email-notifications>
Setup webhook notifications </guides/build/webhooks>
Configuring pull request builds </guides/pull-requests>
Using custom environment variables </guides/environment-variables>
Managing versions automatically </guides/automation-rules>
187 changes: 84 additions & 103 deletions docs/user/guides/build-notifications.rst → docs/user/guides/build/webhooks.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,37 +1,18 @@
How to setup build notifications and webhooks
=============================================
How to setup webhook notifications
==================================
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess we should be systematic about calling the feature "build status webhooks" since that's how it is right now.

If we're gonna do anything more drastic, I think it should include the Dashboard terminology, so I would just save that for later..


In this guide, you can learn how to setup a number of build notification mechanisms.
In this guide, you can learn how to setup build notification with webhooks.
Build notifications can alert you when your builds fail so you can take immediate action.

.. note::

Currently we don't send notifications or trigger :term:`webhooks <webhook>`
on :doc:`builds from pull requests </pull-requests>`.
Currently we don't trigger :term:`webhooks <webhook>` on :doc:`builds from pull requests </pull-requests>`.


.. 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:

* 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!
Similarly to webhook notifications,
you can also configure automated feedback for your pull requests.

Build status webhooks
---------------------
Expand All @@ -40,7 +21,7 @@ Read the Docs can also send webhooks when builds are triggered, successful or fa

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`
Expand Down Expand Up @@ -80,7 +61,7 @@ you will see the server response, the webhook request, and the payload.
Activity of a webhook

Custom payload examples
~~~~~~~~~~~~~~~~~~~~~~~
-----------------------
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we shouldn't change these here. ~~~~ are used as subsections of Build status webhooks and I think it's correct to be subsections.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I reverted it 👍

But essentially, it's because I wanted to go towards a step-wise how-to (and not nested sections like we have in reference or explanation). Unfortunately, this how-to is very far from such a result :)

In general, how-tos are better like....

Do this
-------

lorem ipsum

Then do this
------------

lorem ipsum

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The following two were not updated and they should because of the same reason.

I understand what you want to achieve with the sections, but this case doesn't work like that since they are subsections and not steps the user has to follow.


You can customize the payload of the webhook to suit your needs,
as long as it is valid JSON. Below you have a couple of examples,
Expand All @@ -93,84 +74,84 @@ 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 <https://api.slack.com/messaging/webhooks>`_.

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 <https://api.slack.com/messaging/webhooks>`_.

.. 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 <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks>`_.
More information on `the Discord webhooks documentation <https://support.discord.com/hc/en-us/articles/228383668-Intro-to-Webhooks>`_.

Variable substitutions reference
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
--------------------------------

``{{ event }}``
Event that triggered the webhook, one of ``build:triggered``, ``build:failed``, or ``build:passed``.
Expand Down Expand Up @@ -213,7 +194,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
Expand Down Expand Up @@ -255,7 +236,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:
Expand Down
7 changes: 5 additions & 2 deletions docs/user/guides/setup/git-repo-manual.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down