GitHub Automation

This is the supported GitHub automation path for DebugBundle.

Before you start:

1. Open the Project GitHub tab in the DebugBundle web app.
2. Connect the GitHub App installation and assign a primary repository.
3. Create at least one GitHub automation rule, either in the web app or with debugbundle github rules create.
4. Add a DEBUGBUNDLE_TOKEN secret to the repository so workflows can fetch the full bundle and reproduction.

What DebugBundle sends

DebugBundle sends a GitHub repository_dispatch event into the assigned repository. The dispatch event_type is always debugbundle.incident, so the repository must contain a workflow that listens for:

on:
  repository_dispatch:
    types: [debugbundle.incident]

The dispatch payload is intentionally small. It includes target summary fields such as incident_id, improvement_id, debugbundle_event, bundle_type, severity, title, and retrieval links. Delivery metadata such as dispatch_id, project_id, and dispatched_at lives under github.event.client_payload.debugbundle.

For incident dispatches, incident_id is set and debugbundle/action@v1 can fetch the incident bundle and reproduction. For hosted improvement dispatches, incident_id is null, improvement_id is set, bundle_type is improvement, and links.bundle points at the hosted improvement bundle route while links.reproduction is null. Repository workflows that subscribe to improvement_bundle.created should branch on github.event.client_payload.bundle_type or debugbundle_event and fetch the improvement bundle from links.bundle with a DebugBundle member token. Incident-backed improvement opportunities do not emit this event because they reuse the related incident bundles.

DebugBundle delivery status means GitHub accepted or rejected the repository_dispatch API call. A delivered record with GitHub status 204 proves GitHub accepted the dispatch, but it does not prove a GitHub Actions workflow completed. The receiving repository still owns the workflow file, run result, issue creation, agent invocation, and any follow-up policy.

After an incident workflow starts, fetch the full context with debugbundle/action@v1. Improvement workflows can use the same dispatch trigger and fetch the improvement bundle from the payload link.

Basic GitHub Triage Workflow

Use this when the repository only needs to print or route incident information.

name: DebugBundle Basic Triage

on:
  repository_dispatch:
    types: [debugbundle.incident]

jobs:
  triage:
    runs-on: ubuntu-latest
    permissions:
      contents: read
    steps:
      - uses: actions/checkout@v4

      - name: Fetch DebugBundle context
        uses: debugbundle/action@v1
        with:
          incident-id: ${{ github.event.client_payload.incident_id }}
          debugbundle-token: ${{ secrets.DEBUGBUNDLE_TOKEN }}

      - name: Print the dispatch summary
        run: |
          echo "Title: ${{ github.event.client_payload.title }}"
          echo "Severity: ${{ github.event.client_payload.severity }}"
          echo "Bundle path: .debugbundle/bundles/cloud/${{ github.event.client_payload.incident_id }}.bundle.json"

Use the checked-in example at examples/github-actions/basic.yml if you want a ready-made starting point.

Agent-Capable Workflow

Use this when the repository will hand the fetched bundle to a coding agent, internal script, or reusable workflow.

name: DebugBundle Agent-Capable Workflow

on:
  repository_dispatch:
    types: [debugbundle.incident]

jobs:
  investigate:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Fetch DebugBundle context
        id: debugbundle
        uses: debugbundle/action@v1
        with:
          incident-id: ${{ github.event.client_payload.incident_id }}
          debugbundle-token: ${{ secrets.DEBUGBUNDLE_TOKEN }}

      - name: Invoke repository-owned automation
        run: |
          echo "Bundle path: ${{ steps.debugbundle.outputs.bundle-path }}"
          echo "Reproduction path: ${{ steps.debugbundle.outputs.reproduction-path }}"
          echo "Run your coding agent or reusable workflow here."

Use the checked-in example at examples/github-actions/agent-capable.yml when you want the workflow skeleton without coupling DebugBundle to a specific agent runtime.

Issue Creation Workflow

Use this when the repository wants a low-friction first automation outcome: create a tracking issue from the dispatch payload and bundle links.

name: DebugBundle Issue Creation Workflow

on:
  repository_dispatch:
    types: [debugbundle.incident]

jobs:
  create-issue:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - uses: actions/checkout@v4

      - name: Fetch DebugBundle context
        uses: debugbundle/action@v1
        with:
          incident-id: ${{ github.event.client_payload.incident_id }}
          debugbundle-token: ${{ secrets.DEBUGBUNDLE_TOKEN }}

      - name: Open a tracking issue
        uses: actions/github-script@v7
        with:
          script: |
            const payload = context.payload.client_payload;

            await github.rest.issues.create({
              owner: context.repo.owner,
              repo: context.repo.repo,
              title: `[debugbundle] ${payload.severity}: ${payload.title}`,
              body: [
                `Incident: ${payload.incident_id}`,
                `Bundle: ${payload.links.bundle}`,
                `Reproduction: ${payload.links.reproduction}`,
              ].join('\n'),
            });

Use the checked-in example at examples/github-actions/issue-creation.yml if you want a minimal repository-owned follow-up policy.

Operational notes

• repository_dispatch is the only supported GitHub trigger for this integration.
• DebugBundle owns repo connection, rule evaluation, delivery history, and retry.
• DebugBundle delivery history tracks GitHub dispatch acceptance. Check GitHub Actions for workflow run status and logs.
• Your repository owns everything after the workflow starts: issue creation, agent invocation, PR creation, and triage policy.
• Full bundle JSON is not embedded in the dispatch payload. Incident workflows can fetch it on demand with debugbundle/action@v1; hosted improvement workflows can fetch github.event.client_payload.links.bundle with a DebugBundle member token.
• The fetch step uses the separately published debugbundle/action@v1; the core repo only keeps the example workflow YAML files.

Validate the automation path

Use this loop when you want to prove a new repository connection before keeping permanent automation in place.

1. Add a temporary workflow that listens for repository_dispatch with types: [debugbundle.incident].
2. Trigger one controlled high-severity incident or hosted improvement bundle that matches a GitHub dispatch rule.
3. Open the project GitHub tab or run debugbundle github deliveries --project-id <project-id>.
4. Confirm the latest delivery is delivered with GitHub status 204.
5. Open the repository's Actions tab and confirm the temporary workflow run completed.
6. Resolve the intentional incident and remove the temporary workflow.

CLI parity

# Inspect the connected repository and installation state
debugbundle github status --project-id proj_123

# Review existing automation rules
debugbundle github rules --project-id proj_123

# Review recent deliveries and retry failures when needed
debugbundle github deliveries --project-id proj_123
debugbundle github deliveries retry del_123 --project-id proj_123

Next Steps

• Agent Skill File — How agents discover DebugBundle
• MCP Workflows — MCP-specific agent patterns
• Webhook Events — Lifecycle events that feed GitHub automation rules
• Pricing — GitHub automation is available on Solo and Team