Dependabot ‐ Dependency Pull Request Procedure
NIST staff configure the OSCAL project's repositories to the best extent possible to use Dependabot to automatically update dependencies.
GitHub allows Dependabot configuration in two places: in the repo's settings interface for repository administrators or the dependabot.yml file in the relevant repo's .github directory. Review this information to understand how or when Dependabot updates are scheduled or which ones are silenced, which target branch is chosen, etc.
NOTE: As a NIST OSCAL Team developer, you may be responsible for one or more of the core OSCAL repositories, not only github.com/usnistgov/OSCAL. The URLs and repository-specific information in the procedure checklist below is given as an example.
- Visit the pull requests for the repository, and filter on the
dependenciestag used by Dependabot for its automated PRs. It is recommended, but not required, to also sort by the oldest PRs created. - Before you select a PR for review, select your GitHub account as the assignee so team members can move onto other PRs without reviews that have not yet been merged.
- Ensure the PR is targeting the correct branch. In most cases, the target branch should be
developor the "non-stable" branch for the repository in question. (See additional guidance in the appendix regarding high-priority security updates). - If the target branch is active, make sure the PR is not targeting an older revision of that branch (e.g. it does not have a merge conflict warning or the GitHub web interface does not have an "update branch" button for the PR). If it is targeting an older version, you can update it by writing the following message in a comment window:
@dependabot rebase- see this example from the usnistgov/OSCAL repo. - Review the changes between the current version and the new updated version of the dependency in the commits or release notes provided by the Dependabot PR message. If you have concerns, make a comment on the PR and ask team members for assistance. (NOTE: for some projects, there will be no commit summary and/or release notes, such as the Saxon XSLT processor, which does not rely primarily on GitHub, instead it uses its own website for release notes. It is recommended, but not required, to make a best effort attempt to find the official release notes and review code changes and/or release notes for changes with potential impact. Again, ask the team for assistance.
- Ensure that all of the relevant continuous integration workflows on the PR pass and have a green checkmark.
- For Dockerfile based dependencies, checkout the branch locally and attempt to build the container and run the
validate-metaschema.shand/or other relevant utility scripts in thebuild/ci-cddirectory. If unfamiliar, ask team members or the technical director for assistance. - For GitHub Actions dependency updates, ensure all workflows that use that workflow pass.
- For Hugo, Javascript (Node-based), usnistgov/hugo-uswds, and website-related dependencies (for repositories with website-related content), ensure the website's generate and publication workflows pass.
- For Saxon and Java-based dependencies for Java and XSLT-based tooling for schema generation, ensure the Metaschema artifact and/or model documentation generation workflows work as intended.
- Finally, if you have review the PR and found no potential risks and all GitHub Actions workflows pass, you can approve the PR and merge it into the target branch.
As of July 2023, changing the target branch in the web interface for Dependabot PRs, for updates before and after requesting a rebase for high-impact security fixes, is ignored. For more details, see the issue summarized in the comments of thedependabot/dependabot-core#2146, is ignored. It will always target main or the default mainish branch.
The current solution is to rebase locally and forcefully rewrite the PR or have the developer create their own PRs without automation, link to the opened PR for historical tracking and close the Dependabot-generated PR. See the bug "in-action" in the usnistgov/OSCAL#1670 issue.