CircleCI configuration for test and deployment

We use CircleCI to perform testing, continuous integration (CI), and to deploy new releases to the npm repository. The CircleCI tasks run on every commit to the master and production branches; they also run on every pull request made on this repo.

The tasks run each time are defined in the .circleci/config.yml file in the registry. Note that if a branch or pull request modifies this file, it will perform a different set of tasks than the ones in master. In general, the procedure is:

• Start a preconfigured CircleCI docker container that contains node
• Install npm itself
• Check out the commit to be tested on the branch or pull request
• npm install based on the package.json in this branch
• npm run lint and npm test

On commits to the production branch, CircleCI runs a task to create any additional build artifacts and npm publish the result. See the Release Process wiki page for details on the publishing procedure.

The CircleCI task requires access to the npm account in order to publish to npm. This is accomplished through an access token. Because the access token is private information, it can't be put into a configuration file in the repo or anyone could use it to publish in our name. Instead, we set a CircleCI environment variable that contains the value. The config.yml file uses this variable to provide authentication in the publishing step. See this CircleCI blog post for details on how to configure the token.

At times there have been cases of security issues that allow attackers to steal npm access tokens. When this happens, npm has sometimes invalidated existing access tokens to ensure they are not misused. If the token currently stored in CircleCI is invalidated, it can lead to error messages when you attempt to publish:

ERR! publish Failed PUT 401
npm ERR! code E401
npm ERR! 404 You must be logged in to publish packages

If this occurs, you must log into an account with permission to publish the package (i.e., one that has been added with read-write access via npm owner add), create a new token, and use that for the NPM_TOKEN CircleCI environment variable.

The account currently used to publish is usds-publisher because it is not possible to enable two-factor authentication for accounts that are used to publish in CircleCI. Personal accounts should always use 2FA to reduce the chances of compromise. The login information should be shared via LastPass with the Engineering team members and the Engineering CoP Lead.