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

# GitHub Actions

> Run clickproof tests on every pull request and block the merge when one fails.

The [`clickproof-ai/run-tests`](https://github.com/clickproof-ai/run-tests) Action
uploads your build, runs the project's tests on a real cloud device, and **exits
non-zero if any test fails** — so a broken flow blocks the merge, and each result
links to a full video report.

## 1. Create an API key

In the dashboard, go to **Integrations → GitHub** and create a key. Add it to your
repository as a secret named `CLICKPROOF_API_KEY`
(*Settings → Secrets and variables → Actions*).

<Warning>
  The key is shown only once. Copy it immediately — you can always revoke it and
  create a new one.
</Warning>

## 2. Add the workflow

Commit this as `.github/workflows/clickproof.yml`:

```yaml theme={null}
name: Mobile E2E
on: [pull_request]

jobs:
  clickproof:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      # …your own build step that produces an .apk or a simulator .app.zip…
      - run: ./gradlew assembleRelease

      - uses: clickproof-ai/run-tests@v1
        with:
          api-key: ${{ secrets.CLICKPROOF_API_KEY }}
          project: your-project-id
          build: app/build/outputs/apk/release/app-release.apk
```

The **Integrations → GitHub** page generates this snippet with your project id and
base URL already filled in.

## 3. See results in the PR

Each run writes a table to the job's **Summary** — every test with a ✅ / ❌ and a
link to its video report. Because a failing test exits non-zero, the check turns
red and blocks the merge.

<Frame>
  | Test run   | Status   | Report    |
  | ---------- | -------- | --------- |
  | `a1b2c3d4` | ✅ passed | [view](#) |
  | `e5f6a7b8` | ❌ failed | [view](#) |
</Frame>

## Options

Common tweaks — see the [Action reference](/ci-cd/action-reference) for all inputs.

<CodeGroup>
  ```yaml Run one test theme={null}
  - uses: clickproof-ai/run-tests@v1
    with:
      api-key: ${{ secrets.CLICKPROOF_API_KEY }}
      project: your-project-id
      build: app.apk
      test-id: your-test-id
  ```

  ```yaml Report only (never fail the job) theme={null}
  - uses: clickproof-ai/run-tests@v1
    with:
      api-key: ${{ secrets.CLICKPROOF_API_KEY }}
      project: your-project-id
      build: app.apk
      fail-on-failure: false
  ```

  ```yaml Test against staging theme={null}
  - uses: clickproof-ai/run-tests@v1
    with:
      api-key: ${{ secrets.CLICKPROOF_API_KEY }}
      project: your-project-id
      build: app.apk
      base-url: https://staging.clickproof.app
  ```
</CodeGroup>

<Info>
  **Coming soon:** a clickproof GitHub App for native PR checks and inline
  comments — zero YAML. The Action stays the primary path since your build
  artifact is produced inside your pipeline.
</Info>