Pull request checks and GitHub App

Raigal connects to GitHub to create status checks when pull requests open, evaluate code changes with six diagnostic engines, and enforce branch protection.

Architecture

┌───────────────────────────────┐        ┌───────────────────────────────┐
│     GitHub Repository         │        │       Raigal Cloud            │
│                               │        │                               │
│  Developer Opens Pull Request │───────►│ 1. GitHub App Receives Event  │
│  (Head SHA: 3b2a1c...)        │        │    (pull_request.opened)      │
│                               │        │                               │
│  Actions Runner Starts        │        │                               │
│  (runs npx raigal ci)         │        │                               │
│          │                    │        │                               │
│          ▼ (POST /v1/runs)    │        │ 2. Creates Pending Check      │
│   Ingest Metrics & Head SHA   │───────►│    "Raigal Quality Gate"      │
│                               │        │                               │
│                               │        ▼                               │
│                               │◄─────── Resolves Check Run             │
│                               │         (Success / Failure + Summary)  │
│                               │        │                               │
│  Branch Protection Enforced   │        │                               │
│  Board Card Updated           │        │                               │
└───────────────────────────────┘        └───────────────────────────────┘

How this setup works:

Local AST processing: Rule evaluation and AST analysis run entirely inside your CI runner. Raigal Cloud does not clone or store your codebase.
Immediate pending check: When a pull request opens or receives new commits, the GitHub App instantly registers a "Raigal Quality Gate" check in in_progress status on the head commit.
Check run resolution: Once the CI runner posts scan metrics to /v1/runs, Raigal Cloud matches the commit SHA and updates the check run with a detailed markdown summary.
Branch protection enforcement: The "Raigal Quality Gate" check can be selected as a required status check in GitHub branch protection rules.
Automatic updates on merge or close: GitHub sends merge and close webhook events directly to the app, updating board cards without extra CI steps.
Safety timeout: If a CI job is cancelled or fails before running raigal ci, Raigal Cloud automatically cleans up orphaned pending check runs after 20 minutes to prevent PRs from being blocked indefinitely.

Setup: GitHub App and Actions

1. Install the GitHub App

Open the Raigal Cloud GitHub App.
Click Install.
Choose your organization or personal account.
Select all repositories or choose specific ones.
Click Install & authorize.

2. Copy your organization token

Sign in to your dashboard at app.raigal.dev.
Open Settings.
Under API Tokens, select Create new token.
Name the token (e.g., ci-runner) and copy the generated key (rgl_live_...).

3. Add token to GitHub repository

In your GitHub repository, open Settings > Secrets and variables > Actions.
Click New repository secret.
Set the name to RAIGAL_TOKEN and paste your key.
Click Add secret.

If you prefer not to manage static tokens, add permissions: id-token: write to your workflow. Raigal Cloud validates the runner using GitHub OIDC directly.

4. Add the GitHub Actions workflow

Create .github/workflows/raigal.yml in your repository:

name: Raigal quality gate

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main, master, develop]
  push:
    branches: [main, master, develop]

jobs:
  quality-gate:
    name: Code quality gate
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
      pull-requests: write

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Full history required for diffs

      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Run Raigal quality gate
        env:
          RAIGAL_TOKEN: ${{ secrets.RAIGAL_TOKEN }}
          # RAIGAL_ORG_ID: ${{ vars.RAIGAL_ORG_ID }} # Required only if owner belongs to multiple orgs
        run: |
          if [ "${{ github.event_name }}" = "pull_request" ]; then
            git fetch origin ${{ github.base_ref }} --depth=1
            npx --yes @methiu/raigal@latest ci --changes --base origin/${{ github.base_ref }}
          else
            npx --yes @methiu/raigal@latest ci .
          fi

Because the GitHub App receives pull_request.closed events directly, you do not need an additional workflow to notify Raigal when PRs close.

5. Require status check in branch protection

In your GitHub repository, open Settings > Branches (or Rules > Rulesets).
Under Branch protection rules, edit the rule for your default branch (main).
Check Require status checks to pass before merging.
Search for and select Raigal Quality Gate.
Save changes.

Three-state quality gate verdicts

