Skip to main content

Labels and Review Status

diffray uses automatic labels to track review status in your pull requests.

Status Labels​

diffray automatically adds and manages the following labels:

🟡 diffray-review-started​

When added:

  • Immediately after review starts
  • On any trigger (opened, synchronize, reopened, labeled)

What it means:

  • Review has been accepted for processing
  • ECS task has started and is analyzing code
  • Expect results in 5-10 minutes

Color: Yellow/orange

✅ diffray-review-completed​

When added:

  • After successful review completion
  • Results published in PR comment

What it means:

  • AI analysis completed
  • Comment with results added to PR
  • GitHub Check Run updated to Success

Color: Green

Replaces: diffray-review-started (old label is removed)

❌ diffray-review-failed​

When added:

  • If review completes with an error
  • On technical issues (timeout, GitHub unavailability, internal errors)

What it means:

  • Review could not complete successfully
  • Check GitHub Check Run for error details
  • Possible refund of spent review (automatic)

Color: Red

Replaces: diffray-review-started

🔵 diffray-review​

Trigger label - used to manually start a review

When to add:

  • To restart a review manually
  • To start a review on an old PR
  • After fixing an error

What happens:

  • New review starts
  • Old status labels (completed/failed) are removed
  • diffray-review-started is added
  • diffray-review is removed automatically

Learn more: Rerun Review

GitHub Check Runs​

Besides labels, diffray creates a GitHub Check Run for each review.

Check Run Statuses​

Queued​

⏳ diffray Code Review — Queued

Review accepted but execution hasn't started yet.

In Progress​

🔄 diffray Code Review — In Progress

Code analysis is running, awaiting results.

Success​

✅ diffray Code Review — Completed

Review completed successfully, results published.

Failure​

❌ diffray Code Review — Failed

Review completed with error, check details.

Viewing Check Run​

In the pull request:

  1. Scroll down to the "Checks" section
  2. Find "diffray Code Review"
  3. Click "Details" to view details and logs

Label Lifecycle​

Scenario 1: Successful Review​

[PR created]
    ↓
[diffray-review-started] added
    ↓
[Analysis 5-10 minutes]
    ↓
[diffray-review-started] removed
[diffray-review-completed] added
    ↓
[Results in comment]

Scenario 2: Review with Error​

[PR created]
    ↓
[diffray-review-started] added
    ↓
[Error during analysis]
    ↓
[diffray-review-started] removed
[diffray-review-failed] added
    ↓
[Check Run: Failure + error details]

Scenario 3: New Push to PR​

[PR with diffray-review-completed]
    ↓
[git push new commits]
    ↓
[diffray-review-completed] removed (automatically)
[diffray-review-started] added
    ↓
[New review starts]
    ↓
... (cycle repeats)

Scenario 4: Manual Restart​

[PR with diffray-review-failed]
    ↓
[User adds diffray-review]
    ↓
[diffray-review-failed] removed (automatically)
[diffray-review-started] added
    ↓
[New review starts]
    ↓
... (cycle repeats)

Managing Labels​

Automatic Management​

diffray manages status labels automatically:

  • Adds: diffray-review-started on start
  • Replaces: started → completed or failed on completion
  • Removes: old status labels on new start

You do NOT need to manually manage these labels.

Manual Management​

You can:

  • Add diffray-review to start a new review
  • Remove status labels (but they'll return on next review)

Not recommended:

  • Manually adding diffray-review-started/completed/failed
  • Removing labels during review execution

Label Customization (Future Feature)​

Future versions plan to add:

  • Label color customization
  • Custom label names
  • Option to disable automatic labels

Notifications​

GitHub sends notifications when labels change if you have enabled:

Settings → Notifications → Email notifications:

  • Participating
  • Watching

You'll receive notification when:

  • Review starts (diffray-review-started added)
  • Review completes (diffray-review-completed added)
  • Comment with results is posted

CI/CD Integration​

You can use status labels in your CI/CD:

GitHub Actions Example​

name: Check diffray Review
on:
  pull_request:
    types: [labeled]

jobs:
  check-review:
    runs-on: ubuntu-latest
    if: contains(github.event.pull_request.labels.*.name, 'diffray-review-completed')
    steps:
      - name: Review completed
        run: echo "diffray review is complete!"

Branch Protection Rules​

You can require successful diffray Check Run completion:

  1. Repository Settings → Branches → Branch protection rules
  2. Enable "Require status checks to pass before merging"
  3. Select "diffray Code Review"

Now PRs cannot be merged until review completes successfully.

Troubleshooting​

Label Not Updating​

Problem: diffray-review-started present for more than 20 minutes

Causes:

  • Review is still executing (large PR can take up to 15 minutes)
  • Review completed with error but label wasn't updated

Solution:

  1. Check GitHub Check Run for status
  2. Check diffray Dashboard for review status
  3. If Check Run shows Failure but label wasn't updated:
    • Remove label manually
    • Add diffray-review to restart

Multiple Status Labels Simultaneously​

Problem: Both diffray-review-started and diffray-review-completed present

Cause: Race condition or synchronization error

Solution:

  1. Remove both labels manually
  2. Add diffray-review for clean restart

Labels Not Adding at All​

Problem: Review executes but labels don't appear

Causes:

  • GitHub App doesn't have permissions to manage labels
  • Issues with GitHub API

Solution:

  1. Check GitHub App permissions in Repository Settings
  2. Reinstall GitHub App
  3. Contact support

Next step: How to Rerun Review →