> ## Documentation Index
> Fetch the complete documentation index at: https://www.bugzy.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# CI/CD

> Trigger Bugzy tasks and send test results from CI/CD pipelines, deployment hooks, and scheduled runs.

Bugzy integrates into your CI/CD workflows through API triggers, webhook events, GitHub deployment events, and scheduled task runs. This lets you automate test execution and failure triage as part of your deployment pipeline.

## Prerequisites

Before integrating with your CI/CD pipeline, you need a **project API key**:

1. Go to **Dashboard > Project Settings > API Keys**
2. Click **Generate API Key**
3. Copy the key immediately -- it's only shown once
4. Store it as a CI secret (e.g., `BUGZY_API_KEY`)

See the [Authentication guide](/docs/api-reference/authentication) for details on key types and rate limits.

## Trigger methods

| Method                   | Use case                                   | Endpoint                                     |
| ------------------------ | ------------------------------------------ | -------------------------------------------- |
| API call                 | Trigger tasks from any CI system           | `POST /api/v1/projects/{id}/executions`      |
| Send test results        | Forward CI test output to Bugzy for triage | `POST /api/v1/projects/{id}/webhooks/events` |
| GitHub deployment events | Post-deploy verification                   | Dashboard event triggers                     |
| Scheduled runs           | Nightly regression, periodic smoke tests   | Dashboard schedule configuration             |
| GitHub webhook events    | Test on push or PR                         | Dashboard event triggers                     |

## API trigger

Trigger any Bugzy task programmatically from your CI/CD pipeline:

```bash theme={null}
curl -X POST https://app.bugzy.ai/api/v1/projects/{projectId}/executions \
  -H "Authorization: Bearer $BUGZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskSlug": "run-tests",
    "parameters": {"target": "staging"}
  }'
```

### Response

```json theme={null}
{
  "data": {
    "executionId": "exec_abc123",
    "taskSlug": "run-tests",
    "status": "queued"
  }
}
```

The task executes asynchronously. Use the execution ID to poll for status via `GET /api/v1/projects/{projectId}/executions/{executionId}`, or configure notifications via Slack/Teams to receive results.

## Send test results to Bugzy

If you run tests in your own CI pipeline (Playwright, Cypress, Jest, pytest, etc.), you can forward the results to Bugzy for AI-powered triage. Bugzy analyzes failures, identifies flaky tests, and can file bugs automatically.

### Endpoint

```
POST /api/v1/projects/{projectId}/webhooks/events
```

### Example

```bash theme={null}
curl -X POST https://app.bugzy.ai/api/v1/projects/{projectId}/webhooks/events \
  -H "Authorization: Bearer $BUGZY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "test_results.received",
    "results": {
      "framework": "playwright",
      "total": 142,
      "passed": 138,
      "failed": 3,
      "skipped": 1,
      "failures": [
        {
          "test": "checkout flow > applies discount code",
          "error": "TimeoutError: locator.click: Timeout 30000ms exceeded",
          "file": "tests/checkout.spec.ts"
        }
      ]
    },
    "metadata": {
      "ci_pipeline_url": "https://github.com/org/repo/actions/runs/123",
      "commit_sha": "abc123",
      "branch": "main"
    }
  }'
```

### Response

```json theme={null}
{
  "data": {
    "accepted": true,
    "executionId": "exec_def456",
    "taskSlug": "triage-results"
  }
}
```

<Note>
  The `results` field accepts any JSON structure. Bugzy's triage agent parses common formats including Playwright JSON reporter output, Jest JSON, JUnit XML converted to JSON, and pytest JSON. Include as much detail as available -- test names, error messages, stack traces, and file paths help the agent produce better analysis.
</Note>

## GitHub Actions

### Run tests on PR

```yaml theme={null}
name: Bugzy Tests
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  bugzy-tests:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Bugzy test run
        run: |
          curl -X POST https://app.bugzy.ai/api/v1/projects/${{ secrets.BUGZY_PROJECT_ID }}/executions \
            -H "Authorization: Bearer ${{ secrets.BUGZY_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"taskSlug": "run-tests", "parameters": {"branch": "${{ github.head_ref }}"}}'
```

