Skip to main content
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

1

Navigate to connections

Go to Dashboard > Projects > [Your Project] > Connections.
2

Connect GitHub

Click Connect GitHub. This opens the GitHub OAuth flow managed by Nango.
3

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

Configure webhook events

After connecting, configure which GitHub events should trigger Bugzy tasks. This is done in Dashboard > Projects > [Your Project] > Event Triggers.
No manual token or webhook URL configuration is needed. The OAuth flow provisions all credentials automatically.

​
Webhook events

Bugzy receives GitHub webhook events at: 
https://app.bugzy.ai/api/webhook/events?provider=github

​
Supported events

EventTriggerTypical agent task
pushCode pushed to a branchRun smoke tests on changed areas
pull_requestPR opened, updated, or mergedRun tests on the PR branch, post results as PR comment
deploymentDeployment status changePost-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:
PermissionAccessPurpose
Repository contentsRead & WriteRead code, commit test artifacts
Pull requestsRead & WriteCreate PRs, post comments
IssuesRead & WriteTrack test-related issues
WebhooksRead & WriteReceive push, PR, deployment events
MetadataRead-onlyRepository metadata
DeploymentsRead-onlyDeployment status events

​
Troubleshooting

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