DOCSEARCHbyAlgolia
Submit Docs

dependabot CLI

repository·main·Indexed 19 days ago

https://github.com/dependabot/cli

A tool for running Dependabot update jobs locally or in CI using containerized isolation. It allows users to execute package manager updates, record API calls for automation, and verify behavior via smoke tests. Key subcommands include `update` for triggering update jobs, `test` for validating smoke tests, and `graph` for listing dependencies of manifests or lockfiles.

Tokens
5.7K
Snippets
22
Records
24
Agent score
66%

What's inside dependabot-cli

  1. How the dependabot CLI works

    main

    The CLI orchestrates the update process using container isolation to protect secrets:

    1. Container Setup: It pulls the updater and proxy images and configures a container network.
    2. Proxy Isolation: The proxy starts first. All network requests from the updater are routed through this proxy. The proxy injects credentials into outbound requests so the updater (which may run untrusted code from package manifests) never has direct access to secrets.
    3. Execution: The updater runs using the job description as input.
    4. Recording: The CLI records the calls made by the updater (e.g., to create/update PRs). If the --output / -o flag is used, these recorded calls are written to a YAML file.

  2. Use interactive debugging with dependabot-core

    main

    To debug the actual updater logic, you should use the dependabot-core repository, which contains the source for the updater images. The script/dependabot script in that repository mounts ecosystems into a container and provides an interactive session.

    1. Clone https://github.com/dependabot/dependabot-core.
    2. Start an interactive session with the --debug flag:
      script/dependabot update go_modules dependabot/cli --debug
    3. Once in the session, use the following commands to drive the update process:
      • bin/run fetch_files: Executes the file fetching step.
      • bin/run update_files: Executes the file update step.

    Tip: If you are debugging a problem that occurs after the fetch step, you can repeatedly run bin/run update_files while you debug.

    script/dependabot update go_modules dependabot/cli --debug

  3. Verify your Dependabot CLI installation

    main

    Before debugging, ensure your CLI is working correctly by performing a simple update and inspecting the output. This confirms the environment is capable of generating pull request instructions.

    Run a test update:

    dependabot update go_modules dependabot/cli -o out.yml

    Check the resulting out.yml file; it should contain two calls to create_pull_request.

  4. Install the dependabot CLI

    main

    You can install the dependabot CLI using Go, Homebrew (on macOS), or by downloading pre-built binaries from the releases page.

    Requirements:

    • [Docker]
    # Using Go
go install github.com/dependabot/cli/cmd/dependabot@latest

# Using Homebrew (macOS)
brew install dependabot

  5. Debug updater logic using Ruby debugger statements

    main

    You can insert debugger statements directly into the ecosystem source code within the dependabot-core project to trigger the Ruby debugger during an update.

    Workflow

    1. Open the relevant ecosystem file in your editor (e.g., go_modules/lib/dependabot/go_modules/update_checker.rb).
    2. Insert a debugger statement in the desired method:
      def latest_resolvable_version
  debugger
  latest_version_finder.latest_version
end
    3. Run bin/run fetch_files and bin/run update_files in your interactive CLI session.
    4. When the execution hits the debugger line, the session will pause at the (rdbg) prompt.

    Debugger Usage

    • Use Ruby debugger commands to navigate.
    • Enter variable names (e.g., dependency) to inspect their contents.
    • Use bt to view the stack trace frames.

    Important Notes:

    • Hot Reloading: Changes to source code are automatically synced to the container and do not require a CLI restart. However, if you are already inside an active debugger session, new code changes will not be picked up until you end the session and restart it.
          def latest_resolvable_version
        debugger
        latest_version_finder.latest_version
      end

  6. Produce a smoke test for a repository

    main

    To create a new smoke test for a specific repository, follow these two steps:

    1. Generate the test file: Run update with the --output / -o flag to record the actual behavior of a job.

      dependabot update go_modules dependabot/cli -o go-smoke-test.yml

    2. Verify with cache: Run the test command using the generated file and specify a cache directory with --cache.

      dependabot test -f go-smoke-test.yml --cache ./tmp/cache

    Note on Caching: The CLI caches responses to requests. When the cache coverage reaches 100%, subsequent runs are fast and deterministic. If you see cache misses, it means the updater made an external request that wasn't captured, which can lead to flaky tests.

    # 1. Generate
