<GitHubPullRequest>

The <GitHubPullRequest> block commits the changes made in a repository cloned by <GitClone>, pushes them to a new branch, and opens a GitHub pull request. It is a GitHub-locked alias of <GitPullRequest>, equivalent to <GitPullRequest provider="github" />.

Basic usage

Pair it with <GitHubAuth> and <GitClone>:

<GitHubAuth
  id="gh-auth"
  title="Connect to GitHub"
/>

<GitClone
  id="clone-repo"
  githubAuthId="gh-auth"
  title="Clone Repository"
  prefilledUrl="https://github.com/acme-corp/infrastructure"
/>

<GitHubPullRequest
  id="create-pr"
  githubAuthId="gh-auth"
  title="Open Pull Request"
  description="Create a PR with the changes made in this runbook"
/>

Pre-filled values

You can pre-populate the PR title, description, labels, branch name, and commit message. Users can still edit these values before creating the PR.

<GitHubPullRequest
  id="create-pr"
  githubAuthId="gh-auth"
  prefilledPullRequestTitle="Add VPC module configuration"
  prefilledPullRequestDescription="## Changes\n- Added VPC module\n- Configured NAT gateway"
  prefilledPullRequestLabels={["enhancement", "terraform"]}
  prefilledBranchName="feature/add-vpc"
  prefilledCommitMessage="Add VPC module configuration"
/>

Note

<GitLabMergeRequest> and <GitPullRequest> accept the same prefilled props, including prefilledCommitMessage.

Template expressions

The prefilledPullRequestTitle, prefilledPullRequestDescription, prefilledBranchName, and prefilledCommitMessage props support template expressions that reference inputs and outputs from other blocks. Escape sequences like \n are converted to real newlines, which is useful for multi-line PR descriptions:

<GitHubPullRequest
  id="create-pr"
  githubAuthId="gh-auth"
  prefilledPullRequestTitle="Add {{ .outputs.config.MODULE_NAME }} module"
  prefilledBranchName="feature/{{ .outputs.config.MODULE_NAME }}"
/>

Template expressions are resolved in real-time as upstream blocks produce outputs. If the block references outputs from blocks that haven’t run yet, it displays a warning and disables the “Create Pull Request” button until all dependencies are satisfied.

Props

Prop	Type	Required	Description
id	string	Yes	Unique block identifier. Used by downstream blocks to reference outputs.
title	string	No	Display title for the block header. Supports inline markdown and template expressions.
description	string	No	Description text below the title. Supports inline markdown and template expressions.
inputsId	string | string[]	No	Reference to one or more <Inputs> blocks by ID for template variable substitution. When multiple IDs are provided, variables are merged in order (later IDs override earlier ones).
githubAuthId	string	No	Reference to a <GitHubAuth> block. When set, the block waits for authentication to complete and uses the token for GitHub API access.
prefilledPullRequestTitle	string	No	Pre-fills the PR title field. Supports template expressions.
prefilledPullRequestDescription	string	No	Pre-fills the PR description field. Supports template expressions, markdown, and \n for newlines.
prefilledPullRequestLabels	string[]	No	Pre-selects labels by name. Labels must exist in the repository.
prefilledBranchName	string	No	Pre-fills the branch name. Supports template expressions. Defaults to runbook/<timestamp>.
prefilledCommitMessage	string	No	Pre-fills the commit message field. Supports template expressions.

Block outputs

After a successful PR creation, the block produces outputs that can be referenced by downstream blocks:

Output	Description	Example
PR_ID	The pull request number	42
PR_URL	The full URL of the created pull request	https://github.com/org/repo/pull/42

Reference outputs in downstream blocks using template variables:

<Command
  id="notify"
  title="Post PR Link"
  command="echo 'PR created: {{ .outputs.create_pr.PR_URL }}'"
/>

Note

Block IDs with hyphens are converted to underscores in template variables. For example, create-pr becomes create_pr.

Git Push

After creating a PR, the block shows a Git Push button. It runs git push -u origin <branch> for the PR’s branch with the authenticated token. It does not stage or commit anything, so use it to push commits made since the PR was created, for example by a Command block that ran git commit. To commit uncommitted changes onto the open PR, choose “create another PR” and enter the open PR’s branch name. See Creating another PR.

