Coding Chica

Table of Contents

1. Table of Contents
2. Overview
3. Prerequisites
4. Add A Maven Build Yaml File
5. Testing for Failure – Viewing Logs and Checking Notifications
6. Testing for Success – Removing our Intentional Failure

Overview

When a repository’s code base is only built locally, it makes it difficult to track code quality.

• When was a bug introduced? Investigations may require you to checkout individual commits and build them locally until a successful build is encountered.
• Is a pull request ready to merge? Similarly, we may have to checkout the code locally and run a build to answer this question.
• Are my tests flaky? Not receiving notifications of build failures may mask such issues.

Having a remote build done on each important commit on the main / other important branches for the repo, where the build status is reported back to the repository’s commit, can help mitigate these problems. Often build services will also send out notifications when a build fails.

In this case, our Java101 project uses Maven for local builds, so we are going to replicate that in GitHub actions.

Prerequisites

In order to use these step-by-step instructions, you first need:

• A GitHub account, for which you are logged in via a browser.
• An existing repository for a Java project using a Maven build.
  • The assumption is also made that any of the server’s operating systems that GitHub offers can be used for the build.
• No existing file in your repo at the path: .github/workflows/maven.yml. If you have an existing file, you can instead view / edit that file directly, if desired.
• You have watched the GitHub repo in question, so you can receive notifications, or are coordinating with someone who is receiving those notifications.
• You are either the owner of the repository, or have been granted permissions to configure actions in the repository settings.

Add A Maven Build Yaml File

GitHub will add a template file for you.

1. Go to your GitHub repository.
2. Click on the Actions button along the top.
3. In the Search Box, enter Java with Maven.
4. On the Java with Maven action, click the Configure button.
5. Compare the generated file with the commented one below. If you find the added comments beneficial, feel free to update your file to match.
6. Unless you have already setup additional authentication steps, you will likely need to remove the section named “Update dependency graph“. This can be commented out (using a pound (#) sign) or removed entirely, depending upon whether you think you may want to re-add in the future.

If desired, you can update the generated file to include some additional comments, like the following:

# This workflow will build a Java project with Maven, and cache/restore any dependencies to improve the workflow execution time
# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-java-with-maven

# This workflow uses actions that are not certified by GitHub.
# They are provided by a third-party and are governed by
# separate terms of service, privacy policy, and support
# documentation.

name: Java CI with Maven

# When to perform the build action.
on:
  push:
    # When changes are made to the key branches
    branches: [ "main" ]
  pull_request:
    # When a pull request targets a key branch
    branches: [ "main" ]

# What will be done as part of this action.
jobs:
  build:

    # Default version - Linux servers.  Shouldn't matter for this project.
    runs-on: ubuntu-latest

    steps:
    # Checkout the code from the source code repository.
    - uses: actions/checkout@v3
    
    # Setup the desired Java version in the environment with a Maven local 
    # cache of dependencies (better build performance)
    - name: Set up JDK 17
      uses: actions/setup-java@v3
      with:
        java-version: '17'
        distribution: 'temurin'
        cache: maven
   
    # Perform the Maven build locally.  No artifacts are deployed
    - name: Build with Maven
      run: mvn -B package --file pom.xml

Note: Most of the code above was auto-generated by the GitHub action. It has been updated to add comments and spacing for readability.

Testing for Failure – Viewing Logs and Checking Notifications

If you do not own this repo, talk to the owner(s) before performing this step, so they know to expect the failure notification and are OK telling you that they received it.

Looking at the top of the screen, it should be adding a new file to your repo at: .github/workflows/maven.yml.

1. Within .github/workflow/maven.yml’s contents:
   • Let’s change the mvn -B package –file pom.xml run value in the “Build with Maven” step to mvn -B doesNotExist package –file pom.xml (adding a doesNotExist phase) in order to force a failure and test notifications.
2. Commit the Changes
   • In the upper right corner of the page, click on the Commit changes… button.
   • In the popup, within the Extended description section, it may be worthwhile to mention that we are intentionally testing a failure scenario.
   • Choose whether you are able to commit directly to the main (or whatever your main branch is named) or if you need to create a new branch, so you can create a pull request.
   • Click on the Commit changes button.
   • It should take you to the Code tab for your repo.
3. Check your email to ensure you got a notification that the build failed.
4. View the failed GitHub Action
   • Click on the Actions tab at the top of the page.
   • In case you have other, existing actions, choose Java CI with Maven along the left-hand-side to filter down to just our new action.
   • There should be a red X icon next to your commit message, such as “Create maven.yml”
   • Clicking on the commit message, such as Create maven.yml, should show a details page that shows that the build failed.
   • In the middle of the screen, in the maven.yml section of the page, click on the build button should show Maven build logs.
   • In the Maven build logs, you should see output like:

[INFO] ------------------------------------------------------------------------
[INFO] BUILD FAILURE
[INFO] ------------------------------------------------------------------------
...
[INFO] ------------------------------------------------------------------------
Error:  Unknown lifecycle phase "doesNotExist". You must specify a valid lifecycle phase or a goal in the format <plugin-prefix>:<goal> or <plugin-group-id>:<plugin-artifact-id>[:<plugin-version>]:<goal>. Available lifecycle phases are: validate, initialize, generate-sources, process-sources, generate-resources, process-resources, compile, process-classes, generate-test-sources, process-test-sources, generate-test-resources, process-test-resources, test-compile, process-test-classes, test, prepare-package, package, pre-integration-test, integration-test, post-integration-test, verify, install, deploy, pre-clean, clean, post-clean, pre-site, site, post-site, site-deploy. -> [Help 1]

Testing for Success – Removing our Intentional Failure

Let’s modify the new maven.yml file to remove the intentional error scenario.

1. Find the file to update.
   • Go to the Code tab for the repo.
   • Ensure that the desired branch is displayed in the upper left corner. Likely, this will be main.
   • Click on the .github/workflows folder to display its contents.
   • Click on maven.yml to display the current contents.
2. Edit the file.
   • Click on the pencil icon in the upper right corner of the maven.yml display, to switch to editing mode.
   • Update the Build with Maven step’s run value to remove the doesNotExist keyword / intentional failure.
3. Commit the update
   • Click on the Commit changes… button in the upper-right corner.
   • In the Extended description, it may be helpful to put something like: Removing intentional failure scenario.
   • Decide whether you are going to commit directly to the current branch, or create a new branch.
   • Click on Commit changes.
4. Confirm successful execution in the Actions tab.
   • Click on the Actions tab at the top of the page.
   • In case you have other, existing actions, choose Java CI with Maven along the left-hand-side to filter down to just our new action.
   • Your new commit should be displayed at the top of the page. It should carry a green check-mark icon to indicate a successful run.
     Note: The prior commit’s failure is still shown, but further down the page. This will help you if troubleshooting the build in the future.