# Gitea // :toc: // Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key :toclevels: 4 == Description The `gitea` scm plugin clones a repository hosted on a Gitea instance and pushes changes back to it. It is referenced by a resource through its `scmid`, as described on the link:/docs/core/scm/["SCM" page]. Its behavior depends on the stage referencing it: **source** and **condition**:: The repository is cloned and the resource works on the files from the branch defined by `branch`. Nothing is pushed. **target**:: Updatecli creates a *working branch* based on `branch`, commits the changes to it, and pushes that branch. The `branch` value itself is left untouched. IMPORTANT: This plugin does not open pull requests. Pushing a working branch and opening a pull request are two distinct steps: the pull request comes from an `actions` block of kind `gitea/pullrequest`, documented on the link:/docs/plugins/actions/gitea/["Gitea Pull Request" page]. Without such an action, the branch is pushed and nothing else happens. == Parameters {{< resourceparameters "scms" "gitea" >}} `url`, `owner`, and `repository` are mandatory. A missing `owner` or `repository` aborts the run with `wrong gitea configuration`; a missing `url` with `wrong configuration`. NOTE: The table is generated from the Updatecli JSON schema, refreshed by a bot after each release. A recently added parameter (currently `singleBranch`, which restricts clone and fetch to the configured branch) may work in the binary before it appears there. The `directory` description also mentions a `github` path; on this plugin the default is under `gitea`, as described below. === Authentication `url` points at your instance, with or without a scheme (`try.gitea.io` and `https://try.gitea.io` are equivalent, and `https://` is assumed when none is given). `token` is used both for the Gitea API and, together with `username`, as the HTTP credentials for git operations. Keep it out of the manifest: [source,yaml] ---- url: "try.gitea.io" username: '{{ requiredEnv "GITEA_USERNAME" }}' token: '{{ requiredEnv "GITEA_TOKEN" }}' ---- The token needs read access for a source or a condition, and write access to the repository for a target. Reading from a public repository works without any credential. === Working branch For a target, the working branch is derived from three components joined by a separator: [source,text] ---- ---- With the defaults (`updatecli` and `_`), a pipeline based on `main` produces `updatecli_main_`, where `pipelineID` is a hash derived from the manifest - so the same pipeline reuses the same branch instead of piling up new ones. Characters git refuses in a ref are stripped, and the name is truncated to 255 characters. Setting `workingBranchPrefix: ""` gives `_`. `branch` defaults to `main`, with a warning in the logs when it is left unset. ==== Disabling the working branch `workingBranch: false` makes Updatecli commit and push straight to `branch`. Since `force` defaults to `true` (meaning `git push --force`), that combination is refused unless `force` is also set explicitly: [source,text] ---- Better safe than sorry. Updatecli may be pushing unwanted changes to the branch "main". ---- Set `force: false` to push without forcing, or `force: true` to acknowledge the force push. When `force` is `true`, Updatecli also recreates working branches that diverged from their base branch. TIP: `updatecli apply --clean-git-branches` deletes, at the end of a run, the working branches that ended up identical to their base branch (those left behind by pipelines that had nothing to change). === Commit message Updatecli generates link:https://www.conventionalcommits.org/[conventional commits]. The `commitMessage` parameters (`type`, `scope`, `body`, `footers`, `hideCredit`, `squash`) shape the result. The commit title always comes from the target's `name`, or from its description when `name` is unset. It is capped at 72 characters minus the room taken by `type` and `scope`; the overflow moves into the body. With the default type `chore`: [source,text] ---- Author: updatecli-bot Date: Tue May 4 15:41:44 2021 +0200 chore: Update key "dependencies[0].version" from file "charts/jenkins/r... ... equirements.yaml" Made with ❤️️ by updatecli ---- Setting `body` replaces the generated body entirely, including that overflow. `hideCredit: true` drops the credit line. `squash: true` collapses the commits of the working branch into one (set `body` when you use it, since the individual messages are lost). [WARNING] ==== `commitMessage.title` is deprecated and ignored. Rename the target instead; Updatecli logs a warning when the field is present. ==== NOTE: `commitMessage` applies to every target linked to the same scm. === Commit signing and identity `gpg.signingkey` takes an *armored private* GPG key and `gpg.passphrase` its passphrase. Both are secrets: [source,yaml] ---- gpg: signingkey: '{{ requiredEnv "GPG_SIGNING_KEY" }}' passphrase: '{{ requiredEnv "GPG_PASSPHRASE" }}' ---- `user` and `email` name the commit author, defaulting to `updatecli-bot` and `updatecli-bot@updatecli.io`. Set them to an identity your Gitea instance recognises if you want the commits attributed to an account. === Clone behavior Left unset, `directory` defaults to `/updatecli/gitea//` - `/tmp/updatecli/gitea/olblak/updatecli-mirror` on Linux. Overriding it is rarely useful, as Updatecli may clean that directory up after a run. `submodules`:: Defaults to `true`; set it to `false` to skip submodule checkout. `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves an incomplete history, which can break pushes; `force: true` is often needed alongside. `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. `true` fetches only `branch` (much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch and opening a duplicate pull request). == Example [source,yaml] ---- # updatecli.yaml {{}} ----