Integrating Code Formatting and Linting Checks in GitHub Actions

In professional software development workflows, the standard approach to handling code formatting and linting issues in CI/CD pipelines involves a combination of automation and manual review.

A Practical Guide to Code Formatting and Linting in GitHub Actions Workflows

Introduction

Here’s a breakdown of the common practices and why they are preferred:

Standard Approach for Handling Code Formatting

Automate Checks and Report Issues
- CI/CD Workflow: Run code formatting and linting checks as part of your CI/CD pipeline. This ensures that code quality issues are detected early in the development process.
- Check-Only Mode: Configure the CI/CD pipeline to use black --check, flake8, and isort --check to report issues without automatically applying changes. This approach ensures that issues are identified but requires manual intervention to fix them.
```
- name: Run Black
  run: pipenv run black --check .

- name: Run Flake8
  run: pipenv run flake8 .

- name: Run isort
  run: pipenv run isort --check .
```
Manual Fixes and Reviews
- Local Fixes: Developers run the formatting and linting tools locally before pushing changes. This allows developers to address issues interactively.
- Pull Request Reviews: Ensure that all formatting issues are resolved before merging code. Code reviews can include checks for formatting compliance.
```
pipenv run black .
pipenv run flake8 .
pipenv run isort .
```
Branch Protection Rules
- Enforce Standards: Set up branch protection rules to ensure that code cannot be merged into important branches (e.g., main or develop) unless all required checks pass.
- Status Checks: Configure required status checks to prevent merging if formatting or linting issues are present.
GitHub Branch Protection Setup:
- Go to the repository settings.
- Add a branch protection rule for the main branch.
- Enable status checks to require passing results from your CI workflow.

Automated Reformatting (Optional)

Auto-Fix and Commit: Optionally, configure GitHub Actions to automatically reformat code and commit the changes if formatting issues are detected. This can be useful for maintaining consistency but should be used carefully to avoid unwanted changes.

-   name: Run Black
    run: |
        pipenv run black --check . || true

-   name: Reformat code with Black
    run: |
        pipenv run black . || true

-   name: Commit changes
    if: ${{ github.ref == 'refs/heads/main' }}
    run: |
        git config --global user.name 'GitHub Actions'
        git config --global user.email 'actions@github.com'
        git add .
        git commit -m 'Auto-format code with Black'
        git push

Why These Practices are Standard

Automation with Manual Review: Automating checks and reporting issues ensures consistency and quality, while manual fixes and reviews allow for careful code handling and decision-making.
Enforcement Through Branch Protection: Protecting branches from being updated with non-compliant code ensures that code quality standards are enforced.
Balancing Automation and Manual Effort: Automated reformatting can be useful but should be balanced with manual review to avoid accidental or undesired changes.

Summary

The standard approach in professional environments is to use automated checks for formatting and linting in your CI/CD pipeline, combined with manual fixes and reviews. This ensures that code quality is maintained while allowing for developer oversight and intervention. Automated reformatting can be used optionally, but it should be implemented carefully to avoid unintended changes.

Question 1:

Why Manual Code Formatting and Linting Are Preferred Over Automatic Commits in CI/CD

If you choose not to use the step that automatically commits and pushes changes in your GitHub Actions workflow, here's what happens and what alternatives you might consider:

Consequences of Not Using Automatic Committing

Manual Intervention Required:
- Without this step, if black, flake8, or isort find issues that need fixing, those issues will be reported, but the formatting and linting fixes won’t be applied automatically. You or other developers will need to manually run the tools and commit the changes locally.
Workflow Passes Only on Success:
- The GitHub Actions workflow will only pass if the code is already compliant with formatting and linting standards at the time of the push or pull request. If the code is not compliant, the workflow will fail, and manual intervention is needed to correct the issues.
Increased Developer Responsibility:
- Developers must ensure that code adheres to formatting and linting standards before pushing their changes. This can be done by running the tools locally before pushing.

Benefits of Not Automatically Committing Changes

Controlled Code Changes:
- Manual fixing ensures that changes are reviewed and intentionally applied, maintaining code quality and avoiding unintended changes.
Code Review and Quality Assurance:
- Developers can review and discuss code formatting changes during code reviews, ensuring that all changes meet project standards and do not introduce issues.
Avoids Potential Issues:
- Automatically committing and pushing changes can sometimes result in conflicts or undesired changes if not managed carefully. Manual intervention can help avoid these issues.

Alternative Approaches

Local Formatting and Linting:
- Developers can run formatting and linting tools locally before pushing code. This ensures that the code adheres to standards before it reaches the CI/CD pipeline.
  Local Commands
