Failed Build Issue Action

Important

We've moved! This repository has transferred from jayqi/failed-build-issue-action to drivendataorg/failed-build-issue-action. Old references will continue to redirect but we recommend updating.

This action makes it easy to notify maintainers of a GitHub Actions workflow failure via GitHub's issue tracker. By default, the action will find the latest open issue with the label build failed and add a comment. If no such issue is open, it will instead open a new issue.

Basic usage

Tip

GitHub recommends always pinning third-party actions to a full-length commit SHA as a security best practice.

- uses: drivendataorg/failed-build-issue-action@940568ce50eeef3f31a920614cefcc6102d2f930 # v1.3.0

For available options, see action.yml

This action creates and comments on issues, so the GITHUB_TOKEN needs issues: write permission. The recommended way to grant it is with the permissions keyword on the job that runs the action, which keeps the token scoped to only what's needed:

# on the job that runs the action:
permissions:
  issues: write

See the two examples below for realistic usage in full workflows.

Example 1: As a step

Below is an example GitHub Workflow YAML file that demonstrates a simple case of using this action in a workflow. If your workflow just runs a single job, then you can set things up in this way.

name: tests

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: "0 0 * * 0"  # Run every Sunday at 00:00 UTC

jobs:
  tests:
    name: Tests
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Run tests
        run: |
          bash run_tests.sh
      - name: Notify failed build
        uses: drivendataorg/failed-build-issue-action@940568ce50eeef3f31a920614cefcc6102d2f930 # v1.3.0
        if: failure() && github.event.pull_request == null

Explanation

In this example, we run failed-build-issue-action as a step in the single job in the workflow. One key part is the if conditional to control when the step runs.

if: failure() && github.event.pull_request == null

There are two conditions here that we combine with a && (and) operator:

1. failure() — the step will only run if there is a failure in any previous step in this job.
2. github.event.pull_request == null — In this example, we exclude pull requests because they represent in-development work where failures are more expected. See "Conditioning on event triggers" below for additional discussion.

You'll want to make sure the failed-build-issue-action step is after any step that you might want to trigger it.

We also set job-level permissions so the GITHUB_TOKEN has the access this action needs.

permissions:
  contents: read
  issues: write

Declaring permissions on a job overrides the defaults, setting any scope you don't list to none. This job needs issues: write for the action and contents: read for actions/checkout, so we grant both. (Normally, contents: read is available by default when you don't declare anything.)

Example 2: As a job

Below is an example GitHub Workflow YAML file that demonstrates a more complex workflow with multiple jobs. If your workflow has multiple jobs, such as from a matrix, then you'll want to follow this example.

name: tests

on:
  pull_request:
  push:
    branches: [main]
  schedule:
    - cron: "0 0 * * 0"  # Run every Sunday at 00:00 UTC

jobs:
  code-quality:
    name: Code quality
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Run linting
        run: |
          bash run_linting.sh

  tests:
    name: Tests - ${{ matrix.os }}
    needs: [code-quality]
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, macos-latest, windows-latest]
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
      - name: Run tests
        run: |
          bash run_tests.sh

  notify:
    name: Notify failed build
    needs: [code-quality, tests]
    if: failure() && github.event.pull_request == null
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - uses: drivendataorg/failed-build-issue-action@940568ce50eeef3f31a920614cefcc6102d2f930 # v1.3.0

Explanation

In this example, we've separated things out into multiple stages using jobs. First, the code-quality job runs to perform linting. Next, if code-quality succeeded, the tests job runs on a matrix of operating systems. We want to run failed-build-issue-action when either code-quality failures or if tests failures on any OS. To do this, we define a separate notify job. We use the needs keyword to define the prerequisite of our notify job.

needs: [code-quality, tests]

We also use the if keyword to condition the notify job on one of its prerequisites failing, as well as skipping pull requests as described in the previous example.

if: failure() && github.event.pull_request == null

Note that we don't need to use actions/checkout in this job because it doesn't depend on any files in our repository. This also means the notify job needs only issues: write permission and no contents: read, so we scope its GITHUB_TOKEN to just that.

permissions:
  issues: write

Because these permissions are declared on the notify job alone, the other jobs keep their default permissions.

Conditioning on event triggers

Events in GitHub Actions refer to things that can cause a workflow to run, such as a pushing a commit to a branch or pushing a commit to a pull request.

You may not want failed-build-issue-action to run for all of the same event triggers as the workflow itself. For instance, our examples above run on (1) commits to pull requests, (2) pushes to the main branch, and (3) on a weekly schedule on the main branch. You probably don't want to be notified for every test failure for pull requests, since in-development work is expected to fail more often. You can easily use the github.event payload to determine whether a particular type of event is running. For example:

• if: github.event.pull_request will be true if it's a pull request
• if: github.event.pull_request == null will be true if it's not a pull request

See the GitHub Actions documentation for more details. The "Using event information" documentation provides for information about how to use the metadata provided in the event payload. You can find a full list of supported events in "Events that trigger workflows".

Title and body templates

This action accepts title and body templates to use when creating new issues or comments through the title-template and body-template parameters, respectively.

These templates can render data from the GitHub Actions run context using mustache.js. For example, to render the run number, use the double-curly-brace mustache syntax: {{runNumber}}. See the attributes of the Context class in actions/toolkit for available context variables that you can use. For documention on the environment variables used to populate the context, see the documentation for GitHub Actions' default environment variables.

In addition to the attributes of the Context class, this action provides two variables of its own:

Variable	Description
refName	Display name of the branch or tag whose build failed. For a pull request from a fork, this is prefixed with the fork's owner, e.g., contributor:feature/foo.
refUrl	Full URL to that branch or tag. Percent-encoded, and based on the fork's repository for a pull request from a fork.

The two are resolved together from the event payload, because neither GITHUB_REF nor GITHUB_REF_NAME identifies the right branch for every event — a pull request reports refs/pull/<number>/merge, and workflow_run reports the repository's default branch rather than the branch that failed:

Event	Resolved from
pull_request, pull_request_target	event.pull_request.head
workflow_run	event.workflow_run.head_branch and head_repository
everything else	the GITHUB_REF_NAME environment variable

Use {{refUrl}} rather than interpolating {{refName}} into a URL yourself. refName is display text and is not URL-encoded, and for a pull request from a fork it names a branch that does not exist in your repository.

Note

refName was previously called refname (no capitalization). refname is deprecated and will be removed in a future major version.Using {{refname}} logs a warning on the workflow run.

If you need to inject data that isn't available from the context object within the Javascript, you can also use the GitHub Actions expressions and workflow run context to generate the strings that you pass to this action as a title or body template.

Comments vs. new issues

By default, the action adds a comment to the most recently created open issue labeled build failed. If there is no such issue, it opens a new one with that label. This assumes only one such issue is open at a time (true as long as this action is the only thing creating them) and that a still-open issue means the new failure shares the same underlying cause as the earlier one.

If you would like to always create a new issue, set the parameter always-create-new-issue to true.

If you are sticking with the default behavior of appending a comment, but you have a particular case where you don't want it to append a comment and instead open a new issue, you can remove the build failed label from the open issue(s). One situation where you might want to do this is if you've temporarily fixed the cause of a failure, but you want to keep the issue open to track additional to-dos.

Using with GitHub Projects

GitHub Projects is a work planning tool in GitHub that provides additional ways to view and interact with issues and pull requests across repos. Since this action just creates or interacts with issues, you can use GitHub Projects to manage those issues like any other issue.

One common requirement may be to automatically add issues created by this action to a GitHub Project. You can use the built-in auto-add workflow with the build failed label (or whatever label you've configured) to accomplish this.