docs/integrations/github_actions.md

   1 # GitHub Actions integration
   2
   3 You can use _Black_ within a GitHub Actions workflow without setting your own Python
   4 environment. Great for enforcing that your code matches the _Black_ code style.
   5
   6 ## Compatibility
   7
   8 This action is known to support all GitHub-hosted runner OSes. In addition, only
   9 published versions of _Black_ are supported (i.e. whatever is available on PyPI).
  10
  11 Finally, this action installs _Black_ with the `colorama` extra so the `--color` flag
  12 should work fine.
  13
  14 ## Usage
  15
  16 Create a file named `.github/workflows/black.yml` inside your repository with:
  17
  18 ```yaml
  19 name: Lint
  20
  21 on: [push, pull_request]
  22
  23 jobs:
  24   lint:
  25     runs-on: ubuntu-latest
  26     steps:
  27       - uses: actions/checkout@v3
  28       - uses: psf/black@stable
  29 ```
  30
  31 We recommend the use of the `@stable` tag, but per version tags also exist if you prefer
  32 that. Note that the action's version you select is independent of the version of _Black_
  33 the action will use.
  34
  35 The version of _Black_ the action will use can be configured via `version`. This can be
  36 any
  37 [valid version specifier](https://packaging.python.org/en/latest/glossary/#term-Version-Specifier)
  38 or just the version number if you want an exact version. The action defaults to the
  39 latest release available on PyPI. Only versions available from PyPI are supported, so no
  40 commit SHAs or branch names.
  41
  42 If you want to include Jupyter Notebooks, _Black_ must be installed with the `jupyter`
  43 extra. Installing the extra and including Jupyter Notebook files can be configured via
  44 `jupyter` (default is `false`).
  45
  46 You can also configure the arguments passed to _Black_ via `options` (defaults to
  47 `'--check --diff'`) and `src` (default is `'.'`). Please note that the
  48 [`--check` flag](labels/exit-code) is required so that the workflow fails if _Black_
  49 finds files that need to be formatted.
  50
  51 Here's an example configuration:
  52
  53 ```yaml
  54 - uses: psf/black@stable
  55   with:
  56     options: "--check --verbose"
  57     src: "./src"
  58     jupyter: true
  59     version: "21.5b1"
  60 ```
  61
  62 If you want to match versions covered by Black's
  63 [stability policy](labels/stability-policy), you can use the compatible release operator
  64 (`~=`):
  65
  66 ```yaml
  67 - uses: psf/black@stable
  68   with:
  69     options: "--check --verbose"
  70     src: "./src"
  71     version: "~= 22.0"
  72 ```