openrag/.github/BRANCH_PROTECTION_GUIDE.md

Branch Protection Configuration Guide

This guide explains how to configure branch protection rules for the main branch to ensure all tests pass before merging.

Quick Setup

1. Navigate to Branch Protection Settings

1. Go to your repository on GitHub
2. Click Settings → Branches
3. Click Add rule or Edit for the main branch

2. Configure Required Settings

Enable the following options:

Required Status Checks

[x] Require status checks to pass before merging

• Require branches to be up to date before merging
• Required checks:
  • Test Validation (from pr-checks.yml)
  • Run Tests (from tests.yml)
  • test-validation (job name)

Additional Protections (Recommended)

• Require a pull request before merging
  • Required approvals: 1 (recommended)
  • Dismiss stale reviews when new commits are pushed
• Require conversation resolution before merging
• Do not allow bypassing the above settings

CI Workflows Overview

1. tests.yml - Main Test Workflow

Triggers:

• Push to main branch
• Pull requests to main branch

Jobs:

• test: Runs unit tests (required to pass)
• integration-test: Runs integration tests with OpenSearch (optional)
• lint: Code quality checks (optional)
• test-summary: Aggregates results

Required for merge: [x] Yes (test job must pass)

2. pr-checks.yml - PR-specific Validation

Triggers:

• Pull request opened/updated to main

Jobs:

• test-validation: Strict unit test validation
• code-quality: Linting and code quality
• pr-validation: Final validation check

Required for merge: [x] Yes (test-validation job must pass)

What Tests Must Pass?

Required [x]

• All unit tests (77+ tests)
• Runtime: ~2 seconds
• No external dependencies

Optional [INFO]

• Integration tests (require OpenSearch)
• Linting checks
• Code quality checks

Test Commands Run in CI

# Unit tests (REQUIRED - must pass for merge)
uv run pytest tests/ -v \
  -m "not requires_opensearch and not requires_langflow" \
  --cov=src \
  --cov-report=xml \
  --cov-fail-under=1

# Integration tests (OPTIONAL - informational)
uv run pytest tests/ -v \
  -m "integration and requires_opensearch" \
  --cov=src \
  --cov-report=xml

PR Workflow

Contributor Flow

1. Create feature branch

   git checkout -b feature/my-feature
   

2. Make changes and run tests locally

   make test-unit
   

3. Push changes

   git push origin feature/my-feature
   

4. Create Pull Request

   • CI automatically runs
   • Status checks appear on PR

5. Review CI Results

   • Green checks = ready to merge
   • [FAIL] Red checks = fix issues

6. Merge when tests pass

   • All required checks must be green
   • PR can be merged to main

Status Check Results

[x] Success

[x] Test Validation
[x] Run Tests
[x] All required tests passed

Action: PR can be merged

[FAIL] Failure

[FAIL] Test Validation
[FAIL] Some tests failed

Action: Fix failing tests and push changes

Local Testing Before Push

Ensure tests pass locally before pushing:

# Quick check (recommended)
make test-unit

# Full test suite
make test

# With coverage
make test-coverage

# Specific tests
make test-api
make test-service

Troubleshooting CI Failures

Tests fail in CI but pass locally

1. Check Python version

   python --version  # Should be 3.13
   

2. Ensure dependencies are in sync

   uv sync --extra dev
   

3. Run tests in CI mode

   uv run pytest tests/ -v -m "not requires_opensearch and not requires_langflow"
   

Permission errors in CI

• Ensure workflow has necessary permissions
• Check GitHub Actions settings

Flaky tests

• Integration tests may be flaky (that's why they're optional)
• Unit tests should be stable
• Report flaky tests as issues

Bypassing Branch Protection (Emergency Only)

[WARN] Not recommended for normal workflow

If you're a repository admin and need to bypass:

1. Go to Settings → Branches
2. Temporarily uncheck protection rules
3. Merge PR
4. Immediately re-enable protection

[WARN] Always fix tests instead of bypassing!

Configuration Examples

Minimal Configuration (Recommended)

Branch Protection Rules for main:
☑ Require status checks to pass before merging
  ☑ Require branches to be up to date
  Required checks:
    - test-validation
    - Run Tests
☑ Require a pull request before merging

Strict Configuration (Team Environment)

Branch Protection Rules for main:
☑ Require status checks to pass before merging
  ☑ Require branches to be up to date
  Required checks:
    - test-validation
    - Run Tests
    - code-quality
☑ Require a pull request before merging
  Number of approvals: 2
  ☑ Dismiss stale reviews
☑ Require conversation resolution
☑ Require signed commits
☑ Include administrators

Monitoring Test Health

View Test Results

1. In Pull Request:

   • Check "Checks" tab
   • View detailed logs
   • See test output

2. In Actions Tab:

   • View all workflow runs
   • Check historical pass rates
   • Monitor performance

Test Metrics

• Success Rate: Should be 100% for unit tests
• Runtime: ~2 seconds for unit tests
• Coverage: Growing toward 70%+

FAQ

Q: Can I merge if integration tests fail? A: Yes, integration tests are optional. Only unit tests are required.

Q: How do I skip CI for a commit? A: You can't skip required checks. All PRs must pass tests.

Q: What if tests are flaky? A: Fix the flaky tests. Unit tests should never be flaky.

Q: Can I run CI locally? A: Yes, use make test-unit to run the same tests CI runs.

Q: How do I add new required checks? A: Update branch protection settings and add job name to required checks.

Support

• Tests failing? Check test logs in GitHub Actions
• Need help? See tests/README.md for testing guide
• Issues? Open a GitHub issue

Summary

[x] Required for merge to main:

1. All unit tests pass (77+ tests)
2. No test failures
3. Code builds successfully

[FAIL] Blocks merge:

• Any unit test failure
• Build failures
• Missing required checks

Optional:

• Integration tests
• Linting checks
• Code coverage improvements

Enable branch protection to enforce these rules automatically!