This project is not affiliated with, funded by, or associated with the Dependabot team or GitHub

This software is Work in Progress: features will appear and disappear, API will be changed, bugs will be introduced, your feedback is always welcome!

Support

Supported by

Sponsor

If you find this project useful, you can help me cover hosting costs of my dependabot-gitlab test instance:

---

Application providing automated dependency updates based on dependabot-core

[[TOC]]

Docker image

• Dockerhub - docker.io/andrcuns/dependabot-gitlab:latest
• Gitlab - registry.gitlab.com/dependabot-gitlab/dependabot:latest

Usage

Standalone

It is possible to use app in "standalone" mode without the need to deploy. Project dependabot-standalone contains pipeline configuration to run dependency updates via scheduled gitlab pipelines.

This mode can be used similarly to dependabot-script, which inspired creation of this project. Standalone mode is limited to following features:

• basic dependency updates
• limited ability of MR automerge

Features not supported:

• security vulnerability detection
• automatic closure of superseded merge requests
• merge request commands
• webhooks
• UI with managed project list

Service

dependabot-gitlab is packaged as docker container and it's possible to deploy it via various means described in Deployment section.

Deployed version is considered to be the primary and has priority on adding and maintaining features.

Deployment

Helm

Preferred way of deployment is via helm package manager using dependabot-gitlab chart.

helm repo add dependabot https://dependabot-gitlab.gitlab.io/chart
helm install dependabot dependabot/dependabot-gitlab --set credentials.gitlab_access_token=$gitlab_access_token

Docker Compose

Simple example deployment can be seen in docker-compose.yml. Deployment consists of 5 containers - web server, sidekiq worker, migrations, mongodb and redis. Simple production like deployment using docker-compose can be done with following command:

docker compose up

Configuration

dependabot.yml

Repository must contain .gitlab/dependabot.yml configuration for dependabot updates to work. dependabot-gitlab strives to achieve parity with all possible Github native options. Some of the options can have slightly different behavior which is described in the documentation linked below.

• Github documentation: configuration options
• Additional dependabot-gitlab specific options: configuration options

Following configuration options are currently supported:

option	dependabot	dependabot-standalone
package-ecosystem	✅	✅
directory	✅	✅
allow	✅	✅
ignore	✅	✅
assignees	✅	✅
reviewers	✅	✅
approvers	✅	✅
commit-message	✅	✅
insecure-external-code-execution	✅	✅
labels	✅	✅
milestone	✅	✅
open-pull-requests-limit	✅	✅
pull-request-branch-name	✅	✅
rebase-strategy	✅	✅
target-branch	✅	✅
vendor	✅	✅
versioning-strategy	✅	✅
registries	✅	✅
fork	✅	✅
updater-options	✅	✅
vulnerability-alerts	✅	❌
schedule.interval	✅	❌
schedule.day	✅	❌
schedule.time	✅	❌
schedule.timezone	✅	❌
schedule.hours	✅	❌

base configuration file

App supports setting a base configuration template via config_base_filename configuration option. Base configuration supports same values as the project specific dependabot.yml with one difference that updates key must define a map instead of an array. Project specific configuration would be merged on top of base configuration and options defined in updates of base configuration are merged with options of each updates entry in project specific configuration.

Project specific options will override base configuration options.

Application

Helm chart

For all configuration options, refer to chart repository

Manual

environment.md describes all possible environment variables for use with docker-compose or standalone mode.

Webhooks

If env.dependabotUrl in helm values or SETTINGS__DEPENDABOT_URL is not set, following webhooks with url http://{dependabot_host}/api/hooks and optional secret token have to be created in project manually:

• Push events - default repository branch
• Merge request events
• Comments
• Pipeline events

Authentication

To use Secret token for payload validation, token needs to be configured using SETTINGS__GITLAB_AUTH_TOKEN environment variable.

Security updates

Application supports syncing with GitHub Advisory Database for security vulnerability data retrieval when performing dependency updates.

