This package is compatible with Node 12+ and is distributed on npm.
The fastest way to get developing with
rel-engage is to run the package via npx:
Alternatively you can run the both install steps manually:
# 1. Download and save the package npm install --save-dev @financial-times/rel-engage # 2. Run the install command ./node_modules/.bin/rel-engage
As part of the install step several configuration files will be created as well as a new
Makefile. See the commands documentation to find out more.
rel-engage a new
Makefile will be added to your project. This provides a number of commands for common tasks, including:
installto install Node modules and create configuration files.
verifyto run linting and formatting tools.
cleanto undo all changes and remove files that are not tracked by version control.
envto fetch and save project secrets
To view a list of all commands and their descriptions, run:
Each time you run the
make install command provided by this package a number of configuration files will be added to your project if not already present:
.editorconfig) - provides whitespace settings for your editor when creating new files.
.huskyrc.js) - installs and configures Git hooks to run commands before committing and pushing code.
.lintstagedrc.js) - configures commands to run only on changed files that will be committed.
The created "dotfiles" link to shared configuration provided by this package and do not contain any rules themselves.
These rules should rarely need to be overridden but if you do need to then it's possible to directly modify them, either by using the built in support for the tool (e.g ESLint supports an
Project secrets (such as API keys) are stored in Vault and can be retrieved and stored in a
.env file in your project. If a
.env file exists in your project then
rel-engage will use it each time you run a command defined in the
Secrets in Vault are stored in folders and may be arranged hierarchically up to 3 levels deep:
To configure where the secrets for your project should be fetched from you should set one or more of the following variables in your
PROJECT_NAME=your-project-name PRODUCT_NAME=your-product-name PLATFORM_NAME=your-platform-name
Please note that you should always take steps to prevent ever committing secrets to your code repository and it is strongly advised to add
.env to your gitignore rules.
Secrets for local development
To get started, ensure that you have the vault-cli installed and configured correctly and that you are in the
reliability-engineering GitHub team.
Once this is done you should be able to run the
make test-env command. If you run into any problems then you can ask for help on the #reliability-eng Slack channel.
Secrets on CircleCI
When Vault credentials are required as part of your CI pipeline these can be retrieved by appending the
rel-eng-creds context to your workflow jobs:
jobs: install: steps: - run: name: Get secrets command: make .env workflows: build-and-release: jobs: - install: context: rel-eng-creds
N.B: use as a context
rel-eng-basic-creds- for a CI job that you want to be run by anyone outside of our team members in Github.
rel-eng-creds- for a CI job that you want to only be run by our team, Cloud enablement team members in Github and Githuhub org owners as well as for jobs that require you to fetch secrets from Vault
Keeping secrets safe
To help ensure that your project's secrets stay private this package depends on Secret Squirrel which is a tool used to scans your source code and warn you if it finds anything that looks like it might be better kept secret. This project configures Secret Squirrel to scan your code before each Git commit is made.
Snyk can be used to scan dependencies for security vulnerabilities after installing your project. The Snyk tool will be installed by
rel-engage but to ensure it is protecting your project you'll need to ensure Snyk is able to test and monitor it. To do so run the following command (this may require you to login to Snyk via SSO):
This will add the
snyk package as a direct dependency of your project. To integrate Snyk as part of your project's CI workflow you can use the Snyk Orb.
To get started with this project you'll need to make sure you have the following software tools installed.
Please note that Page Kit has only been tested in Mac and Linux environments. If you are on a Mac you may find it easiest to install the Command Line Tools package which includes Git.
Clone the project's Git repository and change to the new directory that has been created:
git clone firstname.lastname@example.org:Financial-Times/rel-engage cd rel-engage
Install all of the project dependencies (this may take a few minutes if you are running this for the first time):