Fleetshift: Writing and Publishing npm Package Shifts

Fleetshift’s npm-package shift type lets you write a deterministic shift as a standard npm package. You publish a Node.js CLI to your Portal instance’s private registry and select it in the fleetshift wizard. This is useful when you want the shift logic to live in your own repository, go through your normal code review process, and be pinned to an exact version. Each change to the shift is a reviewed PR, and each deployment is an npm publish.

Writing a shift package

A shift package is a regular npm package with a bin entry. When fleetshift runs your shift against a target repository, it:

Clones the target repository into a working directory.
Sets process.cwd() to the cloned repo.
Runs your binary.

Your binary modifies files in the working directory and exits. Fleetshift handles the git diff, branch creation, and pull request.

Minimal example

Directory structure:

my-shift/
├── package.json
└── bin/
    └── my-shift

package.json:

{
  "name": "@fleetshift/my-shift",
  "version": "1.0.0",
  "bin": "./bin/my-shift",
  "files": ["bin"],
  "license": "UNLICENSED"
}

bin/my-shift:

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

const configPath = path.join(process.cwd(), '.eslintrc.json');

if (!fs.existsSync(configPath)) {
  console.log('No .eslintrc.json found — skipping.');
  process.exit(0);
}

const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
config.rules = config.rules ?? {};
config.rules['no-console'] = 'warn';

fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
console.log('Added no-console rule to .eslintrc.json');

Make the binary executable: chmod +x bin/my-shift

Package naming rules

All packages must use the @fleetshift/ scope: @fleetshift/my-shift
The unscoped part must be lowercase and can only contain letters, digits, ., _, -
No protocol or path specifiers (github:, https://, file:)

Exit codes

Exit code	Result
`0`	Success. If your binary made file changes, fleetshift creates a PR. If no files changed, the target is marked “no changes”.
Non-zero	The target is marked as failed.

Publishing to your Portal registry

Portal exposes an npm registry proxy that your shift packages are published through. This works the same way as publishing custom plugins — you use your existing Backstage service token to authenticate.

Step 1: Configure npm authentication

Add an .npmrc file to your shift repository (or your home directory):

@fleetshift:registry=https://<your-portal-host>/api/fleetshift/registry/npm/
//<your-portal-host>/api/fleetshift/registry/npm/:_authToken=${PORTAL_SERVICE_TOKEN}

Replace <your-portal-host> with your Portal instance’s hostname (for example, my-company.spotifyportal.com). The first line tells npm to route @fleetshift/* packages to your Portal registry. Without it, npm uses the default registry and authentication will fail. To create your publish token:

Generate a secure random token string (e.g. openssl rand -base64 32).
In your Portal instance, go to App Settings (/admin/app-settings).
Under External Access, click Add Item.
Set type static, subject fleetshift-npm-registry, access restriction plugin fleetshift, and paste your generated token.
Save. Use the same token value in your .npmrc above.

Step 2: Publish

npm publish

No --registry flag is needed — the .npmrc scope line handles routing.

Publishing from CI

For automated publishing, store the service token as a CI secret. Example with GitHub Actions:

- name: Publish shift package
  env:
    PORTAL_SERVICE_TOKEN: ${{ secrets.PORTAL_SERVICE_TOKEN }}
  run: |
    echo "@fleetshift:registry=https://<your-portal-host>/api/fleetshift/registry/npm/" >> .npmrc
    echo "//<your-portal-host>/api/fleetshift/registry/npm/:_authToken=${PORTAL_SERVICE_TOKEN}" >> .npmrc
    npm publish

Creating a shift in the wizard

Open Fleetshift in your Portal sidebar.
Click New Shift and select npm Package.
Enter the package name (for example, @fleetshift/my-shift).
Pick a version to pin. Only exact versions are accepted — no ranges like ^1.0.0 or ~1.0.0.
Optionally specify a custom bin name. Defaults to the unscoped package name (for example, my-shift for @fleetshift/my-shift).
Optionally add arguments to pass to the binary.
Configure targets, PR template, and other settings as usual.
Click Create.

Updating a shift version

To roll out a new version of your shift logic:

Make your changes and bump the version in package.json.
Open a PR in your shift repository and get it reviewed.
Merge and publish the new version.
In Fleetshift, edit the shift and update the pinned version.

Sandbox constraints

npm package shifts run inside a locked-down container. Keep these restrictions in mind when writing your binary.

Constraint	Detail
No lifecycle scripts	`npm install` runs with `--ignore-scripts`. Your package and its dependencies cannot run postinstall, preinstall, or prepare scripts. Native addons will not work.
Restricted network	Outbound network is restricted. Your binary should not depend on making HTTP requests to external services at runtime.
No root	The container runs as a non-root user.
Non-interactive	No stdin. Your binary cannot prompt for user input.

A note on dependencies

Since lifecycle scripts are disabled, stick to pure JavaScript or TypeScript dependencies.

​Writing a shift package

​Minimal example

​Package naming rules

​Exit codes

​Publishing to your Portal registry

​Step 1: Configure npm authentication

​Step 2: Publish

​Publishing from CI

​Creating a shift in the wizard

​Updating a shift version

​Sandbox constraints

​A note on dependencies