Installing Custom Plugins

⚠️ We are soon deprecating legacy custom plugins pipeline. Take a look at the documentation for current custom plugin method instead

Introduction

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

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.