blob: 0037f8573c5fb058bc6b1365803fda39ede19cec [file] [view]
# 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+.