DoctoR-CLAw

Contributor License Agreement Tooling

This is a set of tools for dealing with Contributor License Agreements for Open Source Salesforce projects. This repository is affectionately referred to as "Dr. Claw" after the Inspector Gadget villain.

The tools provided are:

• Pull Request CLA Verifier
• GitHub Org Audit

This application is built with:

• Play Framework 2.5
• Scala
• Postgres
• Heroku Connect
• Reactive I/O (Non-Blocking)

How it Works

When someone sends a Pull Request to a project on GitHub, a Webhook sends details to this app. The authors of the commits in the PR are checked to see if they are collaborators on the repo. If not, the app checks if they have signed CLAs. If there are missing CLAs then the status of the PR is set to failed. Otherwise it is set to success. Also if there are missing CLAs then a comment is posted on the PR asking the contributors to sign the CLA. Once a contributor signs a CLA, all of the open PRs are revalidated.

Optional Customization Env Vars

ORG_NAME = Your organization's name
ORG_URL = A homepage to redirect to when someone visits /
ORG_EMAIL = An email users can reach out to you at
ORG_LOGO = URL to a logo you want to display
ORG_CLA = URL to the CLA text
ORG_DOMAIN = Domain name that internal users will have in their git commit emails
ORG_INTERNAL_INSTRUCTIONS_URL = URL with instructions for internal users who are not on the org

Local Dev Setup

1. Install Java 8

2. Install Postgres

3. Install ngrok

4. Start ngrok: ngrok http 9000

5. Create local Postgres databases:

    $ psql
    # CREATE ROLE salesforcecla LOGIN password 'password';
    # CREATE DATABASE salesforcecla ENCODING 'UTF8' OWNER salesforcecla;
    # CREATE DATABASE "salesforcecla-test" ENCODING 'UTF8' OWNER salesforcecla;
   

6. Setup a new OAuth App for CLA signing:

   • This will be at: https://github.com/organizations/{your-organization}/settings/applications/new
   • Application name = Something descriptive
   • Authorization callback URL = https://YOUR_NGROK_ID.ngrok.io/_github_oauth_callback
   • Homepage URL = https://YOUR_NGROK_ID.ngrok.io/
   • Once finished, set the GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET env vars accordingly

7. Setup a new GitHub App with the following settings:

   • Webhook URL = https://YOUR_NGROK_ID.ngrok.io/webhook-integration
   • User authorization callback URL = https://YOUR_NGROK_ID.ngrok.io/_github_app_oauth_callback
   • Repository administration = Read-only
   • Commit statuses = Read & Write
   • Issues = Read & Write
   • Pull requests = Read & Write
   • Repository contents = Read-only
   • Organization members = Read-only
   • Under Subscribe to events select Pull request

   It is not required, but if you set the GitHub Integration Secret Token, then set the GITHUB_INTEGRATION_SECRET_TOKEN env var accordingly.

8. Set the GITHUB_INTEGRATION_CLIENT_ID and GITHUB_INTEGRATION_CLIENT_SECRET env vars with the OAuth app associated with the GitHub App.

9. Generate and save a new Private key for the new Integration, then set the GITHUB_INTEGRATION_PRIVATE_KEY env var accordingly, like:

    export GITHUB_INTEGRATION_PRIVATE_KEY=$(cat ~/somewhere/your-integration.2017-02-07.private-key.pem)
   

10. Your new GitHub App will have a numeric id, set the GITHUB_INTEGRATION_ID env var accordingly.

11. Your new GitHub App will have a slug / URL friendly name, set the GITHUB_INTEGRATION_SLUG env var accordingly.

12. Set the GITHUB_BOT_NAME env var to the value of what you'd like your public facing bot to appear as

export GITHUB_BOT_NAME=salesforce-cla

Run the Web App

1. Start the web app:

    $ ./sbt ~run
   

2. Authenticate to GitHub with your test user

3. Open the audit page: https://SOMETHING.ngrok.com/audit

4. You should see a list of organizations which have the GitHub App installed and which you are an admin of

5. In GitHub edit the README file the testing repo and submit a pull request

6. This will make a webhook request to your local application and validate the CLA status of the submitter

7. You can see event deliveries in the Developer Settings for your GitHub App

8. If you make a PR with a testing user that is not part of the org, you should see the PR validation failure and be able to sign the CLA

Run the Tests

1. You will need two GitHub testing users. For each, create a personal access token with the following permissions: admin:org, admin:org_hook, admin:public_key, admin:repo_hook, delete_repo, repo, user

2. For user one, create a new testing organization (because this can't be done via the API). Add the second user as a member of this org.

3. For user one, install the GitHub App into the user's account and into the testing org.

4. Set the GITHUB_TEST_TOKEN1, GITHUB_TEST_ORG, and GITHUB_TEST_TOKEN2 env vars.

5. Run all of the tests continuously:

    $ ./sbt ~test
   

1 Run just the GitHubSpec tests continuously:

    $ ./sbt ~testOnly utils.GitHubSpec

License

This repo is licensed under the BSD-3-Clause.