# CLA Assistant for GitHub Contributor Agreements

> CLA Assistant is a JavaScript GitHub integration for collecting Contributor License Agreement signatures inside pull requests. It suits open source maintainers who need a hosted or self-managed signing workflow tied to GitHub identities and agreement versions.

**cla-assistant/cla-assistant** — Contributor License Agreement assistant (CLA assistant)

- Repository: https://github.com/cla-assistant/cla-assistant
- Website: https://cla-assistant.io
- Stars: 1,549 · Forks: 287
- Language: JavaScript
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/cla-assistant-cla-assistant

## What CLA Assistant Automates for GitHub Maintainers

CLA Assistant addresses a specific administrative problem: contributors often need to sign a Contributor License Agreement before their pull request can be accepted, but maintainers otherwise have to request signatures, track who has agreed and identify which version each person accepted. The service places that process into the GitHub pull request workflow. According to the README, it comments on each opened pull request, asks the contributor to sign, authenticates the signer with their GitHub account and updates the pull request status when agreement is recorded.

The intended users are repository and organization owners who already use GitHub and need a repeatable CLA process. Contributors do not need to move to a separate signing system. They can act from within a pull request, while maintainers can review the users associated with each agreement version. The README also documents a CSV export for the signee list.

This is a workflow service rather than a general-purpose license scanner or a tool that decides whether a contribution is legally acceptable. The repository's responsibility is to collect agreement data and expose it through its GitHub integration. The text of the CLA remains the responsibility of the maintainer. The README suggests contributoragreements.org for drafting an agreement, but it does not provide legal advice or certify the contents of an agreement.

## Gist-Based Agreement Versions and Pull Request State

The documented configuration starts with a GitHub Gist containing the CLA. The Gist is linked to a repository or organization in CLA Assistant. That link gives the service a source for the agreement text and a way to associate a signature with a particular agreement version. When the Gist and CLA change, the README states that users are automatically asked to re-sign for each new pull request.

The pull request is the operational boundary. CLA Assistant comments on opened pull requests and records whether the contributor agrees, but the README does not describe a separate approval queue, merge policy engine or automatic merge action. Repository owners would therefore need to interpret the resulting pull request status in their own process.

The service can also request more information from signers. A file named `metadata` in the Gist describes fields using JSON that follows the repository's JSON Schema. CLA Assistant generates a form from that metadata, and contributors fill it before signing. The README shows fields such as `githubKey`, which can prefill information from the user's GitHub account, along with `required`, numeric limits and enumerated choices.

That design makes agreement changes explicit. It does not silently treat every signature as permission for every future revision. The version boundary is the relevant control, so maintainers should decide how they will distribute agreement changes before linking the Gist.

## Hosted Service Versus a Self-Managed Node.js Instance

The simplest documented route is the hosted offering at cla-assistant.io, which SAP provides as a free hosted service. That route removes the repository operator's need to run the application and database, but it also means the signing workflow depends on an external service and its operating boundaries.

For a self-managed instance, the README gives a development-oriented setup. The application is an Express-based Node.js project with a browser interface built around the source in `src/`. It expects configuration in a `.env` file and a MongoDB-compatible database. The supplied Compose file is explicitly marked `NOT PRODUCTION READY`, although it defines the application on port 5000 and a MongoDB service for development.

The repository also includes a `Dockerfile` based on `node:16-alpine`. It installs dependencies, builds the application, removes development dependencies and starts the package with `npm start`. This is useful as a concrete container baseline, but the Compose file's own development warning means it should not be treated as a complete production deployment guide. The README excerpt does not document production secrets, backups, database replication, observability or a supported upgrade procedure.

## Local Installation and the First Hosted-Style Run

To set up the repository locally, clone it, enter the directory and install dependencies as shown in the README. The package metadata is marked `name` as `cla-assistant` and uses the Apache-2.0 license. The repository's package version is listed as `1.8.3`, while the supplied release history lists `v2.13.2`, so version identification should be checked before deployment.

```sh
git clone https://github.com/cla-assistant/cla-assistant
cd ./cla-assistant
npm install
```

After installation, copy the sample environment file. The README instructs operators to register a GitHub OAuth application and use a callback URL in the form `<PROTOCOL>://<HOST>:<PORT>/auth/github/callback`. The sample configuration contains GitHub application and OAuth variables, a `PORT`, `HOST`, `PROTOCOL` and `MONGODB` value.

```sh
cp .env.example .env
```

For a local public callback during development, the README gives `ngrok http 5000`. It then requires updating `HOST` in `.env` and setting `PROTOCOL` to `https`. The excerpt ends while describing development database requirements, so it does not provide a complete first-run command, startup instructions or a list of required GitHub permissions. A first real hosted use is instead to visit cla-assistant.io, link the Gist containing the CLA and connect the repository or organization through the hosted interface.

