From 6609b2b8582a775b328f3784307a0860244920f0 Mon Sep 17 00:00:00 2001 From: Rhys Koedijk Date: Tue, 22 Oct 2024 15:18:47 +1300 Subject: [PATCH] Update documentation --- README.md | 18 ++++++++++-------- docs/migrations/v1-to-v2.md | 20 +++++++++++--------- extension/tasks/dependabotV2/index.ts | 2 +- 3 files changed, 22 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 3138832a..dcf971b9 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,11 @@ In this repository you'll find: - [Configuring experiments](#configuring-experiments) - [Configuring assignees and reviewers](#configuring-assignees-and-reviewers) - [Unsupported features and configurations](#unsupported-features-and-configurations) - * [Extension Task](#extension-task) + * [Dependabot Task](#dependabot-task) + [dependabot@V2](#dependabotv2) + [dependabot@V1](#dependabotv1) - * [Updater Docker image](#updater-docker-image) - * [Server](#server) + * [Dependabot Updater Docker image](#dependabot-updater-docker-image) + * [Dependabot Server](#dependabot-server) - [Migration Guide](#migration-guide) - [Contributing](#contributing) * [Reporting issues and feature requests](#reporting-issues-and-feature-requests) @@ -154,7 +154,7 @@ Experiments vary depending on the package ecyosystem used; They can be enabled u > Dependabot experinment names are not [publicly] documented. For convenience, some known experiments are listed below; However, **be aware that this may be out-of-date at the time of reading.**
-List of known experiments from dependabot-core@0.280.0 +List of known experiments from dependabot-core@0.281.0 |Package Ecosystem|Experiment Name|Value Type|More Information| |--|--|--|--| @@ -166,6 +166,7 @@ Experiments vary depending on the package ecyosystem used; They can be enabled u | All | dependency_change_validation | true/false | https://github.com/dependabot/dependabot-core/pull/9888 | | All | add_deprecation_warn_to_pr_message | true/false | https://github.com/dependabot/dependabot-core/pull/10421 | | All | threaded_metadata | true/false | https://github.com/dependabot/dependabot-core/pull/9485 | +| All | lead_security_dependency | true/false | https://github.com/dependabot/dependabot-core/pull/10727 | | Bundler | bundler_v1_unsupported_error | true/false | https://github.com/dependabot/dependabot-core/pull/10601 | | Composer | composer_v1_deprecation_warning | true/false | https://github.com/dependabot/dependabot-core/pull/10716 | | Composer | composer_v1_unsupported_error | true/false | https://github.com/dependabot/dependabot-core/pull/10716 | @@ -194,12 +195,13 @@ Reviewers can be any of the following values: - Team name ## Unsupported features and configurations -We aim to support all [official configuration options](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file), but there are some limitations for: +We aim to support all [official configuration options](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file), but there are some limitations: -### Extension Task +### Dependabot Task #### `dependabot@V2` - [`schedule`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#scheduleinterval) is ignored, use [pipeline scheduled triggers](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/scheduled-triggers?view=azure-devops&tabs=yaml#scheduled-triggers) instead. +- [`securityAdvisoriesFile`](#configuring-security-advisories-and-known-vulnerabilities) task input is not yet supported. #### `dependabot@V1` - [`schedule`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#scheduleinterval) is ignored, use [pipeline scheduled triggers](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/scheduled-triggers?view=azure-devops&tabs=yaml#scheduled-triggers) instead. @@ -209,11 +211,11 @@ We aim to support all [official configuration options](https://docs.github.com/e - [`assignees`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#assignees) and [`reviewers`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#reviewers) must be a list of user guids or email addresses; group/team names are not supported. - Private feed/registry authentication may not work with all package ecyosystems. Support is _slightly_ improved when task input `useUpdateScriptVNext: true` is set, but not still not fully supported. See [problems with authentication](https://github.com/tinglesoftware/dependabot-azure-devops/discussions/1317) for more. -### Updater Docker image +### Dependabot Updater Docker Image - `DEPENDABOT_ASSIGNEES` and `DEPENDABOT_REVIEWERS` must be a list of user guids; email addresses and group/team names are not supported. - Private feed/registry authentication may not work with all package ecyosystems. See [problems with authentication](https://github.com/tinglesoftware/dependabot-azure-devops/discussions/1317) for more. -### Server +### Dependabot Server - [`directories`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#directories) are not supported. - [`groups`](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) are not supported. diff --git a/docs/migrations/v1-to-v2.md b/docs/migrations/v1-to-v2.md index 8c7a7e91..caf24491 100644 --- a/docs/migrations/v1-to-v2.md +++ b/docs/migrations/v1-to-v2.md @@ -20,6 +20,11 @@ The task now uses [Dependabot CLI](https://github.com/dependabot/cli) to perform > [!WARNING] > **It is strongly recommended that you complete (or abandon) all active Depedabot pull requests created in V1 before migrating to V2.** Due to changes in Dependabot dependency metadata, V2 pull requests are not compatible with V1 (and vice versa). Migrating to V2 before completing existing pull requests will lead to duplication of pull requests. +### Security-only updates +Security-only updates (i.e. `open-pull-requests-limit: 0`) incur a performance overhead due to [limitations in Dependabot CLI (#360)](https://github.com/dependabot/cli/issues/360). To work around this, vulnerable dependencies will first be discovered using an "ignore everything" update job; After which, security advisories for the discovered dependencies will be checked against the [GitHub Advisory Database](https://github.com/advisories) before finally performing the requested security-only update job. Because of these required extra steps, the task will take longer to complete than usual. + +Currently the [`securityAdvisoriesFile`](../../README.md#configuring-security-advisories-and-known-vulnerabilities) task input is not supported, but is expected to be supported before GA. + ### New pipeline agent requirements; "Go" must be installed Dependabot CLI requires [Go](https://go.dev/doc/install) (1.22+) and [Docker](https://docs.docker.com/engine/install/) (with Linux containers). If you use [Microsoft-hosted agents](https://learn.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops&tabs=yaml#software), we recommend using the [ubuntu-latest](https://github.com/actions/runner-images/blob/main/images/ubuntu/Ubuntu2404-Readme.md) image, which meets all task requirements. @@ -66,13 +71,10 @@ The following environment variables have been removed entirely; the feature is n ## Todo before general availability Before removing the preview flag from V2 `task.json`, we need to: - - [x] Open an issue in Dependabot-CLI, enquire how security-advisories are expected to be provided **before** knowing the list of dependencies. (https://github.com/dependabot/cli/issues/360) - - [ ] Convert GitHub security advisory client in `vulnerabilities.rb` to TypeScript code - - [ ] Implement `security-advisories` config once the answer the above is known - - [x] Review `task.json`, add documentation for new V2 inputs - - [x] Update `\docs\extension.md` with V2 docs - - [x] Update `\extension\README.MD` with V2 docs - - [x] Update `\README.MD` with V2 docs - - [ ] Do a general code tidy-up pass (check all "TODO" comments) + - [ ] Fix PR description text "@���" encoding issues + - [ ] Add "superseded by X" close reason when PR is closed during a PR update + - [ ] Add documentation for required permissions and PAT scopes + - [ ] Add support for 'securityAdvisoriesFile' task input - [ ] Add unit tests for V2 utils scripts - - [ ] Investigate https://zod.dev/ \ No newline at end of file + - [ ] General code tidy-up (check all "TODO" comments) + - [ ] Investigate https://zod.dev/ diff --git a/extension/tasks/dependabotV2/index.ts b/extension/tasks/dependabotV2/index.ts index 9aa978e2..2ddea286 100644 --- a/extension/tasks/dependabotV2/index.ts +++ b/extension/tasks/dependabotV2/index.ts @@ -38,7 +38,7 @@ async function run() { // TODO: If and when Dependabot supports a better way to do security-only updates, remove this. if (dependabotConfig.updates?.some((u) => u['open-pull-requests-limit'] === 0)) { warning( - 'Security-only updates have a performance overhead due to the limitations of Dependabot CLI. For more info, see: https://github.com/tinglesoftware/dependabot-azure-devops/blob/main/docs/migrations/v1-to-v2.md#security-only-updates', + 'Security-only updates incur a performance overhead due to the limitations of Dependabot CLI. For more info, see: https://github.com/tinglesoftware/dependabot-azure-devops/blob/main/docs/migrations/v1-to-v2.md#security-only-updates', ); }