31  Playing with GitHub Actions

Author

Affiliation

Dr Randy Johnson

Hood College

Introduction

Today we will put what we’ve learned regarding GitHub Actions into practice. We’ll be building onto the DNAanalyzer app we built over the past few exercises.

Email notification on push

Our first action will be to initiate an email notification each time a new commit is pushed to a repository.

Setup

This exercise assumes you have Gmail and GitHub accounts. We’ll need to set up some secrets on GitHub, but first we’ll need an app password for your Gmail account. App passwords are not recommended unless you are unable to log in using Google’s web-signin protocol. That is not an option in this case, so we’ll start with setting up the app password.

• Create an app password on Google: https://myaccount.google.com/apppasswords
• Open the settings on your forked repository
  • Navigate to Settings > Secrets and Variables > Actions
  • Create the GMAIL_USERNAME and GMAIL_APP_PASS secrets for sending email
  • Create a HOOD_EMAIL for receiving notifications

Create GitHub Action yaml file

Open the repository you just forked and:

• Navigate to the Actions tab
• Click “New Workflow” and select “Configure” under the Simple Workflow option
• Change the name from “blank.yml” to something more appropriate
• Change the name field to match
• Remove the on: pull-request option, as we’ll only be triggering notifications on push
• Remove the workflow_dispatch item, as this is less helpful for this application
• Change the build workflow under jobs to send-email
• Under steps add the code below with the following modifications:
  • to should list the email where you would like to be notified
  • from should list the sending email - use the same email we set above

# draft yml code courtesy of Gemini
      - name: Send mail
        uses: dawidd6/action-send-mail@v3
        with:
          server_address: smtp.gmail.com
          server_port: 465
          username: ${{ secrets.GMAIL_USERNAME }}
          password: ${{ secrets.GMAIL_APP_PASS }}
          subject: New commit pushed to ${{ github.repository }}
          body: "New commit by ${{ github.actor }} on branch ${{ github.ref_name }}. The commit message is: ${{ github.event.head_commit.message }}""
          to: ${{secrets.HOOD_EMAIL}}
          from: ${{secrets.GMAIL_USERNAME}}@gmail.com

Once you push this, you should see a list of all workflow runs under your Actions tab.

Automated documentation

Next we will incorporate a GitHub action that will automatically render the documentation in our README file whenever it is updated. The setup for this is much simpler than the previous exercise, as it doesn’t require any secrets for interacting with outside services.

Create the GitHub Actions yaml file

Navigate to the Actions tab of your repository. You should see your existing workflow from the previous section.

• Click on “New Workflow” on the left
• Select the “Simple Workflow” option
• Copy the following code into the yaml file:

# draft yml code courtesy of Gemini
name: Render README

on:
  push:
    paths:
      - 'README.qmd'
  workflow_dispatch:

jobs:
  render-quarto:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Set up Quarto
        uses: quarto-dev/quarto-actions/setup@v2

      - name: Render README.qmd
        uses: quarto-dev/quarto-actions/render@v2
        with:
          to: gfm
          path: README.qmd
          
      - name: Commit changes
        run: |
          git config --global user.email "github-actions[bot]@users.noreply.github.com"
          git config --global user.name "github-actions[bot]"
          git add README.md
          git commit -m "docs: Render README.md from README.qmd" || echo "No changes to commit"
          git push

Edit README.qmd

Once you have created the workflow, we’ll test it out by creating / updating README.qmd.

• Make some changes to your README.qmd file (or create one if you don’t already have one)

Commit and Verify

• Commit and push your changes to GitHub
• Check your Actions tab to verify that your workflow completes successfully
  • (Your push should have activated two workflows)
• If it completed successfully, navigate to the main page for your repository to visually inspect your README output.

Assignment

Once you have tested and verified your GitHub actions, submit a link to your repository on Blackboard.