README.md

dco-check

Simple DCO check script to be used in any CI.

Motivation

Many open-source projects require the use of a Signed-off-by: line in every commit message. This is to certify that a contributor has the right to submit their code according to the Developer Certificate of Origin (DCO). However, to my knowledge, there is no automated check that can run on any CI platform (or most platforms). Some platforms simply do not possess such a feature.

This was inspired by the DCO GitHub App.

How to get & use

There are a few options:

1. Using the package from PyPI

   $ pip install dco-check
   $ dco-check

2. Using the Docker image (christophebedard/dco-check) with your CI (see examples)

   $ dco-check

3. Downloading the script and running it (you can replace master with a specific version)
   This is enabled by the fact that dco-check is a single Python file without any third-party dependencies.

   $ wget https://raw.githubusercontent.com/christophebedard/dco-check/master/dco_check/dco_check.py
   $ python3 dco_check.py

It exits with 0 if all checked commits have been signed-off. Otherwise, it exits with a non-zero number.

Run with --help for more information and options, including:

• ignoring merge commits
• default branch
• default remote
• list of commit author emails to exclude from checks
• regular expression pattern to exclude generic emails when matched
• quiet mode
• verbose mode
• excluding certain author emails (e.g., for bots)

Those options can alternatively be set through environment variables (see --help), but commandline arguments always have precedence over environment variables.

How it works

dco-check focuses on two use-cases:

1. Commits part of a feature branch, i.e. a proposed change (pull request or merge request)
2. Commits on the default branch, e.g. master, or more specifically the new commits pushed to the default branch

The first use-case is easy to cover given a normal git repository. We can simply use git merge-base --fork-point $DEFAULT_BRANCH to get the list of commits on a specific feature branch off of the default branch. Some CIs provide even more information, such as the target branch of the change, which is useful if we don't expect to always target the default branch. Then we can just check every commit using git log and make sure it is signed-off by the author.

The second use-case isn't really possible with simple git repositories, because they do not contain the necessary information (AFAIK). Fortunately, some CIs do provide this information.

Furthermore, by default, some CI platforms only clone git repositories up to a specific depth, i.e. you only get a partial commit history. This depth can sometimes be 1 for some CIs, i.e. a shallow clone. For those cases, it is usually possible to prevent shallow cloning by setting the right parameter(s) in the job configuration. However, since one of the goals of dco-check is to be as easy to use as possible, it tries not to rely on that.

This is why dco-check detects the current CI platform and uses whatever information that platform can provide. Otherwise, it falls back on a default generic implementation which uses simple git commands. In those cases, the CLI options allow users to provide a lot of the missing information.

CI support

Below is a summary of the supported CIs along with their known behaviours.

CI	Detects new changes when pushing to default branch	Detects PRs/MRs	Gets base branch using	Gets default branch using	Notes
GitHub	✓	✓	CI	(not used)	retrieves commit data using the GitHub API, since GitHub does shallow clones by default
GitLab	✓	✓	CI	CI	detects normal GitLab MRs and external (GitHub) MRs
Azure Pipelines		✓	CI	CLI arguments
AppVeyor		✓	CI	CLI arguments
CircleCI	✓		CI* (or CLI arguments)	CLI arguments	*can use base revision information if provided (see example)
Travis CI			CLI arguments	CLI arguments	supported by default as a normal git repo
default (git)			CLI arguments	CLI arguments	use locally; using in an unsupported CI which only does a shallow clone might cause problems

Example CI configurations

Here are some example CI configurations.

GitHub

# .github/workflows/dco.yml
name: DCO
on:
  pull_request:
  push:
    branches:
      - master
jobs:
  check_dco:
    runs-on: ubuntu-latest
    name: Check DCO
    steps:
      - name: Run dco-check
        uses: christophebedard/[email protected]
        with:
            python-version: '3.12'
            args: '--verbose'
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Please note that the with: property is optional, the default Python version is 3.12 and no additional arguments are passed by default.

GitLab

# .gitlab-ci.yml
variables:
  DOCKER_DRIVER: overlay2
dco:
  image: christophebedard/dco-check:latest
  rules:
    - if: $CI_MERGE_REQUEST_ID
    - if: $CI_EXTERNAL_PULL_REQUEST_IID
    - if: $CI_COMMIT_BRANCH == 'master'
  script:
    - pip3 install -U dco-check  # optional
    - dco-check

Python version support

Python 3.6+ is required because of the use of f-strings. However, it shouldn't be too hard to remove them to support older versions of Python 3, if there is a demand for it, or if such a change is contributed to dco-check.

Contributing

See CONTRIBUTING.md.