diff --git a/docs/advanced/github_actions.md b/docs/advanced/github_actions.md index 0612e4966..97986e3c4 100644 --- a/docs/advanced/github_actions.md +++ b/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.23.0 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//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,7 +242,7 @@ 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 ``` @@ -250,7 +250,7 @@ As a result, all installed binaries can be accessed without having to call `pixi 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 ``` diff --git a/docs/advanced/updates_github_actions.md b/docs/advanced/updates_github_actions.md new file mode 100644 index 000000000..c5e47f3a1 --- /dev/null +++ b/docs/advanced/updates_github_actions.md @@ -0,0 +1,77 @@ +--- +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 + - uses: prefix-dev/setup-pixi@v0.8.0 + with: + run-install: false + - run: | + pixi global install pixi-diff-to-markdown + pixi update --json | pixi-diff-to-markdown >> diff.md + - 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 autmated 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). diff --git a/docs/assets/allow-github-actions-prs-dark.png b/docs/assets/allow-github-actions-prs-dark.png new file mode 100644 index 000000000..41a3a5143 Binary files /dev/null and b/docs/assets/allow-github-actions-prs-dark.png differ diff --git a/docs/assets/allow-github-actions-prs-light.png b/docs/assets/allow-github-actions-prs-light.png new file mode 100644 index 000000000..4b9a3664e Binary files /dev/null and b/docs/assets/allow-github-actions-prs-light.png differ diff --git a/docs/assets/update-lockfile-dark.png b/docs/assets/update-lockfile-dark.png new file mode 100644 index 000000000..c7560d691 Binary files /dev/null and b/docs/assets/update-lockfile-dark.png differ diff --git a/docs/assets/update-lockfile-light.png b/docs/assets/update-lockfile-light.png new file mode 100644 index 000000000..7cf72ca12 Binary files /dev/null and b/docs/assets/update-lockfile-light.png differ diff --git a/mkdocs.yml b/mkdocs.yml index e17b23f0b..fd8b11c8e 100644 --- a/mkdocs.yml +++ b/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