Level Up Your Workflows with the GitHub API

In the last couple of years, I’ve seen more and more teams starting to use GitHub as their primary platform for source code hosting and CI/CD for newer projects.

Therefore I want to showcase some of the more advanced capabilities of GitHub Actions workflows that can improve your developer experiences.

The Baseline Workflow

Coming from the infrastructure world, the most common use-cases I see for CI/CD workflows are created around building, testing, and deploying infrastructure code, so while I’ll take examples from that, similar ideas can be applied to other types of code projects as well.

Some of the common workflows I see are typically looking like this:
Repository checkout -> Install dependencies -> Run test/validation -> Deploy.

1
- uses: actions/checkout@v4
2
- uses: hashicorp/setup-terraform@v3
3

4
- name: Terraform Fmt
5
  id: fmt
6
  run: terraform fmt -check
7
  continue-on-error: true # The check will exit with code 1 and stop the workflow unless this is set
8

9
- name: Terraform Init
10
  id: init
11
  run: terraform init
12

13
- name: Terraform Validate
14
  id: validate
15
  run: terraform validate -no-color
16

17
- name: Terraform Plan
18
  id: plan
19
  run: terraform plan -out=tfplan -no-color
20

21
- name: Terraform Apply
22
  run: terraform apply -auto-approve tfplan

But besides adding more features to perform more advanced terraform operations, let’s have a look at some capabilities of improving the developer experience.

Accessing the GitHub Context and API

GitHub has a powerful API that allows you to interact with various aspects of your repositories, including workflows, pull requests, issues and other aspects.

It can easily be accessed by using the actions/github-script action. This action provides a Node.js environment, allowing you to write JavaScript directly in your workflow file. Since each workflow run has a built-in GITHUB_TOKEN secret which is passed into the step per default, it requires almost no setup.

A simple example of using this API in a workflow could be to get the title of the pull request that triggered the workflow:

1
- name: Get PR Title
2
  id: get_pr_title
3
  uses: actions/github-script@v8
4
  with:
5
  script: |
6
    const pr = await github.rest.pulls.get({
7
      owner: context.repo.owner,
8
      repo: context.repo.repo,
9
      pull_number: context.payload.pull_request.number
10
    });
11
    return pr.data.title

This capability suddenly enables us to do a lot on the GitHub platform directly from our workflows in a context aware manner.

Real World Example: Automating PR Comments

So let’s take a look at a real world example that I personally use quite often in projects with multiple contributors.

In a Terraform based project I find it quite important to have validation and visibility into the changes you are suggesting before merging a pull request. I typically see a lot of automation being built inside the github workflows, meaning that the contributor that wants to add something, might not be familiar with the workflows and I don’t necessarily see a need for everyone to have a deep understanding of the entire repository, if their task is just focused around the infrastructure of the project.

Therefore when creating a pull request I like to provide all the necessary information directly in the pull request itself, so that the contributor and reviewer can focus on the changes.

1
- uses: actions/github-script@v8
2
  if: github.event_name == 'pull_request'
3
  env:
4
    PLAN: "terraform\n${{ steps.plan.outputs.stdout }}"
5
  with:
6
    github-token: ${{ secrets.GITHUB_TOKEN }}
7
    script: |
8
      const output = `#### Terraform Format and Style 🖌\`${{ steps.fmt.outcome }}\`
9
      #### Terraform Initialization ⚙️\`${{ steps.init.outcome }}\`
10
      #### Terraform Validation 🤖\`${{ steps.validate.outcome }}\`
11
      <details><summary>Validation Output</summary>
12

13
      \`\`\`\n
14
      ${{ steps.validate.outputs.stdout }}
15
      \`\`\`
16

17
      </details>
18

19
      #### Terraform Plan 📖\`${{ steps.plan.outcome }}\`
20

21
      <details><summary>Show Plan</summary>
22

23
      \`\`\`\n
24
      ${process.env.PLAN}
25
      \`\`\`
26

27
      </details>
28

29
      *Pusher: @${{ github.actor }}, Action: \`${{ github.event_name }}\`, Working Directory: \`${{ env.tf_actions_working_dir }}\`, Workflow: \`${{ github.workflow }}\`*`;
30

31
      github.rest.issues.createComment({
32
        issue_number: context.issue.number,
33
        owner: context.repo.owner,
34
        repo: context.repo.repo,
35
        body: output
36
      })

This leverages previous steps output and combines it with the GitHub API, which enables you to create comments directly on the pull request with all the changes that are going to be applied if the PR is merged.

So when a reviewer comes to review the changes, they don’t need to run any terraform commands locally or go into the logs of the workflow run and dig through the output, instead they get a nicely formatted comment with all the necessary information right in the PR.

