Installing Custom Plugins
Published on March 17th, 2021Introduction
Custom plugins are a feature of the Growth Plan.
Your plugins can be published via npm or yarn, like publishing a normal package. We will provide you a unique scope for your plugins, and we host a dedicated npm registry which you can publish to.
Prerequisites
Contact us to get added to our private and secure plugin artefact repository.
Pushing the plugin to Roadie
Step 1. Get credentials
Get your credentials for the npm registry.
Follow this link and click “Forgot password?” to reset your password. The username is
<your-company>-roadie
. This will send a reset link to the email we have associated with your account. You can
change this email as you wish.
When you follow the link in this email you will be asked to enter the new password. Then you will be asked to configure MFA. This is only required using the web interface. While the Artifactory UI suggests you must use Google Authenticator other applications are accepted. We have tested with 1Password for example.
Step 2. Configure NPM
To configure NPM there are two options:
-
Interactively using npm login. Suitable for a developer testing the process.
npm config set @<your-company>-roadie:registry https://roadiehq.jfrog.io/artifactory/api/npm/<your-company>-roadie/ npm login --scope=@<your-company>-roadie # This will prompt for your username, password and email
-
For a CI/CD engironment you can write a local
.npmrc
file. Start by creating the authentication token by applying base64 to the username and password. Example:printf "%s:%s"
| base64 --wrap 0 Then create the
.npmrc
file like in the following example:@<your-company>-roadie:registry=<https://roadiehq.jfrog.io/artifactory/api/npm/<your-company>-roadie/> #_auth = base64(username:password) _auth = ${NPM_AUTH} # You can also use an environment variable email = your-artifactory-account-email-address always-auth = true
Step 3. Publishing
Once you’re ready to publish your plugin these are the steps you’ll need to follow:
- Ensure your package is scoped correctly in package.json. The name field should follow this pattern
@<your-company>-roadie/<package-name>
- Select a new package version to publish. You can’t overwrite a version once published (e.g.
npm version patch
) - Build your plugin (e.g.
yarn && yarn tsc && yarn build
) - Publish your plugin
npm publish
- (Optional) Check the registry
npm info @<your-company>-roadie/<package-name>
We will notify you via Slack once the plugin is ready in your Roadie Backstage instance. Further updates to the npm package will be picked up and released automatically and you can expect the changes to appear in Backstage after 15-20 minutes.
Conclusion
Once the steps above have been completed successfully and you have been notified that your plugin is ready to use, you should be able to log into your Backstage instance and use the plugin just like any other plugin.
You can update your plugin at will and modify its versions if needed in the custom plugin configuration page. Using the version keyword latest
will always update plugins automatically with the latest version when new plugin is published to Artifactory.