GitHub Check Runs and pull request cards evaluate results into three clear states:

Status verdict	Criteria	Check run outcome
PASSED	Score >= threshold (default 70), 0 errors, 0 warnings	`success` (Green check)
PASSED (WITH WARNINGS)	Score >= threshold (default 70), 0 errors, non-blocking warnings present	`neutral` (Advisory pass, does not block merge)
FAILED / BLOCKED	Score < threshold (default 70), exit code != 0, or blocker errors present	`failure` (Red cross, blocks merge)

Standalone CI mode (without GitHub App)

If your organization policies prevent installing third-party GitHub Apps, you can run Raigal using GitHub Actions alone:

1. Configure secret

In Settings > Secrets and variables > Actions, add RAIGAL_TOKEN.

2. Add workflow

Add .github/workflows/raigal.yml using the workflow above. In standalone mode, the gate reports status as a standard Actions job.

3. Add close sync workflow (optional)

To update the board when PRs close without the GitHub App, add a lifecycle sync workflow:

name: Raigal PR lifecycle

on:
  pull_request:
    types: [closed]

jobs:
  sync-pr-closed:
    name: Sync closed PR status
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Report PR closure to Raigal Cloud
        env:
          RAIGAL_TOKEN: ${{ secrets.RAIGAL_TOKEN }}
          RAIGAL_API_URL: ${{ secrets.RAIGAL_API_URL || 'https://app.raigal.dev' }}
        run: |
          npx --yes @methiu/raigal@latest report-pr-closed \
            --pr ${{ github.event.pull_request.number }} \
            ${{ github.event.pull_request.merged && '--merged' || '' }}

Tracking PRs on the board

In Raigal Cloud, open your repository board:

Pull requests column:
- Passed: shows the quality score (e.g. 94/100), author, source branch, and target branch.
- Blocked: shows blocker counts and failing rule categories.
Inspection drawer:
- Click a card to open its detail panel.
- Review blocking findings with rule IDs, file paths, and line numbers.
- Inspect diff statistics and unified diff preview.
- Copy the git checkout command to inspect changes locally, or select Open on GitHub to jump directly to the pull request.

Troubleshooting

Symptom	Probable cause	Actionable fix
`ambiguous_organization` (HTTP 400)	Repository owner account belongs to multiple Raigal organizations	In your workflow, set `RAIGAL_ORG_ID: ${{ vars.RAIGAL_ORG_ID }}` with your organization ID (`org_...`) from Settings.
Check run remains pending	CI workflow did not run or failed before executing `raigal ci`	Check that your GitHub Actions job completed for the commit `head_sha`. Raigal Cloud cleans up orphaned pending checks after 20 minutes.
Check run does not appear on PR	GitHub App not installed on the repository	Ensure the raigal-cloud GitHub App is installed on the organization or user owning the repository.
HTTP 401 Unauthorized in CI	Missing or expired `RAIGAL_TOKEN`	Confirm that `RAIGAL_TOKEN` is set in GitHub repository secrets and matches an active token in Settings.
HTTP 403 `owner_not_allowed` in CI	Repository owner is not linked to your Raigal organization	Go to Settings > Allowed Owners in Raigal Cloud and click Sync GitHub.
Diff preview shows 0 files changed	Shallow checkout (`fetch-depth: 1`)	Set `fetch-depth: 0` in `actions/checkout@v4` so full git commit history is available to compare against the base branch.
PR card does not update on merge	Standalone mode without sync workflow	If running without the GitHub App, add the `report-pr-closed` workflow.

Getting started

Core concepts

CLI reference

Automation & CI/CD

Cloud platform

Pull request checks and GitHub App

Architecture

Setup: GitHub App and Actions

Three-state quality gate verdicts

Standalone CI mode (without GitHub App)

Tracking PRs on the board

Troubleshooting

​Architecture

​Setup: GitHub App and Actions

​Three-state quality gate verdicts

​Standalone CI mode (without GitHub App)

​Tracking PRs on the board

​Troubleshooting

Architecture

Setup: GitHub App and Actions

Three-state quality gate verdicts

Standalone CI mode (without GitHub App)

Tracking PRs on the board

Troubleshooting