node-core-utils

Node.js Core Utilities

CLI tools for Node.js Core collaborators.

Tools
Usage
Contributing
License

Tools

git-node: Custom Git commands for working with Node.js core, e.g. landing Pull Requests.
ncu-config: Configure variables for node-core-utils to use.
ncu-team: Listing members of a team, synchronizing special blocks in files with the list of members.
get-metadata: Retrieving metadata for a Pull Request. DEPRECATED: use git node metadata instead.
ncu-ci: Parse the results of a Jenkins CI run and display a summary for all the failures.

Usage

Install

npm install -g @node-core/utils

If you would prefer to build from the source, install and link:

git clone git@github.com:nodejs/node-core-utils.git
cd node-core-utils
npm ci
npm link

Setting up GitHub credentials

Most of the tools need your GitHub credentials to work. You can either

Run any of the tools and you will be asked in a prompt to provide your username and password in order to create a personal access token.
Or, create a personal access token yourself on GitHub, then set them up using an editor.

If you prefer option 2, follow these instructions to create the token.

When creating the token, the following boxes need to be checked:

user:email: Used by git-node and get-metadata to read the email of the PR author in order to check if it matches the email of the commit author.
read:org: Used by ncu-team to read the list of team members.

Optionally, if you want to grant write access so git-node can write comments:

public_repo (or repo if you intend to work with private repositories).

You can also edit the permission of existing tokens later.

After the token is generated, create an rc file with the following content: (~/.ncurc or $XDG_CONFIG_HOME/ncurc):

{
  "username": "your_github_username",
  "token": "token_that_you_created"
}

Note: you could use ncu-config to configure these variables, but it’s not recommended to leave your tokens in your command line history.

Setting up Jenkins credentials

The git-node and ncu-ci commands need to query the Node.js Jenkins API for CI results, so you’ll need to configure the Jenkins API token before using these commands.

To obtain the Jenkins API token

Open https://ci.nodejs.org/user/<your-github-username>/security (replace <your-github-username> with your own GitHub username).
Click on the ADD NEW TOKEN button in the API Token section.
Enter an identifiable name (for example, node-core-utils) for this token in the inbox that appears, and click GENERATE.
Copy the generated token.
Add it into your ncurc file (~/.ncurc or $XDG_CONFIG_HOME/ncurc, or ~/.ncurc.gpg or $XDG_CONFIG_HOME/ncurc.gpg) with jenkins_token as key, like this:
```
{
  "username": "your_github_username",
  "token": "your_github_token",
  "jenkins_token": "your_jenkins_token"
}
```

Protecting your credentials

If you have gpg installed and setup on your local machine, it is strongly recommended to store an encrypted version of this file:

$ gpg --default-recipient-self --encrypt ~/.ncurc
$ rm ~/.ncurc

The credentials are now encrypted in ~/.ncurc.gpg and everytime it’s needed, node-core-utils will invoke gpg that may ask you to decrypt it using your default key via pinentry.

Put the following entries into your global gitignore file ($XDG_CONFIG_HOME/git/ignore or a file specified by core.excludesFile). For example:

$ git config --global core.excludesfile ~/.gitignore_global

# In ~/.gitignore_global
# node-core-utils configuration file
.ncurc
.ncurc.gpg
# node-core-utils working directory
.ncu

Mind that .ncu/land could contain your access token since it contains the serialized configurations.

If you ever accidentally commit your access token on GitHub, you can simply revoke that token and use a new one.

Shell autocomplete

To add autocomplete just run git-node completion and follow the instructions. (same for the rest of the tools)

Troubleshooting

If you encounter an error that you cannot fix by yourself, please

Make sure you update NCU to the latest version
Try again with the NCU_VERBOSITY=debug environment variable set and open an issue at https://github.com/nodejs/node-core-utils/issues with detailed logs.

Contributing

See CONTRIBUTING.md.

License

MIT. See LICENSE.

This site is open source. Improve this page.