A Helpful GitHub Actions Workflow

This repository provides a GitHub Actions workflow to check and nicely comment on pull requests in python code bases.

It will help with:

• PR quality, like making sure there is a description and there aren't secrets or .zip and similar files being checked in
• Code quality, by running tools like
  • black for consistent formatting,
  • flake8 for pip8 conformance,
  • interrogate for presence of docstrings,
  • mypy for typechecking,
  • pytest for testing.

It also reports to codecov and codeclimate quality to help you have a healthier, easier to evolve codebase.

---

Folder structure convention

Getting these tools and checks to work together nicely takes some configuration. The expected layout is:

.
├── .github
│   └── workflows              # Workflow directory for your workflow files
│       └── pm-gh-actions.yml
├── projectname                # Project directory - top level directory for project
│   └── example.py
├── .codeclimate.yml           # Configuration file for codeclimate analysis
├── .pre-commit-config.yaml    # pre-commit configuration file, see https://pre-commit.com
├── pyproject.toml             # Configuration file for black, interrogate, mypy & pytest
├── requirements-dev.txt       # Development requirements file
├── requirements.txt           # Requirements file
├── setup.cfg                  # Configuration file for flake8, mypy
└── tests                      # Test directory for project level tests
    └── projectname
        └── test_example.py

---

Installation:

• Copy and paste pm-gh-actions.yml and relevant config files. OR call this workflow as one of the jobs under your repo's workflow - this workflow is reusable workflow, so you can call this from your workflow as followed:

  # file: caller_workflow_name.yaml
  
  name: CI workflow
  on:
    push:
      branches:
        - main
    pull_request:
      types:
        - opened
      branches:
        - main
  
  jobs:
    # reference: https://docs.github.com/en/actions/learn-github-actions/reusing-workflows#example-caller-workflow
    org-checks:
      uses: predictionmachine/pm-github-actions/.github/workflows/pm-gh-actions.yml@main
      secrets:
        CC_TEST_REPORTER_ID: ${{ secrets.CC_TEST_REPORTER_ID }}
        CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}

• Set a couple of secrets:

  • CC_TEST_REPORTER_ID (a repo-specific id provided by Codeclimate) See finding your test coverage token.
  • CODECOV_TOKEN, a similar token provided by CodeCov. See where is the repository upload token found.
  • You don't need to set up GITHUB_TOKEN for pm-gh-actions.yml to work.

• Copy setup.cfg, pyproject.toml and .codeclimate.yml files to the root directory of your repo. These files are being used for configuration of linting, formatting, testing and code analysis (using code climate) tools invoked by pm-gh-actions.yml.

• Add output/ to your top-level .gitignore. Things like coverage reports are written to that directory.

  It's a good idea to invoke the configured linting tools locally prior to creating the PR. ProTip: it is likely you can configure them in your IDE.

  You can also configure and use pre-commit hooks.
  Copy .pre-commit-config.yaml to the root directory of your repo and follow the installation instructions to run it.

Take the workflow for a spin by making a PR in your repo.

• black and flake8 configurations are in setup.cfg; interrogate, mypy and pytest are in pyproject.toml; code climate configurations are in .codeclimate.yml, update as needed.
• UPDATE in pyproject.toml, added [tool.mypy] and [[tool.mypy.overrides]] section.
• For more config tips see the FAQ below or raise an issue labeled "question".

---

How it works:

• This workflow uses the configuration files for black and flake8 from the setup.cfg; interrogate, mypy and pytest from pyproject.toml and for code analysis from .codeclimate.yml respectively.
• This workflow also creates intermediate output files during the CI build, under output/ folder, mentioned below:
  • output/coverage.xml - contains the coverage report - generated by coverage.py.
  • output/docstring_report.txt - contains the docstring report - generated by interrogate.

The checks in the work flow include:

• Check for valid branch name as per pm-coding-template standard.
• Check for empty PR description.
• Check for unwanted files - *.zip etc.
• Check hardcoded credentials in files.
• Linting, formatting and type check - black, flake8, interrogate, mypy
• Check for missing docstrings using interrogate
• Run test suite & coverage using codecov; look for code issues with code climate

Note: For the above checks, the github-actions bot will comment on the issues in the PR and fail the relevant check if it finds problems.

---

Few screenshots from the PR:

• Empty PR description check:
• Black format check:
• flake8 checks
• Hardcoded secret check:

(see more screenshots here)

The GH action from marketplace used are:

• reviewdog - for black, flake8, hard code credentials and mypy
• sticky-pull-request-comment - for PR comments.
• paambaati/codeclimate-action - for code climate test coverage comments.

---

FAQ

Question: What's GITHUB_TOKEN and do I need to set it up to run pm-gh-actions.yml?

Answer: No. GitHub automatically creates a GITHUB_TOKEN secret to use in your workflow. You can use the GITHUB_TOKEN to authenticate in a workflow run. When you enable GitHub Actions, GitHub installs a GitHub App on your repository. TheGITHUB_TOKEN secret is a GitHub App installation access token. You can use the installation access token to authenticate on behalf of the GitHub App installed on your repository. The token's permissions are limited to the repository that contains your workflow. Before each job begins, GitHub fetches an installation access token for the job. The token expires when the job is finished. You can read more about this here

Question: How can I add secrets to repo and test them in workflow?

Answer: Yep. Secrets are encrypted environment variables that you create in an organization, repository, or repository environment. To use the secret, simply use an expression: ${{ secrets.YOUR_SECRET_NAME }} in a workflow step. You can read more about how to setup secrets

Question: How do I tweak configurations of the checkers?

Answer: If you want to pass additional args, change location of config file, proceed as follows:

• For black replace the value of black_args: '--config=pyproject.toml' in pm-gh-actions.yml. This workflow uses default configuration provided by black.
• For flake8, replace the value of flake8_args: '--config=setup.cfg' to your config file present in the repo.
• For interrogate, you need to add configuration file path to interrogate command in pm-gh-actions.yml file.
• For mypy replace the value of mypy_flags: '--config-file=setup.cfg' to your config file present in the repo.
• For pytest, you need to add configuration file path to pytest command in pm-gh-actions.yml file.
• For code climate, you need to update configurations in .codeclimate.yml file.

Question: How can I execute an additional workflow after this workflow succeeds?

Answer: If you want to make a conditional run (stage-wise/sequential) for your existing workflow after successful execution of pm-gh-actions.yml workflow then include following yml code in your existing workflow file on top:

```yaml
on:
 workflow_run:
      workflows: ["PM CI Workflow"] # name of the workflow you want to execute after
      types:
        - completed
```

In our case, workflows: ["PM CI Workflow"] - "CI Workflow" is the workflow name of pm-gh-actions.yml

Question: How does hardcoded secrets scan work in the workflow?

Answer: The workflow uses reviewdog/action-detect-secrets action to detect the secrets in code. reviewdog/action-detect-secrets action uses detect-secrets which is a module for detecting secrets within a code base.
For tweaking the behaviour of secret scan for the workflow run, you can change the configuration of reviewdog/action-detect-secrets in pm-gh-actions.yml.
For more details please see reviewdog/action-detect-secrets and detect-secrets

---

Developed and used by Prediction Machine.