Retrying after a failure

If creation fails after the branch was created (for example, the push is rejected or the API call fails), fix the cause and create the PR again with the same branch name. The block picks up on the existing branch: it commits any new changes and pushes, then opens the PR.

You can also retry under a new branch name. The new branch starts from the branch the failed attempt left checked out, so if that attempt’s push failed, its commits are pushed under the new name, along with any new changes.

If a local branch with that name already exists but isn’t checked out (for example, one left over from an earlier run), the block offers to delete it and retry. The delete is refused if the branch has commits that haven’t been pushed or merged; choose a new branch name instead.

The branch name can’t be the base branch or a protected name (main, master, develop, dev, staging, release, prod, production).

Creating another PR

After a PR is created, its branch stays checked out, and “create another” fills in a new branch name such as runbook/<timestamp>. What the next create does depends on the branch name and on whether anything changed since:

• With a new name and new changes, the new branch starts from the open PR’s branch, so the new PR also contains the open one’s commits.
• With a new name and no new changes, the create is refused with “Nothing to commit”. The open PR’s commits are already on GitHub, and a new PR would only repeat them. Nothing is pushed, and the open PR’s branch stays checked out.
• With the open PR’s branch name, the block picks up on that branch, commits any new changes and pushes them to it, so they become part of the open PR, and then reports that the PR already exists.

The block shows Git Push until you choose “create another”.

Prerequisites

The block needs a completed <GitHubAuth> block, for the token, and a <GitClone> block that has cloned a repository, which the PR is created against. It checks both and shows an amber warning for whichever is missing. The Create PR button stays disabled until both are met.

For authentication, the block looks for a GITHUB_TOKEN output from the block referenced by githubAuthId. When that block picked up existing credentials (environment variables or the GitHub CLI) rather than running its OAuth flow, it registers an __AUTHENTICATED marker instead, which also satisfies the check. Until one is present, the block displays “Waiting for GitHub authentication” and names the block to complete.

For the repository, the block checks whether a GitClone block has registered an active worktree. Until one has, it displays “No repository available”.

Labels

The block fetches available labels from the repository and presents them in a searchable multi-select dropdown. Labels can also be pre-selected using the prefilledPullRequestLabels prop.

Labels are applied after the PR opens. If applying them fails, the PR is still created and the logs show a warning.

GitHub Enterprise

The pull request is opened against the host of the cloned repository’s origin remote: github.com, a GitHub Enterprise Server host such as github.example.com, or a GHE.com tenant such as acme.ghe.com. The block uses that host’s API (https://api.github.com, https://<host>/api/v3, or https://api.<tenant>.ghe.com) and fetches labels from it.

That host must be the one the linked auth block authenticated to (its GITHUB_HOST output). If they differ, for example a repository cloned from github.example.com while the auth block signed in to github.com, the block fails with an error and sends the token nowhere. Links to token settings shown by the block also follow the authenticated host.

<GitHubAuth
  id="gh-auth"
  host="github.example.com"
/>

<GitClone
  id="clone-repo"
  githubAuthId="gh-auth"
  prefilledUrl="https://github.example.com/platform/infrastructure-live"
/>

<GitHubPullRequest
  id="create-pr"
  githubAuthId="gh-auth"
  title="Open Pull Request"
/>

See GitHub Enterprise support for configuring the host.

Example: full workflow

<GitHubAuth
  id="gh-auth"
  title="Authenticate to GitHub"
/>

<GitClone
  id="clone-infra"
  githubAuthId="gh-auth"
  title="Clone Infrastructure Repo"
  prefilledUrl="https://github.com/acme-corp/infrastructure-live"
/>

<Command
  id="make-changes"
  title="Apply Configuration"
  command="echo 'new_setting = true' >> config.hcl"
/>

<GitHubPullRequest
  id="open-pr"
  githubAuthId="gh-auth"
  title="Open Pull Request"
  prefilledPullRequestTitle="Update infrastructure configuration"
  prefilledPullRequestLabels={["infrastructure"]}
  prefilledCommitMessage="Update infrastructure configuration"
/>