npm

Description

This plugin enables the ability to manage artifacts in npm in a Vela pipeline.

Source Code: https://github.com/go-vela/vela-npm

Registry: https://hub.docker.com/r/target/vela-npm

Usage

NOTE:
Users should refrain from using latest as the tag for the Docker image.
It is recommended to use a semantically versioned tag instead.

Sample of publishing package:

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org

Sample of publishing if registry does not support npm ping:

NOTE:
Recommended if you are deploying to a registry inside Artifactory

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org
+     skip_ping: true

Sample of pretending to publish package:

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org
+     dry_run: true

Sample of first time publishing package:

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org
+     first_publish: true

Sample of publishing with additional dist-tag:

NOTE:
Tags are used as an alias and cannot be valid semver

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org
+     tag: beta

Higher level of tolerance for npm audit:

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org
+     audit_level: critical

Secrets

NOTE:
Users should refrain from configuring sensitive information in their pipeline in plain text.

Internal

The plugin accepts the following parameters for authentication:

Parameter	Environment Variable Configuration
`password`	`NPM_PASSWORD`, `PARAMETER_PASSWORD`
`username`	`NPM_USERNAME`, `PARAMETER_USERNAME`
`registry`	`NPM_REGISTRY`, `PARAMETER_REGISTRY`
`email`	`NPM_EMAIL`, `PARAMETER_EMAIL`

Users can use Vela internal secrets to substitute these sensitive values at runtime:

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    secrets: [ npm_password ]
    parameters:
      username: npmUsername
      registry: https://registry.npmjs.org
-     password: superSecretPassword

This example will add the secrets to the npm_publish step as environment variables:
NPM_PASSWORD=value

External

The plugin accepts the following files for authentication:

Parameter	Volume Configuration
`password`	`/vela/parameters/npm/password`, `/vela/secrets/npm/password`, `/vela/secrets/managed-auth/password`
`username`	`/vela/parameters/npm/username`, `/vela/secrets/npm/username`, `/vela/secrets/managed-auth/username`
`registry`	`/vela/parameters/npm/registry`, `/vela/secrets/npm/registry`
`email`	`/vela/parameters/npm/email`, `/vela/secrets/npm/email`

Users can use Vela external secrets to substitute these sensitive values at runtime:

steps:
  - name: npm_publish
    image: target/vela-npm:latest
    pull: not_present
    parameters:
      registry: https://registry.npmjs.org
-     username: npmUsername
-     password: superSecretPassword

Parameters

The following parameters are used to configure the image:

Name	Description	Required	Default	Environment Variables
`username`	username for communication with npm	`true`	`N/A`	`PARAMETER_USERNAME` `NPM_USERNAME`
`password`	password for communication with npm	`false`	`N/A`	`PARAMETER_PASSWORD` `NPM_PASSWORD`
`email`	email for communication with npm	`false`	`N/A`	`PARAMETER_EMAIL` `NPM_EMAIL`
`token`	auth token for communication with npm	`false`	`N/A`	`PARAMETER_TOKEN` `TOKEN`
`registry`	npm instance to communicate with	`false`	`https://registry.npmjs.org`	`PARAMETER_REGISTRY` `NPM_REGISTRY`
`audit_level`	level at which the audit check should fail (valid options: `low`, `moderate`, `high`, `critical`, `none` to skip)	`false`	`low`	`PARAMETER_AUDIT_LEVEL` `AUDIT_LEVEL`
`strict_ssl`	whether or not to do SSL key validation during communication	`false`	`true`	`PARAMETER_STRICT_SSL` `STRICT_SSL`
`always_auth`	force npm to always require authentication	`false`	`false`	`PARAMETER_ALWAYS_AUTH` `ALWAYS_AUTH`
`skip_ping`	whether or not to skip `npm ping` authentication command	`false`	`false`	`PARAMETER_SKIP_PING` `SKIP_PING`
`dry_run`	enables pretending to perform the action	`false`	`false`	`PARAMETER_DRY_RUN` `DRY_RUN`
`tag`	publish package with given alias tag	`false`	`latest`	`PARAMETER_TAG` `TAG`
`log_level`	set the log level for the plugin (valid options: `info`, `debug`, `trace`)	`true`	`info`	`PARAMETER_LOG_LEVEL` `LOG_LEVEL`
`workspaces`	publish all workspaces	`false`	`false`	`PARAMETER_WORKSPACES` `WORKSPACES`
`workspace`	publish a specific workspace by specifying the workspace name or relative path	`false`	`N/A`	`PARAMETER_WORKSPACE` `WORKSPACE`
`access`	Tells the registry whether this package should be published as public or restricted. Only applies to scoped packages, which default to restricted	`false`	`restricted`	`PARAMETER_ACCESS` `ACCESS`

package.json

This is your module’s manifest. There are a few important keys that need to be set in order to publish your module

name - your package name that will be checked against in the registry
version - your package version that will be used to publish, it must be valid semver and unique to the registry
private - this needs to be set to false even if you are publishing it internally.
publishConfig - this should be configured to your registry location and registry parameter should match this value

For example values, see npm’s documentation

Template

COMING SOON!

Troubleshooting

Here are the available log levels to assist in troubleshooting: trace, debug, info, warn, error, fatal, panic

Last modified September 1, 2022: feat: npm plugin docs (#317) (fa9bbf5a)