> ## 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.

# GitHub

> Connect GitHub for repository access, webhook-driven test execution, and automated test artifact commits.

GitHub is Bugzy's primary source control integration. It provides repository access for test commits, webhook events for triggering automated tasks, and PR-level feedback.

## What GitHub enables

* **Repository access** — Bugzy reads your codebase and commits test artifacts (test plans, test cases, execution results) directly to your repo
* **Webhook events** — Push, pull request, and deployment events trigger agent tasks automatically
* **PR comments** — Test results and findings posted as PR comments for review
* **Repository scaffolding** — Bugzy creates the test infrastructure directory structure (`tests/`, `test-cases/`, `.bugzy/`) in your project repo

## Setup

<Steps>
  <Step title="Navigate to connections">
    Go to **Dashboard > Projects > \[Your Project] > Connections**.
  </Step>

  <Step title="Connect GitHub">
    Click **Connect GitHub**. This opens the GitHub OAuth flow managed by Nango.
  </Step>

  <Step title="Authorize and select repositories">
    Authorize the Bugzy GitHub App and select which repositories to grant access to. You can limit access to specific repos or grant organization-wide access.
  </Step>

  <Step title="Configure webhook events">
    After connecting, configure which GitHub events should trigger Bugzy tasks. This is done in **Dashboard > Projects > \[Your Project] > Event Triggers**.
  </Step>
</Steps>

<Info>
  No manual token or webhook URL configuration is needed. The OAuth flow provisions all credentials automatically.
</Info>

## Webhook events

Bugzy receives GitHub webhook events at:

```
https://app.bugzy.ai/api/webhook/events?provider=github
```

### Supported events

| Event          | Trigger                       | Typical agent task                                     |
| -------------- | ----------------------------- | ------------------------------------------------------ |
| `push`         | Code pushed to a branch       | Run smoke tests on changed areas                       |
| `pull_request` | PR opened, updated, or merged | Run tests on the PR branch, post results as PR comment |
| `deployment`   | Deployment status change      | Post-deploy verification against staging/production    |

### Event trigger configuration

In **Dashboard > Event Triggers**, map GitHub events to specific agent tasks:

* **Push to `main`** — Run full regression suite
* **PR opened/updated** — Run targeted tests for changed files
* **Deployment succeeded** — Run post-deploy smoke tests
* **Custom filters** — Filter by branch pattern, file paths, or labels

## How test commits work

After Bugzy generates or executes tests, it commits results back to your repository:

1. Bugzy runs the assigned task (generate test plan, execute tests, etc.)
2. Test artifacts are written to the project's directory structure
3. Bugzy commits changes to a branch (configurable: direct to `main`, feature branch, or PR)
4. If configured, a PR is opened with the test changes for team review

### Repository structure after scaffolding

```
your-project/
  .bugzy/           # Bugzy runtime configuration
  .claude/           # Claude Code config (commands, agents, MCP)
  tests/             # Playwright test files
  test-cases/        # Manual test case definitions
  test-plans/        # Generated test plans
  test-runs/         # Execution results
```

## GitHub App permissions

The Bugzy GitHub App requests the following permission scopes:

| Permission          | Access       | Purpose                             |
| ------------------- | ------------ | ----------------------------------- |
| Repository contents | Read & Write | Read code, commit test artifacts    |
| Pull requests       | Read & Write | Create PRs, post comments           |
| Issues              | Read & Write | Track test-related issues           |
| Webhooks            | Read & Write | Receive push, PR, deployment events |
| Metadata            | Read-only    | Repository metadata                 |
| Deployments         | Read-only    | Deployment status events            |

## Troubleshooting

<Warning>
  If Bugzy cannot commit to your repository, verify that the GitHub connection has write access to the target repo. You can check and update repository access in **Dashboard > Connections > GitHub**.
</Warning>

**Webhook events not triggering tasks** — Verify event triggers are configured in the dashboard. Check that the webhook URL is correctly registered in your GitHub App settings.

**Permission errors on commit** — The OAuth connection may need to be refreshed. Disconnect and reconnect GitHub from the project connections page.

**PR comments not appearing** — Ensure the GitHub App has pull request write permissions on the target repository.