OpenAgentsControl/.github/EXTERNAL_PR_GUIDE.md

External PR Guide

This guide explains how GitHub Actions workflows behave for external contributors (fork PRs).

For External Contributors (Fork PRs)

When you submit a PR from a fork, workflows run but cannot auto-commit fixes due to GitHub security restrictions.

What Runs Automatically

✅ Fast Build Check (< 2 minutes)

• TypeScript compilation check
• YAML test suite validation
• Quick feedback on code quality

✅ Registry Validation

• Checks if registry.json matches actual files
• Validates all paths are correct
• Checks prompts use defaults
• Cannot auto-commit (you'll need to fix locally)

❌ What Doesn't Run on PRs

• Full AI agent tests (too expensive, run manually by maintainers)
• Auto-version bumping (happens after merge)

What You Need to Do

If the validation workflow reports issues, you'll need to fix them locally:

1. Build Failures

If TypeScript compilation fails:

# Build locally to see errors
cd evals/framework
npm install
npm run build

# Fix the errors, then commit
git add .
git commit -m "fix: resolve build errors"
git push

2. Registry Issues

If new components are detected (you'll get a comment on your PR):

# Run auto-detect locally
./scripts/registry/auto-detect-components.sh --auto-add

# Commit the updated registry
git add registry.json
git commit -m "chore: update registry with new components"
git push

3. Prompt Issues

If prompts don't match defaults:

# Restore default prompts
./scripts/prompts/use-prompt.sh <agent-name> default

# Commit the changes
git add .opencode/agent/
git commit -m "chore: restore default prompts"
git push

4. Path Issues

If registry paths are invalid:

# Validate and see suggestions
./scripts/validate-registry.sh --fix

# Manually fix paths in registry.json
# Then commit
git add registry.json
git commit -m "fix: correct registry paths"
git push

What Happens Next

1. Fix Issues Locally: If validation fails, fix issues and push
2. Fast Feedback: Build checks complete in < 2 minutes
3. Maintainer Review: A maintainer will review your code
4. Merge: Once everything passes, your PR will be merged!
5. Auto-Release: After merge, version is auto-bumped and release created (you don't need to do anything!)

---

For Maintainers

Handling External PRs

External PRs run normally but cannot auto-commit due to GitHub security (can't push to fork branches).

Simple Overrides

If you need to override checks:

Skip Validation:

1. Go to Actions → Validate Registry on PR
2. Click "Run workflow"
3. Enable "Skip validation checks"
4. Run on the PR branch

Skip Version Bump:

1. Go to Actions → Post-Merge Automation
2. Click "Run workflow"
3. Enable "Skip version bump"
4. Run manually

Workflow Behavior

PR Type	Build Check	Registry Validation	Auto-Commit	AI Tests
Internal PR (branch)	✅ Yes	✅ Yes	✅ Yes	❌ No*
External PR (fork)	✅ Yes	✅ Yes	❌ No**	❌ No*

*AI tests don't run on PRs (too expensive) - maintainers run manually if needed
**Cannot push to fork branches - contributor must fix locally

Manual Testing External PRs

If you want to test an external PR locally:

# Fetch the PR
gh pr checkout <PR_NUMBER>

# Run build check
cd evals/framework
npm install
npm run build
npm run validate:suites:all

# Run validation
./scripts/registry/validate-registry.sh -v
./scripts/prompts/validate-pr.sh

# Auto-fix registry if needed
./scripts/registry/auto-detect-components.sh --auto-add

# Run AI tests (optional - only if needed)
npm run test:ci

# If everything passes, approve and merge
gh pr review <PR_NUMBER> --approve
gh pr merge <PR_NUMBER>

Note: AI tests are optional for PRs. The build check is usually sufficient.

---

Workflow Files

• .github/workflows/pr-checks.yml: Fast build validation (< 2 min)
• .github/workflows/validate-registry.yml: Registry validation with override
• .github/workflows/post-merge.yml: Auto-versioning after merge (main only)

Questions?

• Contributors: See CONTRIBUTING.md
• Maintainers: See WORKFLOW_GUIDE.md
• Issues: Open a GitHub Issue