Fix GitHub Actions Workflow Trigger For PR Linter

Nov 14, 2025 by Alex Johnson 50 views

PR Linter Workflow Trigger Issue: Seamless Integration with CodeBuild

The Problem: When the PR Linter Didn't Do Its Job

Sometimes, even in the most streamlined development processes, things don't go exactly as planned. We encountered a peculiar issue where our PR Linter workflow, designed to automatically check code quality for pull requests, failed to trigger correctly after a crucial step: the completion of the "Codebuild PR Build." This workflow is set up to be initiated via a workflow_run event, which means it should kick off automatically once the preceding Codebuild job finishes successfully. However, for a specific pull request, PR #36049, this vital automation faltered. The workflow_run event did fire, signaling that Codebuild was done, but the PR Linter immediately stalled. The core reason? It couldn't figure out which pull request needed its attention.

This is a significant hurdle because the PR Linter acts as a gatekeeper, ensuring that only code meeting our standards gets merged. When it doesn't run, we risk bypassing essential quality checks, potentially leading to bugs or style inconsistencies down the line. The expected behavior is a smooth, automatic handoff from Codebuild to the PR Linter, creating a continuous flow of quality assurance. The current behavior, unfortunately, breaks this chain, leaving us with a non-functional linter when it's triggered by Codebuild. This article delves into the nitty-gritty of why this happened and, more importantly, how we've put a stop to it.

Unpacking the Failure: Missing Artifacts and Empty Arrays

The root cause of the PR Linter's failure lies in a missing piece of information: the pr_info artifact. The PR Linter workflow is designed to download this specific artifact, which contains essential details like the PR number and its associated commit SHA. This information is crucial for the linter to accurately identify and validate the correct pull request. When the "Codebuild PR Build" workflow completes, it should be uploading this pr_info artifact. However, in the case of PR #36049, this step was conspicuously absent.

Let's break down the technical details of this disconnect. First, consider how the PR Linter expects to receive its information. It uses an action called dawidd6/action-download-artifact@v11. This action attempts to download an artifact named pr_info from the completed workflow_run. If this artifact isn't found, the linter has a fallback mechanism: it tries to derive the PR number directly from the github.event.workflow_run.pull_requests array. This array is supposed to contain details about the pull request associated with the workflow run.

Now, here's where the "Codebuild PR Build" workflow falls short. It lacks the necessary steps to create and upload the pr_info artifact. Specifically, it doesn't include a step to save the PR number and SHA into files within a pr/ directory and then upload that directory as the pr_info artifact. This omission is the primary culprit.

Furthermore, we discovered a subtle yet critical limitation within GitHub Actions itself. When a workflow is triggered by the pull_request event (as opposed to pull_request_target), and it's operating within the same repository (not a fork), the github.event.workflow_run.pull_requests array is empty. This means the fallback mechanism, which is intended to save the day when the artifact is missing, actually fails even harder. Instead of finding a PR number, it finds null because the array is empty. The script then attempts to echo null, creating an invalid or empty pr_number file. Consequently, the PR Linter job cannot determine the PR number, leading to its immediate failure. This chain reaction of missing artifacts and empty event data created the perfect storm for our workflow interruption.

Why Other Triggers Work: A Tale of Two Workflows

It's natural to wonder why, if the PR Linter fails when triggered by Codebuild, it succeeds when triggered by other events, such as a pull request review. The key difference lies in the triggering mechanism and the information available at that precise moment. The "PR Linter Trigger" workflow, for instance, operates under the pull_request_review event. This event provides the workflow with direct access to detailed PR information, including the PR number and SHA, which are then promptly saved and uploaded as the pr_info artifact.

Let's examine the "PR Linter Trigger" workflow (.github/workflows/pr-linter-review-trigger.yml) more closely. Its on: clause specifies pull_request_review with types like submitted, edited, and dismissed. When one of these events occurs, the trigger job in this workflow executes. Within this job, the first step is to save the PR number and SHA by creating files in a ./pr directory: echo ${{ github.event.pull_request.number }} > ./pr/pr_number and echo ${{ github.event.pull_request.head.sha }} > ./pr/pr_sha. Immediately following this, the actions/upload-artifact@v5 action is used to upload the contents of the ./pr directory as the pr_info artifact. Because the pull_request_review event provides the necessary github.event.pull_request context, this process is seamless and reliable. The PR Linter, when triggered by a review, always receives the required pr_info artifact and functions as expected.

Contrast this with the workflow_run event triggered by Codebuild. The workflow_run event fires after another workflow has completed. While it contains information about the run itself, the context provided by the pull_request event (which Codebuild uses) is not directly available or is structured differently in the workflow_run context, especially concerning the pull_requests array. As we discussed, this array is empty under certain conditions. Therefore, the Codebuild workflow must explicitly capture the PR details before it finishes and upload them as an artifact for any downstream workflow (like the PR Linter) to consume. The absence of this explicit artifact upload step in the "Codebuild PR Build" workflow is precisely why it fails to provide the necessary pr_info for the PR Linter when using the workflow_run trigger. This highlights how critically dependent the workflow_run event is on the upstream workflow to package and pass along any required contextual data.

The Evidence of Failure: A Run Gone Wrong

To truly understand the problem, let's look at the concrete evidence from our GitHub Actions logs. On one occasion, a run-triggered PR Linter execution did indeed occur. This was run #19344816945, initiated at 20:24:28. However, this run was associated with the main branch rather than a specific PR and, critically, it FAILED. The failure wasn't subtle; it was evident right from the start.

