Introduction

In this article, I will explain the specifics of integrating Black with GitHub Actions.

Setting up a GitHub Action for Black

To set up a GitHub Action that uses Black to format your Python code, follow these steps:

1. Create a Workflow File

In your repository, create a directory named .github and within it, create another directory named workflows. In the workflows directory, create a new file named black.yml. This file will define the workflow.

2. Define the Workflow

In the black.yml file, define the workflow. Below is an example workflow configuration:

name: Code Formatting with Black

on: [push, pull_request]

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.x'

      - name: Install Black
        run: pip install black

      - name: Check code formatting with Black
        run: black --check .

Let’s break down what this configuration does:

• The workflow is named “Code Formatting with Black”.
• It triggers on both push and pull_request events.
• There is a single job named format.
• The job runs on the latest Ubuntu.
• It checks out your code.
• Sets up Python 3.x.
• Installs Black.
• Runs Black in check mode to see if the code is properly formatted.

3. Commit and Push the Workflow File

Commit the .github/workflows/black.yml file to your repository and push it to GitHub.

$ git add .github/workflows/black.yml
$ git commit -m "Add Black formatting check workflow"
$ git push

Handling Workflow Results

Once you've pushed the workflow file, GitHub Actions will start running the workflow on the specified events (pushes and pull requests in this example). If Black finds that code is not properly formatted, the workflow will fail.

• If the workflow fails, you should run Black locally to format the code, commit the changes, and push them.

$ black .
$ git add .
$ git commit -m "Format code with Black"
$ git push

• If the workflow passes, it means your code is properly formatted according to Black's rules.

Automating Code Formatting

In some cases, you might want to automate the process of code formatting with Black as part of your GitHub Actions workflow. This means that instead of just checking whether the code complies with Black's style, the workflow would actually format the code automatically and push the changes back to the repository.

While this approach can save you time, it's important to use it with caution. Automatically pushing changes to the repository can create unexpected results, especially if multiple contributors are working on the project concurrently.

Here are the steps to set up a GitHub Action for automated code formatting:

1. Create a Personal Access Token

To push changes from the workflow back to your repository, you need a GitHub Personal Access Token (PAT). The PAT will have permissions to perform actions on behalf of your GitHub user.

To create a PAT, go to your GitHub Settings, then select "Developer settings" > "Personal access tokens". Click "Generate new token", give the token a descriptive name, and select the necessary permissions. For this use case, you'll need at least the repo permission. Click "Generate token" and make sure to save the token somewhere secure - you won't be able to view it again.

2. Add the PAT as a Secret

Next, you need to add the PAT as a secret to your repository so it can be accessed by the GitHub Action. Go to your repository's settings, then select "Secrets" > "New repository secret". Enter a name for the secret (e.g., BLACK_FORMATTER_TOKEN) and paste your PAT as the value.

3. Modify the Workflow File

Adjust your workflow file to format the code with Black and push changes if necessary. Below is an example of a modified workflow:

name: Automated Code Formatting with Black

on: [push, pull_request]

jobs:
  format:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
        with:
          token: ${{ secrets.BLACK_FORMATTER_TOKEN }}  # Use the PAT to check out code

      - name: Set up Python
        uses: actions/setup-python@v2
        with:
          python-version: '3.x'

      - name: Install Black
        run: pip install black

      - name: Format code with Black
        run: black .

      - name: Commit and push changes
        run: |
          git config --local user.email "action@github.com"
          git config --local user.name "GitHub Action"
          git commit -am "Format code with Black" || exit 0  # The exit 0 is used to prevent the workflow from failing if no changes are made
          git push

4. Commit and Push the Workflow File

Commit the modified .github/workflows/black.yml file to your repository and push it to GitHub.

$ git add .github/workflows/black.yml
$ git commit -m "Modify workflow for automated formatting"
$ git push

After these steps, the workflow will not only check the code formatting but also automatically format the code and push the changes back to the repository if necessary.