Skip to content

Latest commit

 

History

History
248 lines (189 loc) · 18.5 KB

README.md

File metadata and controls

248 lines (189 loc) · 18.5 KB
Raw

Dependabot for Azure DevOps

This repository contains tools for updating dependencies in Azure DevOps repositories using Dependabot.

GitHub Workflow Status Release license

In this repository you'll find:

  1. Azure DevOps Extension, source code and docs.
  2. Dependabot Server, source code and docs.
  3. Dependabot Updater image, Dockerfile, source code and docs. (Deprecated since v2.0)

Important

This project is currently undergoing a major version increment (V1 → V2); See the migration guide for more details and progress updates.

Table of Contents

Getting started

Unlike the GitHub-hosted version, Dependabot for Azure DevOps must be explicitly setup in your organisation; creating a dependabot.yml file alone is not enough to enable updates. There are two ways to enable Dependabot, using:

  • Azure DevOps Extension - Ideal if you want to get Dependabot running with minimal administrative effort. The extension can run directly inside your existing pipeline agents and doesn't require hosting of any additional services. Because the extension runs in pipelines, this option does not scale well if you have a large number of projects and repositories.

  • Hosted Server - Ideal if you have a large number of projects and repositories or prefer to run Dependabot as a managed service instead of using pipeline agents. See why should I use the server? for more info.

Note

A hosted version is available to sponsors (most, but not all). It includes hassle free runs where the infrastructure is maintained for you. Much like the GitHub hosted version. Alternatively, you can run and host your own self-hosted server. Once you sponsor, you can send out an email to a maintainer or wait till they reach out. This is meant to ease the burden until GitHub/Azure/Microsoft can get it working natively (which could also be never) and hopefully for free.

Using a configuration file

Similar to the GitHub-hosted version, Dependabot is configured using a dependabot.yml file located at .azuredevops/dependabot.yml or .github/dependabot.yml in your repository.

Most official configuration options are supported since V2; Earlier versions have several limitations, see unsupported features and configurations for more.

Configuring private feeds and registries

Besides accessing the repository, sometimes private feeds/registries may need to be accessed. For example a private NuGet feed or a company internal docker registry.

Private registries are configured in dependabot.yml, refer to the official documentation.

Examples:

version: 2
registries:

  # Azure DevOps private feed, all views
  my-analyzers:
    type: nuget-feed
    url: https://dev.azure.com/organization2/_packaging/my-analyzers/nuget/v3/index.json
    token: PAT:${{ MY_DEPENDABOT_ADO_PAT }}

  # Azure DevOps private feed, "Release" view only
  my-Extern@Release: 
    type: nuget-feed
    url: https://dev.azure.com/organization1/_packaging/my-Extern@Release/nuget/v3/index.json
    token: PAT:${{ MY_DEPENDABOT_ADO_PAT }}

  # Artifactory private feed using PAT
  artifactory:
    type: nuget-feed
    url: https://artifactory.com/api/nuget/v3/myfeed
    token: PAT:${{ MY_DEPENDABOT_ARTIFACTORY_PAT }}

  # Other private feed using basic auth (username/password)
  telerik:
    type: nuget-feed
    url: https://nuget.telerik.com/v3/index.json
    username: ${{ MY_TELERIK_USERNAME }}
    password: ${{ MY_TELERIK_PASSWORD }}
    token: ${{ MY_TELERIK_USERNAME }}:${{ MY_TELERIK_PASSWORD }}

updates:
  ...

Note when using authentication secrets in configuration files:

Important

${{ VARIABLE_NAME }} notation is used liked described here BUT the values will be used from pipeline environment variables. Template variables are not supported for this replacement. Replacement only works for values considered secret in the registries section i.e. username, password, token, and key

Important

When using an Azure DevOps Artifact feed, the token format must be PAT:${{ VARIABLE_NAME }} where VARIABLE_NAME is a pipeline/environment variable containing the PAT token. The PAT must:

  1. Have Packaging (Read) permission.
  2. Be issued by a user with permission to the feed either directly or via a group. An easy way for this is to give Contributor permissions the [{project_name}]\Contributors group under the Feed Settings -> Permissions page. The page has the url format: https://dev.azure.com/{organization}/{project}/_packaging?_a=settings&feed={feed-name}&view=permissions.

Note

When using dependabot@V1 with a private feed/registry secured with basic auth, the username, password, and token properties are all required. The token format must be ${{ USERNAME }}:${{ PASSWORD }}.

Note

When using dependabot@V1 with a repository containing a nuget.config file configured with custom package sources, the key property is required for each registry. The key must match between dependabot.yml and nuget.config otherwise the package source will be duplicated, package source mappings will be ignored, and auth errors will occur during dependency discovery. If your nuget.config looks like this:

 <?xml version="1.0" encoding="utf-8"?>
 <configuration>
   <packageSources>
     <clear />
     <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
     <add key="my-organisation1-nuget" value="https://dev.azure.com/my-organization/_packaging/my-nuget-feed/nuget/v3/index.json" />
   </packageSources>
   <packageSourceMapping>
     <packageSource key="nuget.org">
       <package pattern="*" />
     </packageSource>
     <packageSource key="my-organisation-nuget">
       <package pattern="Organisation.*" />
     </packageSource>
   </packageSourceMapping>
 </configuration>