The job responsible for fetching artifacts, download-if-workflow-run, encountered an issue. While the step to "Download workflow_run artifact" reported success (meaning it tried and didn't error out immediately), the subsequent step, "Determine PR info," failed catastrophically. This step is where the workflow attempts to get the PR number, either from the downloaded artifact or via the fallback mechanism. Since the pr_info artifact was missing from the Codebuild run, and the workflow_run.pull_requests array was empty (as explained earlier), this step couldn't find any valid PR information. It failed because it couldn't determine which PR to validate.

Following the failure of download-if-workflow-run, the next job in the sequence, validate-pr, was automatically SKIPPED. This is expected behavior in GitHub Actions; if a dependency job fails, subsequent jobs that rely on it are often skipped to prevent further errors or wasted computation. The log snippet clearly shows:

Job: download-if-workflow-run
- ✓ Download workflow_run artifact (success)
- ✗ Determine PR info (FAILURE)
Job: validate-pr
- (SKIPPED - dependency failed)

This sequence of events provides undeniable proof that the PR Linter, when triggered by the workflow_run event from Codebuild, cannot proceed because it lacks the essential PR identification data. The failure isn't in the linter's logic itself, but in the preceding Codebuild workflow's inability to provide the necessary input. This empirical evidence confirms our diagnosis of the missing artifact problem.

The Solution: Equipping Codebuild for Success

Fortunately, the fix for this issue is straightforward and involves augmenting the "Codebuild PR Build" workflow. The core problem, as we've identified, is that this workflow doesn't create or upload the pr_info artifact that the PR Linter workflow relies upon. By adding a few simple steps, we can ensure that the necessary information is packaged and passed along, enabling the PR Linter to function correctly after Codebuild completes.

The proposed solution involves modifying the .github/workflows/codebuild-pr-build.yml file. Specifically, within the build job's steps, we need to add two new steps. These steps should only execute when the workflow is triggered by a pull_request event, ensuring they don't interfere with other types of runs. The first new step will be responsible for saving the PR details. It will create a directory named pr/ if it doesn't already exist and then write the current PR number (${{ github.event.pull_request.number }}) and the commit SHA (${{ github.event.pull_request.head.sha }}) into two separate files, pr/pr_number and pr/pr_sha, respectively. This step captures the critical context that the downstream PR Linter needs.

      - name: Save PR info for PR Linter
        if: github.event_name == 'pull_request'
        run: |
          mkdir -p ./pr
          echo ${{ github.event.pull_request.number }} > ./pr/pr_number
          echo ${{ github.event.pull_request.head.sha }} > ./pr/pr_sha

The second new step will use the actions/upload-artifact@v5 action to upload the contents of the ./pr directory. This directory will be named pr_info, matching exactly what the PR Linter workflow expects to download. This ensures that the artifact containing the PR number and SHA is persisted and made available for the workflow_run event to pick up.

      - name: Upload PR info artifact
        if: github.event_name == 'pull_request'
        uses: actions/upload-artifact@v5
        with:
          name: pr_info
          path: pr/

By incorporating these two steps into the "Codebuild PR Build" workflow, we bridge the gap. When Codebuild completes, it will now reliably upload the pr_info artifact. The subsequent PR Linter workflow, triggered by workflow_run, will be able to download this artifact, retrieve the PR number, and perform its validation checks without issue. This simple addition ensures the integrity of our automated code quality pipeline, making sure the PR Linter is always ready to do its job, regardless of how it's triggered.

Timeline of Events and Root Cause Clarification

To provide a clear picture of the issue's progression, let's trace the events chronologically. Understanding the sequence helps solidify the root cause and the effectiveness of the implemented solution. The timeline begins with the opening of PR #36049.

18:53:15 - PR #36049 opened: This marks the start of the process that would eventually expose the workflow issue.
18:53:19 - PR Linter run #19342493014 (pull_request_target) ✓ SUCCESS: It's important to note that the PR Linter did run successfully initially. This is likely because it was triggered by a pull_request_target event, which provides a different context and potentially different information availability compared to a pull_request event or a workflow_run event. This indicates the linter itself is functional.
18:53:20 - Codebuild PR Build #19342493369 started: The automated build process using Codebuild begins.
20:24:25 - Codebuild PR Build COMPLETED ✓ SUCCESS: The Codebuild job finishes successfully. This is the moment when the workflow_run event is supposed to be triggered for the PR Linter.
20:24:28 - PR Linter run #19344816945 (workflow_run) ✗ FAILED: As expected, the PR Linter workflow attempts to run, triggered by the completion of the Codebuild build. However, it fails shortly after.
- └─ download-if-workflow-run job FAILED: The specific job within the PR Linter workflow responsible for getting necessary data fails.
- └─ "Determine PR info" step FAILED: Within that job, the step designed to identify the PR number fails. This is where the lack of the pr_info artifact and the empty pull_requests array in the workflow_run event context come into play, preventing the workflow from knowing which PR to validate.

This detailed timeline confirms that the failure occurred specifically during the transition from the "Codebuild PR Build" workflow to the "PR Linter" workflow via the workflow_run event. The root cause is definitively the "Codebuild PR Build" workflow's failure to upload the pr_info artifact, which the "PR Linter" workflow requires when triggered in this manner. The solution directly addresses this by ensuring the artifact is created and uploaded, thereby fixing this specific failure point in our CI/CD pipeline.

For more insights into GitHub Actions and workflow automation, you can refer to the official GitHub Actions Documentation. Understanding these workflows is key to maintaining robust and efficient development processes.