From eedc0fbd4ec6a6977d5773c6c7fd3f7cbc40f16d Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Thu, 22 Apr 2021 22:14:24 +0200 Subject: [PATCH 1/5] docs: rewrite private npm module support --- docs/usage/private-modules.md | 55 ++++++++++++++++++++--------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/docs/usage/private-modules.md b/docs/usage/private-modules.md index de8f6e3a801f4a..d19e04af0c2b49 100644 --- a/docs/usage/private-modules.md +++ b/docs/usage/private-modules.md @@ -1,28 +1,37 @@ --- title: Private npm module support -description: How to support private npm modules when using Renovate +description: How to support private npm modules when using Renovate --- # Private npm module support ## When are npm private modules used? -Private npm modules are used at two times during Renovate's process. +Private npm modules are used at two times during Renovate's process: -### 1. Module lookup +1. Module lookup +1. Lock file generation -If a private npm module is listed as a dependency in a `package.json`, then Renovate will attempt to keep it up-to-date by querying the npm registry like it would for any other package. -Hence, by default with no configuration a private package lookup will fail, because of lack of credentials. -This means it won't be "renovated" and its version will remain unchanged in the package file unless you update it manually. -These failures don't affect Renovate's ability to look up _other_ modules in the same package file. +This is explained in more detail below. -Assuming the private module lookup succeeds (solutions for that are described later in this document) then private package versions will be kept up-to-date like public package versions are. +### Module lookup -### 2. Lock file generation +If a private npm module is listed as a dependency in the `package.json` file Renovate attempts to keep it up-to-date. +Renovate queries the npm registry like it does for any other package. +By default Renovate runs without any credentials, and so any private package lookup will fail. +This means, that any private package will not be renovated, and must be updated manually. +The failure to authenticate doesn't affect Renovate's ability to look up _other_ modules in the same package file. -If you are using a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate needs to update that lock file whenever _any_ package listed in your package file is updated to a new version. +You can fix the private package lookup problem by providing the Renovate bot with the proper credentials. +This is described later in this document. -To do this, Renovate will run `npm install` or equivalent and save the resulting lock file. +Assuming the private module lookup succeeds then private package versions will be kept up-to-date like the public package versions are. + +### Lock file generation + +If you use a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate must update that lock file whenever _any_ package listed in your package file is updated to a new version. + +To do this, Renovate runs `npm install` or equivalent and saves the resulting lock file. If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. It's therefore better to provide Renovate with all the credentials it needs to look up private packages. @@ -31,13 +40,11 @@ It's therefore better to provide Renovate with all the credentials it needs to l The recommended approaches in order of preference are: -**Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `hostName` and `token` specified - -**Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config - -**Renovate App with a private registry**: Add an unencrypted `npmrc` plus an encrypted `npmToken` in config +1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `hostName` and `token` specified +1. **Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config +1. **Renovate App with a private registry**: Add an unencrypted `npmrc` plus an encrypted `npmToken` in config -All the various approaches are described below: +These approaches are described in full below. ### Add hostRule to bots config @@ -88,7 +95,7 @@ If you are using the main npmjs registry then you can configure just the npmToke ### Add an encrypted npm token to Renovate config -If you don't wish for all users of the repository to be able to see the unencrypted token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. +If you don't want all users of the repository to see the unencrypted token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. Go to , paste in your npm token, click "Encrypt", then copy the encrypted result. @@ -102,7 +109,7 @@ Add the encrypted result inside an `encrypted` object like this: } ``` -If you have no `.npmrc` file then Renovate will create one for you, pointing to the default npmjs registry. +If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. ```json @@ -117,15 +124,15 @@ If instead you use an alternative registry or need an `.npmrc` file for some oth Renovate will then use the following logic: 1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry -2. If an `npmrc` string is present and contains `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token -3. If an `npmrc` string is present but doesn't contain `${NPM_TOKEN}` then the file will have `_authToken=` appended to it +1. If an `npmrc` string is present and contains `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token +1. If an `npmrc` string is present but doesn't contain `${NPM_TOKEN}` then the file will have `_authToken=` appended to it ### Encrypted entire .npmrc file into config -Copy the entire .npmrc, replace newlines with `\n` chars, and then try encrypting it at +Copy the entire `.npmrc`, replace newlines with `\n` chars, and then try encrypting it at -You will then get an encrypted string that you can substitute into your renovate.json instead. -The result will now look something like this: +You will then get an encrypted string that you can substitute into your `renovate.json` instead. +The end-result looks like this: ```json { From edbde5cc1752a5e98be7019dbea697c6d06bc2db Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Thu, 22 Apr 2021 22:22:00 +0200 Subject: [PATCH 2/5] further improvements --- docs/usage/private-modules.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/usage/private-modules.md b/docs/usage/private-modules.md index d19e04af0c2b49..d7efa9c7fad7f5 100644 --- a/docs/usage/private-modules.md +++ b/docs/usage/private-modules.md @@ -85,7 +85,7 @@ If configured like this, Renovate will use this to authenticate with npm and wil ### Add npmToken to Renovate config -If you are using the main npmjs registry then you can configure just the npmToken instead: +If you are using the main npmjs registry then you can configure just the `npmToken` instead: ```json { @@ -99,7 +99,7 @@ If you don't want all users of the repository to see the unencrypted token, you Go to , paste in your npm token, click "Encrypt", then copy the encrypted result. -Add the encrypted result inside an `encrypted` object like this: +Paste the encrypted result inside an `encrypted` object like this: ```json { @@ -129,7 +129,7 @@ Renovate will then use the following logic: ### Encrypted entire .npmrc file into config -Copy the entire `.npmrc`, replace newlines with `\n` chars, and then try encrypting it at +Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . You will then get an encrypted string that you can substitute into your `renovate.json` instead. The end-result looks like this: From c9ba0c41690cc2c26d24aede2404dc7e8b4569bb Mon Sep 17 00:00:00 2001 From: HonkingGoose <34918129+HonkingGoose@users.noreply.github.com> Date: Fri, 23 Apr 2021 14:46:30 +0200 Subject: [PATCH 3/5] rename file to be npm specific --- docs/usage/{private-modules.md => private-npm-modules.md} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/usage/{private-modules.md => private-npm-modules.md} (100%) diff --git a/docs/usage/private-modules.md b/docs/usage/private-npm-modules.md similarity index 100% rename from docs/usage/private-modules.md rename to docs/usage/private-npm-modules.md From 7279b2eec3d9be95d1b83e1eb530a28dc93bd445 Mon Sep 17 00:00:00 2001 From: Rhys Arkins Date: Fri, 23 Apr 2021 15:34:48 +0200 Subject: [PATCH 4/5] add private-modules --- docs/usage/private-modules.md | 145 ++++++++++++++++++++++++++++++ docs/usage/private-npm-modules.md | 145 ++---------------------------- 2 files changed, 150 insertions(+), 140 deletions(-) create mode 100644 docs/usage/private-modules.md diff --git a/docs/usage/private-modules.md b/docs/usage/private-modules.md new file mode 100644 index 00000000000000..d7efa9c7fad7f5 --- /dev/null +++ b/docs/usage/private-modules.md @@ -0,0 +1,145 @@ +--- +title: Private npm module support +description: How to support private npm modules when using Renovate +--- + +# Private npm module support + +## When are npm private modules used? + +Private npm modules are used at two times during Renovate's process: + +1. Module lookup +1. Lock file generation + +This is explained in more detail below. + +### Module lookup + +If a private npm module is listed as a dependency in the `package.json` file Renovate attempts to keep it up-to-date. +Renovate queries the npm registry like it does for any other package. +By default Renovate runs without any credentials, and so any private package lookup will fail. +This means, that any private package will not be renovated, and must be updated manually. +The failure to authenticate doesn't affect Renovate's ability to look up _other_ modules in the same package file. + +You can fix the private package lookup problem by providing the Renovate bot with the proper credentials. +This is described later in this document. + +Assuming the private module lookup succeeds then private package versions will be kept up-to-date like the public package versions are. + +### Lock file generation + +If you use a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate must update that lock file whenever _any_ package listed in your package file is updated to a new version. + +To do this, Renovate runs `npm install` or equivalent and saves the resulting lock file. +If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. +However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. +It's therefore better to provide Renovate with all the credentials it needs to look up private packages. + +## Supported npm authentication approaches + +The recommended approaches in order of preference are: + +1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `hostName` and `token` specified +1. **Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config +1. **Renovate App with a private registry**: Add an unencrypted `npmrc` plus an encrypted `npmToken` in config + +These approaches are described in full below. + +### Add hostRule to bots config + +Define `hostRules` like this: + +```js +module.exports = { + hostRules: [ + { + hostType: 'npm', + hostName: 'registry.npmjs.org', + token: process.env.NPMJS_TOKEN, + }, + { + hostType: 'npm', + baseUrl: + 'https://pkgs.dev.azure.com/{organization}/_packaging/{feed}/npm/registry/', + username: 'VssSessionToken', + password: process.env.AZURE_NPM_TOKEN, + }, + ], +}; +``` + +**NOTE:** Do not use `NPM_TOKEN` as an environment variable. + +### Add npmrc string to Renovate config + +You can add an `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: + +```json +{ + "npmrc": "//some.registry.com/:_authToken=abcdefghi-1234-jklmno-aac6-12345567889" +} +``` + +If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. + +### Add npmToken to Renovate config + +If you are using the main npmjs registry then you can configure just the `npmToken` instead: + +```json +{ + "npmToken": "abcdefghi-1234-jklmno-aac6-12345567889" +} +``` + +### Add an encrypted npm token to Renovate config + +If you don't want all users of the repository to see the unencrypted token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. + +Go to , paste in your npm token, click "Encrypt", then copy the encrypted result. + +Paste the encrypted result inside an `encrypted` object like this: + +```json +{ + "encrypted": { + "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" + } +} +``` + +If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. +If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. + +```json +{ + "encrypted": { + "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" + }, + "npmrc": "registry=https://my.custom.registry/npm\n//my.custom.registry/npm:_authToken=${NPM_TOKEN}" +} +``` + +Renovate will then use the following logic: + +1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry +1. If an `npmrc` string is present and contains `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token +1. If an `npmrc` string is present but doesn't contain `${NPM_TOKEN}` then the file will have `_authToken=` appended to it + +### Encrypted entire .npmrc file into config + +Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . + +You will then get an encrypted string that you can substitute into your `renovate.json` instead. +The end-result looks like this: + +```json +{ + "encrypted": { + "npmrc": "WOTWu+jliBtXYz3CU2eI7dDyMIvSJKS2N5PEHZmLB3XKT3vLaaYTGCU6m92Q9FgdaM/q2wLYun2JrTP4GPaW8eGZ3iiG1cm7lgOR5xPnkCzz0DUmSf6Cc/6geeVeSFdJ0zqlEAhdNMyJ4pUW6iQxC3WJKgM/ADvFtme077Acvc0fhCXv0XvbNSbtUwHF/gD6OJ0r2qlIzUMGJk/eI254xo5SwWVctc1iZS9LW+L0/CKjqhWh4SbyglP3lKE5shg3q7mzWDZepa/nJmAnNmXdoVO2aPPeQCG3BKqCtCfvLUUU/0LvnJ2SbQ1obyzL7vhh2OF/VsATS5cxbHvoX/hxWQ==" + } +} +``` + +However be aware that if your `.npmrc` is too long to encrypt then the above command will fail. diff --git a/docs/usage/private-npm-modules.md b/docs/usage/private-npm-modules.md index d7efa9c7fad7f5..f64a6dfe4eb656 100644 --- a/docs/usage/private-npm-modules.md +++ b/docs/usage/private-npm-modules.md @@ -1,145 +1,10 @@ --- -title: Private npm module support -description: How to support private npm modules when using Renovate +title: Private module support +description: How to support private modules when using Renovate --- -# Private npm module support +# Private module support -## When are npm private modules used? +## npm -Private npm modules are used at two times during Renovate's process: - -1. Module lookup -1. Lock file generation - -This is explained in more detail below. - -### Module lookup - -If a private npm module is listed as a dependency in the `package.json` file Renovate attempts to keep it up-to-date. -Renovate queries the npm registry like it does for any other package. -By default Renovate runs without any credentials, and so any private package lookup will fail. -This means, that any private package will not be renovated, and must be updated manually. -The failure to authenticate doesn't affect Renovate's ability to look up _other_ modules in the same package file. - -You can fix the private package lookup problem by providing the Renovate bot with the proper credentials. -This is described later in this document. - -Assuming the private module lookup succeeds then private package versions will be kept up-to-date like the public package versions are. - -### Lock file generation - -If you use a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate must update that lock file whenever _any_ package listed in your package file is updated to a new version. - -To do this, Renovate runs `npm install` or equivalent and saves the resulting lock file. -If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. -However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. -It's therefore better to provide Renovate with all the credentials it needs to look up private packages. - -## Supported npm authentication approaches - -The recommended approaches in order of preference are: - -1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `hostName` and `token` specified -1. **Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config -1. **Renovate App with a private registry**: Add an unencrypted `npmrc` plus an encrypted `npmToken` in config - -These approaches are described in full below. - -### Add hostRule to bots config - -Define `hostRules` like this: - -```js -module.exports = { - hostRules: [ - { - hostType: 'npm', - hostName: 'registry.npmjs.org', - token: process.env.NPMJS_TOKEN, - }, - { - hostType: 'npm', - baseUrl: - 'https://pkgs.dev.azure.com/{organization}/_packaging/{feed}/npm/registry/', - username: 'VssSessionToken', - password: process.env.AZURE_NPM_TOKEN, - }, - ], -}; -``` - -**NOTE:** Do not use `NPM_TOKEN` as an environment variable. - -### Add npmrc string to Renovate config - -You can add an `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: - -```json -{ - "npmrc": "//some.registry.com/:_authToken=abcdefghi-1234-jklmno-aac6-12345567889" -} -``` - -If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. - -### Add npmToken to Renovate config - -If you are using the main npmjs registry then you can configure just the `npmToken` instead: - -```json -{ - "npmToken": "abcdefghi-1234-jklmno-aac6-12345567889" -} -``` - -### Add an encrypted npm token to Renovate config - -If you don't want all users of the repository to see the unencrypted token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. - -Go to , paste in your npm token, click "Encrypt", then copy the encrypted result. - -Paste the encrypted result inside an `encrypted` object like this: - -```json -{ - "encrypted": { - "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" - } -} -``` - -If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. -If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. - -```json -{ - "encrypted": { - "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" - }, - "npmrc": "registry=https://my.custom.registry/npm\n//my.custom.registry/npm:_authToken=${NPM_TOKEN}" -} -``` - -Renovate will then use the following logic: - -1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry -1. If an `npmrc` string is present and contains `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token -1. If an `npmrc` string is present but doesn't contain `${NPM_TOKEN}` then the file will have `_authToken=` appended to it - -### Encrypted entire .npmrc file into config - -Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . - -You will then get an encrypted string that you can substitute into your `renovate.json` instead. -The end-result looks like this: - -```json -{ - "encrypted": { - "npmrc": "WOTWu+jliBtXYz3CU2eI7dDyMIvSJKS2N5PEHZmLB3XKT3vLaaYTGCU6m92Q9FgdaM/q2wLYun2JrTP4GPaW8eGZ3iiG1cm7lgOR5xPnkCzz0DUmSf6Cc/6geeVeSFdJ0zqlEAhdNMyJ4pUW6iQxC3WJKgM/ADvFtme077Acvc0fhCXv0XvbNSbtUwHF/gD6OJ0r2qlIzUMGJk/eI254xo5SwWVctc1iZS9LW+L0/CKjqhWh4SbyglP3lKE5shg3q7mzWDZepa/nJmAnNmXdoVO2aPPeQCG3BKqCtCfvLUUU/0LvnJ2SbQ1obyzL7vhh2OF/VsATS5cxbHvoX/hxWQ==" - } -} -``` - -However be aware that if your `.npmrc` is too long to encrypt then the above command will fail. +Please see [Private npm module support](./private-npm-modules) From fb791fbcad5c74ef356127d8b87712159e2759a9 Mon Sep 17 00:00:00 2001 From: Rhys Arkins Date: Fri, 23 Apr 2021 15:36:30 +0200 Subject: [PATCH 5/5] switch --- docs/usage/private-modules.md | 145 ++---------------------------- docs/usage/private-npm-modules.md | 145 ++++++++++++++++++++++++++++-- 2 files changed, 145 insertions(+), 145 deletions(-) diff --git a/docs/usage/private-modules.md b/docs/usage/private-modules.md index d7efa9c7fad7f5..f64a6dfe4eb656 100644 --- a/docs/usage/private-modules.md +++ b/docs/usage/private-modules.md @@ -1,145 +1,10 @@ --- -title: Private npm module support -description: How to support private npm modules when using Renovate +title: Private module support +description: How to support private modules when using Renovate --- -# Private npm module support +# Private module support -## When are npm private modules used? +## npm -Private npm modules are used at two times during Renovate's process: - -1. Module lookup -1. Lock file generation - -This is explained in more detail below. - -### Module lookup - -If a private npm module is listed as a dependency in the `package.json` file Renovate attempts to keep it up-to-date. -Renovate queries the npm registry like it does for any other package. -By default Renovate runs without any credentials, and so any private package lookup will fail. -This means, that any private package will not be renovated, and must be updated manually. -The failure to authenticate doesn't affect Renovate's ability to look up _other_ modules in the same package file. - -You can fix the private package lookup problem by providing the Renovate bot with the proper credentials. -This is described later in this document. - -Assuming the private module lookup succeeds then private package versions will be kept up-to-date like the public package versions are. - -### Lock file generation - -If you use a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate must update that lock file whenever _any_ package listed in your package file is updated to a new version. - -To do this, Renovate runs `npm install` or equivalent and saves the resulting lock file. -If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. -However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. -It's therefore better to provide Renovate with all the credentials it needs to look up private packages. - -## Supported npm authentication approaches - -The recommended approaches in order of preference are: - -1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `hostName` and `token` specified -1. **Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config -1. **Renovate App with a private registry**: Add an unencrypted `npmrc` plus an encrypted `npmToken` in config - -These approaches are described in full below. - -### Add hostRule to bots config - -Define `hostRules` like this: - -```js -module.exports = { - hostRules: [ - { - hostType: 'npm', - hostName: 'registry.npmjs.org', - token: process.env.NPMJS_TOKEN, - }, - { - hostType: 'npm', - baseUrl: - 'https://pkgs.dev.azure.com/{organization}/_packaging/{feed}/npm/registry/', - username: 'VssSessionToken', - password: process.env.AZURE_NPM_TOKEN, - }, - ], -}; -``` - -**NOTE:** Do not use `NPM_TOKEN` as an environment variable. - -### Add npmrc string to Renovate config - -You can add an `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: - -```json -{ - "npmrc": "//some.registry.com/:_authToken=abcdefghi-1234-jklmno-aac6-12345567889" -} -``` - -If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. - -### Add npmToken to Renovate config - -If you are using the main npmjs registry then you can configure just the `npmToken` instead: - -```json -{ - "npmToken": "abcdefghi-1234-jklmno-aac6-12345567889" -} -``` - -### Add an encrypted npm token to Renovate config - -If you don't want all users of the repository to see the unencrypted token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. - -Go to , paste in your npm token, click "Encrypt", then copy the encrypted result. - -Paste the encrypted result inside an `encrypted` object like this: - -```json -{ - "encrypted": { - "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" - } -} -``` - -If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. -If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. - -```json -{ - "encrypted": { - "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" - }, - "npmrc": "registry=https://my.custom.registry/npm\n//my.custom.registry/npm:_authToken=${NPM_TOKEN}" -} -``` - -Renovate will then use the following logic: - -1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry -1. If an `npmrc` string is present and contains `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token -1. If an `npmrc` string is present but doesn't contain `${NPM_TOKEN}` then the file will have `_authToken=` appended to it - -### Encrypted entire .npmrc file into config - -Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . - -You will then get an encrypted string that you can substitute into your `renovate.json` instead. -The end-result looks like this: - -```json -{ - "encrypted": { - "npmrc": "WOTWu+jliBtXYz3CU2eI7dDyMIvSJKS2N5PEHZmLB3XKT3vLaaYTGCU6m92Q9FgdaM/q2wLYun2JrTP4GPaW8eGZ3iiG1cm7lgOR5xPnkCzz0DUmSf6Cc/6geeVeSFdJ0zqlEAhdNMyJ4pUW6iQxC3WJKgM/ADvFtme077Acvc0fhCXv0XvbNSbtUwHF/gD6OJ0r2qlIzUMGJk/eI254xo5SwWVctc1iZS9LW+L0/CKjqhWh4SbyglP3lKE5shg3q7mzWDZepa/nJmAnNmXdoVO2aPPeQCG3BKqCtCfvLUUU/0LvnJ2SbQ1obyzL7vhh2OF/VsATS5cxbHvoX/hxWQ==" - } -} -``` - -However be aware that if your `.npmrc` is too long to encrypt then the above command will fail. +Please see [Private npm module support](./private-npm-modules) diff --git a/docs/usage/private-npm-modules.md b/docs/usage/private-npm-modules.md index f64a6dfe4eb656..d7efa9c7fad7f5 100644 --- a/docs/usage/private-npm-modules.md +++ b/docs/usage/private-npm-modules.md @@ -1,10 +1,145 @@ --- -title: Private module support -description: How to support private modules when using Renovate +title: Private npm module support +description: How to support private npm modules when using Renovate --- -# Private module support +# Private npm module support -## npm +## When are npm private modules used? -Please see [Private npm module support](./private-npm-modules) +Private npm modules are used at two times during Renovate's process: + +1. Module lookup +1. Lock file generation + +This is explained in more detail below. + +### Module lookup + +If a private npm module is listed as a dependency in the `package.json` file Renovate attempts to keep it up-to-date. +Renovate queries the npm registry like it does for any other package. +By default Renovate runs without any credentials, and so any private package lookup will fail. +This means, that any private package will not be renovated, and must be updated manually. +The failure to authenticate doesn't affect Renovate's ability to look up _other_ modules in the same package file. + +You can fix the private package lookup problem by providing the Renovate bot with the proper credentials. +This is described later in this document. + +Assuming the private module lookup succeeds then private package versions will be kept up-to-date like the public package versions are. + +### Lock file generation + +If you use a lock file (e.g. Yarn's `yarn.lock` or npm's `package-lock.json`) then Renovate must update that lock file whenever _any_ package listed in your package file is updated to a new version. + +To do this, Renovate runs `npm install` or equivalent and saves the resulting lock file. +If a private module hasn't been updated, it _usually_ won't matter to npm/Yarn because they won't attempt to update its lock file entry anyway. +However it's possible that the install will fail if it attempts to look up that private module for some reason, even when that private module is not the main one being updated. +It's therefore better to provide Renovate with all the credentials it needs to look up private packages. + +## Supported npm authentication approaches + +The recommended approaches in order of preference are: + +1. **Self-hosted hostRules**: Configure a hostRules entry in the bot's `config.js` with the `hostType`, `hostName` and `token` specified +1. **Renovate App with private modules from npmjs.org**: Add an encrypted `npmToken` to your Renovate config +1. **Renovate App with a private registry**: Add an unencrypted `npmrc` plus an encrypted `npmToken` in config + +These approaches are described in full below. + +### Add hostRule to bots config + +Define `hostRules` like this: + +```js +module.exports = { + hostRules: [ + { + hostType: 'npm', + hostName: 'registry.npmjs.org', + token: process.env.NPMJS_TOKEN, + }, + { + hostType: 'npm', + baseUrl: + 'https://pkgs.dev.azure.com/{organization}/_packaging/{feed}/npm/registry/', + username: 'VssSessionToken', + password: process.env.AZURE_NPM_TOKEN, + }, + ], +}; +``` + +**NOTE:** Do not use `NPM_TOKEN` as an environment variable. + +### Add npmrc string to Renovate config + +You can add an `.npmrc` authentication line to your Renovate config under the field `npmrc`. e.g. a `renovate.json` might look like this: + +```json +{ + "npmrc": "//some.registry.com/:_authToken=abcdefghi-1234-jklmno-aac6-12345567889" +} +``` + +If configured like this, Renovate will use this to authenticate with npm and will ignore any `.npmrc` files(s) it finds checked into the repository. + +### Add npmToken to Renovate config + +If you are using the main npmjs registry then you can configure just the `npmToken` instead: + +```json +{ + "npmToken": "abcdefghi-1234-jklmno-aac6-12345567889" +} +``` + +### Add an encrypted npm token to Renovate config + +If you don't want all users of the repository to see the unencrypted token, you can encrypt it with Renovate's public key instead, so that only Renovate can decrypt it. + +Go to , paste in your npm token, click "Encrypt", then copy the encrypted result. + +Paste the encrypted result inside an `encrypted` object like this: + +```json +{ + "encrypted": { + "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" + } +} +``` + +If you have no `.npmrc` file then Renovate creates one for you, pointing to the default npmjs registry. +If instead you use an alternative registry or need an `.npmrc` file for some other reason, you should configure it too and substitute the npm token with `${NPM_TOKEN}` for it to be replaced. e.g. + +```json +{ + "encrypted": { + "npmToken": "xxT19RIdhAh09lkhdrK39HzKNBn3etoLZAwHdeJ25cX+5y52a9kAC7flXmdw5JrkciN08aQuRNqDaKxp53IVptB5AYOnQPrt8MCT+x0zHgp4A1zv1QOV84I6uugdWpFSjPUkmLGMgULudEZJMlY/dAn/IVwf/IImqwazY8eHyJAA4vyUqKkL9SXzHjvS+OBonQ/9/AHYYKmDJwT8vLSRCKrXxJCdUfH7ZnikZbFqjnURJ9nGUHP44rlYJ7PFl05RZ+X5WuZG/A27S5LuBvguyQGcw8A2AZilHSDta9S/4eG6kb22jX87jXTrT6orUkxh2WHI/xvNUEout0gxwWMDkA==" + }, + "npmrc": "registry=https://my.custom.registry/npm\n//my.custom.registry/npm:_authToken=${NPM_TOKEN}" +} +``` + +Renovate will then use the following logic: + +1. If no `npmrc` string is present in config then one will be created with the `_authToken` pointing to the default npmjs registry +1. If an `npmrc` string is present and contains `${NPM_TOKEN}` then that placeholder will be replaced with the decrypted token +1. If an `npmrc` string is present but doesn't contain `${NPM_TOKEN}` then the file will have `_authToken=` appended to it + +### Encrypted entire .npmrc file into config + +Copy the entire `.npmrc`, replace newlines with `\n` characters , and then try encrypting it at . + +You will then get an encrypted string that you can substitute into your `renovate.json` instead. +The end-result looks like this: + +```json +{ + "encrypted": { + "npmrc": "WOTWu+jliBtXYz3CU2eI7dDyMIvSJKS2N5PEHZmLB3XKT3vLaaYTGCU6m92Q9FgdaM/q2wLYun2JrTP4GPaW8eGZ3iiG1cm7lgOR5xPnkCzz0DUmSf6Cc/6geeVeSFdJ0zqlEAhdNMyJ4pUW6iQxC3WJKgM/ADvFtme077Acvc0fhCXv0XvbNSbtUwHF/gD6OJ0r2qlIzUMGJk/eI254xo5SwWVctc1iZS9LW+L0/CKjqhWh4SbyglP3lKE5shg3q7mzWDZepa/nJmAnNmXdoVO2aPPeQCG3BKqCtCfvLUUU/0LvnJ2SbQ1obyzL7vhh2OF/VsATS5cxbHvoX/hxWQ==" + } +} +``` + +However be aware that if your `.npmrc` is too long to encrypt then the above command will fail.