updatecli · olblak · Aug 27, 2026
diff --git a/README.md b/README.md
@@ -1,8 +1,12 @@
 # Updatecli Github Action
 
 * [Usage](#usage)
+  * [Updatecli version file](#updatecli-version-file)
   * [Workflow](#workflow)
-* [Deprecation](#deprecation) 
+    * [Manual setup](#manual-setup)
+    * [Scaffold the workflows with an Updatecli policy](#scaffold-the-workflows-with-an-updatecli-policy)
+    * [Keep the workflows up to date](#keep-the-workflows-up-to-date)
+* [Deprecation](#deprecation)
 * [License](#license)
 
 ## Usage
@@ -15,6 +19,13 @@ Install Updatecli for GitHub Action
 
 - `version-file`: The path to a file containing updatecli version. Supported file types are `.updatecli-version` and `.tool-versions`. See more details in [about version-file](#Updatecli-version-file).
 
+Please check whether you need to allow Github Action tokens to create pull
+requests in the repository settings in addition to granting write permissions in
+the workflow. This is [required by GitHub in new repositories](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests).
+
+Go to the Repository Settings → "Actions" → "General" → "Workflow permissions"
+and enable "Allow GitHub Actions to create and approve pull requests"
+
 ### Updatecli version file
 
 If the `version-file` input is specified, the action will extract the version from the file and install it.
@@ -30,6 +41,10 @@ If the file contains multiple versions, only the first one will be recognized.
 
 ### Workflow
 
+#### Manual setup
+
+The minimal workflow to install and run Updatecli on a schedule:
+
 ```yaml
 name: updatecli
 
@@ -59,34 +74,140 @@ jobs:
         uses: updatecli/updatecli-action@v3.6.0
 
       - name: Run Updatecli in Dry Run mode
-        run: updatecli diff
+        run: updatecli pipeline diff --config updatecli/updatecli.d
         env:
           UPDATECLI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Run Updatecli in Apply mode
-        run: updatecli apply --config updatecli/updatecli.d
+        run: updatecli pipeline apply --config updatecli/updatecli.d
         env:
           UPDATECLI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 ```
 
-Please check whether you need to allow Github Action tokens to create pull
-requests in the repository settings in addition to granting write permissions in
-the workflow. This is [required by GitHub in new repositories](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests).
+WARNING: Dont enable --debug mode in Github Action as it may leak information.
+=======
+> [!WARNING]
+> Do not enable `--debug` mode in GitHub Actions as it may leak information.
 
-Go to the Repository Settings → "Actions" → "General" → "Workflow permissions"
-and enable "Allow GitHub Actions to create and approve pull requests"
+#### Scaffold the workflows with an Updatecli policy
 
-WARNING: Dont enable --debug mode in Github Action as it may leak information.
+Instead of writing the workflows by hand, the `updatecli/githubaction/scaffold` policy generates
+them, and re-renders them on every run so their pinned action digests never go stale.
+
+| File | Trigger | What it does |
+| --- | --- | --- |
+| `.github/workflows/updatecli.yaml` | `release`, `workflow_dispatch`, `schedule` | `updatecli compose apply`, opens pull requests |
+| `.github/workflows/updatecli_test.yaml` | `pull_request` | `updatecli compose diff`, read only dry run |
+| `.github/workflows/updatecli_update.yaml` | `workflow_dispatch`, push to the default branch, `schedule` | `updatecli compose apply` over a job matrix, refreshes the pull requests already opened |
+
+Worth knowing before you run it:
+
+* the generated workflows all run `updatecli compose`, so your repository needs an
+  `updatecli-compose.yaml`. This policy does not create one for you.
+* the three workflow files become policy owned. They are rewritten in full on every run, so any
+  hand edit is reverted. Use the `gha.steps` value to add your own steps.
+* writing into `.github/workflows/` requires a token with the `workflow` scope on top of `repo`.
+* do not run it alongside `ghcr.io/updatecli/policies/updatecli/githubaction`. Both rewrite the
+  same files and would revert each other on every run.
+
+From the root of your repository:
+
+```bash
+# The policy reads its token from GITHUB_TOKEN, configurable with the scm.env_token value
+export GITHUB_TOKEN=<PAT with the repo and workflow scopes>
+
+# To show what would be created
+updatecli diff ghcr.io/updatecli/policies/updatecli/githubaction/scaffold:0.1.1
+# To apply the changes if you are happy with the diff
+updatecli apply ghcr.io/updatecli/policies/updatecli/githubaction/scaffold:0.1.1
+```
+
+Run that way the policy uses its default `scm.enabled: false`: the workflows are written to your
+working copy, and committing them is up to you.
+
+The policy documentation can be found [here](https://github.com/updatecli/policies/tree/main/updatecli/policies/updatecli/githubaction/scaffold).
+
+#### Keep the workflows up to date
+
+To keep the generated workflows in sync with the policy, declare it in an Updatecli compose file
+instead of running it once. That compose file is also the one the generated workflows execute.
+
+`updatecli-compose.yaml`
+
+```yaml
+# export GITHUB_TOKEN=<PAT with the repo and workflow scopes>
+# export UPDATECLI_GITHUB_TOKEN=<PAT used by your own manifests>
+# updatecli compose diff
+# updatecli compose apply
+
+name: Default Updatecli Policies
+
+valuesinline:
+  scm:
+    enabled: true
+    user: updatecli
+    email: bot@updatecli.io
+    owner: <replace with your GitHub organization>
+    repository: <replace with your GitHub repository>
+    username: "updatecli-bot"
+    branch: main
+
+policies:
+  - name: Local Updatecli policies
+    id: local
+    config:
+      - updatecli/updatecli.d
+
+  - name: Configure Updatecli workflows
+    id: updatecli
+    policy: ghcr.io/updatecli/policies/updatecli/githubaction/scaffold:0.1.1
+    valuesinline:
+      gha:
+        # Credentials referenced by the generated workflows
+        #   token -> secrets.GITHUB_TOKEN, works with no further setup
+        #   app   -> UPDATECLIBOT_APP_* secrets, the default, used by the Updatecli project itself
+        auth: token
+        udash:
+          # Reports the pipeline results to Udash, requires the UPDATECLI_UDASH_* secrets
+          enabled: false
+        apply:
+          # Opens new pull requests, default "0 12 */14 * *"
+          cron: "0 12 */14 * *"
+        update:
+          # Refreshes the existing ones, default "0 1 * * *"
+          cron: "0 3 * * *"
+          matrix:
+            - target_name: "existing pipelines"
+              apply_args: "--existing-only=true"
+            # Only useful if you label your manifests with "monitor: active"
+            - target_name: "monitored pipelines"
+              apply_args: "--labels=monitor:active"
+```
+
+With this configuration, the policy installs the three workflows described above:
+
+* `updatecli.yaml` opens new pull requests every two weeks, as set by `gha.apply.cron`
+* `updatecli_update.yaml` refreshes the pull requests already opened by Updatecli, on every push to
+  the default branch and once a day at 3 AM UTC, as set by `gha.update.cron`
+* `updatecli_test.yaml` runs Updatecli in dry run mode on every pull request
+
+More Updatecli policies are available on [updatecli/policies](https://github.com/updatecli/policies).
+>>>>>>> 8d9036c (doc: update documentation)
 
 ## Deprecation
 
 > [!IMPORTANT]  
-> The branch v1 and v2 are deprecated and will be remove soon.
+> The branch v1 and v2 are deprecated and will be removed at some point.
 > You should use GitHub action version instead (or track the main branch if you really want to).
 > You can migrate to the latest GitHub action version using the following Updatecli policy:
 
-.updatecli-compose.yaml
-```
+This policy patches the `uses:` and `with.version` of your existing workflows. It is an
+alternative to the [scaffold policy](#scaffold-the-workflows-with-an-updatecli-policy), not a
+companion: running both continuously makes them revert each other on every run.
+
+`updatecli-compose.yaml`
+
+```yaml
 # export UPDATECLI_GITHUB_TOKEN=<insert PAT>
 # export UPDATECLI_GITHUB_USERNAME=<insert username>
 # updatecli compose diff --file updatecli-compose.yaml
@@ -105,10 +226,10 @@ valuesinline:
 
 policies:
   - name: Update Updatecli GitHub action version
-    policy: ghcr.io/updatecli/policies/updatecli/githubaction:0.8.1
+    policy: ghcr.io/updatecli/policies/updatecli/githubaction:0.9.1
 ```
 
 ## License
 
-MIT. See `LICENSE` for more details.
+Apache-2.0. See `LICENSE` for more details.
 
diff --git a/updatecli/updatecli.d/readme.yaml b/updatecli/updatecli.d/readme.yaml
@@ -48,14 +48,33 @@ sources:
       versionfilter:
         kind: semver
 
+  version-policy-githubaction-scaffold:
+    name: Get latest updatecli/githubaction/scaffold policy version
+    kind: dockerimage
+    spec:
+      image: ghcr.io/updatecli/policies/updatecli/githubaction/scaffold
+      versionfilter:
+        kind: semver
+
+  version-policy-githubaction:
+    name: Get latest updatecli/githubaction policy version
+    kind: dockerimage
+    spec:
+      image: ghcr.io/updatecli/policies/updatecli/githubaction
+      versionfilter:
+        kind: semver
+
 targets:
+  # matchpattern captures a bare version (vX.Y.Z or X.Y.Z) rather than the rest of the
+  # line, so a tracked reference does not have to sit at the end of its line.
+  # A digest pinned reference (:X.Y.Z@sha256:...) needs its own pattern.
   version-updatecli-action:
     name: 'docs: update issue template with Updatecli gha version to {{ source "version-updatecli-action" }}'
     disablesourceinput: true
     kind: file
     spec:
       file: README.md
-      matchpattern: "uses: updatecli/updatecli-action@(.*)"
+      matchpattern: 'uses: updatecli/updatecli-action@(v?\d+\.\d+\.\d+)'
       replacepattern: 'uses: updatecli/updatecli-action@{{ source "version-updatecli-action" }}'
     scmid: default
 
@@ -65,6 +84,26 @@ targets:
     kind: file
     spec:
       file: README.md
-      matchpattern: "uses: actions/checkout@(.*)"
+      matchpattern: 'uses: actions/checkout@(v?\d+\.\d+\.\d+)'
       replacepattern: 'uses: actions/checkout@{{ source "version-actions-checkout" }}'
     scmid: default
+
+  version-policy-githubaction-scaffold:
+    name: 'docs: update updatecli/githubaction/scaffold policy version to {{ source "version-policy-githubaction-scaffold" }}'
+    disablesourceinput: true
+    kind: file
+    spec:
+      file: README.md
+      matchpattern: 'updatecli/githubaction/scaffold:(v?\d+\.\d+\.\d+)'
+      replacepattern: 'updatecli/githubaction/scaffold:{{ source "version-policy-githubaction-scaffold" }}'
+    scmid: default
+
+  version-policy-githubaction:
+    name: 'docs: update updatecli/githubaction policy version to {{ source "version-policy-githubaction" }}'
+    disablesourceinput: true
+    kind: file
+    spec:
+      file: README.md
+      matchpattern: 'updatecli/githubaction:(v?\d+\.\d+\.\d+)'
+      replacepattern: 'updatecli/githubaction:{{ source "version-policy-githubaction" }}'
+    scmid: default