# GitHub Actions

> Run a Ritla scan from a GitHub workflow with ritla-app/scan-action, and fail the job on Arabic defects at the severity you choose.

Source: https://ritla.app/docs/integrations/github-actions

`ritla-app/scan-action` runs a Ritla scan of one of your projects from a GitHub workflow and fails the job when it finds Arabic defects at or above the severity you choose. It is the same scan as `ritla scan` in the [CLI](https://ritla.app/docs/cli#scan), packaged as a step.

## The workflow

Create a scan API key in your dashboard (Settings) and save it as a repository secret named `RITLA_API_KEY`. The project id is the UUID in the project's dashboard URL.

```yaml
name: Arabic QA
on:
  push:
    branches: [main]
jobs:
  ritla:
    runs-on: ubuntu-latest
    timeout-minutes: 40
    steps:
      - uses: ritla-app/scan-action@v1
        with:
          api-key: ${{ secrets.RITLA_API_KEY }}
          project-id: <project UUID from the dashboard URL>
          fail-on: high
```

> [!WARNING]
> Pass the key only as a GitHub secret. A key written into the workflow, or kept in `vars`, is printed in the log before the action can mask it.

## Inputs

| Input | Default | What it does |
| --- | --- | --- |
| `api-key` | Required | A Ritla scan API key, from a secret. |
| `project-id` | Required | The project's UUID from its dashboard URL. A site URL is refused. |
| `fail-on` | `critical` | `critical`, `high`, `medium`, `low` or `never`. A ladder: `high` fails on critical findings too, and `never` reports without failing. |
| `timeout-seconds` | `1800` | How long to wait for the result, time in the queue included. A timeout fails the job. |
| `api-url` | `https://ritla.app` | Only for testing another deployment. HTTPS only. |

## Outputs

| Output | What it holds |
| --- | --- |
| `scan-id` | The scan's id. |
| `score` | The score from 0 to 100, for the pages crawled. |
| `band` | `Excellent`, `Good`, `Needs work` or `Not ready`. |
| `pages` | How many pages the scan crawled. |
| `report-url` | The full report in your dashboard. |

The job summary shows the score, the page count, the findings by severity and a link to the report.

## What to expect

- A scan takes minutes, not seconds: it renders every page at three widths (desktop, tablet and mobile). Keep `timeout-minutes` on the job above `timeout-seconds`, as the workflow above does.
- Each run spends one scan of your plan's monthly allowance, so run it on pushes to your main branch or on a schedule rather than on every commit.
- Pull requests from forks get no secrets, so the action does not run on them.
- A scan that fails or times out fails the job. It is never a pass.
- It runs on GitHub-hosted Linux, macOS and Windows runners, and needs `bash`, `curl` and `jq`, which they all have.