---
url: https://salimhamed.github.io/jigs/api/steps/pull-requests.md
---
# 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

```ts
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

```ts
{
  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

```ts
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

```ts
const fetchPullRequestState: FetchPrState;
```

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

## Functions

### commentOnPullRequest()

```ts
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()

```ts
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`](../jigs.md#pullrequestsnapshot)>

***

### mergePullRequest()

```ts
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`](#mergeoutcome)>

***

### openPullRequest()

```ts
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`](#githubreporef); `title`: `string`; } |
| `request.base` | `string` |
| `request.body` | `string` |
| `request.draft?` | `boolean` |
| `request.head` | `string` |
| `request.repo` | [`GitHubRepoRef`](#githubreporef) |
| `request.title` | `string` |

#### Returns

`Promise`<[`OpenedPullRequest`](#openedpullrequest)>

***

### replyToPullRequestReviewThread()

```ts
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()

```ts
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()

```ts
function resolveRepository(binding): Promise<GitHubRepoRef>;
```

Find the GitHub repository configured for a binding.

#### Parameters

| Parameter | Type |
| :------ | :------ |
| `binding` | `string` |

#### Returns

`Promise`<[`GitHubRepoRef`](#githubreporef)>

***

### reviewPullRequest()

```ts
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`;
}>