This feature requires for github access token to be configured.

Currently security updates are not supported in standalone mode

Vulnerability alerts

When dependabot-gitlab detects security vulnerability in a dependency but is unable to update it, it will create security vulnerability issue.

Adding projects

In order for application to start updating dependencies, projects have to be registered first which will create scheduled dependency update jobs. Several ways of adding projects exist.

Automatically

Project registration job

It is possible to enable project registration job, which will periodically scan for projects to register. Configuration options

The job will also update dependency update jobs if configuration in dependabot.yml has changed and remove dependency updates for projects that no longer have the configuration.

Since the job tries to register all of the projects where user associated with the access token used has at least developer access, it might be necessary to disable hook creation, because it requires maintainer level access. SETTINGS_CREATE_PROJECT_HOOK must be set to false in this case.

Additionally option SETTINGS__PROJECT_REGISTRATION_NAMESPACE can restrict namespaces allowed to automatically register projects.

System webhook

If project registration option is set to system_hook, endpoint api/project/registration endpoint is enabled which listens for following system hook events to automatically register projects:

• project_create
• project_destroy
• project_rename
• project_transfer

Additionally option SETTINGS__PROJECT_REGISTRATION_NAMESPACE can restrict namespaces allowed to automatically register projects.

If projects are registered using system webhook, SETTINGS__CREATE_PROJECT_HOOK should be set to false to disable project specific webhook automatic creation

Manually

Project webhook

If project webhook was added manually beforehand, project will be registered once .dependabot.yml configuration file is pushed to repository.

Project is removed from dependabot instance if dependabot.yml file is deleted from repository.

API

add project

Rake task

register rake task

Project access tokens

Both API and rake task registration methods support registering project with specific gitlab access tokens.

Api endpoints

Gitlab webhooks

POST /api/hooks

Handle following gitlab event webhooks

• Push events - default repository branch
• Merge request events
• Comments
• Pipeline events

List projects

GET /api/projects

Response:

[
  {
    "id": 1,
    "name": "dependabot-gitlab/dependabot",
    "forked_from_id": null,
    "webhook_id": 1,
    "web_url": "https://gitlab.com/dependabot-gitlab/dependabot",
    "config": [
      {
        "package_manager": "bundler",
        "package_ecosystem": "bundler",
        "directory": "/",
        "milestone": "0.0.1",
        "assignees": ["john_doe"],
        "reviewers": ["john_smith"],
        "approvers": ["jane_smith"],
        "custom_labels": ["dependency"],
        "open_merge_requests_limit": 10,
        "cron": "00 02 * * sun Europe/Riga",
        "branch_name_separator": "-",
        "branch_name_prefix": "dependabot",
        "allow": [
          {
            "dependency_type": "direct"
          }
        ],
        "ignore": [
          {
            "dependency_name": "rspec",
            "versions": ["3.x", "4.x"]
          },
          {
            "dependency_name": "faker",
            "update_types": ["version-update:semver-major"]
          }
        ],
        "rebase_strategy": "auto",
        "auto_merge": true,
        "versioning_strategy": "lockfile_only",
        "reject_external_code": true,
        "commit_message_options": {
          "prefix": "dep",
          "prefix_development": "bundler-dev",
          "include_scope": "scope"
        },
        "registries": [
          {
            "type": "docker_registry",
            "registry": "https://registry.hub.docker.com",
            "username": "octocat"
          }
        ]
      }
    ]
  }
]

Get project

GET /api/projects/:id

• id - URL escaped full path or id of the project

Response:

