Dependabot + PR Workflow Guide for WordPress+JavaScript and Next.js Repositories

This document provides comprehensive guidelines for managing dependencies and reviewing Dependabot-generated PRs using GitHub workflows. It covers the configurations and steps needed to ensure a consistent, SOC-2-compliant approach to dependency management across different project types.

Standard Dependabot Configuration

All repositories follow a consistent Dependabot configuration specified in .github/dependabot.yml:


version: 2
updates:
  - package-ecosystem: 'npm'
    directory: '/'
    schedule:
      interval: 'weekly'
      day: 'friday'
      time: '06:00'
      timezone: 'America/Chicago'
    versioning-strategy: 'increase-if-necessary'
    reviewers:
      - 'integritystl/react-devs'
      # - 'integritystl/wordpress-devs' # for WordPress+JavaScript repositories
      # - 'integritystl/python-devs' # for python repositories
    groups:
      major-updates:
        update-types: ['major']
      minor-patch-updates:
        update-types: ['minor', 'patch']
    allow:
      - dependency-type: "all"

Key Configuration Elements:

Package Ecosystem: npm (JavaScript dependencies managed by npm/yarn).
Directory: Root directory ('/').
Schedule: Weekly on Fridays at 06:00 AM (America/Chicago).
Versioning Strategy: increase-if-necessary.
Reviewers: Dependabot PRs are reviewed by bpkennedy and jetboh (for example).
Update Groups: Major updates and minor/patch updates, as described in the configuration.

IMPORTANT: Dependabot uses a separate set of repository secrets. If your project relies on Github repository secrets during the Github Actions build, then you’ll need to duplicate them in Repo Settings > Secrets and variables > Dependabot. This does not apply for organization secrets which are available by default to Dependabot.

WordPress+JavaScript Repository Workflow

For WordPress+JavaScript repositories, the PR Composer Check workflow ensures Dependabot PRs pass essential checks for Composer (PHP) and Node.js dependencies.

Example Workflow File (.github/workflows/pr-check.yml):


name: Basic PR Validation
on:
  pull_request:
    branches:
      - develop
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      # example using dependabot repository secrets
      ACF_USERNAME: ${{ secrets.ACF_LICENSE_KEY }}
      WPMUDEV_USERNAME: ${{ secrets.WPMU_DEV_API_KEY }}
      WPMIGRATE_USERNAME: ${{ secrets.DELICIOUS_BRAINS_USERNAME }}
      WPMIGRATE_PASSWORD: ${{ secrets.DELICIOUS_BRAINS_PASSWORD }}
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Set Composer authentication
        run: |
          composer config --global --auth http-basic.connect.advancedcustomfields.com $ACF_USERNAME https://operationshower.org  # example
          composer config --global --auth http-basic.wpmudev.com $WPMUDEV_USERNAME "" # example
          composer config --global --auth http-basic.composer.deliciousbrains.com $WPMIGRATE_USERNAME $WPMIGRATE_PASSWORD # example
 
      - name: Install Composer dependencies
        run: composer install --no-interaction --prefer-dist --optimize-autoloader
 
      - name: Verify Composer installation
        run: composer show
 
      - name: Set up Node.js 18
        uses: actions/setup-node@v4
        with:
          node-version: '18'
 
      - name: Install Node.js dependencies
        run: npm ci
 
      - name: Build assets
        run: npm run build

Next.js Repository Workflow

Next.js repositories use a workflow to validate Node.js dependencies, ensuring Dependabot PRs pass linting and build steps before review.

Example Workflow File (.github/workflows/pr-check.yml):


name: Basic PR Validation
on:
  pull_request:
 
jobs:
  build:
    runs-on: ubuntu-latest
 
    env:
      SOME_SECRET: ${{ secrets.SOME_SECRET }}
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Set up Node.js 18
        uses: actions/setup-node@v4
        with:
          node-version: '18'
 
      - name: Install dependencies
        run: yarn install --immutable --immutable-cache
 
      - name: Run lint
        run: yarn lint
 
      - name: Run build
        run: yarn build

