Docs

Github Pull Request

Description

The github/pullrequest action opens (or updates) a GitHub pull request once a target linked to the same scm has changed something and the change has been pushed.

It is the second half of the GitHub workflow: the github scm commits to a working branch and pushes it, this action turns that branch into a pull request. Without it, the branch is pushed and nothing else happens.

Note
kind: github is a deprecated alias for kind: github/pullrequest. It still works and logs a warning.

Requirements

An action never runs on its own: it needs an scmid pointing at an scm declared in the same manifest, and that scm must be of the matching kind. Both are checked when the manifest loads:

missing value for parameter(s) ["scmid"]
scm of kind "git" is not compatible with action of kind "github/pullrequest"

The action then reuses that scm rather than being configured twice. From it, it inherits:

FieldInherited value

sourcebranch

The working branch the scm created and pushed - the branch carrying the changes.

targetbranch

The scm’s branch - the branch the pull request is opened against.

owner, repository

The repository the scm points at.

credentials, URL

Whatever the scm was given, when the action does not set its own.

Every one of these can be overridden in the action spec, but there is rarely a good reason to: a mismatch between the branch the scm pushed and the branch the action opens the request from produces a request with no changes in it.

Where the title comes from

The title is resolved from the first of these that is set:

  1. spec.title on the action

  2. title on the action itself, one level above spec

  3. the name of the associated target, when there is exactly one

  4. the pipeline name

The second form is the usual one:

actions:
  default:
    kind: <the action kind>
    scmid: default
    title: 'deps: bump axios version'

Create or update

Updatecli looks for a request already open between the same two branches before creating one, so running the same pipeline repeatedly gives you one long-lived request per pipeline and repository rather than one per run. Whether that existing request is then refreshed with the latest title and description differs by plugin (each page says which).

Creation is also skipped, without failing the pipeline, when either branch is missing from the remote. Updatecli attempts it on every run regardless, so that a request closed by hand or lost to an earlier failure gets reopened on the next one.

Pipeline URL

When Updatecli detects that it runs inside a CI job, it appends a link to that job in the request description. Set disablepipelineurl: true on the action (next to kind and scmid, not inside spec) to leave it out.

Detection is limited to three engines, each recognised by one environment variable: Jenkins (JENKINS_URL), GitLab CI (GITLAB_CI), and GitHub Actions (GITHUB_ACTION), checked in that order. Anywhere else no link is added, whatever this setting says.

The credential the scm uses must also be allowed to open pull requests. Requesting reviews from a team additionally requires organization read permission.

Parameters

NameTypeDescriptionRequired
assigneesarray

Assignees contains the list of assignee to add to the pull request

default: empty

remark:

  • Please note that contrary to reviewers, assignees only accept GitHub usernames
automergeboolean

automerge allows to enable/disable the automerge feature on new pullrequest deprecated since the field “merge.strategy” should now be used to specify the merge strategy and enable automerge with “auto” value.

compatible:

  • action

default: false

deprecated: use merge.strategy: auto instead

descriptionstring

description allows to prepend information to the pullrequest description.

compatible:

  • action

default: empty

draftboolean

draft allows to set pull request in draft

compatible:

  • action

default: false

labelsarray

labels specifies repository labels used for the Pull Request.

compatible:

  • action

default: empty

remark: Labels must already exist on the repository

maintainercannotmodifyboolean

maintainercannotmodify allows to specify if maintainer can modify pullRequest

compatible:

  • action

default: false

mergeobject

merge configures automatic merge behavior for the pull request.

compatible:

  • action

default: strategy: manual (no automatic merge)

example: merge: strategy: client # merge immediately via API (no server-side automerge needed) after: 24h # never merge before waiting 24h

    afterstringafter specifies a minimum duration to wait before merging (e.g., “24h”, “30m”) The pull request will not be merged until it has been open for at least this duration.
    strategystringstrategy specifies the merge strategy: “client”, “auto”, or “manual” (default) client: merge immediately via GitHub API (no server-side automerge needed) auto: enable server-side auto-merge (requires branch protection rules) manual: do not merge automatically (default)
mergemethodstring

mergemethod allows to specifies what merge method is used to incorporate the pull request.

compatible:

  • action

default: ""

remark: Accept “merge”, “squash”, “rebase”, or ""

