Set up your project and connect to Azure Artifacts

TFS 2018

Azure Artifacts enables you to publish various package types to your feeds and install packages from both feeds and public registries like npmjs.com. Before we can authenticate with Azure Artifacts, we need to configure our .npmrc file, which stores the feed URLs and credentials that Npm uses. This file can be used to customize the behavior of the Npm client, such as setting up proxies, specifying default package locations, or configuring private package feeds. The .npmrc file is located in the user's home directory and can also be created at the project level to override the default settings. By editing the .npmrc file, users can customize their Npm experience and make it more tailored to their needs.

Project setup

For best practice, we suggest using two separate configuration files. The first file is used to authenticate with Azure Artifacts, while the second file is stored locally and contains your credentials. To set up the second file, place it in your home directory on your development machine and include all of your registry credentials. By using this approach, the Npm client can easily retrieve your credentials for authentication, allowing you to share your configuration file while keeping your credentials secure. These steps will walk you through the process of setting up the first configuration file:

Windows

1. Select Build and Release.

2. Select Packages, and then select Connect to feed.

   

3. Select npm from the left navigation pane.

4. Follow the instructions provided in the Other tab to set up your project.

Tip

Using multiple registries in .npmrc files is supported with scopes and upstream sources.

Other

1. Add a .npmrc file in your project's directory, in the same directory as your package.json file, and copy the following snippet into it.

   registry=https://pkgs.dev.azure.com/ramiMSFTDevOps/_packaging/OrgScopedDemo/npm/registry/ 
   
   always-auth=true
   

2. Copy the following snippet into your user-level .npmrc file (~/.npmrc). Make sure that you don't add it to the .npmrc file in your source repository:

   • Organization-scoped feed:

     ; begin auth token
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:email=npm requires email to be set but doesn't use the value
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:username=[ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:email=npm requires email to be set but doesn't use the value
     ; end auth token
     

   • Project-scoped feed:

     ; begin auth token
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:email=npm requires email to be set but doesn't use the value
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:email=npm requires email to be set but doesn't use the value
     ; end auth token
     

3. Generate a personal access token with packaging read and write scopes.

4. Encode your newly generated personal access token as follows:

   1. Run the following command in a command prompt window, and then paste your personal access token when prompted:

      node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"
      

      You can also use the following command to convert your personal access token to Base64.

      • Linux/Mac:

        echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64
        

   2. Copy the Base64 encoded value.

5. Open your .npmrc file and replace the placeholder [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] with your encoded personal access token that you created in the previous step.

Note

vsts-npm-auth is not supported in TFS and Azure DevOps Server.

Pipeline authentication

For authentication with your pipeline, Azure Artifacts recommends using the npm authenticate task. When using a task runner like gulp or Grunt, it's important to add the npm authenticate task to the beginning of your pipeline. By doing so, your credentials are injected into your project's .npmrc file and persisted during the pipeline run, enabling subsequent steps to use the credentials in the configuration file.

Classic

1. Select Build and Release, and then select Builds.

   

2. Select your pipeline, and then select Edit.

3. Select + to add a task to your pipeline.

   

4. Search for the npm Authenticate task, and then select Add to add it to your pipeline.

   

5. Select your .npmrc file.

   

6. Select Save & queue when you're done.

YAML

- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc                ## Path to the npmrc file
    customEndpoint: #Optional          ## Comma-separated list of npm service connection names for registries from external organizations. For registries in your org, leave this blank

Note

To grant your pipeline access to your feed, make sure you set the build service role to Contributor in your feed settings.

Note

If your organization is using a firewall or a proxy server, make sure you allow the appropriate domain URLs. For more information, please refer to the list of Allowed IP addresses and domain URLs.

Troubleshoot

vsts-npm-auth is not recognized

If you encounter the following error while running your project:

• Cmd: 'vsts-npm-auth' is not recognized as an internal or external command, operable program or batch file.
• PowerShell: vsts-npm-auth : The term 'vsts-npm-auth' is not recognized as the name of a cmdlet, function, script file, or operable program.

Then it's likely that the npm modules folder is not added to your path. To resolve this issue, rerun the Node.js setup and make sure to select the Add to PATH option.

As an alternative solution, you can add the npm modules folder to your path by editing the PATH variable %APPDATA%\npm in Command Prompt or $env:APPDATA\npm in PowerShell.

Unable to authenticate

If you're running into a E401 error: code E401 npm ERR! Unable to authenticate. Run the vsts-npm-auth command with -F flag to reauthenticate.

vsts-npm-auth -config .npmrc -F

Reset vsts-npm-auth

Follow the steps below to modify/reset your vsts-npm-auth credentials:

• Uninstall vsts-npm-auth.

  npm uninstall -g vsts-npm-auth
  

• Clear your npm cache.

  npm cache clean --force
  

• Delete your .npmrc file.

• Reinstall vsts-npm-auth.

  npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false
  

Related articles

• Publish npm packages (YAML/Classic)
• Use npm scopes
• Use npm audit