Skip to content

Latest commit

 

History

History
161 lines (129 loc) · 7.49 KB

extension.md

File metadata and controls

161 lines (129 loc) · 7.49 KB
Raw

Table of Contents

Using the extension

Refer to the extension README.md.

Troubleshooting issues

Dependabot will log more diagnostic information when verbose logs are enabled; i.e. system.debug variable is set to true.

When verbose logs are enable, Dependabot will also generate a Flame Graph performance metrics report, which can be viewed by downloading the pipeline logs, then locating the corresponding HTML report file in the Job folder. To understand how to read Flame Graph reports, see: https://www.brendangregg.com/flamegraphs.html#summary

Warning

When sharing pipeline logs, please be aware that the task log contains potentionally sensitive information such as your DevOps organisation name, project names, repository names, private package feeds URLs, list of used dependency names/versions, and the contents of any dependency files that are updated (e.g. package.json, *.csproj, etc). The Flame Graph report does not contain any sensitive information about your DevOps environment.

Development guide

Getting the development environment ready

Install Node.js (18+), Go (1.22+), and Docker (with Linux containers); Install project dependencies using NPM:

cd extension
npm install

Building the extension

cd extension
npm run build

To then generate the a Azure DevOps .vsix extension package for testing, you'll first need to create a publisher account for the Visual Studio Marketplace Publishing Portal. After this, use npm run package to build the package, with an override for your publisher ID:

npm run package -- --overrides-file overrides.local.json --rev-version --publisher your-publisher-id-here

Installing the extension

To test the extension in a Azure DevOps organisation:

  1. Build the extension .vsix package
  2. Publish the extension to your publisher account
  3. Share the extension with the organisation.

Running the task locally

To run the latest task version:

npm start

To run a specific task version:

npm run start:V1 # runs dependabot@1 task
npm run start:V2 # runs dependabot@2 task

Running the unit tests

cd extension
npm test

Architecture

dependabot2 versioned update process diagram

High-level sequence diagram illustrating how the dependabot@2 task performs versioned updates using dependabot-cli. For more technical details, see how dependabot-cli works.

 sequenceDiagram
    participant ext as Dependabot DevOps Extension
    participant agent as DevOps Pipeline Agent
    participant devops as DevOps API
    participant cli as Dependabot CLI
    participant core as Dependabot Updater
    participant feed as Package Feed

    ext->>ext: Read and parse `dependabot.yml`
    ext->>ext: Write `job.yaml`
    ext->>agent: Download dependabot-cli from github
    ext->>+cli: Execute `dependabot update -f job.yaml -o update-scenario.yaml`
    cli->>+core: Run update for `job.yaml` with proxy and dependabot-updater docker containers
    core->>devops: Fetch source files from repository
    core->>core: Discover dependencies
    loop for each dependency
        core->>feed: Fetch latest version
        core->>core: Update dependency files
    end
    core-->>-cli: Report outputs
    cli->>cli: Write outputs to `update-sceario.yaml`
    cli-->>-ext: Update completed

    ext->>ext: Read and parse `update-sceario.yaml`
    loop for each output
      alt when output is "create_pull_request"
        ext->>devops: Create pull request source branch
        ext->>devops: Push commit to source branch
        ext->>devops: Create pull request
        ext->>devops: Set auto-approve
        ext->>devops: Set auto-complete
      end
      alt when output is "update_pull_request"
        ext->>devops: Push commit to pull request
        ext->>devops: Update pull request description
        ext->>devops: Set auto-approve
        ext->>devops: Set auto-complete
      end
      alt when output is "close_pull_request"
        ext->>devops: Create comment thread on pull request with close reason
        ext->>devops: Abandon pull request
        ext->>devops: Delete source branch
      end
    end
Loading

dependabot2 security-only update process diagram

High-level sequence diagram illustrating how the dependabot@2 task performs security-only updates using dependabot-cli.

 sequenceDiagram
    participant ext as TaskV2
    participant cli as Dependabot CLI
    participant gha as GitHub Advisory Database

    ext->>ext: Write `list-dependencies-job.yml`
    Note right of ext: The job file contains `ignore: [ 'dependency-name': '*' ]`.<br>This will make Dependabot to discover all dependencies, but not update anything.<br>We can then extract the dependency list from the "depenedency_list" output.
    ext->>+cli: Execute `dependabot update -f list-dependencies-job.yml -o output.yml`
    cli->>cli: Run update job
    cli->>cli: Write `output.yaml`
    cli-->>-ext: Update completed

    ext->>ext: Read and parse `output.yaml`, extract "dependency_list"
    loop for each dependency
      ext->>gha: Check security advisories for dependency
    end
    ext->>ext: Filter dependency list to only ones containing security advisories
    ext->>ext: Write `security-only-update-job.yml`
    Note right of ext: The job file contains the list of `dependency-names` and `security-advisories`.<br>This will make Dependanbot only update the dependencies named in the job file.
    ext->>+cli: Execute `dependabot update -f security-only-update-job-job.yml -o output.yml`
    cli->>cli: Run update job
    cli->>cli: Write `output.yaml`
    cli-->>-ext: Update completed
    ext->>ext: Read and parse `output.yaml`
    Note right of ext: Normal update logic resumes from this point.<br/>Outputs are parsed, pull requests are created/updated/closed based on the outputs
Loading