This tool is intended to allow managing GitHub Contributor License Agreements.

= Setup

Below are the steps that are necessary to set this project up.

== Register a new OAuth application with GitHub

This application uses https://developer.github.com/v3/oauth/[OAuth to access GitHub's APIs]. The first step is to https://github.com/settings/applications/new[Register a new OAuth application] with GitHub.

Example values for the form might be:

• Application Name - Pivotal CLA
• Homepage URL - https://pivotal.io
• Application description - Allows managing Contributor License Agreements for contributions to Pivotal sponsored projects
• Authorization callback URL - This needs to point back to your application's OAuth endpoint. For development it might be http://localhost:8080/login/oauth2/github If you are needing to test receiving GitHub events, you will probably want to setup https://ngrok.com/#download[ngrok]. If you are using ngrok, the URL would look something like https://123456.ngrok.io/login/oauth2/github

After clicking Register application you should make the application aware of the Client ID and the Client Secret.

Create a new file named application-local.properties

.src/main/resources/application-local.properties [source]

Replace values from registered application at https://github.com/settings/developers

See the README for additional detail

security.oauth2.main.clientId=Value from Client ID security.oauth2.main.clientSecret=Value from Client Secret

== Register a personal access token

• Generate a https://github.com/settings/tokens/new[New personal access token] that contains only public_repo scope. This will be used for adding comments to pull requests that require the contributor to sign the CLA.
• Copy the personal access token and place it in application-local.properties

Modify application-local.properties

.src/main/resources/application-local.properties [source]

Replace values from registered application at https://github.com/settings/developers

See the README for additional detail

security.oauth2.main.clientId=Value from Client ID security.oauth2.main.clientSecret=Value from Client Secret security.oauth2.pivotal-cla.token-secret=A Personal Access Token with public_repo scope

== Setup ngrok

If you are needing to test receiving GitHub events, you will probably want to setup https://ngrok.com/#download[ngrok]. If there is no need to test receiving the GitHub events from GitHub, then you can skip this step.

= Running the Application

== Gradle

You can run the application using:

[source,bash]

$ ./gradlew bootRun

This mode enables the local profile which uses H2 for the in-memory database and Redis for storing sessions. Redis must be started locally on port 6379.

NOTE: To start a docker image for Redis and MySQL invoke ./ci/scripts/start-services.sh. The docker images can be shutdown using ./ci/scripts/stop-services.sh.

=== Open the Application

You can open the application at a context root of "/". If you are running, the default URL is at http://localhost:8080/

== Cloud Foundry

Deploying the application to Cloud Foundry can be performed using the https://docs.cloudfoundry.org/cf-cli/[Cloud Foundry CLI]. It is set up for TravisCI and manual deployment mode.

=== Required Properties

Deployment scripts for pivotal-cla require a set of properties to be deployed. Please keep in mind that secrets should not get published.

• cfUsername: Your username to log into Pivotal Cloud Foundry
• cfPassword: Your password to log into Pivotal Cloud Foundry
• security.oauth2.main.clientId: GitHub Client ID
• security.oauth2.main.clientSecret: GitHub Client Secret
• security.oauth2.pivotal-cla.token-secret: A Personal Access Token with public_repo scope
• For manual deployment only: space: Name of the space

=== Zero-downtime Deploys

Deployment is done with zero-downtime using a strategy similar to the https://github.com/contraband/autopilot[autopiolot plugin]. The application is deployed to multiple application names and if successful, the old application name is removed.

=== Manual Deployment with Cloud Foundry CLI

Manual deployment with https://docs.cloudfoundry.org/cf-cli/[Cloud Foundry CLI] can be done after https://docs.cloudfoundry.org/cf-cli/use-cli-plugins.html#plugin-install[installing it].

First log into Cloud Foundry. For example:

[source,bash]

$ cf login -a api.run.pivotal.io -o pivotal-cla -s production -u $CF_USERNAME -p $CF_PASSWORD

Pushing to Cloud Foundry activates the cloudfoundry profile which requires a MySQL database and a Redis instance. You can perform a zero-downtime deploy to Cloud Foundry using the included cf-push.sh script. For example:

[source,bash]

$ ./ci/scripts/cf-push.sh pivotal-cla-production $CLIENT_ID $CLIENT_SECRET $TOKEN_SECRET $TRAVIS_BUILD_NUMBER-$TRAVIS_COMMIT

== Profiles

pivotal-cla uses two profiles to distinguish between running modes:

• local (enabled by default): Uses a H2 in-memory database
• cloudfoundry: Uses a MySQL database, Spring Session and Spring Data Redis. All connectors are obtained using Spring Cloud.