```
pipenv run black .
pipenv run flake8 .
pipenv run isort .
```

Pre-commit Hooks:

Use pre-commit hooks to automatically format code before committing it. This ensures code is consistently formatted before it’s pushed to the repository.

Pre-commit Configuration

repos:
    -   repo: https://github.com/pre-commit/mirrors-black
        rev: v23.9.0
        hooks:
          - id: black

    -   repo: https://github.com/pre-commit/mirrors-flake8
        rev: v6.0.0
        hooks:
          - id: flake8

    -   repo: https://github.com/pre-commit/mirrors-isort
        rev: v5.12.0
        hooks:
          - id: isort

Manual Code Reviews:
- Ensure code reviews include checks for adherence to formatting and linting standards. This can be combined with CI/CD checks to enforce quality.
Branch Protection Rules:
- Set up branch protection rules to ensure that only code passing all required checks (including formatting and linting) can be merged into important branches.

Summary

Not using the automatic commit step means that formatting and linting issues will not be automatically fixed and committed. This approach requires developers to address formatting issues manually but provides more control over code changes and quality. To ensure code quality, developers should run formatting and linting tools locally or use pre-commit hooks, and code reviews should include checks for adherence to standards. Branch protection rules can help enforce quality by requiring passing checks before merging into protected branches.

Question 2:

Standard Practices for Code Formatting and Linting in CI/CD Pipelines

Automatically committing changes in CI/CD workflows is less common and not generally considered a best practice in most professional development environments. Here’s why and what the standard approaches are:

Why Automatic Committing is Less Common

Controlled Code Changes:
- Review Process: Automatic commits can bypass code review processes, potentially introducing unwanted changes without proper review.
- Accidental Changes: Automated changes might inadvertently alter code in ways that were not intended or that could introduce issues.
Conflict Management:
- Merge Conflicts: Automatically committing changes can lead to conflicts with other ongoing changes, making it difficult to manage the integration process.
Transparency:
- Audit Trails: Automatic commits can obscure the history of changes, making it harder to track why and when certain changes were made.

Standard and Popular Practices

Manual Formatting and Linting:

Local Development: Developers run formatting and linting tools locally before committing. This ensures that code adheres to standards before it reaches the CI/CD pipeline.

Pre-commit Hooks: Use tools like pre-commit to enforce code quality standards automatically before code is committed. This helps maintain consistency and avoids formatting issues.

.pre-commit-config.yaml

repos:
    -   repo: https://github.com/pre-commit/mirrors-black
        rev: v23.9.0
        hooks:
        - id: black

    -   repo: https://github.com/pre-commit/mirrors-flake8
        rev: v6.0.0
        hooks:
        - id: flake8

    -   repo: https://github.com/pre-commit/mirrors-isort
        rev: v5.12.0
        hooks:
        - id: isort

CI/CD Pipeline Checks:

Check Mode: Run formatting and linting tools in check mode (--check for black, flake8, and isort) in CI/CD workflows. This reports issues but does not automatically fix them.

Fail on Issues: Configure the CI/CD pipeline to fail if formatting or linting issues are detected. This encourages developers to fix issues before merging.

GitHub Actions Workflow

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v3

      - name: Install dependencies
        run: |
          pip install black flake8 isort

      - name: Run Black
        run: pipenv run black --check .

      - name: Run Flake8
        run: pipenv run flake8 .

      - name: Run isort
        run: pipenv run isort --check .

Code Reviews:
- Manual Review: Ensure code reviews include checks for formatting and adherence to linting standards. This helps catch issues that automated tools might miss.
Branch Protection Rules:
- Enforce Standards: Use branch protection rules to enforce that all required checks, including formatting and linting, must pass before allowing merges.
GitHub Branch Protection Settings:
- Navigate to repository settings.
- Add a branch protection rule for the main branch.
- Require status checks to pass before merging.

When Automatic Committing Might Be Used

Internal Tools: Some teams use automatic committing in internal tools or experimental setups, but this is less common for production codebases.
Documentation or Generated Code: Automatic commits can be used for non-code files like documentation or generated files where manual review is less critical.

Summary

Automatic committing is not widely used in standard development workflows due to concerns about code control, review processes, and conflict management. The more common and recommended practices are to run formatting and linting tools in CI/CD pipelines in check mode, use pre-commit hooks, and rely on manual code reviews and branch protection rules to enforce code quality standards. This approach ensures code quality while maintaining transparency and control over code changes.