Home

Awesome

WARNING - Scripts are Currently Broken

We recently refactored the monolithic docker image used within the Dependabot Core library into one-image-per-ecosystem. Unfortunately, that broke the scripts in this repo, and we haven't had time to update them yet. We are aware of the problem and hope to provide a solution soon.

Dependabot Script

This repo is a collection of scripts to use as entrypoints to the Dependabot Core library. It is intended as a starting point for advanced users to run a self-hosted version of Dependabot within their own projects.

If you're looking for a hassle-free Dependabot experience, check out the hosted Dependabot Service.

Note: Community Maintained Project

This is a community-maintained project. As such, the Dependabot team at GitHub will review PR contributions to update this repo, but is unable to provide further support such as debugging why something doesn't work.

Local setup and usage

rbenv install # (Install Ruby version from ./.ruby-version)
bundle install

Native helpers

Languages that require native helpers to be installed: Terraform, Python, Go, Elixir, PHP, JS

To install the native helpers, export an environment variable that points to the directory into which the helpers should be installed and add the relevant bins to your PATH:

export DEPENDABOT_NATIVE_HELPERS_PATH="$(pwd)/native-helpers"
mkdir -p $DEPENDABOT_NATIVE_HELPERS_PATH/{terraform,python,dep,go_modules,hex,composer,npm_and_yarn}
export PATH="$PATH:$DEPENDABOT_NATIVE_HELPERS_PATH/terraform/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/python/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/go_modules/bin:$DEPENDABOT_NATIVE_HELPERS_PATH/dep/bin"
export MIX_HOME="$DEPENDABOT_NATIVE_HELPERS_PATH/hex/mix"

Copy the relevant helpers from the gem source to the new install location

LanguageCommand
Terraformcp -r $(bundle show dependabot-terraform)/helpers $DEPENDABOT_NATIVE_HELPERS_PATH/terraform/helpers
Pythoncp -r $(bundle show dependabot-python)/helpers $DEPENDABOT_NATIVE_HELPERS_PATH/python/helpers
Gocp -r $(bundle show dependabot-go_modules)/helpers $DEPENDABOT_NATIVE_HELPERS_PATH/go_modules/helpers
Elixircp -r $(bundle show dependabot-hex)/helpers $DEPENDABOT_NATIVE_HELPERS_PATH/hex/helpers
PHPcp -r $(bundle show dependabot-composer)/helpers $DEPENDABOT_NATIVE_HELPERS_PATH/composer/helpers
JScp -r $(bundle show dependabot-npm_and_yarn)/helpers $DEPENDABOT_NATIVE_HELPERS_PATH/npm_and_yarn/helpers

