doc: Add azure devops documentation

assets/code_example/docs/plugins/actions/azuredevops_pullrequest/updatecli.yaml

@@ -0,0 +1,40 @@
+name: Update a file and open an Azure DevOps Pull Request
+
+scms:
+  default:
+    kind: azuredevops
+    spec:
+      organization: myorg
+      project: myproject
+      repository: myrepo
+      branch: main
+      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'

assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/default.yaml

@@ -0,0 +1,40 @@
+name: Update a file and open an Azure DevOps Pull Request
+
+scms:
+  default:
+    kind: azuredevops
+    spec:
+      organization: myorg
+      project: myproject
+      repository: myrepo
+      branch: main
+      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'

assets/code_example/docs/plugins/scm/azuredevopssearch/updatecli.d/default.yaml

@@ -0,0 +1,48 @@
+name: "Updatecli Golang - Azure DevOps Multi-Repo"
+pipelineid: "golang/version"
+
+scms:
+  default:
+    kind: azuredevopssearch
+    spec:
+      organization: myorg
+      project: "^myproject$"
+      repository: "^.*$"
+      branch: "^main$"
+      token: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_TOKEN" }}'
+      username: '{{ requiredEnv "UPDATECLI_AZURE_DEVOPS_USERNAME" }}'
+      user: updatecli
+      email: updatecli@example.com
+      commitmessage:
+        squash: true
+        type: chore
+        scope: deps
+        title: "update Golang version"
+
+actions:
+  default:
+    kind: azuredevops/pullrequest
+    scmid: default
+    spec:
+      title: "deps(golang): Bump Golang version"
+
+sources:
+  golang:
+    name: Get the latest Golang version
+    kind: golang
+    spec:
+      versionfilter:
+        kind: semver
+        pattern: "1.24.x"
+
+targets:
+  github-action:
+    name: 'deps(github-action): Bump Golang version to {{ source "golang" }}'
+    kind: yaml
+    scmid: default
+    spec:
+      engine: yamlpath
+      files:
+        - ".github/workflows/*"
+      key: '$.jobs.build.steps[?(@.uses =~ /^actions\/setup-go/)].with.go-version'
+      searchpattern: true

content/en/docs/plugins/_azuredevopsAuth.adoc

