Skip to main content

Git and pull requests

Goal: open and merge a pull request from a flow, with the human check a merge needs.

Prerequisites​

  • A GitHub token with permission to open and merge pull requests on the target repository.
  • The token in an environment variable the worker can read.

Steps​

  1. Choose the project's forge with Workspace.forge. The GitHub adapter (afe-github, forges/github) uses the REST API. none keeps everything local.

  2. Name the GitHub token with Workspace.tokenEnv. The adapter sends it only in the Authorization header, never in a URL, a log, an event or an error. Point forgeUrl at a GitHub Enterprise API to use one.

  3. Add builtin:open_pr. It pushes the integration branch and opens a pull request to defaultBranch. The title is afe <ticket>: <flow>, and the body holds the ticket input and the diff stat.

  4. Put a human node on every path from builtin:open_pr to builtin:merge_pr, lanes included. The configuration does not validate otherwise.

  5. Add builtin:merge_pr. It merges with a merge commit. At run time it refuses without a human answer recorded after open_pr: the ticket goes to needs_human.

Notes​

  • With forge: none nothing is pushed. The "PR" is a summary with the diff, and merge_pr fast-forwards the local default branch.
  • builtin:open_pr and builtin:merge_pr are idempotent. A crash that re-runs the node reuses the same PR and never merges twice.
  • A GitHub App is on the backlog.

Troubleshooting​

'merge_node' is reachable from 'open_node' without a human node: a merge needs a human approval in between afe validate rejects a flow where a path skips the human node, including a path through a lane. Add a human node between builtin:open_pr and builtin:merge_pr on that path.

The ticket stays at needs_human after open_pr builtin:merge_pr ran without a recorded human answer after the matching open_pr. Answer the pending request with Answer approvals. The merge only proceeds after that.

merge_pr reruns after a crash and nothing merges twice This is expected, not a failure: both built-in scripts are idempotent. A re-run finds the PR or the merge already done, and reports the same outcome.

See also​