Annotating Code with Actions

In this chapter, we’ll explore annotations within the context of GitHub check runs. Our journey is packed with invaluable insights and practical knowledge that will empower you to leverage annotations for enhanced code review and collaboration. In this chapter, we’ll transition into the practical realm, witnessing annotations in action. Through hands-on demonstrations, you’ll witness how they come to life, translating workflow-generated data into impactful feedback within your code base. By following along, you’ll gain the proficiency to seamlessly incorporate annotations into your development cycle.

In this chapter, we’ll also unlock the magic of turning build warnings and insights into annotations on specific lines of code. This skill not only accelerates the identification of potential issues but also provides a streamlined approach to addressing them effectively. We’ll extend further on the existing RichChecks...

Technical requirements

To follow along with the hands-on material in this chapter, you must follow the steps in the previous chapter or access the resources from that chapter if anything is ambiguous to you.

We’re going to be writing a small JavaScript application, so please install Node.js and npm using the instructions at https://docs.npmjs.com/downloading-and-installing-node-js-and-npm and Visual Studio Code at https://code.visualstudio.com/ or a similar IDE of your choice.

We will be stepping through the process of creating everything else in this chapter.

Exploring annotations within checks

From the previous chapter, where we went over the Checks API, you might have recalled us mentioning that annotations are a sibling to the conclusion field. Annotations, which are often considered concise notes, are your direct line of communication to the code committer against your code base. Imagine providing actionable feedback, context-rich guidance, and real-time insights right where they matter most—within the code itself. In this section, we’ll uncover the powerful synergy between checks and annotations, where code review transforms into a collaborative and insightful experience.

You can create annotations while creating the check run or as another call to the annotations endpoint under a given check run ID. Let’s dive into the structure of annotations and the rules of creating them.

The structure of an annotation

When creating annotations through the REST API, you enrich your code base with contextual feedback...

Annotations in action

In this section, we will leverage an existing script from the previous chapter to demonstrate adding annotations to a file in a pull request check run. We’re looking to clone this script and alter it to add an annotation to the third step within the script to add an annotation to the repository’s README file. We’ll run and observe the different types of annotation levels and target sections or a line within a file.

Follow these steps to create an annotation on our README file:

1. Clone the script at Chapter 8/scratchpad/.github/workflows/build-create-check-in-step-part-three.yml into the scratchpad repository.
2. Change the workflow’s name to avoid a clash with other workflow runs (optionally, disable the workflows, as demonstrated in the previous chapter). I named my copy create a check in a step with annotations, but it doesn’t matter for this exercise.
3. Update the third step in the steps property in the workflow...

Creating annotations from build output

GitHub Actions can interpret specific strings in your workflow’s log output and automatically generate annotations. These annotations can provide visual feedback directly on pull requests or commits, making it easier for developers to understand what went wrong or what might need attention.

To create annotations based on log output, you can use specific formats recognized by GitHub Actions. Let’s look at some examples of these formats:

• error:

  ::error file=FILE_NAME,line=LINE_NUMBER,col=COLUMN_NUMBER::MESSAGE_HERE

• warning:

  ::warning file=FILE_NAME,line=LINE_NUMBER,col=COLUMN_NUMBER::MESSAGE_HERE

• debug:

  ::debug::MESSAGE_HERE

• info:

  ::info::MESSAGE_HERE

Let’s break down the terms used here:

• FILE_NAME is the relative path to the file
• LINE_NUMBER is the line number in the file
• COLUMN_NUMBER is the column number in the file (this is optional)
• MESSAGE_HERE is the message you want to display...

Creating annotations from a GitHub App using Probot

Probot is a pivotal framework in the world of GitHub Apps. Specifically tailored for those aiming to craft GitHub Apps and OAuth apps, Probot simplifies the developmental processes. It eradicates mundane boilerplate tasks, allowing developers to center their attention on creating unique app functionalities.

Building GitHub Apps can be intricate. With Probot, integrating with GitHub’s API becomes more straightforward, making GitHub’s capabilities smoother. It allows developers to find a more direct route to prototype, design, and launch apps that augment GitHub’s native features. By doing so, projects can be tailored more closely to individual needs, driving efficiency in the development life cycle.

Exploring Probot-powered apps

Several apps that have been built using Probot have gained traction due to their utility. Let’s bring a few of these to your attention as they have value in everyday engineering...

Summary

This chapter examined the pivotal role of annotations within GitHub check runs. Our example highlighted how these annotations, beyond mere textual markers, significantly enhance code review processes and foster effective team collaboration. Shifting from theory, we demonstrated the practical utility of annotations. Through real-world scenarios, we showcased how they efficiently transform workflow-generated data into meaningful feedback, offering developers a powerful tool to optimize code quality seamlessly. We unraveled the process of translating build warnings into specific code annotations, enabling quicker issue identification and resolution. Our discussions further led us to an evolved version of the RichChecks action, which has been enhanced with expanded capabilities. We illustrated how integrating linting tools, notably Docker and Bicep, can write their outputs into a check run, offering a holistic view of potential code enhancements. The latter part of this chapter...