This repository provides a GitHub Actions workflow to check and nicely comment on pull requests in python code bases.
It will help with:
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.
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
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.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.[tool.mypy]
and [[tool.mypy.overrides]]
section.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.*.zip
etc.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.
(see more screenshots here)
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.
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:
black_args: '--config=pyproject.toml'
in pm-gh-actions.yml. This workflow uses default configuration provided by black.
flake8_args: '--config=setup.cfg'
to your config file present in the repo.interrogate
command in pm-gh-actions.yml file.mypy_flags: '--config-file=setup.cfg'
to your config file present in the repo.pytest
command in pm-gh-actions.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.