Build the helpers you want to use (you'll also need the corresponding language installed)

LanguageCommand
Terraform$DEPENDABOT_NATIVE_HELPERS_PATH/terraform/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/terraform
Python$DEPENDABOT_NATIVE_HELPERS_PATH/python/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/python
Go$DEPENDABOT_NATIVE_HELPERS_PATH/go_modules/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/go_modules
Elixir$DEPENDABOT_NATIVE_HELPERS_PATH/hex/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/hex
PHP$DEPENDABOT_NATIVE_HELPERS_PATH/composer/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/composer
JS$DEPENDABOT_NATIVE_HELPERS_PATH/npm_and_yarn/helpers/build $DEPENDABOT_NATIVE_HELPERS_PATH/npm_and_yarn

Environment Variables

The update scripts are configured using environment variables. The available variables are listed in the table below. (See ./generic-update-script.rb for more context.)

Variable NameDefaultNotes
DIRECTORY_PATH /Directory where the base dependency files are.
PACKAGE_MANAGERbundlerValid values: bundler, cargo, composer, dep, docker, elm, go_modules, gradle, hex, maven, npm_and_yarn, nuget, pip (includes pipenv), submodules, terraform
PROJECT_PATHN/A (Required)Path to repository. Usually in the format <namespace>/<project>.
BRANCH N/A (Optional)Branch to fetch manifest from and open pull requests against.
PULL_REQUESTS_ASSIGNEEN/A (Optional)User to assign to the created pull request.
OPTIONS{}JSON options to customize the operation of Dependabot

There are other variables that you must pass to your container that will depend on the Git source you use:

Github

VariableDefault
GITHUB_ACCESS_TOKENN/A (Required)

Github Enterprise

VariableDefault
GITHUB_ENTERPRISE_ACCESS_TOKENN/A (Required)
GITHUB_ENTERPRISE_HOSTNAMEN/A (Required)

Gitlab

VariableDefault
GITLAB_ACCESS_TOKENN/A (Required)
GITLAB_AUTO_MERGEN/A (Optional)
GITLAB_HOSTNAMEgitlab.com
GITLAB_ASSIGNEE_IDN/A Deprecated. Use PULL_REQUESTS_ASSIGNEE instead.

Azure DevOps

VariableDefault
AZURE_ACCESS_TOKENN/A (Required)
AZURE_HOSTNAMEdev.azure.com

Also note that the PROJECT_PATH variable should be in the format: organization/project/_git/package-name.

Bitbucket

VariableDefault
BITBUCKET_ACCESS_TOKENN/A (Required*)
BITBUCKET_APP_USERNAMEN/A (Required*)
BITBUCKET_APP_PASSWORDN/A (Required*)
BITBUCKET_API_URLhttps://api.bitbucket.org/2.0
BITBUCKET_HOSTNAMEbitbucket.org

* Either BITBUCKET_ACCESS_TOKEN must be passed, or BITBUCKET_APP_USERNAME and BITBUCKET_APP_PASSWORD.

Running dependabot

There are a few ways of running the script:

You can also set it up to run as part of your repositories workflows

Running update-script.rb (GitHub only)

  1. bundle exec irb
  2. Edit the variables at the top of the script you're using, or set the corresponding environment variables.
  3. Copy and paste the script into the Ruby session to see how Dependabot works.

If you run into any trouble with the above please create an issue!

Running generic-update-script.rb

  1. Configure your shell with the correct environment variables.
  2. Execute the script with Bundler:
    bundle exec ruby ./generic-update-script.rb
    

Running script with dependabot-script Dockerfile

If you don't want to setup the machine where the script will be executed, you could run the script within a dependabot/dependabot-script container.

You can build and run the Dockerfile in order to do that. You'll also have to set several environment variables to make the script work with your configuration, as specified above. (You can find how to pass environment variables to your container in Docker run reference.)

Steps:

  1. Build the dependabot-script Docker image
git clone https://github.com/dependabot/dependabot-script.git
cd dependabot-script

docker build -t "dependabot/dependabot-script" -f Dockerfile .
  1. Run dependabot
docker run --rm \
  --env "PROJECT_PATH=organization/project" \
  --env "PACKAGE_MANAGER=bundler" \
  "dependabot/dependabot-script"

If everything goes well you should be able to see something like:

/home/dependabot/dependabot-script# ./generic-update-script.rb
Fetching gradle dependency files for myorganisation/project
Parsing dependencies information
...

Running scripts with dependabot-core Dockerfile only

The dependabot-core Dockerfile installs dependencies as the dependabot user, so volume mounting won't work unless you build the image by passing in the USER_UID and USER_GID arguments. This creates the dependabot user with the same IDs ensuring it owns the mounted files and can write to them from within the container.

Steps:

  1. Build dependabot-core image
git clone https://github.com/dependabot/dependabot-core.git
cd dependabot-core

docker build \
  --build-arg "USER_UID=$(id -u)" \
   --build-arg "USER_GID=$(id -g)" \
  -t "dependabot/dependabot-core" .
cd ..
  1. Install dependencies
git clone https://github.com/dependabot/dependabot-script.git
cd dependabot-script

docker run -v "$(pwd):/home/dependabot/dependabot-script" -w /home/dependabot/dependabot-script dependabot/dependabot-core bundle install -j 3 --path vendor
  1. Run dependabot
docker run --rm -v "$(pwd):/home/dependabot/dependabot-script" -w /home/dependabot/dependabot-script -e ENV_VARIABLE=value dependabot/dependabot-core bundle exec ruby ./generic-update-script.rb

GitHub Actions Standalone

The easiest and most common way to run Dependabot on GitHub is using the built-in Dependabot service as described here. This is recommended for most users.

However, sometimes you may need to run Dependabot manually either for testing, or to enable features/plugins that are not currently available in Dependabot. This is relatively straight-forward to achieve with a shell-based GitHub action.

By default this action is set to run on workflow dispatch, which means that you need to manually trigger the workflow run. If you would rather run it on a set schedule, you can switch to schedule dispatch.

GitLab CI

The easiest configuration is to have a repository dedicated to the script. Many pipeline schedules can be added on that single repo to manage multiple projects. Thus https://[gitlab.domain/org/dependabot-script-repo]/pipeline_schedules dashboard becomes your own dependabot admin interface.

The scripts