Purpose
Using automation with GitHub Actions is a great way to simplify project updates. This example will demonstrate how to connect an iCloud account to your repository and receive automated emails after a workflow job has completed.
Requirements
- GitHub repository
- iCloud email account
- Enabling an app-specific password in iCloud
- A GitHub actions workflow file
Steps
While this demonstration uses iCloud, adapting Ravgeet Dhillon’s blog post to suit your needs should be fairly easy.
Part 1: iCloud
- Login to your iCloud account and navigate to your icon in the upper right of the screen. Select “Manage Apple Account” from the list of options:
Proceed to login and complete the two-factor authorization, if enabled.
Select “App-Specific Passwords” from the tile options.
- Select the plus symbol (
+
).
- Add a name for your passowrd.
- Complete the verification.
- Save and copy this password immediately! You cannot recover or see it again once you select “Done”.
Part 2: GitHub
- Navigate to the repository where you will be adding the GitHub Action. From the top bar, select “Settings”. On the left side, select “Secrets and variables” then “Actions”.
- Follow this format. Store the iCloud app-specific password you created above in a “New repository secret” named
EMAIL_PASSWORD
. Add your iCloud email address to a “New repository secret” namedEMAIL_USERNAME
.
If you use different secret names, you will need to modify the YAML file provided below to match.
Part 3: Workflow file
- Create a new file in your repository. As an example, the file is named
_build.yml
and will be stored in this path from the root of your project.github/workflows
. If you don’t currently have those directories, you can enter the following command in your terminal:
mkdir -p .github/workflows
touch _build.yml
Using the -p
flag, this will m
ak
e dir
ectory or directories if they do not currently exist and create (touch) the new file. Alternatively, you can use the GUI tools if that’s easier.
- Open
_build.yml
and paste in this content:
name: Build
on:
push:
branches: main
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v2
- name: Hello World
run: echo Hello, world!
- name: Send status email via iCloud
if: always()
uses: dawidd6/action-send-mail@v3
with:
server_address: smtp.mail.me.com
server_port: 587 # iCloud SMTP requires TLS (STARTTLS)
secure: false # This must be false for STARTTLS to work
username: ${{ secrets.EMAIL_USERNAME }}
password: ${{ secrets.EMAIL_PASSWORD }}
subject: "${{ github.repository }} workflow: ${{ job.status }}"
# github.job will be lowercase of the `name` value in line 1. Here, "build".
# github.workflow will will match the `name` value in line 1
# github.repository is the repository name: kyleGrealis/my-repo-name
# job.status: "success" or "failure"
body: |
${{ github.workflow }} of ${{ github.repository }}
Job: ${{ github.job }}
Status: ${{ job.status }}" to: "kylegrealis@icloud.com"
from: "From my GitHub Actions Bot"
Though this file may initially appear as overwhelming or complicated, it uses a relatively straight-forward key:value
syntax:
- Name the workflow “Build”. This will appear under the “Actions” tab and then the left side of the screen for your GitHub repository.
- The
on:
section states that this action will run on each projectpush
on themain
branch. To add other branches, movemain
to the next line with one more indent and a dash:
on:
push:
branches:
- main
- dev
The
jobs
section declares what is to happen and how it is to happen. The explanations are beyond the scope of this, so explore GitHub documentation for more information.There will be two main jobs that will run:
Echo “Hello World” to the Actions console.
Send a status email
The email with
always()
be sent, regardlesss if the job was a success or failure.Be sure not to alter the
server
orsecure
lines or risk unexpected consequences or workflow failure.The
username
andpassword
are self-explanatory. The secret names you provided in Part 2 must match the names inside the braces (e.g.,secrets.EMAIL_USERNAME
) to correctly provide those values. This format prevents leaking your personal information to others, like the author is doing here.The
subject
andbody
can be modfied with whatever information you desire. Usebody: |
then indent to create a multiple line & custom structure to the email. A successful run will return this with your own information included:
- Save, commit, add a message, and push this file to your repository. You should quickly receive a status email if everything was done correctly. You can view the real-time workflow by navigating to the “Actions” tab in your repository, select the name of your action (i.e., “Build”), and select the commit message you gave. Using the image from above (and repeated here), the commit message was “updated”. Selecting that will give you an easy interface to select and check the logs. The logs provide a good amount of detail to help the debugging process if something went wrong.
Conclusion
GitHub Actions can really enhance your data science workflow by offloading manual tasks to action-specific or chronological jobs. Integrating them is quite easy and only requires about 30 minutes of reading and testing before you will be able to adapt this simple example to meet your needs.
Share your insights at kylegrealis@icloud.com. Together, we can make our R projects more robust, reproducible, and ready for collaboration!
Happy coding!
~Kyle