How to Perform Dependabot PR Reviews

Notification: When Dependabot creates a PR, reviewers are notified.
Check Workflow Status: Ensure the GH Actions build completes successfully. If it is a minor or patch update, then the PR can be merged directly. Otherwise proceed to the next step.
Manual Review Steps:

Checkout the Dependabot PR branch.

Clean your Local Environment:


  # For yarn
  rm -rf node_modules
  yarn cache clean
  yarn install --immutable --immutable-cache
 
  # For npm
  rm -rf node_modules
  npm cache clean --force
  npm ci
 
  # For composer - if applicable
  composer clear-cache
  composer install --no-interaction --prefer-dist --optimize-autoloader
  composer validate

Run Lint and Build Steps: Confirm these pass without errors.
Remediate Issues if Needed: Attempt to fix in place. If too complex, defer the update or modify the PR scope.

Merging PRs:

Minor Updates: Merge directly after checks pass.
Major Updates: Perform additional testing, possibly in a staging environment.

Post-Merge Validation: Validate functionality in staging if there were significant changes.

Remediation Tips

If the package having issues is a sub-dependency, you can inspect the package using it with:
```
# For yarn
yarn why <package-name>
 
# For npm
npm ls <package-name>
```
Dependabot could be described as a smart tool trying to keep your packages updated/upgraded/up-to-date. If you find overwhelming messages/PRs from it, consider manually upgrading to the latest packages yourself and handling breakages at that time.


  # For yarn
  yarn upgrade --latest # Upgrades ALL packages to their latest versions
  yarn upgrade <package-name>@latest # Upgrades a specific package to its latest version
 
  # For npm
  npm install <package-name>@latest # Upgrades a specific package to its latest version

To check for your packages with security vulnerabilities (for which Dependabot would try to update/upgrade you to fix):


  # For yarn
  yarn audit
 
  # For npm
  npm audit

To attempt to automatically update/upgrade packages with security vulnerabilities:


  # For yarn
  yarn global add yarn-audit-fix # Install a helper package
  yarn-audit-fix # Attempt to fix security vulnerabilities
 
  # For npm
  npm audit fix # Attempt to fix security vulnerabilities

How to prevent particular packages from upgrading

Sometimes you may need to prevent specific packages from being upgraded, especially when:

The upgrade would require extensive refactoring
A package version is known to have issues
The project depends on specific version functionality
The cost of upgrading exceeds the client’s budget

You can achieve this by adding an ignore configuration to your dependabot.yml file. The ignore section supports various ways to prevent updates:


version: 2
updates:
  - package-ecosystem: 'npm'
    directory: '/'
    # ... other existing configuration ...
    ignore:
      # Block all updates to a package (ex. "pinning" allow 4.3.3 and nothing else)
      - dependency-name: "completely-frozen-package"
 
      # Block only major version updates (ex. allow any 4.x.x but not any >=5.x.x)
      - dependency-name: "major-sensitive-package"
        update-types: ["version-update:semver-major"]
 
      # Block both major and minor updates (ex. only allow patches like any 4.2.x but not any >=4.3.x)
      - dependency-name: "patch-only-package"
        update-types: ["version-update:semver-major", "version-update:semver-minor"]

How to publish our npm packages after Dependabot PRs

If your project is a library or package that is published to npm, you will want to ensure the dependabot PR’s that are merged are also published to npm with the version number updated. A simple rule of thumb is:

If the PR is a minor or a patch group update (as per the dependabot configuration), then you can incrememnt your package’s patch version and publish it to npm. (ex. 1.2.3 -> 1.2.4).
If the PR is a major group update, then you can increment your package’s minor version and publish it to npm. (ex. 1.2.3 -> 1.3.0).
If the changes required you to change your package’s API, causing a breaking change for consumers, then you can increment your package’s major version and publish it to npm. (ex. 1.2.3 -> 2.0.0).