Awesome
CLA bot
CLA bot is a web server which handles GitHub webhook events to check whether PR authors have signed the CLA. It uses Google Sheets as a data source.
Configuration
GitHub Webhook setup
In your repository, go to Settings -> Webhooks
, then choose Add webhook
.
In the Payload URL field type the URL address of this bot with /webhook
endpoint.
Example: https://example.com/webhook
.
As a content type choose application/json
. You can either choose the Send me everything
option or manually select individuals events to send. You need to select at least Pull requests and Issue comments.
NOTE: If using this across an organization you can also set the CLA Bot up at the org level which will then mean any events from your repositories will be sent back to the bot.
Google Sheets setup
The sheets must contain columns with each row containing a GitHub login of the users that have signed the CLA. You can configure which columns the bot should look at.
Service health checks
When running the service exposes a /health
endpoint which can be pinged to verify liveliness of the service.
How to generate the GitHub token?
- Setup a GitHub user which is specifically for CLA signing activites
- Navigate to
Profile -> Settings -> Developer Settings
for this user - Generate a new "classic" token
For the scope if only using for public repos select public_repo
. If using for all repositories in an org select the repo:*
scope.
IMPORTANT: You will then need to ensure that the user you have allocated for CLA activites is given push
access to any repositories you want monitored - without this level of access the bot will not work.
How to generate the OAuth token?
To grant the bot access to Google Sheets we are leveraging a GCP Service Account authentication flow. To do this step you will need access to a GCP Project.
- In your GCP Project navigate to the APIs dashboard: https://console.cloud.google.com/apis/dashboard
- Navigate through
Credentials -> + Create Credentials -> Service Account
- Give it a useful name like “clabot”
- Skip granting permissions -> we do not need permission in the GCP Project for this!
- Select the newly created Service Account and then select
Keys
- Select
Add Key -> JSON
Download the key locally to a file and reference it in your config at oathCredPath
.
IMPORTANT: Within the GCP Project you will need to ensure that both the sheets
ad drive
APIs are enabled so that the service-account can access them.
- https://console.cloud.google.com/apis/api/sheets.googleapis.com/overview
- https://console.cloud.google.com/apis/api/drive.googleapis.com/metrics
Granting access to your spreadsheets?
To grant access to the spreadsheets you will need the email address of the service-account and to then grant viewer
access on the spreadsheet to this email address.
Setting up the config file
Once the setup is done, we can fill our configuration file. An example configuration is shown here:
port = 8080
host = localhost
github {
# a token from the bot account, get at https://github.com/settings/tokens
token = GITHUB_TOKEN
}
oathCredPath = PATH_TO_CRED_JSON
cla {
internalCLA {
# id of the spreadsheet (the one from the spreadsheet URL)
spreadsheetId = GOOGLE_SPREADSHEET_ID
sheetName = GOOGLE_SPREADSHEET_NAME
# columns containing GitHub logins
columns = [ A ]
}
individualCLA {
# id of the spreadsheet (the one from the spreadsheet URL)
spreadsheetId = GOOGLE_SPREADSHEET_ID
sheetName = GOOGLE_SPREADSHEET_NAME
# columns containing GitHub logins
columns = [ A ]
}
corporateCLA {
# id of the spreadsheet (the one from the spreadsheet URL)
spreadsheetId = GOOGLE_SPREADSHEET_ID
sheetName = GOOGLE_SPREADSHEET_NAME
# columns containing GitHub logins
columns = [ A ]
}
# list of GitHub logins which do not require signing the CLA
peopleToIgnore = [ "scala-steward" ]
}
Running
sbt assembly
java -Dconfig.file=application.conf \
-jar clabot/target/scala-2.13/cla-bot-0.3.0.jar
We also produce a Docker image which can be found here: https://hub.docker.com/r/snowplow/cla-bot/tags
docker run \
-p 8080:8080 \
-v /application.conf:/application.conf \
-v /oauth_creds.json:/oauth_creds.json \
--network=host \
snowplow/cla-bot:latest \
-Dconfig.file=application.conf
How the bot algorithm works
Pull Request is opened
-
If user submitting the PR is a collaborator (this includes members of the organization), the bot ignores the PR.
-
If the user is a collaborator (and to combat failures in listing collaborators) add them to the
internalCLA
sheet. -
If the user is not a collaborator
- and is in the
peopleToIgnore
list, or - and has signed the CLA, the bot adds a
cla:yes
label
- and is in the
-
If the user is not a collaborator, is not in the
peopleToIgnore
list and has not signed the CLA, the bot adds acla:no
label and posts a comment reminding the user to sign the CLA.The bot then listens to incoming comments in the PR. If the author of the comment is also the author of the PR ("pinging"), then the bot checks the CLA again. If the CLA is now signed, the bot posts a comment with a thank you message. Otherwise it ignores the comment.
Copyright and license
The CLA Bot is copyright 2018-2022 Snowplow Analytics Ltd.
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this software except in compliance with the License.
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.