└── README.md /README.md: -------------------------------------------------------------------------------- 1 |

2 | Dependabot 3 |

4 | 5 | # Deprecation notice 6 | 7 | Dependabot Preview is [scheduled for shutdown on August 3rd, 2021](https://github.blog/2021-04-29-goodbye-dependabot-preview-hello-dependabot/), 8 | which means that the Dependabot Preview REST API documented here will also 9 | be shut down. This repository has been archived to reflect that. 10 | 11 | Please migrate to [GitHub-native Dependabot](https://docs.github.com/en/code-security/supply-chain-security/keeping-your-dependencies-updated-automatically/about-dependabot-version-updates) 12 | before then in order to continue keeping your dependencies up to date. 13 | 14 | # Dependabot API docs 15 | 16 | Dependabot has a JSON API to make it easy to bulk-import projects. This API is also 17 | used by the Dependabot dashboard. 18 | 19 | **Please note that Dependabot cannot commit to maintaining backwards 20 | compatibility of this API**. We will, however, update these docs 21 | whenever breaking changes are made (likely to be infrequently). We recommend 22 | you "watch" this repo to receive notifications of any changes. 23 | 24 | ## Authentication 25 | 26 | Dependabot uses GitHub access tokens to authenticate users. To use the API: 27 | - Create a [GitHub personal access token](https://github.com/settings/tokens) 28 | with `repo` permissions (so the token can see private repos) 29 | - Add an `Authorization: Personal ` header to all requests using this 30 | access token 31 | 32 | We use the access token you provide to ensure you have sufficient GitHub 33 | permissions to undertake any actions you request through the Dependabot API. 34 | 35 | ## Endpoints 36 | 37 | ### Get Accounts 38 | 39 | ``` 40 | GET https://api.dependabot.com/accounts 41 | ``` 42 | 43 | Returns all Dependabot accounts that the authenticated user has access to. 44 | 45 |
46 | Example response 47 | 48 | ``` 49 | { 50 | "data": [ 51 | { 52 | "id": "27347476", 53 | "type": "accounts", 54 | "attributes": { 55 | "github-id": 27347476, 56 | "github-login": "dependabot", 57 | "github-account-type": "org", 58 | "access-granted-to-all-repos": true, 59 | "current-installation-id": 25920, 60 | "plan-name": "free", 61 | "plan-number": 7, 62 | "free-trial-end-date": null, 63 | "automatically-rebase-prs": true, 64 | "update-run-time": "05:00", 65 | "create-merge-commits": false, 66 | "weekly-update-run-day": "monday", 67 | "limit-initial-update-runs": true, 68 | "limit-open-pull-requests": true 69 | } 70 | }, 71 | { 72 | "id": "1144873", 73 | "type": "accounts", 74 | "attributes": { 75 | "github-id": 1144873, 76 | "github-login": "greysteil", 77 | "github-account-type": "user", 78 | "access-granted-to-all-repos": true, 79 | "current-installation-id": 132882, 80 | "plan-name": "free", 81 | "plan-number": 7, 82 | "free-trial-end-date": null, 83 | "automatically-rebase-prs": true, 84 | "update-run-time": "02:15", 85 | "create-merge-commits": true, 86 | "weekly-update-run-day": "monday", 87 | "limit-initial-update-runs": true, 88 | "limit-open-pull-requests": true 89 | } 90 | } 91 | ] 92 | } 93 | ``` 94 | 95 |
96 | 97 | ### Get Repos for an account 98 | 99 | ``` 100 | GET https://api.dependabot.com/repos?account-id=27347476&account-type=org&installation-state=active 101 | ``` 102 | 103 | Returns active or inactive repos for the specified account. 104 | 105 | #### Breaking change introduced 2019-12-02 106 | 107 | - The `installation-state` param **must** be `active` or `inactive` 108 | - `inactive` repos are paginated (100 repos per page) 109 | - Pass the `page=num` param to paginate the results (defaults to `page=1`) 110 | - The next page number is returned in the response: `response.meta.pages.next` 111 | 112 |
113 | Example response 114 | 115 | ``` 116 | { 117 | "data": [ 118 | { 119 | "id": "93163073", 120 | "type": "repos", 121 | "attributes": { 122 | "github-id": 93163073, 123 | "name": "dependabot-core", 124 | "installation-state": "active", 125 | "private": false, 126 | "fork": false, 127 | "github-url": "https://github.com/dependabot/dependabot-core", 128 | "primary-language": "ruby", 129 | "default-branch": "master", 130 | "using-config-file":true 131 | }, 132 | "relationships": { 133 | "update-configs": { 134 | "data": [ 135 | { 136 | "id": "1332", 137 | "type": "update-configs" 138 | }, 139 | { 140 | "id": "5061", 141 | "type": "update-configs" 142 | }, 143 | { 144 | "id": "275", 145 | "type": "update-configs" 146 | }, 147 | { 148 | "id": "879", 149 | "type": "update-configs" 150 | }, 151 | { 152 | "id": "1672", 153 | "type": "update-configs" 154 | }, 155 | { 156 | "id": "326", 157 | "type": "update-configs" 158 | }, 159 | { 160 | "id": "3123", 161 | "type": "update-configs" 162 | } 163 | ] 164 | }, 165 | "account": { 166 | "data": { 167 | "id": "27347476", 168 | "type": "accounts" 169 | } 170 | } 171 | } 172 | }, 173 | { 174 | "id": "131328855", 175 | "type": "repos", 176 | "attributes": { 177 | "github-id": 131328855, 178 | "name": "dependabot-script", 179 | "installation-state": "active", 180 | "private": false, 181 | "fork": false, 182 | "github-url": "https://github.com/dependabot/dependabot-script", 183 | "primary-language": "ruby", 184 | "default-branch": "master", 185 | "using-config-file":true 186 | }, 187 | "relationships": { 188 | "update-configs": { 189 | "data": [ 190 | { 191 | "id": "4925", 192 | "type": "update-configs" 193 | } 194 | ] 195 | }, 196 | "account": { 197 | "data": { 198 | "id": "27347476", 199 | "type": "accounts" 200 | } 201 | } 202 | } 203 | } 204 | ], 205 | "included": [ 206 | { 207 | "id": "1332", 208 | "type": "update-configs", 209 | "attributes": { 210 | "language": "javascript", 211 | "package-manager": "npm_and_yarn", 212 | "update-schedule": "live", 213 | "directory": "/helpers/npm", 214 | "automerge-rule-runtime-deps": "semver:patch", 215 | "automerge-rule-development-deps": "semver:minor", 216 | "target-branch": null, 217 | "lockfile-only": false, 218 | "security-updates-only": false 219 | }, 220 | "relationships": { 221 | "repo": { 222 | "data": { 223 | "id": "93163073", 224 | "type": "repos" 225 | } 226 | } 227 | } 228 | }, 229 | { 230 | "id": "5061", 231 | "type": "update-configs", 232 | "attributes": { 233 | "language": "java", 234 | "package-manager": "gradle", 235 | "update-schedule": "daily", 236 | "directory": "/helpers/gradle", 237 | "automerge-rule-runtime-deps": "never", 238 | "automerge-rule-development-deps": "never", 239 | "target-branch": null, 240 | "lockfile-only": false, 241 | "security-updates-only": false 242 | }, 243 | "relationships": { 244 | "repo": { 245 | "data": { 246 | "id": "93163073", 247 | "type": "repos" 248 | } 249 | } 250 | } 251 | }, 252 | { 253 | "id": "275", 254 | "type": "update-configs", 255 | "attributes": { 256 | "language": "php", 257 | "package-manager": "composer", 258 | "update-schedule": "live", 259 | "directory": "/helpers/php", 260 | "automerge-rule-runtime-deps": "semver:patch", 261 | "automerge-rule-development-deps": "semver:patch", 262 | "target-branch": null, 263 | "lockfile-only": false, 264 | "security-updates-only": false 265 | }, 266 | "relationships": { 267 | "repo": { 268 | "data": { 269 | "id": "93163073", 270 | "type": "repos" 271 | } 272 | } 273 | } 274 | }, 275 | { 276 | "id": "879", 277 | "type": "update-configs", 278 | "attributes": { 279 | "language": "javascript", 280 | "package-manager": "npm_and_yarn", 281 | "update-schedule": "live", 282 | "directory": "/helpers/yarn", 283 | "automerge-rule-runtime-deps": "semver:patch", 284 | "automerge-rule-development-deps": "semver:minor", 285 | "target-branch": null, 286 | "lockfile-only": false, 287 | "security-updates-only": false 288 | }, 289 | "relationships": { 290 | "repo": { 291 | "data": { 292 | "id": "93163073", 293 | "type": "repos" 294 | } 295 | } 296 | } 297 | }, 298 | { 299 | "id": "1672", 300 | "type": "update-configs", 301 | "attributes": { 302 | "language": "python", 303 | "package-manager": "pip", 304 | "update-schedule": "live", 305 | "directory": "/helpers/python", 306 | "automerge-rule-runtime-deps": "semver:patch", 307 | "automerge-rule-development-deps": "semver:patch", 308 | "target-branch": null, 309 | "lockfile-only": false, 310 | "security-updates-only": false 311 | }, 312 | "relationships": { 313 | "repo": { 314 | "data": { 315 | "id": "93163073", 316 | "type": "repos" 317 | } 318 | } 319 | } 320 | }, 321 | { 322 | "id": "326", 323 | "type": "update-configs", 324 | "attributes": { 325 | "language": "ruby", 326 | "package-manager": "bundler", 327 | "update-schedule": "live", 328 | "directory": "/", 329 | "automerge-rule-runtime-deps": "semver:patch", 330 | "automerge-rule-development-deps": "semver:patch", 331 | "target-branch": null, 332 | "lockfile-only": false, 333 | "security-updates-only": false 334 | }, 335 | "relationships": { 336 | "repo": { 337 | "data": { 338 | "id": "93163073", 339 | "type": "repos" 340 | } 341 | } 342 | } 343 | }, 344 | { 345 | "id": "3123", 346 | "type": "update-configs", 347 | "attributes": { 348 | "language": "elixir", 349 | "package-manager": "hex", 350 | "update-schedule": "live", 351 | "directory": "/helpers/elixir", 352 | "automerge-rule-runtime-deps": "semver:patch", 353 | "automerge-rule-development-deps": "semver:patch", 354 | "target-branch": null, 355 | "lockfile-only": false, 356 | "security-updates-only": false 357 | }, 358 | "relationships": { 359 | "repo": { 360 | "data": { 361 | "id": "93163073", 362 | "type": "repos" 363 | } 364 | } 365 | } 366 | }, 367 | { 368 | "id": "4925", 369 | "type": "update-configs", 370 | "attributes": { 371 | "language": "ruby", 372 | "package-manager": "bundler", 373 | "update-schedule": "daily", 374 | "directory": "/", 375 | "automerge-rule-runtime-deps": "never", 376 | "automerge-rule-development-deps": "never", 377 | "target-branch": null, 378 | "lockfile-only": false, 379 | "security-updates-only": false 380 | }, 381 | "relationships": { 382 | "repo": { 383 | "data": { 384 | "id": "131328855", 385 | "type": "repos" 386 | } 387 | } 388 | } 389 | } 390 | ] 391 | } 392 | ``` 393 | 394 |
395 | 396 | ### Create an Update Config for a repo 397 | 398 | ``` 399 | POST https://api.dependabot.com/update_configs 400 | 401 | { 402 | "repo-id": 93163073, 403 | "package-manager": "bundler", 404 | "update-schedule": "daily", 405 | "directory": "/", 406 | "account-id": "27347476", 407 | "account-type": "org", 408 | } 409 | ``` 410 | 411 | Creates an update config. The following parameters can be passed: 412 | 413 | | Attribute | Default | Description | 414 | |-----------------------------------|----------------|----------------------------------------------| 415 | | `repo-id` | None (required)| The GitHub ID of the repository | 416 | | `account-id` | None (required)| The GitHub ID of the repository owner | 417 | | `account-type` | None (required)| `org` or `user` | 418 | | `directory` | None (required)| The directory of the dependency files. Normally `/` | 419 | | `update-schedule` | None (required)| One of `live`, `daily`, `weekly` or `monthly` | 420 | | `package-manager` | None (required)| One of `bundler`, `composer`, `docker`, `maven`, `npm_and_yarn`, `elm`, `submodules`, `hex`, `cargo`, `gradle`, `nuget`, `dep`, `go_modules`, `pip`, `terraform`, `github_actions` | 421 | | `target-branch` | GitHub default | The branch to create PRs against | 422 | | `lockfile-only` | false | Ignore updates that are out-of-range of the manifest file | 423 | | `security-updates-only` | false | Only generate PRs for updates that fix a security vulnerability | 424 | | `automerge-rule-development-deps` | `never` | One of `never`, `security:patch`, `semver:patch`, `semver:minor`, `in_range` or `all` | 425 | | `automerge-rule-runtime-deps` | `never` | One of `never`, `security:patch`, `semver:patch`, `semver:minor`, `in_range` or `all` | 426 | 427 | 428 | ### Update an existing Update Config 429 | 430 | ``` 431 | PATCH https://api.dependabot.com/update_configs/:id 432 | 433 | { 434 | "update-schedule": "live", 435 | "target-branch": "dev", 436 | "lockfile-only": true, 437 | "security-updates-only": false, 438 | "update-schedule": "daily", 439 | "automerge-rule-development-deps": "semver:patch", 440 | "automerge-rule-runtime-deps": "semver:minor" 441 | } 442 | ``` 443 | 444 | Update an update config, for example, to change its update schedule. 445 | 446 | 447 | ### Delete an existing Update Config 448 | 449 | ``` 450 | DELETE https://api.dependabot.com/update_configs/:id 451 | ``` 452 | 453 | Delete an update config. 454 | 455 | 456 | ### Notify Dependabot of a private dependency release 457 | 458 | ``` 459 | POST https://api.dependabot.com/release_notifications/private 460 | 461 | { 462 | "name": "your_dependency_name", 463 | "version": "1.5.0", 464 | "package-manager": "bundler" 465 | } 466 | ``` 467 | 468 | Notifies Dependabot of a private dependency release. In response, Dependabot 469 | will check all of the repos that belong to an organization your access token has 470 | access to. If any use an outdated version of the dependency Dependabot will 471 | create update PRs for them. 472 | 473 | Note that this API is *not* a substitute for Dependabot being able to access 474 | your registry. When notified of a new version Dependabot triggers update runs 475 | which will query your registry for the latest version. 476 | 477 | The `name` attribute should be the name of the dependency. For Java dependencies 478 | the name is constructed from the `groupId` and `artifactId` of the dependency, 479 | joined by a `:` (for example: `org.kohsuke:github-api`). 480 | 481 | This endpoint is useful to get immediate updates to private dependencies. 482 | However, if you release a new version of a private dependency but don't notify 483 | Dependabot then it will still pick it up the following morning. 484 | --------------------------------------------------------------------------------