Merge pull request #380 from lincc-frameworks/issue/312/failure-emails

Send email on failure

copier.yml

@@ -93,7 +93,7 @@ failure_notification:
     default: [email]
     multiselect: true
     choices:
-        email: email
+        email (additional configuration required): email
         slack bot integration (additional configuration required): slack
         none: none
     when: "{{ custom_install }}"

docs/practices/ci_testing.rst

@@ -61,12 +61,47 @@ looks into the nature of the failure. This can be tricky with github, as a
 worfklow failure will, by default, only notify the maintainer who added the
 workflow file to the repo.
 
-The template supports two types of notifications: email or slack. If you 
-choose slack, some additional configuration is necessary.
+The template supports two types of notifications: email or slack. Both options 
+require some additional configuration, as follows:
 
-Create a Slack App
+Email notifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Create a Gmail app password and add to your repo's secret
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+To send email notifications, you'll need to create a Gmail app password and add
+it to your repo's secrets.
+
+- `Create a Gmail app password <https://support.google.com/accounts/answer/185833?hl=en>`_.
+
+  - You'll need to enable 2-step verification for your Google account to create
+    an app password. This is a good idea anyway, as it adds an extra layer of
+    security to your account.
+
+  - Once you've enabled 2-step verification, you can create an app password
+    for your account. This is a password that you'll use to send emails from
+    your account, without needing to use your actual account password.
+
+  - You'll need to create a new app password for each repo that you want to
+    send email notifications from.
+
+- `Add the app password to your repo's secrets <https://docs.github.com/en/actions/reference/encrypted-secrets#creating-encrypted-secrets-for-a-repository>`_.
+
+  - By default, the template uses the secret names ``MAIL_USERNAME`` and 
+    ``MAIL_PASSWORD``. You can change this in the ``smoke-test.yml`` file.
+
+.. note::
+   The email notifications are sent from the email address associated with the
+   app password, so you may want to create a new email address for this purpose.
+
+
+Slack notifications
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
+Create a Slack App
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 You'll need to create a Slack app. It's not as scary as it sounds!
 It will have certain permissions to post to particular channels, and will have
 an associated webhook URL that we'll use to send messages from GitHub to the app. 
@@ -86,7 +121,7 @@ for setting up an app. We really only need steps 1 and 5, summarized below:
   Copy the webook URL.
 
 Github workflow step to post to webhook
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Now you'll need to configure each project repo to send slack messages.
 

python-project-template/.github/workflows/smoke-test.yml.jinja

@@ -42,12 +42,44 @@ jobs:
       run: |
         python -m pytest
 {%- if 'email' in failure_notification %}
-    - name: Send failure email
+    - name: Send status to author's email      
+      if: {% raw %}${{ failure() }} && github.event_name != 'workflow_dispatch' }}{% endraw %} # Only email if the workflow failed and was not manually started. Customize this as necessary.
+      uses: dawidd6/action-send-mail@v3
+      with:
+        # Required mail server address if not connection_url:
+        server_address: smtp.gmail.com
+        # Server port: (uses TLS by default if server_port is 465)
+        server_port: 465
+
+        # Mail server username:
+        username: {% raw %}${{secrets.MAIL_USERNAME}}{% endraw %}
+        # Mail server password:
+        password: {% raw %}${{secrets.MAIL_PASSWORD}}{% endraw %}
+        # Required recipients' addresses:
+        to: {{ author_email }}
+
+        # Required mail subject:
+        subject: {% raw %}Smoke test ${{ job.status }} in ${{github.repository}}{% endraw %}
+        # Required sender full name:
+        from: GitHub Actions Report
+        # Optional body:
+        html_body: {% raw %}|
+          <!DOCTYPE html>
+          <html>
+          <body>
+          <h3>Smoke test ${{ job.status }}</h3>
+          <p>The smoke test in <b>${{ github.repository }}</b> has completed with result: <b>${{ job.status }}</b></p>
+          <p><a href="${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}">
+          ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+          </a></p>
+          </body>
+          </html>
+          {% endraw %}
 {%- endif %}
 {%- if 'slack' in failure_notification %}
 {%- raw %}
     - name: Send status to Slack app
-      if: ${{ failure() && github.event_name != 'workflow_dispatch' }} # Only post if the workflow failed and was not manually started. Customize this as necessary./
+      if: {% raw %}${{ failure() && github.event_name != 'workflow_dispatch' }}{% endraw %} # Only post if the workflow failed and was not manually started. Customize this as necessary.
       id: slack
       uses: slackapi/[email protected]
       with:
@@ -84,5 +116,4 @@ jobs:
       env:
         SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} # Here is where the webhook URL is provided
         SLACK_WEBHOOK_TYPE: INCOMING_WEBHOOK
-{%- endraw %}
-{%- endif %}
+{%- endif %}