steps/pull-requests

Read and update GitHub pull requests outside workflow code.

Wrap steps in a factory-owned "use step" file. Never call them directly from a workflow.

Interfaces

GitHubRepoRef

Identifies a GitHub repository by its owner and name.

Properties

Property	Type	Description
owner	string	The GitHub organization or account that owns the repository.
repo	string	The repository name.

Type Aliases

MergeOutcome

type MergeOutcome = 
  | {
  mergeCommitSha: string | null;
  merged: true;
}
  | object & MergeRefusal;

What GitHub did, and when it did not, why — and whether asking again could change the answer, which is what decides between standing the commit down and leaving it merge-ready.

Type Declaration

{
  mergeCommitSha: string | null;
  merged: true;
}

Name	Type	Description
mergeCommitSha	string | null	The merge commit, or null when GitHub has not reported it yet.
merged	true	Confirms that GitHub reports the pull request merged.

object & MergeRefusal

---

OpenedPullRequest

type OpenedPullRequest = PullRequestRef & object;

A newly opened or adopted pull request and its browser URL.

Type Declaration

Name	Type	Description
url	string	The pull request's browser URL.

Variables

fetchPullRequestState

const fetchPullRequestState: FetchPrState;

Read the pull request’s checks, reviews, and open review threads.

Functions

commentOnPullRequest()

function commentOnPullRequest(pr, body): Promise<{
  id: number;
}>;

Post a comment on the pull request conversation and return its id.

Parameters

Parameter	Type
pr	PullRequestRef
body	string

Returns

Promise<{ id: number; }>

---

markPullRequestReady()

function markPullRequestReady(pr): Promise<PullRequestSnapshot>;

Mark a draft pull request ready and return its freshly read state.

Parameters

Parameter	Type
pr	PullRequestRef

Returns

Promise<PullRequestSnapshot>

---

mergePullRequest()

function mergePullRequest(
   pr, 
   expectedHeadSha, 
policy): Promise<MergeOutcome>;

Merge the pull request with the configured method, pinned to the head the caller judged ready.

The title is re-read here rather than carried in from describePullRequest: a reviewer who corrects it — to satisfy a conventional-commit check on the target repo, usually — does so between the pull request opening and this merge, and a title captured at open time would ship the one they corrected away. After any ambiguous answer the pull request is read again, and this reports merged only if GitHub says so.

Parameters

Parameter	Type	Description
pr	PullRequestRef	-
expectedHeadSha	string	-
policy	{ approval: | { kind: "review"; } | { kind: "label"; name: string; }; by: "jigs" | "human"; method: "squash" | "merge" | "rebase"; }	-
policy.approval	| { kind: "review"; } | { kind: "label"; name: string; }	The signal that authorizes an automatic merge.
policy.by	"jigs" | "human"	Whether jigs merges an eligible pull request or waits for a person to merge it.
policy.method	"squash" | "merge" | "rebase"	The GitHub merge method to use when jigs performs the merge.

Returns

Promise<MergeOutcome>

---

openPullRequest()

function openPullRequest(request): Promise<OpenedPullRequest>;

Open a pull request from the working branch into the base branch.

The lookup comes first because this is one step: a create that succeeded before the assignment failed, or whose response was lost, leaves a pull request GitHub will refuse to open twice. The retry adopts that pull request and re-attempts only what did not finish.

Parameters

Parameter	Type
request	{ base: string; body: string; draft?: boolean; head: string; repo: GitHubRepoRef; title: string; }
request.base	string
request.body	string
request.draft?	boolean
request.head	string
request.repo	GitHubRepoRef
request.title	string

Returns

Promise<OpenedPullRequest>

---

replyToPullRequestReviewThread()

function replyToPullRequestReviewThread(
   pr, 
   rootId, 
   body): Promise<{
  id: number;
}>;

Reply to a review thread and return the posted comment id.

Parameters

Parameter	Type
pr	PullRequestRef
rootId	number
body	string

Returns

Promise<{ id: number; }>

---

resolveMergePolicy()

function resolveMergePolicy(binding): Promise<{
  approval:   | {
     kind: "review";
   }
     | {
     kind: "label";
     name: string;
   };
  by: "jigs" | "human";
  method: "squash" | "merge" | "rebase";
}>;

Read the effective merge policy for a factory binding.

Parameters

Parameter	Type
binding	string

Returns

Promise<{ approval: | { kind: "review"; } | { kind: "label"; name: string; }; by: "jigs" | "human"; method: "squash" | "merge" | "rebase"; }>

---

resolveRepository()

function resolveRepository(binding): Promise<GitHubRepoRef>;

Find the GitHub repository configured for a binding.

Parameters

Parameter	Type
binding	string

Returns

Promise<GitHubRepoRef>

---

reviewPullRequest()

function reviewPullRequest(pr, review): Promise<{
  id: number;
}>;

Post a pull request review and return its id. GitHub refuses an approval from the pull request's own author with 422 Unprocessable Entity; Jigs lets GitHub's GithubApiError surface unchanged.

Parameters

Parameter	Type
pr	PullRequestRef
review	PullRequestReviewRequest

Returns

Promise<{ id: number; }>