Updatecli
Docs

Gitea Pull Request

Description

The gitea/pullrequest action opens (or updates) a Gitea 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 Gitea workflow: the gitea 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: gitea is a deprecated alias for kind: gitea/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.

Parameters

NameTypeDescriptionRequired
assigneesarray

“assignees” defines the list of users assigned to the pull request.

default: no assignee.

remark:

  • each user must have access to the repository.

example:

  assignees:
    - alice
    - bob
bodystring

“body” defines a custom body for the pull request.

default: a body generated from the pipeline execution.

remark:

  • unless you know what you are doing, do not set this value and rely on the default.
  • it is useful to give reviewers additional information, such as a changelog url.
ownerstring

“owner” defines the owner of the Gitea repository.

default: the owner of the scm, when the action uses a scm of kind “gitea”.

remark:

  • unless you know what you are doing, do not set this value and rely on the scm to provide it.
repositorystring

“repository” defines the name of the Gitea repository for a specific owner.

default: the repository of the scm, when the action uses a scm of kind “gitea”.

remark:

  • unless you know what you are doing, do not set this value and rely on the scm to provide it.
sourcebranchstring

“sourcebranch” defines the branch name used as the source of the Gitea pull request.

default: the working branch of the scm, when the action uses a scm of kind “gitea”.

remark:

  • unless you know what you are doing, do not set this value and rely on the scm to provide it.
  • the Gitea scm creates and uses a working branch such as “updatecli_xxxx”.
targetbranchstring

“targetbranch” defines the branch name used as the target of the Gitea pull request.

default: the branch of the scm, when the action uses a scm of kind “gitea”.

remark:

  • unless you know what you are doing, do not set this value and rely on the scm to provide it.
titlestring

“title” defines the title of the Gitea pull request.

default: the first match from the following list:

  1. the “title” set in the action spec.
  2. the “title” set in the action.
  3. the title of the first associated target.
  4. the title of the pipeline.

remark:

  • setting the title in the action (option 2) is usually preferred.

example:

  actions:
    default:
      kind: gitea/pullrequest
      scmid: default
      title: This is my title
tokenstring

“token” defines the credential used to authenticate with the Gitea API.

remark:

  • a token is sensitive information. Do not set it directly in the manifest. Use an environment variable or a SOPS file instead.
  • {{ requiredEnv "GITEA_TOKEN" }} retrieves the token from the environment variable “GITEA_TOKEN”.
  • {{ .gitea.token }} retrieves the token from a SOPS file. See https://github.com/getsops/sops for more information about SOPS files.
  • in a “gitea/pullrequest” action, the value is inherited from the scm when unset.
urlstring

“url” defines the Gitea url to interact with.

remark:

  • “https://” is added when the url has no “https://” or “http://” prefix.
  • in a “gitea/pullrequest” action, the value is inherited from the scm when unset.

example:

  • url: gitea.com
  • url: https://gitea.example.com
usernamestring

“username” defines the username used to authenticate with the Gitea API.

remark:

  • in a “gitea/pullrequest” action, the value is inherited from the scm when unset.

The spec includes title, body, assignees, merge, and mergemethod, on top of the identity fields inherited from the scm. Labels and reviewers are not exposed by this plugin.

body

Replaces the description Updatecli generates from the pipeline run. Useful to add context a reviewer needs, such as a changelog URL.

assignees

Gitea usernames, who must have access to the repository. They are set when the pull request is created and not reapplied afterwards.

Merge behaviour

merge.strategy accepts the following values (case-insensitive):

manual

The default, also used when merge is omitted or strategy is empty. Updatecli opens the pull request without requesting or cancelling auto-merge.

auto

Requests server-side auto-merge for a new or existing pull request. This requires Gitea 1.22+ or Forgejo 8+. Configure required checks and branch protections on the repository. A pull request that is already mergeable may merge immediately.

mergemethod selects how the merge is performed: merge, rebase, rebase-merge, squash, or fast-forward-only. Leave it empty to use the repository’s default merge style. Values are case-insensitive, and the selected method must be allowed on the repository.

Existing auto-merge schedules are left unchanged. Changing mergemethod does not change the method of an already scheduled pull request.

Updatecli only requests auto-merge when target changes trigger the action. A run without target changes reports the existing pull request without retrying a rejected auto-merge request. Dry-runs do not request auto-merge.

Updating an existing pull request

When a pull request is already open between the two branches in the same repository, this plugin does not refresh its title or description with the latest run, unlike the GitHub, GitLab, Bitbucket Cloud, and Azure DevOps plugins. The report still links to it. With merge.strategy: auto, the action also requests auto-merge as described above.

Warning

With merge.strategy: auto, errors from creating the pull request or requesting auto-merge fail the action. With manual or an empty strategy, a failed creation call logs Gitea pullrequest not created, skipping without failing the pipeline. Run with --debug to see the response body when a pull request you expected does not appear.

Warning

The sourcebranch and targetbranch descriptions in the table above have their defaults swapped: sourcebranch inherits the scm’s working branch (the one carrying the commits) and targetbranch inherits the scm’s branch, the one the pull request is opened against. Leave both unset and the inheritance is correct regardless.

Cleanup

Cleanup is not implemented for this plugin. updatecli apply --clean-git-branches removes working branches that ended up with no changes, but a pull request already opened for one of them is not closed automatically (that stays a manual step).

The same goes for the options this plugin does not expose, such as labels and reviewers. If closing stale pull requests, or anything else missing here, is something you would use, say so on the Updatecli issue tracker (these gaps are unimplemented rather than deliberate, and interest is what gets them prioritised).

Example

The manifest below opens a pull request and requests auto-merge using the squash method.

# updatecli.yaml
# updatecli.yaml
# updatecli diff --config updatecli.yaml
#
name: Show Gitea pipeline example

scms:
  gitea:
    kind: gitea
    spec:
      url: "demo.gitea.com"
      owner: "olblak"
      repository: "updatecli-mirror"
      branch: main

# Sources are responsible to fetch information from third location such as npm registry.
sources:
  updatecli:
    name: Get latest axios version
    kind: npm
    spec:
      name: axios

# Targets are responsible to update targeted files such as a yaml file.
targets:
  npm:
    name: Update e2e test file
    kind: yaml
    sourceid: updatecli
    scmid: gitea
    spec:
      file: e2e/updatecli.d/success.d/npm.yaml
      key: $.conditions.axios.spec.version

# Actions such as gitlab/mergerequest is triggered if a target is updated.
actions:
  default:
    kind: gitea/pullrequest
    scmid: gitea
    title: Bump axios version
    spec:
      merge:
        strategy: auto
      mergemethod: squash

Links

Last updated on October 28, 2026
Prev
Bitbucket Cloud
Next
Bitbucket Server (Stash)