| # GitHub Actions integration | |
| You can use _Black_ within a GitHub Actions workflow without setting your own Python | |
| environment. Great for enforcing that your code matches the _Black_ code style. | |
| ## Compatibility | |
| This action is known to support all GitHub-hosted runner OSes. In addition, only | |
| published versions of _Black_ are supported (i.e. whatever is available on PyPI). | |
| Finally, this action installs _Black_ with the `colorama` extra so the `--color` flag | |
| should work fine. | |
| ## Usage | |
| Create a file named `.github/workflows/black.yml` inside your repository with: | |
| ```yaml | |
| name: Lint | |
| on: [push, pull_request] | |
| jobs: | |
| lint: | |
| runs-on: ubuntu-latest | |
| steps: | |
| - uses: actions/checkout@v6 | |
| - uses: psf/black@stable | |
| ``` | |
| We recommend the use of the `@stable` tag, but per version tags also exist if you prefer | |
| that. Note that the action's version you select is independent of the version of _Black_ | |
| the action will use. | |
| ### Versions | |
| The version of _Black_ the action will use can be configured via `version` or read from | |
| the `pyproject.toml` file. The action defaults to the latest release available on PyPI. | |
| `version` can be any | |
| [valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier) | |
| or just the version number if you want an exact version. | |
| If you want to match versions covered by Black's | |
| [stability policy](labels/stability-policy), you can use the compatible release operator | |
| (`~=`): | |
| ```yaml | |
| - uses: psf/black@stable | |
| with: | |
| options: "--check --verbose" | |
| src: "./src" | |
| version: "~= 26.0" | |
| ``` | |
| To read the version from the `pyproject.toml` file instead, set `use_pyproject` to | |
| `true`. This will first look into the `tool.black.required-version` field, then the | |
| `dependency-groups` table, then the `project.dependencies` array and finally the | |
| `project.optional-dependencies` table. Note that this requires Python >= 3.11, so using | |
| the setup-python action may be required, for example: | |
| ```yaml | |
| - uses: actions/setup-python@v6 | |
| with: | |
| python-version: "3.11" | |
| - uses: psf/black@stable | |
| with: | |
| options: "--check --verbose" | |
| src: "./src" | |
| use_pyproject: true | |
| ``` | |
| ```{note} | |
| This action only reads version specifiers from standard `pyproject.toml` locations. | |
| Poetry-specific dependency tables such as `tool.poetry.dependencies` are not parsed. | |
| If you manage `black` with Poetry, set `tool.black.required-version` or use the | |
| `version` input. | |
| ``` | |
| **Security note:** `use_pyproject` only accepts standard version specifiers for `black` | |
| (for example `==`, `~=`, `>=` and ranges like `>=25,<26`). Only versions available from | |
| PyPI are supported, so no commit SHAs or branch names. Direct references such as | |
| `black @ https://...` are also not supported. If your workflow runs on untrusted pull | |
| requests (for example from forks), prefer setting `with.version` explicitly. | |
| ### Jupyter Notebooks | |
| If you want to include Jupyter Notebooks, it can be enabled by setting `jupyter` to | |
| `true` (default is `false`): | |
| ```yaml | |
| - uses: psf/black@stable | |
| with: | |
| jupyter: true | |
| ``` | |
| See the [Jupyter Notebooks guide](../guides/using_black_with_jupyter_notebooks.md) for | |
| more details. | |
| ### CLI Options | |
| You can also configure the arguments passed to _Black_ via `options` (defaults to | |
| `'--check --diff'`) and `src` (default is `'.'`). Please note that the | |
| [`--check` flag](labels/exit-code) is required so that the workflow fails if _Black_ | |
| finds files that need to be formatted. | |
| Here's an example configuration: | |
| ```yaml | |
| - uses: psf/black@stable | |
| with: | |
| options: "--check --verbose" | |
| src: "./src" | |
| jupyter: true | |
| version: "21.5b1" | |
| ``` | |
| ### Job summary and output file | |
| By default the action also adds _Black_'s output to the workflow's job summary. Set | |
| `summary` to `false` to turn that off. | |
| If you want to keep the output around, for example to upload it as an artifact or use it | |
| in a later step, set `output-file` to a path. The output is then written to that file as | |
| well as printed in the log. | |
| ```yaml | |
| - uses: psf/black@stable | |
| with: | |
| summary: false | |
| output-file: "black-output.txt" | |
| ``` | |
| ### Outputs | |
| The action provides the following outputs: | |
| - `is_formatted`: Set to `"true"` if any files were reformatted (or in `--check` mode, | |
| would be reformatted); `"false"` otherwise. This can be used to run subsequent steps | |
| conditionally (for example, auto-committing formatted changes). | |
| - `change_count`: Number of files that were reformatted (or would be reformatted in | |
| `--check` mode). | |
| - `same_count`: Number of files that were left unchanged. | |
| - `failure_count`: Number of files that failed to reformat. | |
| These outputs are only accessible if the action version as well as `with.version` are | |
| both 26.10.0+. |