dependabot update go_modules dependabot/cli -o go-smoke-test.yml

# 2. Test
dependabot test -f go-smoke-test.yml --cache ./tmp/cache

  7. Configure authentication via environment variables

    main

    The dependabot update command can automatically inject credentials into the job if specific environment variables are present. This is useful for local development to avoid hitting rate limits or for accessing private repositories.

    • GitHub: If LOCAL_GITHUB_ACCESS_TOKEN is set, the CLI inserts a git_source credential for github.com using the username x-access-token.
    • Azure: If LOCAL_AZURE_ACCESS_TOKEN is set and an --api-url is provided, the CLI inserts git_source credentials for both dev.azure.com and <org>.visualstudio.com. Additionally, it may inject Azure Artifacts credentials (e.g., maven_repository, npm_registry) depending on the package manager used.

  8. Configure update jobs with a job description file

    main

    For advanced configurations—such as performing security-only updates, authenticating against private registries, or targeting specific dependencies—use the --file / -f option to pass a job description YAML file. This replaces the positional package manager and repository arguments.

    When using a job file, the CLI automatically replaces any $-prefixed values (e.g., $LOCAL_GITHUB_ACCESS_TOKEN) with values from your environment variables.

    Example job.yaml structure:

    job:
    package-manager: npm_and_yarn
    allowed-updates:
      - update-type: all
    dependencies:
      - 'express'
    security-updates-only: true
    source:
        provider: github
        repo: dependabot/smoke-tests
        directory: /
        commit: 66115359e6f6cc3af6a661c5d5ae803720b98cb8
credentials:
  - type: npm_registry
    registry: https://npm.pkg.github.com
    token: $LOCAL_GITHUB_ACCESS_TOKEN
    dependabot update -f job.yaml

  9. Resolve `ensure_equivalent_gemfile_and_lockfile` error

    main

    The error ensure_equivalent_gemfile_and_lockfile occurs when using script/dependabot if the Updater image is out of sync with dependabot-core.

    You can resolve this by rebuilding the relevant Updater image. For example, to rebuild the Go ecosystem Updater image, run the following command within the dependabot-core repository:

    script/build go_modules

  10. Troubleshoot 'Network internet is ambiguous' error

    main

    If you see the error failed to start container: Error response from daemon: network internet is ambiguous (2 matches found on name), it usually means the CLI exited unexpectedly (e.g., via Ctrl+C) before it could clean up Docker networks.

    To resolve this, remove all unused Docker networks by running:

    docker network prune

  11. Fix API connection issues on WSL2

    main

    When running the CLI locally without the --api-url argument, it defaults to connecting to host.docker.internal. On Linux, the default IP address 0.0.0.0 works, but on WSL2, this may result in the error: POST http://host.docker.internal:(port)/update_jobs/cli/update_dependency_list: No response from server.

    To fix this on WSL2, set the FAKE_API_HOST environment variable to 127.0.0.1:

    export FAKE_API_HOST=127.0.0.1

  12. Debug a hanging Dependabot job

    main

    If a Dependabot job hangs, you can use the CLI to identify the problematic code via a stack trace.

    Steps to debug a hang

    1. Reproduce the hang using a standard update command:
      dependabot update <ecosystem> <org/repo>
    2. Run the same update with the `--debug` flag:
   ```bash
dependabot update <ecosystem> <org/repo> --debug
    1. Inside the interactive session, run bin/run fetch_files and bin/run update_files.
    2. Wait for the job to hang, then press CTRL-C.
    3. The CLI will output a stack trace leading to the code causing the hang.

    Note: In --debug mode, Proxy output is suppressed in the terminal. To monitor when the Proxy starts to hang, use Docker Desktop or another method to view the Proxy logs directly.