From 70e11a07d6bca5d78d41226a80e59a433bcba507 Mon Sep 17 00:00:00 2001 From: Zack Koppert Date: Fri, 24 May 2024 23:56:09 -0700 Subject: [PATCH] docs: Add documentation for new configuration option: UPDATE_EXISTING Signed-off-by: Zack Koppert --- README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 3f305ba..f7f7bf1 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ [![Python package](https://github.com/github/evergreen/actions/workflows/python-ci.yml/badge.svg)](https://github.com/github/evergreen/actions/workflows/python-ci.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/github/evergreen/badge)](https://scorecard.dev/viewer/?uri=github.com/github/evergreen) -This is a GitHub Action that given an organization or specified repositories, opens an issue/PR dependabot is not enabled but could be. It also enables [automated security updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#managing-dependabot-security-updates-for-your-repositories) for the repository. +This is a GitHub Action that given an organization or specified repositories, opens an issue/PR dependabot is not enabled or there are more package ecosystems that could be. It also enables [automated security updates](https://docs.github.com/en/code-security/dependabot/dependabot-security-updates/configuring-dependabot-security-updates#managing-dependabot-security-updates-for-your-repositories) for the repository. This action was developed by the GitHub OSPO for our own use and developed in a way that we could open source it that it might be useful to you as well! If you want to know more about how we use it, reach out in an issue in this repository. @@ -29,6 +29,7 @@ All feedback regarding our GitHub Actions, as a whole, should be communicated th 1. Copy that example into your repository (from step 1) and into the proper directory for GitHub Actions: `.github/workflows/` directory with the file extension `.yml` (ie. `.github/workflows/evergreen.yml`) 1. Edit the values (`ORGANIZATION`, `REPOSITORY`, `EXEMPT_REPOS`, `TYPE`, `TITLE`, `BODY`) from the sample workflow with your information. If running on a whole organization then no repository is needed. If running the action on just one repository or a list of repositories, then no organization is needed. The type should be either `issue` or `pull` representing the action that you want taken after discovering a repository that should enable dependabot. 1. Optionally, edit the value (`CREATED_AFTER_DATE`) if you are setting up this action to run regularly and only want newly created repositories to be considered. Otherwise, if you want all specified repositories regardless of when they were created to be considered, then leave blank. +1. Optionally edit the value (`UPDATE_EXISTING`) if you want to update existing dependabot configuration files. If set to `true`, the action will update the existing dependabot configuration file with any package ecosystems that are detected but not configured yet. If set to `false`, the action will only create a new dependabot configuration file if there is not an existing one. The default value is `false`. 1. Also edit the value for `GH_ENTERPRISE_URL` if you are using a GitHub Server and not using github.com. For github.com users, don't put anything in here. 1. Update the value of `GH_TOKEN`. Do this by creating a [GitHub API token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic) with permissions to read the repository/organization and write issues or pull requests depending on what you put in for the `TYPE`. Additionally, you should set the `administration:write` permission on every repository in scope to successfully enable security updates. Then take the value of the API token you just created, and [create a repository secret](https://docs.github.com/en/actions/security-guides/encrypted-secrets) where the name of the secret is `GH_TOKEN` and the value of the secret the API token. Then finally update the workflow file to use that repository secret by changing `GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}` to `GH_TOKEN: ${{ secrets.GH_TOKEN }}`. The name of the secret can really be anything. It just needs to match between when you create the secret name and when you refer to it in the workflow file. 1. If you want the resulting issue with the output to appear in a different repository other than the one the workflow file runs in, update the line `token: ${{ secrets.GITHUB_TOKEN }}` with your own GitHub API token stored as a repository secret. This process is the same as described in the step above. More info on creating secrets can be found [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets). @@ -70,8 +71,9 @@ This action can be configured to authenticate with GitHub App Installation or Pe | `BODY` | False | **Pull Request:** "Dependabot could be enabled for this repository. Please enable it by merging this pull request so that we can keep our dependencies up to date and secure." **Issue:** "Please update the repository to include a Dependabot configuration file. This will ensure our dependencies remain updated and secure.Follow the guidelines in [creating Dependabot configuration files](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file) to set it up properly.Here's an example of the code:" | The body of the issue or pull request that will be created if dependabot could be enabled. | | `COMMIT_MESSAGE` | False | "Create dependabot.yaml" | The commit message for the pull request that will be created if dependabot could be enabled. | | `CREATED_AFTER_DATE` | False | none | If a value is set, this action will only consider repositories created on or after this date for dependabot enablement. This is useful if you want to only consider newly created repositories. If I set up this action to run weekly and I only want to scan for repos created in the last week that need dependabot enabled, then I would set `CREATED_AFTER_DATE` to 7 days ago. That way only repositories created after 7 days ago will be considered for dependabot enablement. If not set or set to nothing, all repositories will be scanned and a duplicate issue/pull request may occur. Ex: 2023-12-31 for Dec. 31st 2023 | +| `UPDATE_EXISTING` | False | False | If set to true, this action will update the existing dependabot configuration file with any package ecosystems that are detected but not configured yet. If set to false, the action will only create a new dependabot configuration file if there is not an existing one. | | `PROJECT_ID` | False | "" | If set, this will assign the issue or pull request to the project with the given ID. ( The project ID on GitHub can be located by navigating to the respective project and observing the URL's end.) **The `ORGANIZATION` variable is required** | -| `DRY_RUN` | False | false | If set to true, this action will not create any issues or pull requests. It will only log the repositories that could have dependabot enabled. This is useful for testing. | +| `DRY_RUN` | False | False | If set to true, this action will not create any issues or pull requests. It will only log the repositories that could have dependabot enabled. This is useful for testing. | | `GROUP_DEPENDENCIES` | False | false | If set to true, dependabot configuration will group dependencies updates based on [dependency type](https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file#groups) (production or development, where supported) | | `FILTER_VISIBILITY` | False | "public,private,internal" | Use this flag to filter repositories in scope by their visibility (`public`, `private`, `internal`). By default all repository are targeted. ex: to ignore public repositories set this value to `private,internal`. | | `BATCH_SIZE` | False | None | Set this to define the maximum amount of eligible repositories for every run. This is useful if you are targeting large organizations and you don't want to flood repositories with pull requests / issues. ex: if you want to target 20 repositories per time, set this to 20. |