Then your dependabot.yml registry should look like this:

 version: 2
 registries:
   my-org:
     type: nuget-feed
     key: my-organisation1-nuget
     url: https://dev.azure.com/my-organization/_packaging/my-nuget-feed/nuget/v3/index.json
     token: PAT:${{ MY_DEPENDABOT_ADO_PAT }}

Configuring security advisories and known vulnerabilities

Security-only updates is a mechanism to only create pull requests for dependencies with vulnerabilities by updating them to the earliest available non-vulnerable version. Security updates are supported in the same way as the GitHub-hosted version provided that a GitHub access token with public_repo access is provided in the gitHubAccessToken or gitHubConnection task inputs.

You can provide extra security advisories, such as those for an internal dependency, in a JSON file via the securityAdvisoriesFile task input e.g. securityAdvisoriesFile: '$(Pipeline.Workspace)/advisories.json'. An example file is available in ./advisories-example.json.

Configuring experiments

Dependabot uses an internal feature flag system called "experiments". Typically, experiments represent new features or changes in logic which are still being internally tested before becoming generally available. In some cases, you may want to opt-in to experiments to work around known issues or to opt-in to preview features ahead of general availability (GA).

Experiments vary depending on the package ecyosystem used; They can be enabled using the experiments task input with a comma-seperated list of key/value pairs representing the experiments e.g. experiments: 'tidy=true,vendor=true,goprivate=*'.

Note

Dependabot experinment names are not [publicly] documented. For convenience, some known experiments are listed below; However, be aware that this may be out-of-date at the time of reading.

List of known experiments from [email protected]
Package Ecosystem Experiment Name Value Type More Information
All grouped_updates_experimental_rules true/false dependabot/dependabot-core#7581
All grouped_security_updates_disabled true/false dependabot/dependabot-core#8529
All lead_security_dependency true/false dependabot/dependabot-core#10727
All record_ecosystem_versions true/false dependabot/dependabot-core#7517
All enable_record_ecosystem_meta true/false dependabot/dependabot-core#10905
All record_update_job_unknown_error true/false dependabot/dependabot-core#8144
All dependency_change_validation true/false dependabot/dependabot-core#9888
All add_deprecation_warn_to_pr_message true/false dependabot/dependabot-core#10421
All threaded_metadata true/false dependabot/dependabot-core#9485
Go tidy true/false
Go vendor true/false
Go goprivate string
NPM npm_fallback_version_above_v6 true/false dependabot/dependabot-core#10757
NPM enable_corepack_for_npm_and_yarn true/false dependabot/dependabot-core#10985
NuGet nuget_native_analysis true/false dependabot/dependabot-core#10025
NuGet nuget_native_updater true/false dependabot/dependabot-core#10521
NuGet nuget_legacy_dependency_solver true/false dependabot/dependabot-core#10671
NuGet nuget_use_direct_discovery true/false dependabot/dependabot-core#10597

To find the latest list of Dependabot experiments, search the dependabot-core GitHub repository using queries like "enabled?(x)" and "options.fetch(x)".

Configuring assignees and reviewers

Dependabot allows for the configuration of both assignees and reviewers. However, Azure DevOps does not have the concept of pull request assignees. Because of this, assignees will be treated as required reviewers and reviewers will be treated as optional reviewers.

Reviewers can be any of the following values:

  • User GUID
  • User username
  • User email address
  • User full [display] name
  • Group name
  • Team name

Unsupported features and configurations

We aim to support all official configuration options, but there are some limitations:

Dependabot Task

dependabot@V2

dependabot@V1

  • schedule is ignored, use pipeline scheduled triggers instead.
  • directories are only supported if task input useUpdateScriptVNext: true is set.
  • groups are only supported if task input useUpdateScriptVNext: true is set.
  • ignore may not behave to official specifications unless task input useUpdateScriptVNext: true is set. If you are having issues, search for related issues such as tinglesoftware#582 before creating a new issue.
  • assignees and reviewers must be a list of user guids or email addresses; group/team names are not supported.
  • Private feed/registry authentication may not work with all package ecyosystems. Support is slightly improved when task input useUpdateScriptVNext: true is set, but not still not fully supported. See problems with authentication for more.

Dependabot Updater Docker Image

  • DEPENDABOT_ASSIGNEES and DEPENDABOT_REVIEWERS must be a list of user guids; email addresses and group/team names are not supported.
  • Private feed/registry authentication may not work with all package ecyosystems. See problems with authentication for more.

Dependabot Server

Migration Guide

Contributing

👋 Want to give us feedback on Dependabot for Azure DevOps, or contribute to it? That's great - thank you so much!

Reporting issues and feature requests

Please leave all issues, bugs, and feature requests on the issues page. We'll respond ASAP! Use the discussions page for all other questions and comments.

Submitting pull requests

Please refer to the contributing guidelines for more information on how to get started.

Acknowledgements

The work in this repository is based on inspired and occasionally guided by some predecessors in the same area:

  1. Official Script support: code
  2. Andrew Craven's work: blog, code
  3. Chris' work: code
  4. andrcun's work on GitLab: code
  5. WeWork's work for GitLab: code