# dco-check
[](https://pypi.org/project/dco-check/)
[](https://codecov.io/gh/christophebedard/dco-check)
[](https://github.com/christophebedard/dco-check/blob/master/LICENSE)
[](https://hub.docker.com/r/christophebedard/dco-check)
[](https://github.com/christophebedard/dco-check)
[](https://gitlab.com/christophebedard/dco-check/commits/master)
[](https://travis-ci.com/github/christophebedard/dco-check)
[](https://dev.azure.com/christophebedard/dco-check/_build/latest?definitionId=1&branchName=master)
[](https://ci.appveyor.com/project/christophebedard/dco-check)
[](https://circleci.com/gh/christophebedard/dco-check)
Simple DCO check script to be used in [any CI](#ci-support).
## 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)](https://developercertificate.org/).
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](https://github.com/apps/dco).
## How to get & use
There are a few options:
1. Using the [package from PyPI](https://pypi.org/project/dco-check/)
```shell
$ pip install dco-check
$ dco-check
```
1. Using the Docker image ([`christophebedard/dco-check`](https://hub.docker.com/r/christophebedard/dco-check)) with your CI (see [examples](#Example-CI-configurations))
```shell
$ dco-check
```
1. 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.
```shell
$ 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)
1. 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
```yaml
# .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/dco-check@0.5.0
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
```yaml
# .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`](./CONTRIBUTING.md).
Raw data
{
"_id": null,
"home_page": "https://github.com/christophebedard/dco-check/",
"name": "dco-check",
"maintainer": "Christophe Bedard",
"docs_url": null,
"requires_python": null,
"maintainer_email": "bedard.christophe@gmail.com",
"keywords": "dco, check",
"author": "Christophe Bedard",
"author_email": "bedard.christophe@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/57/d5/799848360989674903c05c2115246ba1707fc263520784110498bc92f041/dco_check-0.5.0.tar.gz",
"platform": null,
"description": "# dco-check\n\n[](https://pypi.org/project/dco-check/)\n[](https://codecov.io/gh/christophebedard/dco-check)\n[](https://github.com/christophebedard/dco-check/blob/master/LICENSE)\n[](https://hub.docker.com/r/christophebedard/dco-check)\n\n[](https://github.com/christophebedard/dco-check)\n[](https://gitlab.com/christophebedard/dco-check/commits/master)\n[](https://travis-ci.com/github/christophebedard/dco-check)\n[](https://dev.azure.com/christophebedard/dco-check/_build/latest?definitionId=1&branchName=master)\n[](https://ci.appveyor.com/project/christophebedard/dco-check)\n[](https://circleci.com/gh/christophebedard/dco-check)\n\nSimple DCO check script to be used in [any CI](#ci-support).\n\n## Motivation\n\nMany open-source projects require the use of a `Signed-off-by:` line in every commit message.\nThis is to certify that a contributor has the right to submit their code according to the [Developer Certificate of Origin (DCO)](https://developercertificate.org/).\nHowever, to my knowledge, there is no automated check that can run on any CI platform (or most platforms).\nSome platforms simply do not possess such a feature.\n\nThis was inspired by the [DCO GitHub App](https://github.com/apps/dco).\n\n## How to get & use\n\nThere are a few options:\n\n1. Using the [package from PyPI](https://pypi.org/project/dco-check/)\n ```shell\n $ pip install dco-check\n $ dco-check\n ```\n1. Using the Docker image ([`christophebedard/dco-check`](https://hub.docker.com/r/christophebedard/dco-check)) with your CI (see [examples](#Example-CI-configurations))\n ```shell\n $ dco-check\n ```\n1. Downloading the script and running it (you can replace `master` with a specific version) \n This is enabled by the fact that `dco-check` is a single Python file without any third-party dependencies.\n ```shell\n $ wget https://raw.githubusercontent.com/christophebedard/dco-check/master/dco_check/dco_check.py\n $ python3 dco_check.py\n ```\n\nIt exits with 0 if all checked commits have been signed-off.\nOtherwise, it exits with a non-zero number.\n\nRun with `--help` for more information and options, including:\n\n* ignoring merge commits\n* default branch\n* default remote\n* list of commit author emails to exclude from checks\n* regular expression pattern to exclude generic emails when matched \n* quiet mode\n* verbose mode\n* excluding certain author emails (e.g., for bots)\n\nThose options can alternatively be set through environment variables (see `--help`), but commandline arguments always have precedence over environment variables.\n\n## How it works\n\n`dco-check` focuses on two use-cases:\n\n1. Commits part of a feature branch, i.e. a proposed change (pull request or merge request)\n1. Commits on the default branch, e.g. `master`, or more specifically the new commits pushed to the default branch\n\nThe first use-case is easy to cover given a normal git repository.\nWe 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.\nSome 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.\nThen we can just check every commit using `git log` and make sure it is signed-off by the author.\n\nThe second use-case isn't really possible with simple git repositories, because they do not contain the necessary information (AFAIK).\nFortunately, some CIs do provide this information.\n\nFurthermore, by default, some CI platforms only clone git repositories up to a specific depth, i.e. you only get a partial commit history.\nThis depth can sometimes be 1 for some CIs, i.e. a shallow clone.\nFor those cases, it is usually possible to prevent shallow cloning by setting the right parameter(s) in the job configuration.\nHowever, since one of the goals of `dco-check` is to be as easy to use as possible, it tries not to rely on that.\n\nThis is why `dco-check` detects the current CI platform and uses whatever information that platform can provide.\nOtherwise, it falls back on a default generic implementation which uses simple git commands.\nIn those cases, the CLI options allow users to provide a lot of the missing information.\n\n## CI support\n\nBelow is a summary of the supported CIs along with their known behaviours.\n\n| CI | Detects new changes when pushing to default branch | Detects PRs/MRs | Gets base branch using | Gets default branch using | Notes |\n|:--:|:--------------------------------------------------:|:---------------:|:----------------------:|:-------------------------:|:-----:|\n|GitHub|\u2713|\u2713|CI|(not used)|retrieves commit data using the GitHub API, since GitHub does shallow clones by default|\n|GitLab|\u2713|\u2713|CI|CI|detects normal GitLab MRs and external (GitHub) MRs|\n|Azure Pipelines||\u2713|CI|CLI arguments||\n|AppVeyor||\u2713|CI|CLI arguments||\n|CircleCI|\u2713||CI\\* (or CLI arguments)|CLI arguments|\\*can use base revision information if provided (see example)|\n|Travis CI|||CLI arguments|CLI arguments|supported by default as a normal git repo|\n|default (git)|||CLI arguments|CLI arguments|use locally; using in an unsupported CI which only does a shallow clone might cause problems|\n\n## Example CI configurations\n\nHere are some example CI configurations.\n\n### GitHub\n\n```yaml\n# .github/workflows/dco.yml\nname: DCO\non:\n pull_request:\n push:\n branches:\n - master\njobs:\n check_dco:\n runs-on: ubuntu-latest\n name: Check DCO\n steps:\n - name: Run dco-check\n uses: christophebedard/dco-check@0.5.0\n with:\n python-version: '3.12'\n args: '--verbose'\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\nPlease note that the `with:` property is optional, the default Python version is 3.12 and no additional arguments are passed by default.\n\n### GitLab\n\n```yaml\n# .gitlab-ci.yml\nvariables:\n DOCKER_DRIVER: overlay2\ndco:\n image: christophebedard/dco-check:latest\n rules:\n - if: $CI_MERGE_REQUEST_ID\n - if: $CI_EXTERNAL_PULL_REQUEST_IID\n - if: $CI_COMMIT_BRANCH == 'master'\n script:\n - pip3 install -U dco-check # optional\n - dco-check\n```\n\n## Python version support\n\nPython 3.6+ is required because of the use of f-strings.\nHowever, 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`.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md).\n",
"bugtrack_url": null,
"license": "Apache License, Version 2.0",
"summary": "Simple DCO check script to be used in any CI.",
"version": "0.5.0",
"project_urls": {
"Changelog": "https://github.com/christophebedard/dco-check/milestones?state=closed",
"GitHub": "https://github.com/christophebedard/dco-check/",
"Homepage": "https://github.com/christophebedard/dco-check/"
},
"split_keywords": [
"dco",
" check"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "af466f1df17088aa074bc6b6f06af400864d82c24e58a71d0b0af64a34baea42",
"md5": "a1b9957089528fb38f5dd98bb0f3bcc6",
"sha256": "3c027d2d47b5cbb03f7e2a25ec8ffb56d8a33c49563c8fcd2cef443ebf3cff0d"
},
"downloads": -1,
"filename": "dco_check-0.5.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1b9957089528fb38f5dd98bb0f3bcc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 19083,
"upload_time": "2024-09-20T21:12:04",
"upload_time_iso_8601": "2024-09-20T21:12:04.066232Z",
"url": "https://files.pythonhosted.org/packages/af/46/6f1df17088aa074bc6b6f06af400864d82c24e58a71d0b0af64a34baea42/dco_check-0.5.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "57d5799848360989674903c05c2115246ba1707fc263520784110498bc92f041",
"md5": "083f2a439891e322fd149afa67c8bc5a",
"sha256": "6d76b4efdfb9fdbb14c788c22b0a09b4ada1a6044832d0d7f8303a323088c880"
},
"downloads": -1,
"filename": "dco_check-0.5.0.tar.gz",
"has_sig": false,
"md5_digest": "083f2a439891e322fd149afa67c8bc5a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 24299,
"upload_time": "2024-09-20T21:12:05",
"upload_time_iso_8601": "2024-09-20T21:12:05.475477Z",
"url": "https://files.pythonhosted.org/packages/57/d5/799848360989674903c05c2115246ba1707fc263520784110498bc92f041/dco_check-0.5.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-20 21:12:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "christophebedard",
"github_project": "dco-check",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"circle": true,
"appveyor": true,
"lcname": "dco-check"
}
JSON