{
  "id": 1,
  "name": "dependabot-gitlab/dependabot",
  "forked_from_id": null,
  "webhook_id": 1,
  "web_url": "https://gitlab.com/dependabot-gitlab/dependabot",
  "config": [
    {
      "package_manager": "bundler",
      "package_ecosystem": "bundler",
      "directory": "/",
      "milestone": "0.0.1",
      "assignees": ["john_doe"],
      "reviewers": ["john_smith"],
      "approvers": ["jane_smith"],
      "custom_labels": ["dependency"],
      "open_merge_requests_limit": 10,
      "cron": "00 02 * * sun Europe/Riga",
      "branch_name_separator": "-",
      "branch_name_prefix": "dependabot",
      "allow": [
        {
          "dependency_type": "direct"
        }
      ],
      "ignore": [
        {
          "dependency_name": "rspec",
          "versions": ["3.x", "4.x"]
        },
        {
          "dependency_name": "faker",
          "update_types": ["version-update:semver-major"]
        }
      ],
      "rebase_strategy": "auto",
      "auto_merge": true,
      "versioning_strategy": "lockfile_only",
      "reject_external_code": true,
      "commit_message_options": {
        "prefix": "dep",
        "prefix_development": "bundler-dev",
        "include_scope": "scope"
      },
      "registries": [
        {
          "type": "docker_registry",
          "registry": "https://registry.hub.docker.com",
          "username": "octocat"
        }
      ]
    }
  ]
}

Add project

POST /api/projects

Add new project or update existing one and sync jobs

• project - full project path
• gitlab_access_token - optional project specific gitlab access token

Request:

{
  "project": "dependabot-gitlab/dependabot",
  "gitlab_access_token": "custom-project-access-token"
}

Update project

PUT /api/projects/:id

Update project attributes

Request:

• id - URL escaped full path or id of the project
• name - full project path
• forked_from_id - id of upstream project
• forked_from_name - upstream project path with namespace
• webhook_id - webhook id
• web_url - project web url
• config - dependabot configuration array

{
  "name":"name",
  "forked_from_id": 1,
  "webhook_id":1,
  "web_url": "new-url",
  "config": []
}

Delete project

DELETE /api/projects/:id

• id - URL escaped full path or id of the project

Notify release

POST /api/notify_release

Notifies Dependabot of dependency release. In response, Dependabot will check all projects and update the package.

• name: package name
• package-ecosystem: value from supported ecosystem.

{
  "name": "package-name",
  "package_ecosystem": "package-ecosystem"
}

Healthcheck

GET /healthcheck

Check if application is running and responding

Rake tasks

Several administrative rake tasks exist which can be executed from app working directory.

register

Manually register project for updates. Repository must have valid dependabot config file

/home/dependabot/app$ bundle exec rake 'dependabot:register[project]'

project_name - project full path or multiple space separated project full paths, example: dependabot-gitlab/dependabot

register with specific access token

Manually register project for updates with specific gitlab access token

/home/dependabot/app$ bundle exec rake 'rake dependabot:register_project[project_name,access_token]'

• project_name - project full path, example: dependabot-gitlab/dependabot
• access_token - project access token, example: project access token

bulk register

Manually trigger project registration job

/home/dependabot/app$ bundle exec rake 'dependabot:automatic_registration'

remove

Manually remove project.

/home/dependabot/app$ bundle exec rake 'dependabot:remove[project]'

project - project full path, example: dependabot-gitlab/dependabot

update

Trigger dependency update for single project and single package managed

/home/dependabot/app$ bundle exec rake 'dependabot:update[project,package_ecosystem,directory]'

• project - project full path, example: dependabot-gitlab/dependabot
• package_ecosystem - package-ecosystem parameter like bundler
• directory - directory is path where dependency files are stored, usually /

This task is used to provide standalone use capability

validate

Validate dependabot.yml configuration file

/home/dependabot/app$ bundle exec rake 'dependabot:validate[project]'

project - project full path, example: dependabot-gitlab/dependabot

UI

Index page of application, like http://localhost:3000/ will display a table with jobs currently configured to run dependency updates

Development

• Install dependencies with bundle install
• Setup pre-commit hooks with pre-commit install
• Make change and make sure tests pass with bundle exec rspec (some tests require instance of mongodb and redis which can be started via docker-compose -f docker-compose.yml up command)
• Submit merge request