GitHub Actions Integration Guide: Adding Replixa to Your CI Pipeline

This guide covers a complete Replixa integration with GitHub Actions — from initial token setup through per-team review threshold tuning. The target is an organization that already has a working CI pipeline and wants to add automated inline review as a check in the same workflow. If you're starting fresh, the quickstart guide covers the initial account and repository connection first.

Expected time: 20–30 minutes for a single repository. Subsequent repositories in the same organization take 5–10 minutes each once the initial token scoping is in place.

Prerequisites

• A Replixa account with at least one repository connected (via the dashboard or CLI)
• GitHub Actions enabled for your target repository
• Permissions to create a repository secret (repo admin or organization admin)
• A Replixa API token — generate one at Settings → API Tokens in the Replixa dashboard

Step 1: Configure the API token as a GitHub secret

Replixa uses a scoped API token to authenticate review requests. The token needs read access to your Replixa configuration and write access to post review comments. Generate it with those exact scopes — don't use a personal access token with broader permissions.

In your GitHub repository (or organization, if you want a shared token across repos), navigate to Settings → Secrets and variables → Actions. Create a new secret:

Name: REPLIXA_API_TOKEN
Value: <your token from the Replixa dashboard>

If you're setting this at the organization level, the secret will be available to all repositories you configure. If you're setting it per-repository, you'll need to repeat this step for each repo.

Step 2: Add the Replixa workflow file

Create a file at .github/workflows/replixa-review.yml in your repository. The minimal configuration:

name: Replixa Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  replixa-review:
    name: Automated Review
    runs-on: ubuntu-latest
    permissions:
      pull-requests: write
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Run Replixa review
        uses: replixa/review-action@v2
        with:
          api-token: ${{ secrets.REPLIXA_API_TOKEN }}
          repository: ${{ github.repository }}
          pr-number: ${{ github.event.pull_request.number }}

A few notes on this configuration:

• fetch-depth: 0 is required. Replixa compares the PR diff against the style graph built from the base branch. A shallow clone won't have the full history the graph construction needs.
• pull-requests: write is the permission that allows Replixa to post inline suggestions to the PR diff.
• contents: read allows the checkout action to clone the repository code.

Step 3: Configure review scope with replixa.yml

Drop a replixa.yml file in the root of your repository to control what gets reviewed and how. Without this file, Replixa uses default settings — which is fine for initial setup but won't be calibrated for your team's conventions.

# replixa.yml
version: 2

review:
  # Paths to include in automated review
  include:
    - "src/**"
    - "lib/**"
    - "services/**"

  # Paths to exclude (generated code, vendored deps, etc.)
  exclude:
    - "vendor/**"
    - "**/*.generated.ts"
    - "migrations/**"

  # Minimum confidence threshold for posting a suggestion (0.0–1.0)
  # Higher threshold = fewer, higher-confidence suggestions
  suggestion_threshold: 0.75

  # Whether to post as inline suggestions (patch format) or plain comments
  format: inline_patch  # or: comment_thread

The suggestion_threshold parameter is the one that most teams need to tune in the first week. The default (0.7) tends to post more suggestions than most teams want on first install. Starting at 0.75 or 0.8 and gradually lowering as you build trust in the signal quality is the typical approach.

Step 4: Per-team threshold controls

For organizations with multiple teams in a single repository, Replixa supports per-path threshold overrides. This is useful when one team wants aggressive style enforcement and another wants a lighter touch:

# replixa.yml (continued)

teams:
  - name: platform
    paths:
      - "services/platform/**"
      - "lib/core/**"
    suggestion_threshold: 0.65  # More aggressive for core infra team

  - name: frontend
    paths:
      - "src/client/**"
      - "src/components/**"
    suggestion_threshold: 0.80  # Higher threshold, fewer style comments

  - name: data
    paths:
      - "services/data/**"
    suggestion_threshold: 0.75
    # Data team opted out of security pattern detection
    # (they have a separate SAST pipeline)
    security_patterns: false

Team configuration doesn't require any changes to the Actions workflow file — Replixa resolves team membership by matching the changed file paths against the paths arrays in the config.

Step 5: Handling draft PRs and merge queues

By default, Replixa runs on all PR events including draft PRs. If your team uses draft PRs heavily for work in progress and doesn't want review noise until the PR is ready for review, add a draft filter:

# In your workflow file, replace the trigger with:
on:
  pull_request:
    types: [opened, synchronize, reopened, ready_for_review]

# And add a job condition:
jobs:
  replixa-review:
    if: github.event.pull_request.draft == false
    # ... rest of job config

For repositories using GitHub's merge queue, Replixa runs correctly in the merge queue context — the merge_group event is handled automatically in review-action v2. No additional configuration is needed for merge queue support.

Step 6: Confirming the integration is working

Open a test PR against a branch with a few intentional style deviations — something that clearly diverges from your codebase's conventions. Watch the Actions tab: the replixa-review job should complete within 60–90 seconds for a typical PR. Check the PR's "Files changed" tab for inline suggestions.

If suggestions aren't appearing, check the Actions run log for the review job. Common issues at this stage:

• Token scope error: The API token was created without the review:write scope. Regenerate with correct scopes.
• Style graph not yet built: For newly connected repositories, the initial graph build can take 5–15 minutes depending on repository size. The first few PRs after connection may show no suggestions until the graph is ready.
• All suggestions below threshold: If the test PR is on a file path that's excluded, or if the style deviations are too minor relative to the threshold setting, no suggestions will appear. Lower the threshold temporarily for testing, then reset.

What to watch in the first two weeks

The two metrics worth tracking after integration: suggestion acceptance rate (how often authors are applying the inline patches) and false positive rate (how often authors are dismissing suggestions as unhelpful). Both are visible in the Replixa dashboard.

A suggestion acceptance rate below 50% in the first two weeks is typically a sign that the threshold is too low and you're generating noise. Raising the threshold to 0.80–0.85 and re-evaluating after another week is the standard calibration path. Threshold tuning is iterative — there's no universal right answer because it depends on your codebase's pattern stability and your team's tolerance for automated feedback volume.