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

✅ 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)

✅ Agent Tests

OpenAgent and OpenCoder smoke tests run
Results are reported in the PR

What You Need to Do

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

1. Registry Issues

If new components are detected:

# Run auto-detect locally
./scripts/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

2. 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

3. 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

Fix Issues Locally: If validation fails, fix issues and push
Maintainer Review: A maintainer will review your code
Merge: Once everything passes, your PR will be merged!

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:

Go to Actions → Validate Registry on PR
Click "Run workflow"
Enable "Skip validation checks"
Run on the PR branch

Skip Tests:

Go to Actions → Test Agents
Click "Run workflow"
Enable "Skip tests"
Run on the PR branch

Workflow Behavior

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

*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 validation
./scripts/validate-registry.sh -v
./scripts/prompts/validate-pr.sh

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

# Run tests
npm run test:ci

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

Workflow Files

.github/workflows/validate-registry.yml: Registry validation with override
.github/workflows/test-agents.yml: Agent tests with override

Questions?

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

EXTERNAL_PR_GUIDE.md 3.3 KB History Raw