### Post-deploy smoke tests

```yaml theme={null}
name: Post-Deploy Verification
on:
  deployment_status:
    types: [completed]

jobs:
  verify:
    if: github.event.deployment_status.state == 'success'
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Bugzy verification
        run: |
          curl -X POST https://app.bugzy.ai/api/v1/projects/${{ secrets.BUGZY_PROJECT_ID }}/executions \
            -H "Authorization: Bearer ${{ secrets.BUGZY_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"taskSlug": "verify-changes", "parameters": {"environment": "staging", "url": "${{ github.event.deployment.payload.url }}"}}'
```

### Forward test results

Run your own tests in CI, then send the results to Bugzy for triage:

```yaml theme={null}
name: Tests with Bugzy Triage
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: npx playwright test --reporter=json > test-results.json
        continue-on-error: true

      - name: Send results to Bugzy
        if: always()
        run: |
          curl -X POST https://app.bugzy.ai/api/v1/projects/${{ secrets.BUGZY_PROJECT_ID }}/webhooks/events \
            -H "Authorization: Bearer ${{ secrets.BUGZY_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d "{
              \"event_type\": \"test_results.received\",
              \"results\": $(cat test-results.json),
              \"metadata\": {
                \"ci_pipeline_url\": \"${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\",
                \"commit_sha\": \"${{ github.sha }}\",
                \"branch\": \"${{ github.ref_name }}\"
              }
            }"
```

## Deployment hooks

GitHub deployment events are processed automatically when you configure event triggers in the dashboard:

1. Go to **Dashboard > Projects > \[Your Project] > Event Triggers**
2. Map `deployment_status` events to a Bugzy task (e.g., `verify-changes` or `run-tests`)
3. When a deployment succeeds, Bugzy receives the webhook and executes the mapped task

This works with any deployment tool that creates GitHub deployments (Vercel, Netlify, AWS, custom pipelines).

## Scheduled runs

Configure recurring test execution from the dashboard:

<Steps>
  <Step title="Open task schedule">
    Go to **Dashboard > Projects > \[Your Project] > Schedules**.
  </Step>

  <Step title="Create schedule">
    Select a task, set the cron expression, and configure parameters.
  </Step>

  <Step title="Activate">
    Enable the schedule. Bugzy will execute the task at the specified intervals.
  </Step>
</Steps>

### Common schedules

| Schedule               | Cron        | Task                 | Purpose                                    |
| ---------------------- | ----------- | -------------------- | ------------------------------------------ |
| Nightly regression     | `0 2 * * *` | `run-tests`          | Full test suite against staging            |
| Hourly smoke           | `0 * * * *` | `run-tests`          | Critical path smoke tests on production    |
| Weekly test generation | `0 9 * * 1` | `generate-test-plan` | Refresh test plans based on recent changes |

## Event trigger mapping

The event trigger system maps incoming webhook events to agent tasks:

| Source event            | Agent task       | Outcome                         |
| ----------------------- | ---------------- | ------------------------------- |
| Push to `main`          | `run-tests`      | Regression tests on latest code |
| PR opened/updated       | `run-tests`      | Targeted tests for PR changes   |
| Deployment succeeded    | `verify-changes` | Post-deploy verification        |
| `test_results.received` | `triage-results` | AI-powered failure triage       |
| Jira "Ready for QA"     | `verify-changes` | Re-test after bug fix           |

Configure mappings in **Dashboard > Event Triggers** with optional filters for branch patterns, file paths, or labels.

## Troubleshooting

**API calls returning 401** -- Verify your `BUGZY_API_KEY` is valid and has access to the target project. Keys can be regenerated in **Dashboard > Project Settings > API Keys**.

**Tasks not triggering on deployment** -- Check that event triggers are configured in the dashboard and the deployment creates a GitHub deployment event (not all CI tools do this by default).

**Webhook events returning 404** -- Verify the `event_type` value matches a configured trigger. The default mapping recognizes `test_results.received`. For custom event types, configure a trigger in **Dashboard > Event Triggers**.

**Scheduled runs not executing** -- Verify the schedule is enabled in the dashboard and the cron expression is correct.