parentboolean

parent allows to specifies if a pull request should be sent to the parent of the current fork.

compatible:

  • action

default: false

reviewersarray

Reviewers contains the list of assignee to add to the pull request compatible:

  • action

default: empty

remark:

  • if reviewer is a team, the format is “organization/team” and the token must have organization read permission.
titlestring

title allows to override the pull request title

compatible:

  • action

default: The default title is fetch from the first following location:

  1. The action title
  2. The target title if only one target
  3. The pipeline target
usetitleforautomergeboolean

usetitleforautomerge allows to specifies to use the Pull Request title as commit message when using auto merge,

compatible:

  • action

default: ""

remark: Only works for “squash” or “rebase”

Merge behavior

merge.strategy decides what happens to the pull request once it exists. It accepts three values, and anything else is rejected at load time with invalid merge strategy.

manual

The default, also the behaviour when merge is omitted entirely. Updatecli opens the pull request and stops there.

auto

Enables GitHub’s own auto-merge, so GitHub merges once the required checks pass. This needs "Allow auto-merge" enabled on the repository and branch protection rules on the target branch, without them the API refuses and Updatecli logs which of the two is missing:

Automerge can't be enabled. Make sure to allow it on the repository.
Automerge can't be enabled. Make sure to have branch protection rules enabled on the repository.
client

Updatecli merges the pull request itself through the API, with no repository configuration required. Useful where auto-merge is unavailable, but note that it does not wait for checks the way auto does.

merge.after sets a minimum age before a client merge happens, as a Go duration (30m, 24h, 168h). It defaults to 24h when merge.strategy: client and after is unset, a pull request younger than that is left alone, with a message saying how long it still has to wait, and merged on a later run:

Pull request is only 3h0m0s old — waiting for merge.after duration of 24h

An unparsable value fails with invalid merge.after duration.

spec:
  merge:
    strategy: client
    after: 24h
Warning
automerge: true is deprecated. It is silently translated to merge.strategy: auto (and automerge: false to manual) with a warning in the logs. Use merge instead.

mergemethod selects how the merge is performed - merge, squash, rebase, or empty to use the repository default. Any other value is rejected with wrong merge method defined. usetitleforautomerge: true then uses the pull request title as the resulting commit message, which GitHub only honours for squash and rebase.

Reviewers, assignees, and labels

reviewers

GitHub usernames, or organization/team to request a review from a team. A team entry needs a token with organization read permission.

assignees

GitHub usernames only - the organization/team form is not accepted here.

labels

Must already exist on the repository. GitHub does not create them on the fly, unlike GitLab.

Other options

draft

Opens the pull request as a draft.

description

Prepended to the description Updatecli generates from the pipeline run; it does not replace it.

parent

Opens the pull request against the parent of the current fork instead of the fork itself.

maintainercannotmodify

Denies maintainer edits on the branch. The default, false, leaves them allowed.

Cleanup

Unlike most other action plugins, this one implements cleanup. On updatecli apply, an existing pull request that turns out to have no changed files (because the change was applied by other means in the meantime) is closed automatically, and the report records Pull request closed as no changed file detected.

With merge.strategy: client, cleanup is also where a pull request that has now reached its merge.after age gets merged.

Example

The manifest below opens a labelled pull request from the working branch created by the github scm, and lets GitHub merge it once the checks pass.

# updatecli.yaml
name: Update a file content and open a GitHub Pull Request

scms:
  website:
    kind: "github"
    spec:
      user: "updatecli-bot"
      email: "updatecli-bot@updatecli.io"
      owner: "updatecli"
      repository: "website"
      token: '{{ requiredEnv "GITHUB_TOKEN" }}'
      username: '{{ requiredEnv "GITHUB_AUTHOR" }}'
      branch: "main"

# Define action configurations if one needs to be created
actions:
  helm-charts:
    kind: "github/pullrequest"
    scmid: "website"
    spec:
      merge:
        strategy: auto
      description: "Prepend description"
      draft: false
      labels:
        - "dependencies"
        - "epinio"
      title: "Pull Request Title"

targets:
  default:
    scmid: website
    kind: file
    # spec:
    # ...

Links

Last updated on July 30, 2026
Prev
Bitbucket Server (Stash)
Next
Git