| 1 | --- |
| 2 | title: Dependency updates |
| 3 | description: Keep a repository's dependencies current with a dependabot.yml file. g1t opens pull requests that raise them on the schedule you set, and lands them through your required checks. |
| 4 | --- |
| 5 | |
| 6 | g1t keeps your dependencies current from one file in your repository, |
| 7 | written in `dependabot.yml` version 2 syntax. On the schedule you set, g1t |
| 8 | checks each dependency's registry for newer versions and opens pull |
| 9 | requests that raise them. They land through your branch's required checks |
| 10 | like any other change. |
| 11 | |
| 12 | The same file also shapes the [security updates](/guides/security/#security-updates) |
| 13 | g1t opens for vulnerable dependencies. See |
| 14 | [Security updates follow the same file](#security-updates-follow-the-same-file). |
| 15 | |
| 16 | ## Turn on version updates |
| 17 | |
| 18 | 1. Add `.g1t/dependabot.yml` to your default branch: |
| 19 | |
| 20 | ```yaml |
| 21 | version: 2 |
| 22 | updates: |
| 23 | - package-ecosystem: npm |
| 24 | directory: / |
| 25 | schedule: |
| 26 | interval: weekly |
| 27 | ``` |
| 28 | |
| 29 | 2. Push it. g1t reads the file on every push to the default branch, and |
| 30 | checks each entry it can update once, straight away. |
| 31 | 3. Open the project's **Security** page and choose **Dependency updates**. |
| 32 | It lists each entry, when it runs next, and what its last run found. |
| 33 | |
| 34 | A repository you bring to g1t keeps its existing file. You don't need to |
| 35 | move or change it. |
| 36 | |
| 37 | ## Where g1t reads the file |
| 38 | |
| 39 | g1t reads the file from the default branch, at the first of these paths |
| 40 | that exists: |
| 41 | |
| 42 | | Order | Path | |
| 43 | | --- | --- | |
| 44 | | 1 | `.g1t/dependabot.yml` | |
| 45 | | 2 | `.g1t/dependabot.yaml` | |
| 46 | | 3 | `.github/dependabot.yml` | |
| 47 | | 4 | `.github/dependabot.yaml` | |
| 48 | |
| 49 | When a file exists under both `.g1t/` and `.github/`, g1t reads the one |
| 50 | under `.g1t/`, and the Security page says the other is ignored. |
| 51 | |
| 52 | g1t reads the file on every push to the default branch, and at least once |
| 53 | a day, with the daily [dependency scan](/guides/security/#dependencies). |
| 54 | |
| 55 | ## Checking the file |
| 56 | |
| 57 | g1t checks the whole file each time it reads it. Every problem is reported |
| 58 | with its line and the key it is on: |
| 59 | |
| 60 | ```text |
| 61 | line 6, updates[0].schedule.interval: `hourly` is not an interval. Use `daily`, `weekly`, `monthly`, `quarterly`, `semiannually`, `yearly` or `cron`. |
| 62 | ``` |
| 63 | |
| 64 | - A key g1t does not know is a problem, so a misspelled option is never |
| 65 | passed over in silence. |
| 66 | - A file with any problem is not acted on: g1t opens nothing from it until |
| 67 | it is fixed. The Security page lists each problem. |
| 68 | - `version` must be `2` (or `"2"`). |
| 69 | - The file holds at most 200 entries and 100 registries. Each ecosystem, |
| 70 | directory and target branch is listed once; a second entry for the same |
| 71 | ones is a problem. |
| 72 | - YAML anchors, aliases and `<<` merge keys work. |
| 73 | |
| 74 | ### Checking a pull request that changes the file |
| 75 | |
| 76 | A pull request that changes the file gets a status named |
| 77 | `g1t / dependabot.yml` on its head commit: |
| 78 | |
| 79 | | Status | Description | |
| 80 | | --- | --- | |
| 81 | | Success | `.g1t/dependabot.yml is valid: 3 entries.` | |
| 82 | | Failure | The first problem, and how many more there are, such as `line 6, updates[0].schedule.interval: … (and 2 more)` | |
| 83 | |
| 84 | Make it a [required status check](/guides/pull-requests/#required-status-checks) |
| 85 | to stop a broken file from reaching the default branch. |
| 86 | |
| 87 | ## Ecosystems |
| 88 | |
| 89 | g1t accepts every `package-ecosystem` value the format names, and opens |
| 90 | version update pull requests for four of them: |
| 91 | |
| 92 | | `package-ecosystem` | Lockfiles | Manifests | |
| 93 | | --- | --- | --- | |
| 94 | | `npm` | `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock` | `package.json` | |
| 95 | | `cargo` | `Cargo.lock` | `Cargo.toml` | |
| 96 | | `gomod` | `go.mod`, `go.sum` | `go.mod` | |
| 97 | | `pip` | Pins in `requirements.txt`, `poetry.lock` | `requirements.txt`, `pyproject.toml` | |
| 98 | |
| 99 | A directory is updated only when it has a lockfile: its own, or the |
| 100 | nearest one above it, as in a workspace. |
| 101 | |
| 102 | These values are read and checked, and the Security page lists their |
| 103 | entries as not updated yet: `bazel`, `bun`, `bundler`, `composer`, `conda`, |
| 104 | `deno`, `devcontainers`, `docker`, `docker-compose`, `dotnet-sdk`, `elm`, |
| 105 | `github-actions`, `gitsubmodule`, `gradle`, `helm`, `julia`, `maven`, `mix`, |
| 106 | `nix`, `nuget`, `opentofu`, `pre-commit`, `pub`, `rust-toolchain`, `sbt`, |
| 107 | `swift`, `terraform`, `uv` and `vcpkg`. |
| 108 | |
| 109 | With `enable-beta-ecosystems: true` at the top of the file, any other |
| 110 | `package-ecosystem` name is accepted too. |
| 111 | |
| 112 | ## When updates run |
| 113 | |
| 114 | Each entry g1t updates runs once as soon as g1t first reads the file with |
| 115 | it, and then on its `schedule`. g1t picks up due entries every five |
| 116 | minutes. |
| 117 | |
| 118 | | `interval` | Runs | |
| 119 | | --- | --- | |
| 120 | | `daily` | Monday to Friday. | |
| 121 | | `weekly` | Once a week, on `day` (`monday` unless you set it). | |
| 122 | | `monthly` | On the 1st of each month. | |
| 123 | | `quarterly` | On 1 January, 1 April, 1 July and 1 October. | |
| 124 | | `semiannually` | On 1 January and 1 July. | |
| 125 | | `yearly` | On 1 January. | |
| 126 | | `cron` | When `cronjob` says. | |
| 127 | |
| 128 | The other `schedule` keys: |
| 129 | |
| 130 | | Key | Value | Default | |
| 131 | | --- | --- | --- | |
| 132 | | `day` | A day of the week, such as `friday`. Used by `weekly`. | `monday` | |
| 133 | | `time` | The time of day, as `hh:mm`, such as `"09:00"`. | A time g1t picks | |
| 134 | | `timezone` | An IANA time zone, such as `America/New_York`. Daylight saving is followed. | `UTC` | |
| 135 | | `cronjob` | A five-field cron expression, such as `"0 9 * * 1"`, or a phrase such as `every weekday at 9:30am`. Required with, and only read for, `interval: cron`. | | |
| 136 | |
| 137 | `cronjob` also takes these phrases: `every day at 5pm`, |
| 138 | `every weekday at 9:30am`, `every monday at 09:00`, `every hour` and |
| 139 | `every 6 hours`. |
| 140 | |
| 141 | Without `time`, g1t picks a time of day for each entry of each repository |
| 142 | and keeps it, so your repositories don't all update at once. The Security |
| 143 | page shows it as "a time picked for this repository". |
| 144 | |
| 145 | To run an entry now, choose **Check for updates** next to it on the |
| 146 | Security page. You need the Write [role](/guides/access-and-roles/). |
| 147 | |
| 148 | ## What a run does |
| 149 | |
| 150 | 1. g1t reads the manifests and lockfiles in the entry's directories. |
| 151 | 2. It asks each dependency's registry which versions exist: the npm |
| 152 | registry, crates.io, the Go module proxy or PyPI, or a |
| 153 | [private registry](#private-registries) you name. |
| 154 | 3. It picks each dependency's target version, following `allow`, `ignore`, |
| 155 | `cooldown` and `versioning-strategy`. |
| 156 | 4. It gathers the updates into pull requests, by `groups`, and opens up to |
| 157 | `open-pull-requests-limit` of them. |
| 158 | |
| 159 | What g1t updates and skips: |
| 160 | |
| 161 | - Only dependencies your manifests name (direct dependencies) are updated, |
| 162 | unless an [`allow`](#allow) rule says otherwise. |
| 163 | - Pre-releases are skipped, unless the current version is one. |
| 164 | - Yanked and deprecated versions are skipped. |
| 165 | - A run looks at up to 200 dependencies. When there are more, its summary |
| 166 | says how many were skipped. |
| 167 | |
| 168 | The Security page shows when each entry was last checked and what the run |
| 169 | found: |
| 170 | |
| 171 | ```text |
| 172 | Checked 42 dependencies: 38 up to date, 1 ignored, 3 pull requests asked for, 1 waiting for open-pull-requests-limit. |
| 173 | ``` |
| 174 | |
| 175 | Version updates run in the same sandbox as security updates, and are |
| 176 | metered the same way. g1t never runs a manifest's code while updating |
| 177 | it. |
| 178 | |
| 179 | ## The pull requests |
| 180 | |
| 181 | Version update pull requests are opened by g1t, and show |
| 182 | [@g1t](/guides/security/#the-g1t-identity) as their author. |
| 183 | |
| 184 | | What it updates | Title | |
| 185 | | --- | --- | |
| 186 | | One dependency | `Bump lodash from 4.17.20 to 4.17.21` | |
| 187 | | One dependency, not in the root directory | `Bump lodash from 4.17.20 to 4.17.21 in /web` | |
| 188 | | A group | `Bump the lint group with 3 updates` | |
| 189 | | A group in one directory | `Bump the lint group in /web with 2 updates` | |
| 190 | | A group across directories | `Bump the lint group across 2 directories with 4 updates` | |
| 191 | | A `group-by: dependency-name` group | `Bump eslint to 9.0.0 across 2 directories` | |
| 192 | |
| 193 | The body says what changes and links, when they are known, the |
| 194 | dependency's changelog (when its registry names one), its release notes |
| 195 | (for source on github.com, gitlab.com or g1t.sh), its source and its |
| 196 | package page. A group's body has a table of each package, its old and new |
| 197 | version, and its directory. Every body lists the |
| 198 | [commands](#comment-commands) the pull request takes, and its footer names |
| 199 | the file it came from and the entry's `name`, if it has one. |
| 200 | |
| 201 | The commit message is the title, a line for each update, and an |
| 202 | `updated-dependencies` record: |
| 203 | |
| 204 | ```text |
| 205 | Bump lodash from 4.17.20 to 4.17.21 |
| 206 | |
| 207 | Bumps lodash from 4.17.20 to 4.17.21. |
| 208 | |
| 209 | --- |
| 210 | updated-dependencies: |
| 211 | - dependency-name: lodash |
| 212 | dependency-version: 4.17.21 |
| 213 | dependency-type: direct:production |
| 214 | update-type: version-update:semver-patch |
| 215 | ... |
| 216 | ``` |
| 217 | |
| 218 | `dependency-type` is `direct:production`, `direct:development` or |
| 219 | `indirect`. A grouped update adds `dependency-group: <name>` to each |
| 220 | dependency. |
| 221 | |
| 222 | ### Superseded pull requests |
| 223 | |
| 224 | When a newer version comes out for a dependency (or group) that already |
| 225 | has an open pull request, g1t opens a new pull request and closes the |
| 226 | older one with the comment "Closed: superseded by #N.". It deletes the |
| 227 | older pull request's branch. |
| 228 | |
| 229 | ### Updates you make yourself |
| 230 | |
| 231 | You do not have to merge g1t's pull request to update a dependency. On |
| 232 | every push to the default branch, g1t reads the lockfiles again. When |
| 233 | every dependency an open version update raises is already at its new |
| 234 | version or later, or is no longer a dependency, g1t closes the pull |
| 235 | request with a comment that says so, for example: |
| 236 | |
| 237 | > Closed: `lodash` is already at 4.17.21 on `main`, so this update to |
| 238 | > 4.17.21 is no longer needed. |
| 239 | |
| 240 | g1t then deletes the pull request's branch. While one dependency in a |
| 241 | grouped pull request still needs it, the pull request stays open. This |
| 242 | applies to updates into the default branch; one with a `target-branch` |
| 243 | is left for you to close. |
| 244 | |
| 245 | ### Branches |
| 246 | |
| 247 | Each update pull request is made on a branch g1t creates (see |
| 248 | [branch names](#pull-request-branch-name)). When the pull request merges |
| 249 | or closes, whether g1t or a person closes it, g1t deletes that branch. If |
| 250 | someone pushed to the branch after its last commit in the pull request, |
| 251 | g1t leaves it alone. A branch left from an update pull request that is |
| 252 | already closed is removed on a later push to the default branch. The |
| 253 | branch of a pull request closed because code has to change is kept while |
| 254 | g1t works on the issue for it. |
| 255 | |
| 256 | Deleting the branch means a closed update pull request cannot be reopened |
| 257 | from the page. To make a version update again, comment `@g1t reopen` on |
| 258 | it: g1t makes it again as a new pull request. |
| 259 | |
| 260 | ### Landing them |
| 261 | |
| 262 | Version update pull requests land through the branch's |
| 263 | [required checks](/guides/pull-requests/#required-status-checks) and the |
| 264 | [merge queue](/guides/merge-queue/) like any other change. |
| 265 | |
| 266 | When a required check fails on g1t's own commit (or, on a branch with no |
| 267 | required checks, a workflow's status fails), raising the version was not |
| 268 | enough. g1t closes the pull request and opens an issue titled |
| 269 | `<pull request title>: needs code changes`, assigned to |
| 270 | [g1t](/guides/working-with-g1t/), to make the changes the update needs. |
| 271 | Security updates are handled |
| 272 | [the same way](/guides/security/#when-code-has-to-change). |
| 273 | |
| 274 | If the sandbox has not pushed a branch 45 minutes after an update started, |
| 275 | the update is marked failed, and the entry's next run tries again. |
| 276 | |
| 277 | ## Comment commands |
| 278 | |
| 279 | Comment on a pull request g1t opened for a version or security update, |
| 280 | with a command on the comment's first line: |
| 281 | |
| 282 | | Command | What it does | |
| 283 | | --- | --- | |
| 284 | | `@g1t rebase` | Brings the branch up to date with the default branch. Refused if someone else has pushed to it; use `@g1t recreate`. | |
| 285 | | `@g1t recreate` | Makes the pull request again from scratch, dropping anything pushed to it. | |
| 286 | | `@g1t merge` | Merges it once its required checks pass. | |
| 287 | | `@g1t squash and merge` | The same as `@g1t merge`: g1t merges pull requests one way. | |
| 288 | | `@g1t cancel merge` | Cancels an earlier `@g1t merge`. | |
| 289 | | `@g1t close` | Closes it. g1t does not open one for these versions again, but does for a newer version. | |
| 290 | | `@g1t reopen` | Makes it again, as a new pull request on the same branch. | |
| 291 | | `@g1t ignore this dependency` | Closes it, and stops updating the dependency. | |
| 292 | | `@g1t ignore this major version` | Closes it, and skips this major version. Also `minor` and `patch`. | |
| 293 | | `@g1t ignore <dependency>` | On a grouped pull request, stops updating one dependency. | |
| 294 | | `@g1t ignore <dependency> major version` | On a grouped pull request, skips that dependency's major version. Also `minor` and `patch`. | |
| 295 | | `@g1t unignore <dependency>` | Removes the dependency's ignore conditions. | |
| 296 | | `@g1t unignore <dependency> major version` | Removes one ignore condition. Also `minor` and `patch`. | |
| 297 | | `@g1t unignore *` | Removes the ignore conditions set by comments. | |
| 298 | | `@g1t show <dependency> ignore conditions` | Lists what is skipped for a dependency. | |
| 299 | | `@g1t show ignore conditions` | Lists the ignore conditions set by comments. | |
| 300 | |
| 301 | Commands need the Write [role](/guides/access-and-roles/). `@g1t merge`, |
| 302 | `@g1t squash and merge` and `@g1t cancel merge` need the role that may |
| 303 | merge pull requests. |
| 304 | |
| 305 | Ignoring a version records an ignore condition. On a pull request that |
| 306 | raises a dependency to 5.0.0, `@g1t ignore this major version` records |
| 307 | `>= 5.a, < 6`. Ignore conditions set by comments apply to version and |
| 308 | security updates, and the Security page lists them. |
| 309 | |
| 310 | These commands are not mentions: they never start an agent. |
| 311 | |
| 312 | ## Security updates follow the same file |
| 313 | |
| 314 | [Security updates](/guides/security/#security-updates) are still turned on |
| 315 | and off with the **Security updates** switch. When the file has an entry |
| 316 | for a vulnerable package's ecosystem, in a directory that holds the |
| 317 | package's lockfile, that entry shapes the security update: |
| 318 | |
| 319 | | Option | Effect on security updates | |
| 320 | | --- | --- | |
| 321 | | `ignore` | A rule naming the package, or `versions` that cover the fix, skips it. So do ignore conditions set by comments. | |
| 322 | | `allow` | `dependency-name` rules limit which packages are updated. | |
| 323 | | `groups` with `applies-to: security-updates` | The group's vulnerable packages are fixed in one pull request, `Bump the <group> group with 2 security updates`, on the branch `g1t/security/<group>-<hash>`. | |
| 324 | | `commit-message` | Its prefix starts the title. | |
| 325 | | `assignees`, `reviewers` | Applied when the pull request opens. | |
| 326 | | `labels`, `milestone` | Applied when the pull request opens, as for version updates. Without `labels`, it carries `dependencies` and the ecosystem's label. | |
| 327 | | `open-pull-requests-limit`, `cooldown` | Do not apply. Security updates are never held back. | |
| 328 | |
| 329 | Security updates always merge into the default branch, so an entry whose |
| 330 | `target-branch` is another branch does not apply to them. |
| 331 | |
| 332 | ## The Security page |
| 333 | |
| 334 | Open the project's **Security** page and choose the **Dependency updates** |
| 335 | tab, at `g1t.sh/<owner>/<project>/security/dependency-updates`. It shows: |
| 336 | |
| 337 | - the file g1t read, and any file it ignored; |
| 338 | - each problem in the file, with its line; |
| 339 | - each entry: its ecosystem and directories, its schedule in words, its |
| 340 | next run, when it was last checked and what that run found, whether g1t |
| 341 | updates it, and the options it reads but does not act on; |
| 342 | - the [registries](#private-registries), with the secrets each one names; |
| 343 | - the open version update pull requests; |
| 344 | - the ignore conditions set by comments; |
| 345 | - **Check for updates** next to each entry, to run it now. |
| 346 | |
| 347 | ## Examples |
| 348 | |
| 349 | ### A monorepo |
| 350 | |
| 351 | Every package under `packages/` and the app in `/web`, checked each |
| 352 | weekday morning in New York, with lint tools in one pull request and |
| 353 | everything else in one pull request per dependency: |
| 354 | |
| 355 | ```yaml |
| 356 | version: 2 |
| 357 | updates: |
| 358 | - package-ecosystem: npm |
| 359 | directories: |
| 360 | - /web |
| 361 | - /packages/* |
| 362 | exclude-paths: |
| 363 | - "fixtures/**" |
| 364 | schedule: |
| 365 | interval: daily |
| 366 | time: "08:00" |
| 367 | timezone: America/New_York |
| 368 | open-pull-requests-limit: 10 |
| 369 | groups: |
| 370 | lint: |
| 371 | patterns: |
| 372 | - "eslint*" |
| 373 | - "@typescript-eslint/*" |
| 374 | - prettier |
| 375 | types: |
| 376 | dependency-type: development |
| 377 | patterns: |
| 378 | - "@types/*" |
| 379 | - package-ecosystem: cargo |
| 380 | directory: / |
| 381 | schedule: |
| 382 | interval: weekly |
| 383 | day: tuesday |
| 384 | ``` |
| 385 | |
| 386 | A group across several directories opens one pull request, such as |
| 387 | `Bump the lint group across 3 directories with 6 updates`. |
| 388 | |
| 389 | ### Waiting, and leaving some versions alone |
| 390 | |
| 391 | Wait a week before taking a new major version and two days for anything |
| 392 | else, never take React 19, and never update `left-pad`: |
| 393 | |
| 394 | ```yaml |
| 395 | version: 2 |
| 396 | updates: |
| 397 | - package-ecosystem: npm |
| 398 | directory: / |
| 399 | schedule: |
| 400 | interval: weekly |
| 401 | cooldown: |
| 402 | default-days: 2 |
| 403 | semver-major-days: 7 |
| 404 | exclude: |
| 405 | - "@acme/*" |
| 406 | ignore: |
| 407 | - dependency-name: react |
| 408 | versions: [">=19"] |
| 409 | - dependency-name: react-dom |
| 410 | versions: [">=19"] |
| 411 | - dependency-name: left-pad |
| 412 | ``` |
| 413 | |
| 414 | Your own `@acme/*` packages are taken as soon as they are published. |
| 415 | |
| 416 | ### A private npm registry |
| 417 | |
| 418 | Store the token as a secret named `NPM_TOKEN` in **Settings → Secrets** |
| 419 | (see [Secrets and variables](/guides/secrets-and-variables/)), then name |
| 420 | it in the file: |
| 421 | |
| 422 | ```yaml |
| 423 | version: 2 |
| 424 | registries: |
| 425 | acme-npm: |
| 426 | type: npm-registry |
| 427 | url: https://npm.acme.dev |
| 428 | token: ${{secrets.NPM_TOKEN}} |
| 429 | scope: "@acme" |
| 430 | updates: |
| 431 | - package-ecosystem: npm |
| 432 | directory: / |
| 433 | registries: |
| 434 | - acme-npm |
| 435 | schedule: |
| 436 | interval: daily |
| 437 | ``` |
| 438 | |
| 439 | Packages under `@acme` come from `npm.acme.dev`, and every other package |
| 440 | from the public npm registry. |
| 441 | |
| 442 | ### Commit messages and branch names |
| 443 | |
| 444 | ```yaml |
| 445 | version: 2 |
| 446 | updates: |
| 447 | - package-ecosystem: npm |
| 448 | directory: /web |
| 449 | schedule: |
| 450 | interval: weekly |
| 451 | commit-message: |
| 452 | prefix: build |
| 453 | prefix-development: chore |
| 454 | include: scope |
| 455 | pull-request-branch-name: |
| 456 | prefix: deps |
| 457 | separator: "-" |
| 458 | ``` |
| 459 | |
| 460 | An update to `lodash`, a production dependency, opens: |
| 461 | |
| 462 | ```text |
| 463 | build(deps): bump lodash from 4.17.20 to 4.17.21 in /web |
| 464 | ``` |
| 465 | |
| 466 | on the branch `deps-npm_and_yarn-web-lodash-4.17.21`. An update that |
| 467 | only touches development dependencies is titled |
| 468 | `chore(deps-dev): bump …`. |
| 469 | |
| 470 | ### Security updates in one pull request |
| 471 | |
| 472 | Fix every vulnerable npm package in one pull request, and keep version |
| 473 | updates one per dependency: |
| 474 | |
| 475 | ```yaml |
| 476 | version: 2 |
| 477 | updates: |
| 478 | - package-ecosystem: npm |
| 479 | directory: / |
| 480 | schedule: |
| 481 | interval: weekly |
| 482 | groups: |
| 483 | security: |
| 484 | applies-to: security-updates |
| 485 | patterns: |
| 486 | - "*" |
| 487 | reviewers: |
| 488 | - alice |
| 489 | ``` |
| 490 | |
| 491 | To use the file only for security updates, set |
| 492 | `open-pull-requests-limit: 0` on the entry. |
| 493 | |
| 494 | ## Options |
| 495 | |
| 496 | Each entry under `updates` takes the options below. `package-ecosystem`, |
| 497 | `directory` (or `directories`) and `schedule` are required. Unless a row |
| 498 | says otherwise, g1t acts on every option. |
| 499 | |
| 500 | | Option | What g1t does | Default | |
| 501 | | --- | --- | --- | |
| 502 | | `package-ecosystem` | The [ecosystem](#ecosystems). | Required | |
| 503 | | `directory` | Where the manifest is, from the repository's root, such as `/` or `/web`. No wildcards. | Required, or `directories` | |
| 504 | | `directories` | A list of directories, with globs: `*`, `**` and `?`. | | |
| 505 | | `exclude-paths` | Globs, relative to each directory, of manifests to leave out. | | |
| 506 | | `schedule` | [When updates run](#when-updates-run). | Required | |
| 507 | | `allow` | [Which dependencies are updated](#allow). | Direct dependencies | |
| 508 | | `ignore` | [Dependencies and versions to skip](#ignore). | | |
| 509 | | `cooldown` | [How long a release waits](#cooldown). | 3 days | |
| 510 | | `groups` | [Updates gathered into one pull request](#groups). | One pull request per dependency and directory | |
| 511 | | `versioning-strategy` | [How a requirement is raised](#versioning-strategy). | `increase` | |
| 512 | | `open-pull-requests-limit` | How many of this entry's version update pull requests can be open at once. A group counts as one, and a newer version replacing an open pull request does not add one. `0` turns version updates off for the entry. Security updates are not limited by it. | `5` | |
| 513 | | `commit-message` | [The title and commit message's prefix](#commit-message). | | |
| 514 | | `pull-request-branch-name` | [The branch name](#pull-request-branch-name). | | |
| 515 | | `rebase-strategy` | `auto`: an open pull request whose branch conflicts with the default branch is made again from the default branch, unless someone else pushed to it. `disabled`: never. | `auto` | |
| 516 | | `assignees` | Usernames assigned when the pull request opens. Also applies to security updates. | | |
| 517 | | `reviewers` | Usernames whose review is asked for when the pull request opens. A team (`org/team`) is skipped. Also applies to security updates. | | |
| 518 | | `registries` | The [registries](#private-registries) the entry uses: a list of names, or `"*"` for all of them. | | |
| 519 | | `target-branch` | The branch updates start from and merge into. Its manifests are read, each update is made from it, and its pull request's [base](/guides/base-branches/) is that branch. The default branch's protection does not cover it. | The default branch | |
| 520 | | `labels` | The [labels](/guides/labels/) put on each pull request. A label the repository lacks is created. `labels: []` puts none on. | `dependencies` and the ecosystem's label | |
| 521 | | `milestone` | The number of a [milestone](/guides/milestones/) to put each pull request in. A number the repository has no milestone for is skipped. | | |
| 522 | | `vendor` | Read. Vendored copies of dependencies are not updated. | `false` | |
| 523 | | `insecure-external-code-execution` | Read. g1t never runs a manifest's code while updating it. | | |
| 524 | | `name` | A name for the entry, 3 to 100 characters, shown in the footer of its pull requests. | | |
| 525 | | `multi-ecosystem-group` | The [multi-ecosystem group](#multi-ecosystem-groups) the entry belongs to. | | |
| 526 | | `patterns` | Only read for an entry in a multi-ecosystem group, where it is required. | | |
| 527 | |
| 528 | At the top of the file, beside `version` and `updates`: |
| 529 | |
| 530 | | Option | What g1t does | |
| 531 | | --- | --- | |
| 532 | | `registries` | The [private registries](#private-registries) entries can use. | |
| 533 | | `enable-beta-ecosystems` | `true` accepts any `package-ecosystem` name. | |
| 534 | | `multi-ecosystem-groups` | [Groups across ecosystems](#multi-ecosystem-groups). | |
| 535 | |
| 536 | ### `allow` |
| 537 | |
| 538 | A list of rules. With rules, a dependency is updated only when it matches |
| 539 | one. Without, direct dependencies are. |
| 540 | |
| 541 | | Key | Value | |
| 542 | | --- | --- | |
| 543 | | `dependency-name` | A name. `*` matches any run of characters, and case is ignored. | |
| 544 | | `dependency-type` | `direct`, `indirect`, `all`, `production` or `development`. For `cargo`, `gomod` and `pip`, `indirect` and `all` add the lockfile's other packages. | |
| 545 | | `update-types` | How far a matching dependency may move: a list of `version-update:semver-major`, `version-update:semver-minor` and `version-update:semver-patch`. | |
| 546 | |
| 547 | A rule needs `dependency-name` or `dependency-type`. |
| 548 | |
| 549 | ### `ignore` |
| 550 | |
| 551 | A list of rules. A dependency that matches both an `allow` rule and an |
| 552 | `ignore` rule is ignored. |
| 553 | |
| 554 | | Key | Value | |
| 555 | | --- | --- | |
| 556 | | `dependency-name` | A name. `*` matches any run of characters. Without it, the rule applies to every dependency. | |
| 557 | | `versions` | A requirement, or a list of them, in the ecosystem's own syntax. Versions they match are skipped. | |
| 558 | | `update-types` | Kinds of update to skip: `version-update:semver-major`, `version-update:semver-minor`, `version-update:semver-patch`. | |
| 559 | |
| 560 | A rule with only `dependency-name` skips the dependency entirely. A rule |
| 561 | needs at least one key. `versions` takes each ecosystem's own syntax: |
| 562 | |
| 563 | | Syntax | Examples | |
| 564 | | --- | --- | |
| 565 | | npm | `^1.0.0`, `1.x`, `>=19` | |
| 566 | | pip | `~=1.4`, `==1.*`, `!=1.5.0` | |
| 567 | | Bundler | `~> 2.0` | |
| 568 | | NuGet | `7.*` | |
| 569 | | Maven | `[1.4,)` | |
| 570 | |
| 571 | ### `cooldown` |
| 572 | |
| 573 | A release newer than its cooldown is passed over for the newest version |
| 574 | that is past it. Without `cooldown`, every version waits 3 days. |
| 575 | |
| 576 | | Key | Value | |
| 577 | | --- | --- | |
| 578 | | `default-days` | Days to wait for any update, 1 to 90. | |
| 579 | | `semver-major-days` | Days to wait for a major update, 1 to 90. | |
| 580 | | `semver-minor-days` | Days to wait for a minor update, 1 to 90. | |
| 581 | | `semver-patch-days` | Days to wait for a patch update, 0 to 90. | |
| 582 | | `include` | Dependency names (with `*`) the cooldown applies to, up to 150. | |
| 583 | | `exclude` | Dependency names (with `*`) it does not apply to, up to 150. `exclude` wins over `include`. | |
| 584 | |
| 585 | A registry that does not say when a version was published, such as a |
| 586 | private Cargo index without `pubtime` or most private Go proxies, has no |
| 587 | cooldown applied. Cooldown never applies to security updates. |
| 588 | |
| 589 | ### `groups` |
| 590 | |
| 591 | A mapping of group names to rules. A name starts and ends with a letter or |
| 592 | digit, and holds only letters, digits, `|`, `_` and `-`. |
| 593 | |
| 594 | | Key | Value | Default | |
| 595 | | --- | --- | --- | |
| 596 | | `applies-to` | `version-updates` or `security-updates`. | `version-updates` | |
| 597 | | `patterns` | Dependency names (with `*`) in the group. | Every dependency | |
| 598 | | `exclude-patterns` | Dependency names (with `*`) left out. | | |
| 599 | | `dependency-type` | `production` or `development`. | Both | |
| 600 | | `update-types` | A list of `major`, `minor` and `patch`. | All | |
| 601 | | `group-by` | `dependency-name`: one pull request per dependency, across all the entry's directories. Version updates only. | | |
| 602 | |
| 603 | A dependency joins the first group that takes it. Dependencies no group |
| 604 | takes open one pull request per dependency and directory. A group across |
| 605 | several directories opens one pull request. |
| 606 | |
| 607 | ### `versioning-strategy` |
| 608 | |
| 609 | | Value | What g1t does | |
| 610 | | --- | --- | |
| 611 | | `increase` | Raises the manifest's requirement, keeping its style: `^`, `~` or exact. | |
| 612 | | `auto` | The same as `increase`. | |
| 613 | | `increase-if-necessary` | Updates the lockfile within the requirement when it allows the new version, and raises the requirement when it does not. | |
| 614 | | `widen` | For npm, adds the new range: `^1.2.0 \|\| ^2.0.0`. | |
| 615 | | `lockfile-only` | Updates only lockfiles, and only to versions the requirement already allows. | |
| 616 | |
| 617 | For `gomod`, every strategy runs `go get` and then `go mod tidy`. Pins in |
| 618 | `requirements.txt` are rewritten. |
| 619 | |
| 620 | ### `commit-message` |
| 621 | |
| 622 | | Key | Value | |
| 623 | | --- | --- | |
| 624 | | `prefix` | Starts the title and commit message. At most 50 characters. | |
| 625 | | `prefix-development` | Used instead of `prefix` for an update that only touches development dependencies. At most 50 characters. | |
| 626 | | `include` | `scope` adds `(deps)`, or `(deps-dev)` for development dependencies, after the prefix. | |
| 627 | |
| 628 | How the prefix joins the title: |
| 629 | |
| 630 | - A prefix that ends with a letter, a digit, `)` or `]` is followed by a |
| 631 | colon and a space: `build: bump …`. |
| 632 | - A prefix that ends with a space is used as it is: `deps bump …`. |
| 633 | - Any other prefix is followed by a space. |
| 634 | - With `include: scope` and no prefix, the prefix is `chore`: |
| 635 | `chore(deps): bump …`. |
| 636 | |
| 637 | With a prefix, `Bump` becomes `bump`: |
| 638 | `build(deps): bump lodash from 4.17.20 to 4.17.21`. |
| 639 | |
| 640 | ### `pull-request-branch-name` |
| 641 | |
| 642 | | Key | Value | Default | |
| 643 | | --- | --- | --- | |
| 644 | | `prefix` | What every branch name starts with. At most 50 characters. | `g1t` | |
| 645 | | `separator` | `/`, `-` or `_`, between the parts of the name. | `/` | |
| 646 | | `max-length` | 20 to 244. A longer name is cut, and ends with a hash. | `100` | |
| 647 | | `word-separator` | Replaces `_` after the prefix: `-`, `_`, `/` or `.`. | | |
| 648 | | `branch-name-case` | `lowercase` or `uppercase`, after the prefix. | | |
| 649 | | `template` | The whole name, at most 200 characters, from the placeholders below. | | |
| 650 | |
| 651 | Template placeholders: `{prefix}`, `{package_manager}`, `{directory}`, |
| 652 | `{target_branch}`, `{dependency}`, `{version}`, `{group_name}` and |
| 653 | `{name}`. |
| 654 | |
| 655 | Default branch names: |
| 656 | |
| 657 | | Update | Branch | |
| 658 | | --- | --- | |
| 659 | | `lodash` in `/` | `g1t/npm_and_yarn/lodash-4.17.21` | |
| 660 | | `lodash` in `/web` | `g1t/npm_and_yarn/web/lodash-4.17.21` | |
| 661 | | The `lint` group | `g1t/npm_and_yarn/lint-<10-character hash>` | |
| 662 | |
| 663 | The package manager part is `npm_and_yarn` for npm, `cargo` for Cargo, |
| 664 | `go_modules` for Go and `pip` for pip. |
| 665 | |
| 666 | ### Private registries |
| 667 | |
| 668 | Name registries at the top of the file, under `registries`, and list the |
| 669 | ones each entry uses in its own `registries`. |
| 670 | |
| 671 | | Key | Value | |
| 672 | | --- | --- | |
| 673 | | `type` | The registry's type. Required. | |
| 674 | | `url` | The registry's address, over `https`. | |
| 675 | | `username`, `password` | Credentials for basic sign-in. | |
| 676 | | `token` | A token. | |
| 677 | | `key` | A key. | |
| 678 | | `replaces-base` | `true` to use this registry for every package, not only those it is scoped to. | |
| 679 | | `scope` | For `npm-registry`: an npm scope such as `@acme`, or a list of them. | |
| 680 | |
| 681 | The format's other keys (`organization`, `repo`, `auth-key`, |
| 682 | `public-key-fingerprint`, `registry`, `tenant-id`, `client-id`, |
| 683 | `jfrog-oidc-provider-name`, `identity-mapping-name`, `audience`, |
| 684 | `aws-region`, `account-id`, `role-name`, `domain` and `domain-owner`) are |
| 685 | read and checked. |
| 686 | |
| 687 | `type` is one of `cargo-registry`, `composer-repository`, |
| 688 | `docker-registry`, `git`, `goproxy-server`, `helm-registry`, |
| 689 | `hex-organization`, `hex-repository`, `maven-repository`, `npm-registry`, |
| 690 | `nuget-feed`, `pub-repository`, `python-index`, `rubygems-server` and |
| 691 | `terraform-registry`. g1t uses four of them, for version lookups and in |
| 692 | the update sandbox: |
| 693 | |
| 694 | | Type | Used for | |
| 695 | | --- | --- | |
| 696 | | `npm-registry` | With a `scope`, that scope's packages. With `replaces-base: true`, every package. | |
| 697 | | `cargo-registry` | Every crate, with `replaces-base: true`. | |
| 698 | | `goproxy-server` | Every module, with `replaces-base: true`. | |
| 699 | | `python-index` | Every package, with `replaces-base: true`. | |
| 700 | |
| 701 | A registry that signs in with OIDC is not used. |
| 702 | |
| 703 | Put credentials in [secrets](/guides/secrets-and-variables/) and name |
| 704 | them as `${{secrets.NAME}}`. g1t fills them from the repository's and the |
| 705 | workspace's secrets that are available to workflows. When a secret is |
| 706 | missing, that registry is not used, and the run says which secret it |
| 707 | needed. g1t never stores or shows the credentials; the Security page lists |
| 708 | each registry with the secrets it names. |
| 709 | |
| 710 | ### Multi-ecosystem groups |
| 711 | |
| 712 | `multi-ecosystem-groups` at the top of the file names groups, each with a |
| 713 | `schedule`. An entry joins one with `multi-ecosystem-group: <name>`, and |
| 714 | then needs `patterns` (`["*"]` for every dependency). The entry runs on the |
| 715 | group's schedule. Its updates still open one pull request per ecosystem, |
| 716 | not one for the whole group. |