## Metadata Forms, Signee Records and Bot Exceptions

Custom fields extend the signing form rather than replacing the CLA. The metadata file is validated against `custom-fields-schema.json`, and each field can declare a title, type, description and whether it is required. A `githubKey` value can draw data from the GitHub account, which reduces duplicate entry but also makes the available GitHub data relevant to the form design.

The documented storage arrangement is specific. The README says that since 2021-08-27, data is stored in Cosmos DB, using MongoDB compatibility, hosted by Microsoft Azure in Europe. Earlier data was stored in MongoDB hosted by mLab. Repository operators should not assume that all historical deployments use the current backend, especially when importing, exporting or restoring records.

Signees can be viewed in the user interface and exported as a `.csv` file. The README does not explain the CSV schema, redaction policy, deletion process or retention behavior. Those are concrete questions to settle before collecting personal information through custom fields.

Bot users are a clear boundary. The README says bot users such as Dependabot or Greenkeeper cannot sign a CLA. Maintainers can import names such as `dependabot[bot]` and `greenkeeper[bot]` into the dashboard to allow their contributions without signing. This exception is useful for automated dependency updates, but it should be controlled deliberately because it removes the usual agreement check for those identities.

## The GitHub Actions Lite Alternative

The repository documents a separate `github-action` implementation as a lite version built with GitHub Actions. Its stated status is Alpha. The conventional application described here is a hosted or self-managed service with a database, OAuth application, pull request comments, signing forms and signee records.

That difference matters for evaluation. The GitHub Actions alternative may fit a repository that wants a smaller workflow centered on GitHub-native automation, while the full CLA Assistant provides the documented signing interface, version-aware signee records and dashboard features. The README does not give a detailed feature matrix, configuration example or production support statement for the Action, so the two implementations should not be treated as interchangeable without checking their own documentation.

The main constraint is equally clear: neither approach solves every CLA process. The full service depends on GitHub identity and a connected database, and its own README explicitly excludes bot signing. Organizations that require an offline agreement process, a non-GitHub identity system or a legally reviewed in-house workflow need a different design.

## Maintenance, Licensing and Adoption Boundaries

The repository is not archived. Its last push was on 2026-10-13, and the release list includes `v2.13.2` on 2026-10-13. That indicates recent repository activity in the supplied record, but the README does not define a long-term support policy or compatibility promise for Node.js and npm versions. The README specifically tells operators to check `package.json` for supported and tested versions.

The code is identified as `Apache-2.0`, and the SPDX header in the README and Docker-related files identifies the same license. That is a project licensing fact, not legal advice about a contributor's CLA, personal data handling or the enforceability of any agreement. The repository's CLA documentation is about collecting signatures; maintainers still need to review the agreement text and decide how signatures are retained and used.

Adoption is most credible for maintainers already using GitHub who need a visible pull request workflow and can accept either the hosted service or the operational burden of a Node.js application plus MongoDB-compatible storage. It is a poor fit for bot-heavy repositories unless bot exceptions are planned, for organizations that cannot use GitHub authentication, or for teams seeking a complete legal agreement system. The first verification point is the exact deployment version and its configuration, because the package metadata and release list expose different version labels.

## Conclusion

Adopt CLA Assistant when your repository needs an auditable GitHub-based CLA flow and you are comfortable with a hosted service or operating MongoDB and OAuth yourself. Do not choose it for bot-only contribution workflows without exceptions, or when you need an offline signing process. First verify the agreement storage model, OAuth callback settings, required GitHub permissions and the version-specific deployment instructions before connecting a production repository.

## FAQ

### How do I set up CLA Assistant?

Clone the repository, change into its directory and run `npm install`, then copy `.env.example` to `.env`. Register a GitHub OAuth application with a callback URL in the form `<PROTOCOL>://<HOST>:<PORT>/auth/github/callback`.

### Can contributors sign a CLA from a GitHub pull request?

Yes. The README states that CLA Assistant comments on opened pull requests, allows contributors to sign from within the pull request and authenticates the signee with their GitHub account.

### Where are CLA Assistant signees stored?

According to the README, data has been stored in a Cosmos DB instance hosted by Microsoft Azure in Europe since 2021-08-27. Before that, the data was stored in MongoDB hosted by mLab.

## Sources

- [cla-assistant/cla-assistant on GitHub](https://github.com/cla-assistant/cla-assistant)
- [License: Apache-2.0](https://github.com/cla-assistant/cla-assistant/blob/main/LICENSE)
- [Project website](https://cla-assistant.io)
- [README](https://github.com/cla-assistant/cla-assistant/blob/main/README.md)
- [Releases](https://github.com/cla-assistant/cla-assistant/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/cla-assistant-cla-assistant