Organization setup

​

Setup overview

​

1. Create your organization workspace

1. Open app.raigal.dev.
2. Sign in with GitHub, Google, or your corporate email.
3. Open the organization menu in the top-right corner and select Create organization (or select your existing workspace).
4. Enter your organization or company name (e.g., Acme Corp).
5. Your workspace is immediately created with an active 14-day evaluation trial.

​

2. Install the Raigal GitHub App

1. In the Raigal Cloud dashboard, go to Settings and select Sync GitHub accounts (or open github.com/apps/raigal-cloud directly).
2. Click Install app.
3. Select your GitHub organization or personal account.
4. Choose All repositories or pick specific repositories to monitor.
5. Click Install & authorize.

​

3. Obtain your organization API token

1. Open app.raigal.dev/settings.
2. Under API Tokens, find the Active organization token card and copy your live key (rgl_live_...).
3. To generate a dedicated key for CI or deployment runners, click Create new token, provide a name (e.g., github-actions-ci), and copy the displayed token.

​

4. Add the GitHub Actions workflow

name: Raigal quality gate

on:
  push:
    branches: [main, master, develop]
  pull_request:
    branches: [main, master, develop]

permissions:
  contents: read
  id-token: write        # Enables zero-token GitHub Actions OIDC authentication
  security-events: write # Required if uploading SARIF reports to GitHub Code Scanning

jobs:
  quality-gate:
    name: Code quality gate
    runs-on: ubuntu-latest

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

      - 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 repository 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

      - name: Generate SARIF security report (optional)
        if: always()
        run: npx --yes @methiu/raigal@latest scan . --sarif > raigal-results.sarif

      - name: Upload SARIF to GitHub Code Scanning (optional)
        if: always() && github.event.pull_request.head.repo.full_name == github.repository
        uses: github/codeql-action/upload-sarif@v3
        continue-on-error: true
        with:
          sarif_file: raigal-results.sarif
          category: raigal

​

Save the secret in GitHub:

1. In your GitHub repository, open Settings > Secrets and variables > Actions.
2. Click New repository secret.
3. Name: RAIGAL_TOKEN.
4. Secret: paste your rgl_live_... token.
5. Click Add secret.

​

5. Verify your first scan

1. Pull request scan: Open a pull request in your repository.
   • The Raigal GitHub App creates an in_progress check run named Raigal quality gate.
   • Your GitHub Actions runner executes raigal ci --changes --base origin/<base>.
   • The check run finishes with a summary showing the score (0-100), issue counts, and findings breakdown.
   • A card appears on your Raigal Cloud dashboard under the Pull Requests tab.
2. Main branch scan: Push a commit directly to main (or merge your PR).
   • The workflow executes a full scan (raigal ci .).
   • The repository baseline health score and active issues update across the Errors and Warnings tabs on app.raigal.dev.

​

6. Invite your team

1. In Raigal Cloud, navigate to Settings > Members.
2. Click Invite member and enter your colleague’s email address.
3. Select their role:
   • Admin: Full access to manage repository connections, API tokens, billing, and team members.
   • Member: Access to view repositories, inspect findings, review PR check runs, and use developer tools.
4. The invitee receives an email with an activation link to join your workspace.

​

Developer local workstation setup

# Authenticate local terminal via browser
npx @methiu/raigal login

# Verify active organization and authorized repositories
npx @methiu/raigal whoami

# Check local toolchains and engines
npx @methiu/raigal doctor

# Run full local scan
npx @methiu/raigal scan .

# Apply safe deterministic fixes
npx @methiu/raigal fix .

# Install pre-commit or agent interception hooks
npx @methiu/raigal hook install --claude

​

Troubleshooting common onboarding issues