PR Pairing Explained - Visual Guide

❓ What is PR Pairing?

PR Pairing is a mechanism that allows you to test coordinated changes across multiple repositories in the same CI run. This is crucial when making breaking changes that require updates to both a component repository and its deployment manifests (or test code).

ℹ️ Note: This feature is specific to Prow / OpenShift CI. The "Depends on" syntax is parsed by the CI system to checkout paired PR branches during test execution.

🎯 When Do You Need PR Pairing?

API Breaking Changes: Changing API endpoints in integration-service requires updating e2e-tests
Configuration Changes: New environment variable in build-service needs manifest updates
New Features: Adding new functionality that needs new Kubernetes resources
Test Updates: Updating test code to match component behavior changes

🔴 The Problem: Breaking Changes

❌ Scenario: You're adding a new required field to an API

You're working on integration-service and need to add a new required field to the Integration API. This requires:

Code changes in integration-service
Updated manifest in infra-deployments
Updated tests in e2e-tests

❌ WITHOUT PR Pairing

1 Open PR in integration-service with API changes

2 CI runs tests against OLD manifests and OLD test code

3 Tests FAIL because they don't know about new field

4 You can't merge because tests are red ❌

5 Stuck! Need to merge component first, but can't because tests fail

😫 Deadlock! Can't merge component until tests pass, tests can't pass until component merges

✅ WITH PR Pairing

1 Open PR in integration-service with API changes

2 Open paired PR in e2e-tests with updated tests

3 CI automatically detects pairing via PR description

4 CI tests integration-service PR with e2e-tests PR code

5 Tests PASS! ✅ Both PRs can merge

✅ Success! Both PRs tested together, both can merge safely

📝 How to Pair PRs: Step-by-Step

Step 1: Create Your Component PR

🔧

PR #1234 in integration-service

Add new required field to Integration API

Your normal PR description...

Step 2: Create Paired PR with Special Syntax

🧪

PR #5678 in e2e-tests

Update tests for new Integration API field

Update tests to handle new required field in Integration API

Depends on konflux-ci/integration-service#1234

Changes:
- Add new field to test fixtures
- Update assertions
- Add validation tests

🔑 The Magic Syntax:


                        Depends on {org}/{repo}#{pr-number}

Step 3: CI Detects and Pairs Automatically

# What happens in CI: 1. OpenShift CI webhook receives e2e-tests PR #5678 2. Parses PR description looking for "Depends on" pattern 3. Finds: konflux-ci/integration-service#1234 4. Clones integration-service at PR #1234's branch 5. Clones e2e-tests at PR #5678's branch 6. Runs tests with BOTH changes applied ✅ Tests pass with both PRs' changes!

🌍 Real-World Pairing Examples

📦

Example 1: Component + infra-deployments

Scenario: build-service needs new environment variable

PR #1: konflux-ci/build-service#789 - Add code using NEW_FEATURE env var
PR #2: redhat-appstudio/infra-deployments#456

Update build-service deployment with new env var Depends on konflux-ci/build-service#789 Changes: - Add NEW_FEATURE env var to deployment - Update configuration docs

🧪

Example 2: infra-deployments + e2e-tests

Scenario: Changing how ArgoCD apps are structured

PR #1: redhat-appstudio/infra-deployments#123 - Restructure argo-cd-apps/
PR #2: konflux-ci/e2e-tests#321

Update tests for new ArgoCD app structure Depends on redhat-appstudio/infra-deployments#123 Changes: - Update app discovery logic - Fix namespace expectations - Update bootstrap verification

🔗

Example 3: Triple Pairing (Component + Manifests + Tests)

Scenario: Major API version bump

PR #1: konflux-ci/release-service#555 - Bump to v2 API
PR #2: redhat-appstudio/infra-deployments#666
PR #3: konflux-ci/e2e-tests#777

# In infra-deployments PR #666: Update release-service manifests for v2 API Depends on konflux-ci/release-service#555 # In e2e-tests PR #777: Update release tests for v2 API Depends on konflux-ci/release-service#555 Depends on redhat-appstudio/infra-deployments#666

⚠️ Important Notes & Best Practices

✅ Best Practices

Merge Order: Merge component PR first, then infra-deployments, then e2e-tests
Keep PRs Small: Smaller paired PRs are easier to review and less risky
Clear Documentation: Explain WHY pairing is needed in PR description
Test Locally First: Use paired branches locally before creating PRs
Coordinate Merges: Don't merge one without the other ready to merge

⚠️ Common Pitfalls

Typos in "Depends on" syntax: Must be exact format: org/repo#number
Merging out of order: Component changes must merge before manifest updates
Forgetting to update all repos: Breaking change might need 3+ PRs paired
PR gets abandoned: If one PR closes, the other becomes unpaired and may fail

📚 Complete Syntax Reference

# Basic Pairing (single dependency): Depends on {org}/{repo}#{pr-number} # Examples: Depends on konflux-ci/integration-service#1234 Depends on redhat-appstudio/infra-deployments#5678 Depends on openshift/release#91011 # Multiple Dependencies: Depends on konflux-ci/build-service#111 Depends on redhat-appstudio/infra-deployments#222 # Case Insensitive: depends on konflux-ci/release-service#333 DEPENDS ON konflux-ci/e2e-tests#444 # Works in PR body or PR comments: - Can be anywhere in the PR description - Can be added later via comment - Multiple "Depends on" statements supported

🤝 PR Pairing Explained