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

# GitHub

> Automatically run tests on deployments with GitHub App integration

Connect Bugster to your GitHub repository to automatically run tests on pull requests and preview deployments.

## What It Enables

<CardGroup cols={2}>
  <Card title="Automated Testing" icon="robot">
    Tests run automatically on every pull request
  </Card>

  <Card title="Preview Testing" icon="eye">
    Tests against preview deployments from any platform
  </Card>

  <Card title="PR Status Checks" icon="code-pull-request">
    Pass/fail status reported directly in GitHub
  </Card>

  <Card title="Team Visibility" icon="users">
    Results visible to all team members
  </Card>
</CardGroup>

## Installation

<Steps>
  <Step title="Access GitHub Integration">
    Visit [Bugster Dashboard](https://app.bugster.dev) → Your Project → GitHub Integration
  </Step>

  <Step title="Install GitHub App">
    Click **"Connect Organization"** and authorize the Bugster GitHub App
  </Step>

  <Step title="Select Repository">
    Choose the repository you want to integrate with Bugster
  </Step>

  <Step title="Commit Configuration">
    Add your `.bugster/` folder to the repository:

    ```bash theme={null}
    git add .bugster/
    git commit -m "Add Bugster CLI configuration"
    git push origin main
    ```
  </Step>
</Steps>

## Platform Setup

<Tabs>
  <Tab title="Vercel" icon="triangle">
    <Steps>
      <Step title="Enable Preview Access">
        Configure Vercel protection bypass for automated testing access
      </Step>

      <Step title="Configure Environment Variables">
        Ensure your preview deployments have the necessary environment variables for testing
      </Step>
    </Steps>

    <Card title="Vercel Setup Guide" icon="triangle" href="/integrations/vercel">
      Detailed Vercel configuration and protection bypass setup
    </Card>
  </Tab>

  <Tab title="Railway" icon="train">
    <Steps>
      <Step title="Configure Preview Deployments">
        Ensure Railway preview deployments are enabled for your project
      </Step>

      <Step title="Set Environment Variables">
        Configure necessary environment variables for your Railway previews
      </Step>
    </Steps>

    <Card title="Railway Setup Guide" icon="train" href="/integrations/railway">
      Complete Railway integration and deployment configuration
    </Card>
  </Tab>

  <Tab title="Netlify" icon="globe">
    <Steps>
      <Step title="Configure Webhook Notifications">
        Set up Netlify webhook notifications for deployment events
      </Step>

      <Step title="Add Bugster Webhook URL">
        Configure the webhook URL from your Bugster project settings
      </Step>
    </Steps>

    <Card title="Netlify Setup Guide" icon="globe" href="/integrations/netlify">
      Complete Netlify integration with webhook configuration
    </Card>
  </Tab>

  <Tab title="GitHub Actions" icon="code-merge">
    <Steps>
      <Step title="Add Bugster API Key to Secrets">
        Store your Bugster API key in GitHub repository secrets
      </Step>

      <Step title="Configure Workflow">
        Add the Bugster GitHub Action to your workflow file
      </Step>
    </Steps>

    <Card title="GitHub Actions Setup Guide" icon="code-merge" href="/integrations/github-actions">
      Complete GitHub Actions integration with official Bugster action
    </Card>
  </Tab>

  <Tab title="GCP Cloud Build" icon="box">
    <Steps>
      <Step title="Add Webhook Step">
        Include Bugster webhook step in your cloudbuild.yaml
      </Step>

      <Step title="Configure Substitution Variables">
        Set up Bugster credentials in Cloud Build trigger settings
      </Step>
    </Steps>

    <Card title="Cloud Build Setup Guide" icon="box" href="/integrations/cloud-build">
      Complete GCP Cloud Build integration with webhook configuration
    </Card>
  </Tab>

  <Tab title="Custom Platform" icon="cubes">
    <Steps>
      <Step title="Get API Credentials">
        Collect your Bugster API key, project ID, and organization ID
      </Step>

      <Step title="Add Webhook to Pipeline">
        Call Bugster webhook API after successful deployment
      </Step>
    </Steps>

    <Card title="Custom Integration Guide" icon="cubes" href="/integrations/custom">
      Complete custom integration using Bugster webhook API
    </Card>
  </Tab>
</Tabs>

## How It Works

### Pull Request Workflow

1. **PR Created** → GitHub notifies Bugster
2. **Preview Deployed** → Platform creates preview URL
3. **Tests Execute** → Bugster runs tests against preview
4. **Results Reported** → Status check appears in GitHub PR

### Test Execution

<AccordionGroup>
  <Accordion title="Automatic Triggers" icon="zap">
    **New Pull Request**: Full test suite execution

    **Push to PR Branch**: Affected tests only (smart detection)

    **Preview URL Ready**: Tests run against latest deployment
  </Accordion>

  <Accordion title="Test Selection" icon="filter">
    **Affected Tests**: Only tests related to changed files

    **Always-Run Tests**: Critical tests that always execute

    **Smart Limits**: Respects configured test limits
  </Accordion>
</AccordionGroup>

## GitHub Status Checks

Results appear as status checks in your pull requests:

### Status Types

<CardGroup cols={3}>
  <Card title="Passed" icon="check" color="#green">
    All tests passed successfully
  </Card>

  <Card title="Failed" icon="x" color="#red">
    One or more tests failed
  </Card>

  <Card title="Pending" icon="clock" color="#yellow">
    Tests are currently running
  </Card>
</CardGroup>

### Detailed Results

Click the status check to view:

* Individual test results
* Failure reasons and screenshots
* Execution videos for debugging
* Performance metrics and timing

## Troubleshooting

<AccordionGroup>
  <Accordion title="GitHub App not installed">
    **Issue**: No status checks appearing on PRs

    **Solution**: Reinstall the GitHub App with proper repository permissions
  </Accordion>

  <Accordion title="Tests not running on PRs">
    **Issue**: No test execution triggered

    **Solutions**:

    * Ensure `.bugster/` folder is committed to repository
    * Verify GitHub App has access to the correct repository
    * Check that preview deployments are working
  </Accordion>

  <Accordion title="Preview URL not accessible">
    **Issue**: Tests fail to connect to preview deployment

    **Solutions**:

    * Ensure deployment is complete and URL is publicly accessible
    * **Vercel**: Configure protection bypass correctly
    * **Railway**: Verify deployment settings and environment variables
    * **Netlify**: Check webhook configuration and deployment status
    * **GitHub Actions/Cloud Build/Custom**: Verify environment URL is accessible
    * Check that environment variables are properly configured
  </Accordion>
</AccordionGroup>

## Best Practices

<CardGroup cols={1}>
  <Card title="Repository Setup" icon="folder-open">
    **Commit configuration**: Always commit `.bugster/config.yaml` and test files

    **Branch protection**: Require Bugster status checks before merging

    **Environment consistency**: Match preview and production configurations
  </Card>

  <Card title="Team Workflow" icon="people-group">
    **PR testing**: Let tests complete before code review

    **Failure handling**: Investigate and fix test failures promptly

    **Test maintenance**: Keep tests updated with code changes
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={3}>
  <Card title="Vercel Setup" icon="triangle" href="/integrations/vercel">
    Complete Vercel integration and deployment configuration
  </Card>

  <Card title="Railway Setup" icon="train" href="/integrations/railway">
    Complete Railway integration and deployment configuration
  </Card>

  <Card title="Netlify Setup" icon="globe" href="/integrations/netlify">
    Complete Netlify integration with webhook configuration
  </Card>

  <Card title="GitHub Actions Setup" icon="code-merge" href="/integrations/github-actions">
    Use official GitHub Action for workflow integration
  </Card>

  <Card title="Cloud Build Setup" icon="box" href="/integrations/cloud-build">
    Integrate with GCP Cloud Build pipelines
  </Card>

  <Card title="Custom Integration" icon="cubes" href="/integrations/custom">
    Build custom integration with webhook API
  </Card>
</CardGroup>