docs: automatic updating using github actions

.github/workflows/update-lockfiles.yml

@@ -0,0 +1,37 @@
+name: Update lockfiles
+
+permissions:
+  contents: write
+  pull-requests: write
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: 0 5 1 * *
+
+jobs:
+  pixi-update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up pixi
+        uses: prefix-dev/[email protected]
+        with:
+          run-install: false
+      - name: Update lockfiles
+        run: |
+          set -euo pipefail
+          pixi global install pixi-diff-to-markdown
+          pixi update --json --no-install | pixi-diff-to-markdown >> diff.md
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: 'bump: update pixi lockfile'
+          title: 'bump: update pixi lockfile'
+          body-path: diff.md
+          branch: update-pixi
+          base: main
+          labels: pixi
+          delete-branch: true
+          add-paths: pixi.lock

docs/advanced/github_actions.md

@@ -13,7 +13,7 @@ We created [prefix-dev/setup-pixi](https://github.com/prefix-dev/setup-pixi) to
 ## Usage
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     pixi-version: v0.24.2
     cache: true
@@ -24,7 +24,7 @@ We created [prefix-dev/setup-pixi](https://github.com/prefix-dev/setup-pixi) to
 
 !!!warning "Pin your action versions"
     Since pixi is not yet stable, the API of this action may change between minor versions.
-    Please pin the versions of this action to a specific version (i.e., `prefix-dev/setup-pixi@v0.7.0`) to avoid breaking changes.
+    Please pin the versions of this action to a specific version (i.e., `prefix-dev/setup-pixi@v0.8.0`) to avoid breaking changes.
     You can automatically update the version of this action by using [Dependabot](https://docs.github.com/en/code-security/dependabot/working-with-dependabot/keeping-your-actions-up-to-date-with-dependabot).
 
     Put the following in your `.github/dependabot.yml` file to enable Dependabot for your GitHub Actions:
@@ -66,7 +66,7 @@ You can specify the behavior by setting the `cache` input argument.
     This can be done by setting the `cache-write` argument.
 
     ```yaml
-    - uses: prefix-dev/setup-pixi@v0.5.1
+    - uses: prefix-dev/setup-pixi@v0.8.0
       with:
         cache: true
         cache-write: ${{ github.event_name == 'push' && github.ref_name == 'main' }}
@@ -111,7 +111,7 @@ test:
       environment: [py311, py312]
   steps:
   - uses: actions/checkout@v4
-  - uses: prefix-dev/setup-pixi@v0.7.0
+  - uses: prefix-dev/setup-pixi@v0.8.0
     with:
       environments: ${{ matrix.environment }}
 ```
@@ -121,7 +121,7 @@ test:
 The following example will install both the `py311` and the `py312` environment on the runner.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     environments: >- # (1)!
       py311
@@ -161,7 +161,7 @@ Specify the token using the `auth-token` input argument.
 This form of authentication (bearer token in the request headers) is mainly used at [prefix.dev](https://prefix.dev).
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     auth-host: prefix.dev
     auth-token: ${{ secrets.PREFIX_DEV_TOKEN }}
@@ -173,7 +173,7 @@ Specify the username and password using the `auth-username` and `auth-password`
 This form of authentication (HTTP Basic Auth) is used in some enterprise environments with [artifactory](https://jfrog.com/artifactory) for example.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     auth-host: custom-artifactory.com
     auth-username: ${{ secrets.PIXI_USERNAME }}
@@ -186,7 +186,7 @@ Specify the conda-token using the `conda-token` input argument.
 This form of authentication (token is encoded in URL: `https://my-quetz-instance.com/t/<token>/get/custom-channel`) is used at [anaconda.org](https://anaconda.org) or with [quetz instances](https://github.com/mamba-org/quetz).
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     auth-host: anaconda.org # (1)!
     conda-token: ${{ secrets.CONDA_TOKEN }}
@@ -242,15 +242,15 @@ To this end, `setup-pixi` adds all environment variables set when executing `pix
 As a result, all installed binaries can be accessed without having to call `pixi run`.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     activate-environment: true
 ```
 
 If you are installing multiple environments, you will need to specify the name of the environment that you want to be activated.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     environments: >-
       py311
@@ -267,7 +267,7 @@ You can specify whether `setup-pixi` should run `pixi install --frozen` or `pixi
 See the [official documentation](https://prefix.dev/docs/pixi/cli#install) for more information about the `--frozen` and `--locked` flags.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     locked: true
     # or
@@ -297,7 +297,7 @@ The second type is the debug logging of the pixi executable.
 This can be specified by setting the `log-level` input.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     log-level: vvv # (1)!
 ```
@@ -324,7 +324,7 @@ If nothing is specified, `post-cleanup` will default to `true`.
 On self-hosted runners, you also might want to alter the default pixi install location to a temporary location. You can use `pixi-bin-path: ${{ runner.temp }}/bin/pixi` to do this.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     post-cleanup: true
     pixi-bin-path: ${{ runner.temp }}/bin/pixi # (1)!
@@ -340,7 +340,7 @@ You can also use a preinstalled local version of pixi on the runner by not setti
 This can be overwritten by setting the `manifest-path` input argument.
 
 ```yaml
-- uses: prefix-dev/setup-pixi@v0.7.0
+- uses: prefix-dev/setup-pixi@v0.8.0
   with:
     manifest-path: pyproject.toml
 ```

docs/advanced/updates_github_actions.md

@@ -0,0 +1,80 @@
+---
+part: pixi/advanced
+title: Update lockfiles with GitHub Actions
+description: Learn how to use GitHub Actions to automatically update your pixi lockfiles.
+---
+
+You can leverage GitHub Actions in combination with [pavelzw/pixi-diff-to-markdown](https://github.com/pavelzw/pixi-diff-to-markdown)
+to automatically update your lockfiles similar to dependabot or renovate in other ecosystems.
+
+![Update lockfiles](../assets/update-lockfile-light.png#only-light)
+![Update lockfiles](../assets/update-lockfile-dark.png#only-dark)
+
+!!!note "Dependabot/Renovate support for pixi"
+    You can track native Dependabot support for pixi in [dependabot/dependabot-core #2227](https://github.com/dependabot/dependabot-core/issues/2227#issuecomment-1709069470)
+    and for Renovate in [renovatebot/renovate #2213](https://github.com/renovatebot/renovate/issues/2213).
+
+## How to use
+
+To get started, create a new GitHub Actions workflow file in your repository.
+
+```yaml title=".github/workflows/update-lockfiles.yml"
+name: Update lockfiles
+
+permissions: # (1)!
+  contents: write
+  pull-requests: write
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: 0 5 1 * * # (2)!
+
+jobs:
+  pixi-update:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up pixi
+        uses: prefix-dev/[email protected]
+        with:
+          run-install: false
+      - name: Update lockfiles
+        run: |
+          pixi global install pixi-diff-to-markdown
+          pixi update --json --no-install | pixi-diff-to-markdown >> diff.md
+      - name: Create pull request
+        uses: peter-evans/create-pull-request@v6
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          commit-message: Update pixi lockfile
+          title: Update pixi lockfile
+          body-path: diff.md
+          branch: update-pixi
+          base: main
+          labels: pixi
+          delete-branch: true
+          add-paths: pixi.lock
+```
+
+1. Needed for `peter-evans/create-pull-request`
+2. Runs at 05:00, on day 1 of the month
+
+In order for this workflow to work, you need to set "Allow GitHub Actions to create and approve pull requests" to true in your repository settings (in "Actions" -> "General").
+
+![Allow GitHub Actions PRs](../assets/allow-github-actions-prs-light.png#only-light)
+![Allow GitHub Actions PRs](../assets/allow-github-actions-prs-dark.png#only-dark)
+
+## Triggering CI in automated PRs
+
+In order to prevent accidental recursive GitHub Workflow runs, GitHub decided to not trigger any workflows on automated PRs when using the default `GITHUB_TOKEN`.
+There are a couple of ways how to work around this limitation. You can find excellent documentation for this in `peter-evans/create-pull-request`, see [here](https://github.com/peter-evans/create-pull-request/blob/main/docs/concepts-guidelines.md#triggering-further-workflow-runs).
+
+## Customizing the summary
+
+You can customize the summary by either using command-line-arguments of `pixi-diff-to-markdown` or by specifying the configuration in `pixi.toml` under `[tool.pixi-diff-to-markdown]`. See the [pixi-diff-to-markdown documentation](https://github.com/pavelzw/pixi-diff-to-markdown) or run `pixi-diff-to-markdown --help` for more information.
+
+## Using reusable workflows
+
+If you want to use the same workflow in multiple repositories in your GitHub organization, you can create a reusable workflow.
+You can find more information in the [GitHub documentation](https://docs.github.com/en/actions/using-workflows/reusing-workflows).

mkdocs.yml

@@ -121,6 +121,7 @@ nav:
       - Info Command: advanced/explain_info_command.md
       - Channel Logic: advanced/channel_priority.md
       - GitHub Actions: advanced/github_actions.md
+      - Updates using GitHub Actions: advanced/updates_github_actions.md
       - Pyproject.toml: advanced/pyproject_toml.md
   - Reference:
       - Project Configuration: reference/project_configuration.md