@@ -0,0 +1,69 @@
+Updatecli supports Personal Access Token (PAT) authentication for interacting with Azure DevOps. You can authenticate using environment variables or directly in your manifest.
+
+'''
+
+**1. Personal Access Token via Environment Variables**
+
+Set the following environment variables to enable PAT authentication:
+
+- `UPDATECLI_AZURE_DEVOPS_TOKEN`: Your Azure DevOps Personal Access Token
+- `UPDATECLI_AZURE_DEVOPS_USERNAME`: Your Azure DevOps username
+
+Example:
+
+[source,shell]
+----
+export UPDATECLI_AZURE_DEVOPS_TOKEN="your-pat-token"
+export UPDATECLI_AZURE_DEVOPS_USERNAME="your-username"
+----
+
+[NOTE]
+====
+When these variables are set, Updatecli will use them for all Azure DevOps operations.
+====
+
+'''
+
+**2. Personal Access Token via Manifest**
+
+You can specify your Personal Access Token directly in your Updatecli manifest under the `spec.token` and `spec.username` fields:
+
+[source,yaml]
+----
+scms:
+  default:
+    kind: azuredevops
+    spec:
+      organization: myorg
+      project: myproject
+      repository: myrepo
+      token: "{{ requiredEnv `UPDATECLI_AZURE_DEVOPS_TOKEN` }}"
+      username: "{{ requiredEnv `UPDATECLI_AZURE_DEVOPS_USERNAME` }}"
+----
+
+[WARNING]
+====
+For security reasons, it is recommended to use environment variables or secret management tools (like SOPS) instead of hardcoding tokens in your manifest.
+====
+
+'''
+
+**Precedence and Fallback**
+
+Updatecli will use the first valid authentication method it finds, in the following order:
+
+. Personal Access Token via environment variables
+. Personal Access Token via manifest
+
+If no valid authentication is found, Updatecli will fail with an error.
+
+'''
+
+**Further Reading**
+
+- https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate[Azure DevOps: Use personal access tokens]
+- https://www.updatecli.io/docs/plugins/scm/azuredevops/[Updatecli Azure DevOps SCM Plugin Documentation]
+
+'''
+
+*Tip:* For best security and maintainability, prefer using environment variables for authentication, and avoid hardcoding secrets in your manifests.

content/en/docs/plugins/actions/azuredevops.adoc

@@ -0,0 +1,43 @@
+---
+title: "Azure DevOps Pull Request"
+description: "Open an Azure DevOps Pull Request"
+lead: "kind: azuredevops/pullrequest"
+date: 2025-05-12T00:00:00+00:00
+draft: false
+images: []
+menu:
+  docs:
+    parent: "plugin-actions"
+toc: true
+plugins:
+  - actions
+---
+
+// <!-- Required for asciidoctor -->
+:toc:
+// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
+:toclevels: 4
+
+== Description
+
+The `actions` section describes the link:https://learn.microsoft.com/en-us/azure/devops/repos/git/pull-requests[Azure DevOps Pull Requests] that Updatecli is expected to open (or update) when the manifest is applied.
+
+The `azuredevops/pullrequest` action is typically paired with an `azuredevops` or `azuredevopssearch` SCM block. Updatecli will create or update a pull request from the working branch to the target branch whenever a target produces a change.
+
+== Parameters
+
+{{< resourceparameters "actions" "azuredevops/pullrequest" >}}
+
+== Example
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/actions/azuredevops_pullrequest/updatecli.yaml">}}
+----
+
+== Links
+
+* link:https://learn.microsoft.com/en-us/azure/devops/repos/git/pull-requests[Documentation: Azure DevOps Pull Requests]
+* link:https://learn.microsoft.com/en-us/azure/devops/repos/git/branch-policies[Documentation: Azure DevOps Branch Policies]
+* link:https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate[Documentation: Azure DevOps Personal Access Tokens]

content/en/docs/plugins/scm/azuredevops.adoc

@@ -0,0 +1,72 @@
+---
+title: "Azure DevOps"
+description: "Interact with Azure DevOps repositories"
+lead: "kind: azuredevops"
+date: 2025-05-12T00:00:00+00:00
+draft: false
+images: []
+menu:
+  docs:
+    parent: "plugin-scm"
+toc: true
+plugins:
+  - scm
+---
+// <!-- Required for asciidoctor -->
+:toc:
+// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
+:toclevels: 4
+
+== Description
+
+The Azure DevOps SCM plugin is used to manage git repositories hosted on Azure DevOps. Depending on the stage, it can be used for different purposes:
+
+**condition**
+
+When used in a condition, the SCM block fetches files or metadata from the specified Azure DevOps repository.
+
+**target**
+
+When used in a target, the SCM block pushes changes to that repository.
+
+By default, the Azure DevOps SCM uses a working branch workflow: it creates a temporary branch, commits the changes, and opens a pull request targeting the branch defined in the configuration.
+
+== Parameters
+
+{{< resourceparameters "scms" "azuredevops" >}}
+
+=== Authentication
+
+include::content/en/docs/plugins/_azuredevopsAuth.adoc[]
+
+=== CommitMessage
+
+Updatecli uses conventional commits as describe on link:https://www.conventionalcommits.org/[www.conventionnalcommits.org]. +
+The goal is to add human and machine readable meaning to commit messages
+
+By default, Updatecli generates a commit message using the default type "chore" and split long title message into the body like:
+
+---
+```
+Author: olblak <updatecli@updatecli.io>
+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
+```
+---
+
+== Example
+
+This pipeline automatically updates the Golang version in an Azure DevOps repository.
+Updatecli retrieves the latest matching Golang version and opens a pull request that updates the build workflow file accordingly.
+It creates the pull request on a temporary working branch, following the Azure DevOps workflow.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/azuredevops/updatecli.d/default.yaml">}}
+----

content/en/docs/plugins/scm/azuredevopssearch.adoc

@@ -0,0 +1,72 @@
+---
+title: "Azure DevOps Search"
+description: "Use Azure DevOps search to interact with multiple repositories"
+lead: "kind: azuredevopssearch"
+date: 2025-05-12T00:00:00+00:00
+draft: false
+images: []
+menu:
+  docs:
+    parent: "plugin-scm"
+toc: true
+plugins:
+  - scm
+---
+// <!-- Required for asciidoctor -->
+:toc:
+// Set toclevels to be at least your hugo [markup.tableOfContents.endLevel] config key
+:toclevels: 4
+
+== Description
+
+The Azure DevOps Search SCM plugin allows you to interact with multiple Azure DevOps repositories at once — either by fetching files or by pushing updates to them. Repositories are discovered dynamically using regex patterns for project name, repository name, and branch name.
+
+**condition**
+
+When used in a condition, the SCM block typically fetches files or metadata from the matching repositories.
+
+**target**
+
+When used in a target, the SCM block pushes changes to all matching repositories.
+
+By default, the Azure DevOps Search SCM uses a working branch workflow: it creates a temporary branch, commits the changes, and opens a pull request targeting the branch defined in the configuration for each matching repository.
+
+== Parameters
+
+{{< resourceparameters "scms" "azuredevopssearch" >}}
+
+=== Authentication
+
+include::content/en/docs/plugins/_azuredevopsAuth.adoc[]
+
+=== CommitMessage
+
+Updatecli uses conventional commits as describe on link:https://www.conventionalcommits.org/[www.conventionnalcommits.org]. +
+The goal is to add human and machine readable meaning to commit messages
+
+By default, Updatecli generates a commit message using the default type "chore" and split long title message into the body like:
+
+---
+```
+Author: olblak <updatecli@updatecli.io>
+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
+```
+---
+
+== Example
+
+This pipeline automatically updates the Golang version across multiple Azure DevOps repositories within the `myorg` organization.
+Using the `azuredevopssearch` SCM, it discovers all repositories within projects and branches matching the configured regex patterns, and opens pull requests that update the Golang version in the build workflows accordingly.
+All changes are squashed into one commit per repository.
+
+[source,yaml]
+----
+# updatecli.yaml
+{{<include "assets/code_example/docs/plugins/scm/azuredevopssearch/updatecli.d/default.yaml">}}
+----