Skip to main content
Skip table of contents

Configure Mend for GitHub.com to resolve your private dependencies

Overview

In order to scan dependencies from private registries, Mend must be provided with credentials. These credentials must be added as encrypted secrets to the .whitesource file, either per-repository or in the shared global config if the secret scope is org-wide.

Use Case

Below is an example of applying private registry credentials in the hostRules block of a .whitesource file:

CODE 
{
  "hostRules": [
    {
      "matchHost": "registry.npmjs.org",
      "hostType": "npm",
      "userName": "bot1",
      "encrypted": {
        "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
      }
    },
    {
      "matchHost": "https://custom.registry.company.com/maven/",
      "hostType": "maven",
      "userName": "bot1",
      "encrypted": {
        "password": "p278djfdsi9832jnfdshufwji2r389fdskj........."
      }
    }
  ]
}

Getting It Done

Mend for GitHub.com supports private registries hosted on any platform that can be accessed with credentials (Nexus, GitHub, Artifactory, Azure Artifacts, GitLab, NPM).

Allow Mend for GitHub.com access to resolve your private dependencies by doing the following:

  1. Create the encrypted secrets. To do so, visit Mend's Repository Integration Secrets Encryption. Each secret you encrypt must be scoped to a GitHub organization or repository and use of it will be restricted to those within the app. The following fields are on the encryption page:

    1. Organization\Group - Required; your GitHub organization to which tokens secret be scoped.

    2. Repository - Optional; your GitHub repository to which the secret should be scoped.

    3. Raw value - Required; confidential values/secrets such as tokens or passwords.

    4. Encrypted value - the result of the encryption to be used in the integration.

  2. Add the encrypted secret to the Private Registry Settings (hostRules) block of your .whitesource file.

We use asymmetric public-key cryptography of the PGP methodology. There is a public key on the page we provided for encrypting secrets from passwords or tokens. This public key has a related private key secured by mend.

The private key is used to decrypt secrets created with the public key. In this way, only the holder of the private key (Mend in this situation) can have access to the encrypted contents. Organization/Group, Repository, Raw Value - all information you provide on the encryption page is secured with this approach.

Automate Secret Encryption for Private Registries

You can encrypt secrets from the CLI, using the curl, echo, jq, gpg, grep and tr CLI programs.
Here is an example:

CODE 
curl https://app.renovatebot.com/renovate.pgp --output renovate.pgp
echo -n '{"o":"your-organization", "r":"your-repository (optional)", "v":"your-secret-value"}' | jq . -c | gpg --encrypt -a --recipient-file renovate.pgp | grep -v '^----' | tr -d '\n'

The above script uses:

  • curl to download the Mend Renovate hosted app's public key

  • echo to echo a JSON object into jq

  • jq to validate the JSON and then compact it

  • gpg to encrypt the contents

  • grep and tr to extract the encrypted payload which we will use

The jq step is optional, you can leave it out if you wish. Its primary value is validating that the string you echo to gpg is valid JSON and compact.

Note: Encrypted secrets must have at least an org/group scope, and optionally a repository scope. This means that Renovate will check if a secret's scope matches the current repository before applying it, and warn/discard if there is a mismatch.

Encrypted secrets usually have a single organization. But you may encrypt a secret with more than one organization, for example, org1,org2. This way the secret can be used in both the org1 and org2 organizations.

For more information on how to use secrets for private packages, refer to the Private package support documentation.

Reference

Parameters

Private Registry Settings (hostRules)

Parameter

Type

Description

matchHost

String

Required. The URL of the private registry where the private dependencies are hosted. Here are a few examples:

  • Azure Artifacts:

  • JFrog Artifactory:

  • GitHub Packages:

hostType

String

Required. The type of private registry. Supported values:

  • npm (for both NPM and Yarn projects)

  • maven (for both Maven and Gradle projects)

  • pypi (for Pip and Pipenv)

  • go

  • nuget

  • ruby

  • sbt

Note: When using Renovate with a Ruby private registry, add a hostRules block with hostType=rubygems within the remediateSettings block.

userName

String

Optional. The value used when the private registry requires a username credential for resolution access to its private dependencies.

encrypted.password

String

Required. The value used when the private registry requires a password credential for resolution access to its private dependencies. The value first needs to be encrypted into a secret on this page.

This encrypted secret will be applied as a credential to the set in the matchHost block and must be included inside the encrypted parameter:

CODE 
      "encrypted": {
        "password": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
      }

encrypted.token

String

Required. The value used when the private registry requires a token credential for resolution access to its private dependencies. The value first needs to be encrypted into a secret on this page.

This encrypted secret will be applied as a credential to the set in the matchHost block and must be included inside the encrypted parameter:

CODE 
      "encrypted": {
        "token": "3f832f2983yf89hsd98ahadsjfasdfjaslf............"
      }

envVariablesMapping

Object

Use this parameter if you used environmental variables in the settings of your package manager to include username and password/token (e.g. for a specified package index). envVariablesMapping takes a value as an object with two literals: userName and password / token.
For example, if you have:

