Pull requests and checks

A pull request on a Forge repository works the way you expect from other Git hosts. Checks report results against its commits, and branch policy decides when it can merge.

Open a pull request

Push a branch, then open the pull request against the default branch:

git checkout -b greeting
sed -i.bak 's/Hello from Forge/Hello again from Forge/' public/index.html && rm public/index.html.bak
git commit -am "Change the greeting"
git push -u origin greeting
miosa forge pr new hello-forge --head greeting --title "Change the greeting" --body "Says hello again."

Number:  1
Title:   Change the greeting
State:   open
From:    greeting
Into:    main

Read it back, see what changed and talk about it:

miosa forge pr list hello-forge
miosa forge pr show hello-forge 1
miosa forge pr diff hello-forge 1 --name-only
miosa forge pr comment hello-forge 1 --body "Looks good to me."
miosa forge pr comments hello-forge 1

Branch policy

Branch policy decides what a pull request needs before it can merge into a branch.

miosa forge policy show hello-forge

Policy:         main v1 (default policy)
Merging needs:  no approval needed (solo organization; the default policy tightens when a second member joins)
Approvals:      1
Independent:    yes
Self-merge:     yes
Checks:         none

An organization with one member merges without approvals. Once a second person joins, the default policy asks for one approval from someone other than the author.

Set your own rules with policy set:

miosa forge policy set hello-forge --approvals 1 --check unit-tests

Working alone

An organization with one member can turn off the approval requirement so the author merges their own pull requests:

miosa forge policy set hello-forge --branch main --approvals 0 --independent=false

Required checks still apply.

Report your own checks

Any tool can report a check against a commit, for example a test run. A completed check needs evidence: a JSON file with an evidence object of up to 64 KB.

echo '{"evidence": {"runner": "npm test", "passed": 12, "failed": 0}}' > check.json
miosa forge check report hello-forge --commit "$(git rev-parse HEAD)" --name unit-tests --conclusion passed --summary "12 tests passed" --file check.json
miosa forge check list hello-forge --commit "$(git rev-parse HEAD)"

Review and merge

A teammate reviews the pull request; the author cannot approve their own:

miosa forge pr review hello-forge 1 --decision approved --body "Ship it."

When the branch policy is met, anyone with write access merges it:

miosa forge pr merge hello-forge 1

ok  Merged pull request #1 into main as 0d4d9eebbc76

Fix “needs approval”

When a pull request does not meet its branch policy, the merge is refused and nothing changes:

miosa: pull request #3 cannot merge: policy main v5 needs 1 approval from someone other than the author [REQUIRED_APPROVALS_MISSING]
  Ask someone with write access to approve:  miosa forge pr review hello-forge 3 --decision approved
  Working alone? Let the author merge:      miosa forge policy set hello-forge --branch main --approvals 0 --independent=false

Either ask a member with write access to approve, or, if you work alone, lower the policy with the second command. A missing required check fails the same way with REQUIRED_CHECK_EVIDENCE_UNAVAILABLE; run miosa forge pr show to see which check is missing.

Work on someone else’s pull request

miosa forge pr checkout hello-forge 2 --branch review-2
miosa forge pr close hello-forge 2
miosa forge pr reopen hello-forge 2