From the perspective of being the one that is setting up the workflow, it’s surprisingly simple, but let’s dissect it in detail.

1
  const script = require('./path/to/your/script.js');
2
  await script(github, context, process.env, steps); // Pass in the contexts needed for your script

Breaking Down the Implementation

Any type of variable information defined in the example above is wrapped inside ${{ }} which is the syntax for GitHub Actions expressions. This means that the expression is evaluated at runtime of the step. You might have multiple steps before this one that you want to feed into the comment that you are creating on the PR, so it will run each of these steps first, and finally when this step is reached, it will resolve all the expressions.

Referencing Previous Steps

When defining a step in a GitHub Actions workflow, optionally you can assign an id to the step, which allows you to reference the outputs and status of that step in subsequent steps.

So in this example there are multiple variants to take note of

1. Referencing the outcome of a previous step, in this case the step with the id fmt. The outcome property is exit-code based, so it can be success, failure, or neutral.

1
${{ steps.fmt.outcome }}

2. Referencing output from a previous step, in this case the step with the id plan.

The stdout property contains the standard output of the command that was run in that step.

1
${{ steps.plan.outputs.stdout }}

3. Getting variables from an earlier step.

While not in the example above, dedicated outputs can be defined via shell or powershell commands in previous steps, which can then be referenced in the same way as above.

1
${{ steps.<step_id>.outputs.<output_name> }}

4. Getting context information about the workflow run.

GitHub Actions provides a github context that contains information about the workflow run, including details about the repository, the event that triggered the workflow, and other metadata.

Here are a few of them:

1
${{ github.event_name }}  // The name of the event that triggered the workflow
2
${{ github.actor }}       // The username of the person who triggered the workflow
3
${{ github.workflow }}    // The name of the workflow
4
${{ github.repo.name }}   // The repository name
5
${{ github.repo.owner }}  // The owner / organization of the repository

Interacting with the API

Now that we know how to gather all the information, it’s just a matter of putting it to use.

When running the action as a actions/github-script@v7 step, we have access to a github object that allows us to interact with the GitHub API without any further installation or authentication, since the action automatically uses the provided GITHUB_TOKEN for authentication, only requiring you to specify the permissions you need in the yaml file.

Setting permissions for the GITHUB_TOKEN

Do take note however if you need it to perform write operations, such as creating comments, you need to make sure that the token has sufficient permissions. Setting those permissions however is just adding a few lines on the top level of your workflow file.

To get you started, these are the permission scopes you will likely encounter most often:

1
permissions:
2
  contents: read|write      // Allows reading or writing repository contents
3
  issues: read|write        // Allows creating and modifying issues and comments
4
  pull-requests: read|write // Allows creating and modifying pull requests and comments
5
  id-token: write           // Allows generating OpenID Connect tokens for authentication

Creating the comment

Finally, to create the comment.

Inside the script block we got access to some functions via the github and context objects. We use the github.rest.issues.createComment method from the GitHub API, which requires us to provide the repository owner, repository name, issue number (which is the pull request number in this case), and the body of the comment.

Please note that there is a limit to how much content you can post in a single comment, so if your terraform plan output is very large, you might want to consider truncating it or providing a link to the full output elsewhere.

1
github.rest.issues.createComment({
2
  issue_number: context.issue.number,    // The ID number of the issue or pull request
3
  owner: context.repo.owner,             // The owner of the repository
4
  repo: context.repo.repo,               // The repository where the comment should be posted
5
  body: output                           // The content of the comment to be posted
6
})

And then you are getting something that looks like this directly in your pull request:

Other ideas

To give you some more ideas to explore with the GitHub API in your workflows, here are a few suggestions:

• Labeling pull requests based on certain conditions (e.g., adding a “needs review” label if tests fail)
• Assigning reviewers automatically based on the files changed in the pull request
• Closing stale issues or pull requests after a certain period of inactivity
• Creating issues based on specific events or conditions in your workflows
• Welcoming new contributors by posting a comment on their first pull request

These are just a few more harmless ideas to get you started, but once you start exploring the API, you’ll find that there are many more possibilities to enhance your workflows and developer experience.

Some of the more advanced (and potentially dangerous in regards to permissions) could get you into automating GitHub itself and is starting to get into the realm of GitHub Workflows as an automation platform, rather than just CI/CD.

As an example I’ve seen repositories being dedicated for documenting modules in other repositories being automatically updated with version bumps and changelogs based on releases in the source repositories or repositories acting as management tools to setup and maintain other repositories in an organization.

Conclusion

I hope you enjoyed this deep dive into some of the more advanced capabilities of GitHub Actions workflows.

And in case you are interested in picking up these examples in full detail, ready to use in your own projects, you can find the full workflow examples in my GitHub repository linked below.

Link to examples

Check out the full examples on GitHub