diff --git a/assets/code_example/docs/plugins/gitea/updatecli-performance.yaml b/assets/code_example/docs/plugins/gitea/updatecli-performance.yaml new file mode 100644 index 000000000..35b81b9d2 --- /dev/null +++ b/assets/code_example/docs/plugins/gitea/updatecli-performance.yaml @@ -0,0 +1,20 @@ +--- +name: Test Gitea scm optimized for large repositories + +scms: + gitea: + kind: gitea + spec: + url: "try.gitea.io" + owner: "olblak" + repository: "updatecli-mirror" + branch: main + singleBranch: true + +sources: + license: + name: Retrieve license file content + kind: file + scmid: gitea + spec: + file: LICENSE diff --git a/assets/code_example/docs/plugins/gitlab/updatecli-performance.yaml b/assets/code_example/docs/plugins/gitlab/updatecli-performance.yaml new file mode 100644 index 000000000..957871cb2 --- /dev/null +++ b/assets/code_example/docs/plugins/gitlab/updatecli-performance.yaml @@ -0,0 +1,21 @@ +--- +name: Show Gitlab scm optimized for large repositories + +scms: + gitlab: + kind: gitlab + spec: + # By default url is set to gitlab.com + # url: gitlab.com + owner: "olblak" + repository: "updatecli" + branch: main + singleBranch: true + +sources: + license: + name: Retrieve license file content + kind: file + scmid: gitlab + spec: + file: LICENSE diff --git a/assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/performance.yaml b/assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/performance.yaml new file mode 100644 index 000000000..5ffaacfa0 --- /dev/null +++ b/assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/performance.yaml @@ -0,0 +1,41 @@ +name: Update a file and open an Azure DevOps Pull Request on a large repository + +scms: + default: + kind: azuredevops + spec: + organization: myorg + project: myproject + repository: myrepo + branch: main + singleBranch: true + token: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_TOKEN" }}' + username: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_USERNAME" }}' + user: updatecli + email: updatecli@example.com + +sources: + golang: + name: Get the latest Golang version + kind: golang + spec: + versionfilter: + kind: semver + pattern: "1.24.x" + +targets: + golang-version: + name: 'deps(golang): Bump Golang version to {{ source "golang" }}' + kind: yaml + scmid: default + spec: + file: .github/workflows/*.yaml + key: '$.jobs.build.steps[?(@.uses =~ /^actions\/setup-go/)].with.go-version' + searchpattern: true + +actions: + default: + kind: azuredevops/pullrequest + scmid: default + spec: + title: 'deps(golang): Bump Golang version' diff --git a/assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/performance.yaml b/assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/performance.yaml new file mode 100644 index 000000000..3eddf9655 --- /dev/null +++ b/assets/code_example/docs/plugins/scm/bitbucket/updatecli.d/performance.yaml @@ -0,0 +1,25 @@ +name: "Example with Bitbucket Cloud SCM optimized for large repositories" +pipelineid: bitbucket/scm + +scms: + bitbucket: + kind: bitbucket + spec: + owner: "updatecli" + repository: "updatecli" + branch: main + singleBranch: true + # {{ if (env "BITBUCKET_TOKEN") }} + token: '{{ env "BITBUCKET_TOKEN" }}' + # {{ else if (and (env "BITBUCKET_USER") (env "BITBUCKET_APP_PASSWORD")) }} + username: '{{ env "BITBUCKET_USER" }}' + password: '{{ env "BITBUCKET_APP_PASSWORD" }}' + # {{ end }} + +sources: + source-1: + name: "Source 1" + kind: file + scmid: bitbucket + spec: + file: README.md diff --git a/assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml b/assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml new file mode 100644 index 000000000..593f46b80 --- /dev/null +++ b/assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml @@ -0,0 +1,19 @@ +name: "Example with Git SCM optimized for large repositories" + +scms: + scenario-target: + kind: git + spec: + url: "git@github.com:updatecli/updatecli.git" + branch: "main" + singleBranch: true + user: "git user to push from changes" + email: "git user email to push from change" + +targets: + target-1: + name: "Target 1" + kind: file + scmid: scenario-target + spec: + file: README.md diff --git a/assets/code_example/docs/plugins/scm/github/updatecli.d/performance.yaml b/assets/code_example/docs/plugins/scm/github/updatecli.d/performance.yaml new file mode 100644 index 000000000..18eadf4ad --- /dev/null +++ b/assets/code_example/docs/plugins/scm/github/updatecli.d/performance.yaml @@ -0,0 +1,23 @@ +name: Example of a GitHub SCM configuration optimized for large repositories + +scms: + default: + kind: github + spec: + user: "git user to push from changes" + email: "git user email to push from change" + directory: "directory where to clone the git repository" + owner: "github owner" + repository: "github repository" + token: "github token with enough permission on repository" + username: "github username used for push git changes. Needed in private repositories" + branch: "git branch where to push changes" + singleBranch: true + +targets: + id: + kind: yaml + scmid: default + spec: + file: "Yaml file path from the root repository" + key: "yaml key to update" diff --git a/assets/code_example/docs/plugins/stash/updatecli-performance.yaml b/assets/code_example/docs/plugins/stash/updatecli-performance.yaml new file mode 100644 index 000000000..b4533a7f1 --- /dev/null +++ b/assets/code_example/docs/plugins/stash/updatecli-performance.yaml @@ -0,0 +1,22 @@ +--- +name: Test Bitbucket Server (Stash) scm optimized for large repositories + +scms: + stash: + kind: stash + spec: + url: "https://bitbucket.example.com" + owner: "olblak" + repository: "updatecli-mirror" + branch: "main" + singleBranch: true + username: "user" + token: "123456789ABCDEFGHI" + +sources: + license: + name: Retrieve license file content + kind: file + scmid: stash + spec: + file: LICENSE diff --git a/content/en/docs/plugins/scm/azuredevops.adoc b/content/en/docs/plugins/scm/azuredevops.adoc index 27cd328aa..175d2c9a2 100644 --- a/content/en/docs/plugins/scm/azuredevops.adoc +++ b/content/en/docs/plugins/scm/azuredevops.adoc @@ -129,10 +129,14 @@ Left unset, `directory` defaults to `/updatecli/azuredevops//> for a full manifest. + TIP: To run the same manifest against every repository of an organization instead of a single one, use the link:/docs/plugins/scm/azuredevopssearch/[`azuredevopssearch`] scm. == Example +=== Default + This pipeline updates the Golang version in a single Azure DevOps repository: the change is committed on a working branch, and the `azuredevops/pullrequest` action turns that branch into a pull request against `main`. [source,yaml] @@ -140,3 +144,12 @@ This pipeline updates the Golang version in a single Azure DevOps repository: th # updatecli.yaml {{}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{}} +---- diff --git a/content/en/docs/plugins/scm/bitbucket.adoc b/content/en/docs/plugins/scm/bitbucket.adoc index f73daf7d1..a94bc335b 100644 --- a/content/en/docs/plugins/scm/bitbucket.adoc +++ b/content/en/docs/plugins/scm/bitbucket.adoc @@ -141,8 +141,12 @@ Left unset, `directory` defaults to `/updatecli/bitbucket//> for a full manifest. + == Example +=== Default + The manifest below picks whichever credential is available in the environment, thanks to the Go template guards around the two blocks. [source,yaml] @@ -150,3 +154,12 @@ The manifest below picks whichever credential is available in the environment, t # updatecli.yaml {{}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{}} +---- diff --git a/content/en/docs/plugins/scm/git.adoc b/content/en/docs/plugins/scm/git.adoc index 98a604ec3..555d83c1c 100644 --- a/content/en/docs/plugins/scm/git.adoc +++ b/content/en/docs/plugins/scm/git.adoc @@ -142,12 +142,16 @@ Left unset, `directory` is derived from the URL under your system temporary dire `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone leaves Updatecli with 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. Setting it to `true` fetches only `branch`, which is much faster on repositories with many refs, at the cost of Updatecli sometimes failing to notice an already published working branch. +On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest. + === Commit identity `user` and `email` name the commit author, defaulting to `updatecli-bot` and `updatecli-bot@updatecli.io`. == Example +=== Default + The manifest below uses three separate scms: one to read a file, one to test a condition, and one over SSH to push a change on a working branch. [source,yaml] @@ -155,3 +159,12 @@ The manifest below uses three separate scms: one to read a file, one to test a c # updatecli.yaml {{< include "assets/code_example/docs/plugins/scm/git/updatecli.d/default.yaml" >}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{< include "assets/code_example/docs/plugins/scm/git/updatecli.d/performance.yaml" >}} +---- diff --git a/content/en/docs/plugins/scm/gitea.adoc b/content/en/docs/plugins/scm/gitea.adoc index 724994545..e829a6db6 100644 --- a/content/en/docs/plugins/scm/gitea.adoc +++ b/content/en/docs/plugins/scm/gitea.adoc @@ -133,10 +133,23 @@ Left unset, `directory` defaults to `/updatecli/gitea//` `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). +On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest. + == Example +=== Default + [source,yaml] ---- # updatecli.yaml {{}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{}} +---- diff --git a/content/en/docs/plugins/scm/github.adoc b/content/en/docs/plugins/scm/github.adoc index 5ddc23b16..aa584f942 100644 --- a/content/en/docs/plugins/scm/github.adoc +++ b/content/en/docs/plugins/scm/github.adoc @@ -146,6 +146,8 @@ Three parameters control how much is fetched, all of them trade-offs on large re `depth`:: Number of commits to fetch. Unset means a full clone. A shallow clone gives Updatecli an incomplete history, which can break pushes; setting `force: true` is often necessary alongside it. `singleBranch`:: Defaults to `false`, meaning every branch, tag, and ref is fetched. Set it to `true` to fetch only `branch`, which is significantly faster on repositories with many refs. In return, Updatecli may fail to notice an already published working branch in some edge cases, and open a duplicate pull request. +On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest. + === GitHub Enterprise Point `url` at your instance, for example `github.example.com`. The scheme is optional and defaults to `https://`. Updatecli then talks to the GraphQL API at `/api/graphql` and clones from `//.git`. Left unset, `url` defaults to `github.com`. @@ -179,3 +181,12 @@ Updatecli checks the remaining GitHub API quota before its GraphQL calls. When t # updatecli.yaml {{}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{}} +---- diff --git a/content/en/docs/plugins/scm/gitlab.adoc b/content/en/docs/plugins/scm/gitlab.adoc index e4b22fc97..d7428ef88 100644 --- a/content/en/docs/plugins/scm/gitlab.adoc +++ b/content/en/docs/plugins/scm/gitlab.adoc @@ -149,12 +149,25 @@ Left unset, `directory` defaults to `/updatecli/gitlab// `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 merge request). +On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and merge request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest. + TIP: To run the same manifest against every project of a group instead of a single repository, use the link:/docs/plugins/scm/gitlabsearch/[`gitlabsearch`] scm. == Example +=== Default + [source,yaml] ---- # updatecli.yaml {{}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{}} +---- diff --git a/content/en/docs/plugins/scm/stash.adoc b/content/en/docs/plugins/scm/stash.adoc index b0dce0a91..07b56308c 100644 --- a/content/en/docs/plugins/scm/stash.adoc +++ b/content/en/docs/plugins/scm/stash.adoc @@ -139,10 +139,23 @@ Left unset, `directory` defaults to `/updatecli/stash//` `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). +On a repository with a large number of refs, `singleBranch` is the option that pays off: it skips the fetch that otherwise mirrors every branch, tag, and pull request ref from the remote. It only applies when `branch` is set. See <<_large_repositories,Large repositories>> for a full manifest. + == Example +=== Default + [source,yaml] ---- # updatecli.yaml {{}} ---- + +[#_large_repositories] +=== Large repositories + +[source,yaml] +---- +# updatecli.yaml +{{}} +----