CODE 
[[source]]
url = "https://${USER_PRIVATE_REPO}:{PASS_PRIVATE_REPO}:@pypi/PACKAGE_NAME/simple"
verify_ssl = true
name = "IndexName"

or

CODE 
  {
    url 'https://private.jfrog.io/artifactory/dependencies'
    credentials {
      username System.getenv("USER_PRIVATE_REPO") ?: "${USER_PRIVATE_REPO}"
      password System.getenv("PASS_PRIVATE_REPO") ?: "${PASS_PRIVATE_REPO}"
    }
}

Then, set envVariablesMapping to:

CODE 
"envVariablesMapping": {"userName": "USER_PRIVATE_REPO" ,"password":"PASS_PRIVATE_REPO"}

Below is an example of applying envVariablesMapping in the hostRules block of a .whitesource file:

CODE 
{
  "hostRules": [
    {
      "matchHost": "https://custom.registry.company.com/maven/",
      "hostType": "maven",
      "userName": "bot1",
      "encrypted": {
        "token": "p278djfdsi9832jnfdshufwji2r389fdskj........."
      },
      "envVariablesMapping": {
        "userName": "GITHUB_ACTOR",
        "token": "GITHUB_TOKEN"
      }
    }
  ]
}

sourceName

String

Only for Pipenv private registries. Optional. Use this parameter if you don’t have a specified package index. In this case, Mend will create one for you based on other parameters of hostRules. The value of sourceName should be the index name used for your private dependencies.

For example, if you have packages with the following index:

CODE 
[packages]
<package_name> = { version = "*", index = "IndexName" }

Then, set sourceName to:

CODE 
"sourceName": "IndexName"

Mend for GitHub.com private registry-supported languages

The following languages and their package managers are supported for scanning dependencies from private registries with Mend for GitHub.com.

Language

Package Manager

Details

C#

NuGet

Configuration file(s): nuget.config

  • If the nuget.config preexists, it is appended with the hostRulesprovided.

  • If the nuget.config does not exist, it is temporarily created with the hostRules provided for scanning purposes.

Go

Modules

Configuration file(s): .netrc

  • If the .netrc preexists, it is appended with the hostRulesprovided.

  • If the .netrc does not exist, it is temporarily created with the hostRules provided for scanning purposes.

Specifications:

  • Only HTTPS is available for matchHost, HTTP is not supported.

  • If the private registry is hosted on GitHub, only token can be used in the encrypted parameter (password is not supported).

Java

Gradle

Configuration file(s): build.gradle, settings.gradle

  • If the build.gradle or settings.gradle preexists, it is appended with the hostRulesprovided.

  • If the build.gradle or settings.gradle does not exist, it is temporarily created with the hostRules provided for scanning purposes.

Specifications:

  • We also support the Kotlin format (KTS) of the Gradle configuration files.

  • The buildscript or pluginManagement blocks need to be at the beginning of the build.gradle or settings.gradle, respectively.

  • The matchHost parameter should contain the full path to the private registries, not just the domain.

  • Use the envVariablesMapping parameter if you used environmental variables in your Gradle settings to include the username and password/token.

Java

Maven

Configuration file(s): settings.xml

  • If the settings.xml preexists, it is appended with the hostRulesprovided.

  • If the settings.xml does not exist, it is temporarily created with the hostRules provided for scanning purposes.

JavaScript

NPM

Configuration file(s): .npmrc

  • If the .npmrc preexists, it is appended with the hostRulesprovided.

  • If the .npmrc does not exist, it is temporarily created with the hostRules provided for scanning purposes.

Specifications:

  • If .npmrc is missing and only one host is used in the project, it should be connected to the official public registry: http://npmjs.com. Otherwise, only private dependencies will be scanned and all public dependencies of this registry will be omitted.

  • If several hosts are used in the project, it is required that .npmrc file preexists in the project and contains information about these hosts.

JavaScript

Yarn

Configuration file(s): .npmrc (Yarn 1), .yarnrc (Yarn 2, 3)

  • If the .npmrc or .yarnrc preexists, it is appended with the hostRulesprovided.

  • If the .npmrc or .yarnrc does not exist, it is temporarily created with the hostRules provided for scanning purposes.

Specifications:

  • If .yarnrc is missing (or npmRegistryServer in it is not set) and only one host is used in the project - it will be set to the hostRules.matchHost from the config. In the same case, if several hosts are used, npmRegistryServer will be set to https://registry.yarnpkg.com.

Python

Pip

Specifications:

  • Certain special characters are not valid in the credential part of a URL. If the user or password part of the login credentials contains any of these special characters, then they must be percent-encoded.

Python

Pipenv

Specifications:

  • Use the envVariablesMapping parameter if you used environmental variables in your Pipenv settings to include the username and password/token.

  • Use the sourceName parameter if you don't have a specified package index.

Ruby

Bundler

N/A

Examples of hostRules with specific registries

As AWS Code Artifact tokens rotate every twelve hours, it is recommended to scan applications built using AWS Code Artifact using the Mend CLI. More information can be found at Scan with the Mend CLI.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close