Free audit

Docs

Connect GitHub

Install the WitnessQA GitHub App on the repositories you want. When an issue is opened or closed, the agent reads its acceptance criteria, checks them in your app and reports pass or fail with a screenshot of every step.

Before you start

  • A WitnessQA project with at least one environment. See Getting started.
  • Admin rights on the GitHub account or organization, or an admin who can approve the install.
  • A staging URL is recommended. See Safety.

What WitnessQA can access

WitnessQA never asks for access to your code. It only reads issues.

PermissionAccessWhy
MetadataReadRequired by GitHub for every app. Lists repository names.
IssuesReadReads the title, description and acceptance criteria.
IssuesRead and write (optional)Posts the result as a comment. GitHub has no comment-only permission, so this also allows editing issues. WitnessQA only adds comments. Skip it to keep results in the dashboard only.
Contents (code)NoneNever requested.

Connect in six steps

  1. Open Integrations and click Connect GitHub

    In your project, open Integrations. Choose whether WitnessQA may post results as comments, then click Connect next to GitHub. A GitHub page opens in the same tab.

    Choose comments or read only, then click Connect.

  2. Choose the account and repositories

    Pick your user or organization. Choose Only select repositories and select the ones you want WitnessQA to watch. You can add more later.

    Install the app on selected repositories only.

  3. Review the permissions and install

    GitHub shows the exact permissions before anything is installed. Check that they are read access to issues and metadata, plus write access to issues if you want comments. Click Install.

    GitHub lists the permissions. There is no access to code.

    Read only? Untick Post results as comments in step 1. GitHub then asks only for read access to issues, and nothing is ever posted to GitHub.

  4. Choose when runs start

    Back in WitnessQA, pick the triggers. By default a run starts when an issue is opened and again when it is closed. You can limit runs to issues with a label, for example witnessqa.

    Pick the triggers and an optional label filter.

  5. Map each repository to an environment

    Tell WitnessQA which URL to test for each repository. Staging is selected by default.

    Each repository runs against one environment.

  6. Write acceptance criteria and read the result

    Add an Acceptance criteria section with a checklist to the issue. Each item becomes one check. When the run finishes, the result appears as a comment on the issue and in the dashboard. 

    ## Acceptance criteria

- [ ] The pricing page has a Monthly / Annual toggle
- [ ] Annual shows $290/yr and "2 months free"
- [ ] Checkout charges the annual amount
    The result comment: one line per criterion, with screenshots and a link to the full run.

Writing good acceptance criteria

  • One observable result per item: what a user sees or can do.
  • Use exact text and numbers when they matter, like $290/yr.
  • No criteria found? The agent writes its own from the description and marks them as suggested in the result.

Troubleshooting

  • No run started. Check that the repository is selected in the GitHub install and mapped to an environment, and that the issue has the label if you set one.
  • No comment on the issue. The app has read access only, or write access was not approved. The result is still in the dashboard.
  • Run failed at login. Check the login option for that environment.

Disconnect

Click Disconnect on the GitHub integration in WitnessQA, or uninstall the app in GitHub under Settings → Applications → Installed GitHub Apps (for an organization: Organization settings → GitHub Apps). Past runs stay in the dashboard until your plan's retention ends.