Getting started

Once an instance of the CLA-Bot is deployed and configured to interact with a GitHub organization, it is possible to sign-in into its administrative area.

This page describes the first steps to get started using the system:

• administrators' sign-in
• configuring an agreement
• binding an agreement to a public repository of the GitHub organization
• CLA-Bot status check for pull requests and signing of CLAs

Home page

The organization name (highligted in light green in the picture) can be configured using ORGANIZATION_DISPLAY_NAME environment variable, as described in the README. If this environment variable is not configured, ORGANIZATION_NAME is used instead.

Signing in to the admin area

Click on the Administrator Sign in button in the top right corner of the home page to navigate to the sign in page for the administrative area.

The page contains a single link, styled like a button "Sign in with GitHub".

The image displayed on the sign-in page is always random, downloaded from https://source.unsplash.com/random. In the future, if more identity providers will be supported, it is possible to extend this page to offer more options.

Clicking on this link button redirects the user to a GitHub sign-in page, for the configured OAuth application. The user is requested to grant consent to the OAuth application if necessary, because the application needs permissions to fetch the user's profile with the list of emails. In such cases, the GitHub UI displays a page like in the picture below.

Once the user grants permissions to the OAuth app, the client is redirected to the CLA-Bot instance with a token that is used to obtain information about the user, and eventually grant access to the administrative side.

Users who are administrators of the GitHub organization can sign-in immediately to the CLA-Bot instance. Additionally, it is possible to configure CLA-Bot specific administrators using the interface described later.

Admin home page

After successful login, the administrator is redirected to the home page of the admin area.

Creating an Agreement

1. Insert a name
2. (optional) insert a description
3. Click "Confirm"

After an agreement is created, the user is redirected to the agreement details page.

Editing an Agreement

1. Use the Edit under "Agreement details" to edit the agreement object (name and description).
2. The versions table shows the list of versions configured for this Agreement.
3. The "See preview" link enables seeing a preview of the agreement text in a separate page.
4. The bottom region of the page displays the texts configured for the selected version. The title will be used in the HTML document title element. The markdown body will be rendered to display the agreement. Use the Edit button to edit the markdown for the selected version.
5. The Complete button is used to mark a version in Done status (at this point its text cannot be edited anymore)
6. The Clone button is used to create a clone of the selected version, cloning its texts.

7. Markdown edit area
8. Button for full-screen edit mode
9. Click on Confirm button to save the version text (it is also possible to use CTRL+S)

Note: clicking Done closes the edit view without saving the text.

Once done editing, mark a version as complete.

Finally, make the version current by clicking on the Make current button. This is to enable rolling back in case an agreement version is not edited properly, and selecting the current version among those in complete status. Repositories are bound to agreements, and the current version's text is always used when displaying CLA agreements for new users.

Note: contributors only have to accept an agreement once. So even if the agreement text changes over time and new versions are configured, contributors are not invited to accept again the CLA. However, the system stores the exact version that was accepted by a contributor.

Binding Repositories to Agreements

Navigate to the Repositories page using the main menu.

1. The top region of the page displays a list of current Repository-Agreement bindings.
2. Use delete buttons to remove bindings between repositories and agreements
3. Use the select HTML controls to bind a repository (list of public repositories fetched from GitHub) to an agreement.
4. Click the Add button to create a bound

Now, as long as the bound Agreement has a current version configured, a proper pull request hook is configured in the organization, and the CLA-Bot is properly configured, the CLA-Bot starts verifying if contributors to the selected repositories have signed the CLA, and publishes status checks in repositories.

Pull request status check

Upon a PR (open or reopened even):

1. The cla-bot publishes a comment (or updates, if a comment was already published in the past for the same PR) with status check
2. The cla-bot publishes a status check, containing a link to the CLA-Bot itself, to the page where the user can sign the CLA

Both the comment and the status check details contain links to the CLA-Bot page that displays the CLA.

Note: branch policies to make the CLA-Bot status check required must be configured in GitHub. The CLA-Bot doesn't configure branch policies

Signing a CLA

After a user clicks on the link, the client navigates to the CLA-Bot page displaying the CLA for the given repository.

Note: a signed JWT is used as OAuth flow state parameter to validate that the user is signing the CLA for the required repository.

After the user clicks on the button at the bottom of the page, Sign in with GitHub to Agree, the client redirects to a GitHub sign-in page (similar to the one displayed above, for administrators' sign-in).

After the user authorizes the application, the client is redirected back to the GitHub page with the PR; and the CLA-Bot updates both comment and status check for the PR.