diff --git a/README.md b/README.md index 725f9dd7..98bb58b6 100644 --- 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= + +# 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= +# export UPDATECLI_GITHUB_TOKEN= +# updatecli compose diff +# updatecli compose apply + +name: Default Updatecli Policies + +valuesinline: + scm: + enabled: true + user: updatecli + email: bot@updatecli.io + owner: + 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= # export UPDATECLI_GITHUB_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 index d3905347..b2b6473d 100644 --- 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