Skip to content

Dependency Management Strategy

Overview

This project follows a Zero Pin + Lockfile + Automated Updates strategy:

  • Zero Pins: Gemfile has no version constraints → allows flexibility
  • Lockfile: Gemfile.lock commits exact versions → reproducibility
  • Automated Updates: Weekly workflow keeps dependencies current
  • CI Validation: Tests catch breaking changes before merge

Automated Update Workflow

Schedule

  • Primary: Weekly on Monday at 9:00 AM UTC
  • Secondary: Manual trigger via GitHub Actions UI

Process

  1. Workflow runs bundle update
  2. Creates PR with updated Gemfile.lock
  3. CI validates compatibility:
  4. Build succeeds
  5. Tests pass
  6. Docker container works
  7. Review and merge if green ✅
  8. Investigate if red ❌

Manual Dependency Management

Update All Dependencies

bundle update
git add Gemfile.lock
git commit -m "chore(deps): update all Ruby gems"
git push origin main

Update Specific Gem

bundle update github-pages
git add Gemfile.lock
git commit -m "chore(deps): update github-pages"
git push origin main

Conservative Update (Patch Only)

bundle update --patch
git add Gemfile.lock
git commit -m "chore(deps): patch updates for security fixes"
git push origin main

Check for Outdated Gems

bundle outdated

When Updates Fail

If automated PR shows CI failures:

1. Review the Error

gh pr checkout <PR-number>
docker-compose up  # Test locally

2. Identify Breaking Changes

Check gem changelogs:

bundle outdated | grep "jekyll\|github-pages"

3. Options to Resolve

A. Pin the Problematic Gem (temporary):

# Gemfile
gem "problematic-gem", "~> 1.2.0"  # Pin to working version

B. Fix Code Compatibility:

# Update code to work with new version
# Then commit fixes to the PR branch

C. Wait and Skip:

# Close the automated PR
# Wait for next version or upstream fix

Best Practices

✅ DO

  • Merge automated PRs promptly when CI passes
  • Review changelog for major version bumps
  • Test locally before merging complex updates
  • Keep Gemfile.lock committed to git
  • Monitor GitHub security alerts

❌ DON'T

  • Pin versions in Gemfile unless absolutely necessary
  • Ignore failing update PRs (they indicate problems)
  • Delete Gemfile.lock from git (breaks reproducibility)
  • Skip CI validation (catches issues early)

Troubleshooting

Issue: Update PR Created But No Changes

Cause: Already on latest versions
Action: Close PR, no action needed

Issue: Update Fails to Create PR

Cause: Workflow error or permissions issue
Action: Check workflow run logs, verify GitHub token permissions

Issue: Docker Build Fails After Update

Cause: Incompatible gem versions
Action:

  1. Check docker/Dockerfile for version constraints
  2. Verify Bundler version compatibility
  3. Review gem compilation errors (native extensions)

Issue: Tests Pass Locally But Fail in CI

Cause: Environment differences (Ruby version, OS)
Action:

  1. Match Ruby version with CI (ruby-version in workflow)
  2. Check platform-specific gems in Gemfile.lock
  3. Rebuild Docker container: docker-compose up --build

Monitoring

GitHub Actions

  • Check Actions tab weekly
  • Review automated PR when created
  • Monitor CI status on open PRs

Security Alerts

  • Enable Dependabot security alerts
  • Review GitHub Security tab regularly
  • Apply security patches promptly

Gem Compatibility

  • Monitor github-pages gem versions (pins Jekyll)
  • Check Jekyll changelog for breaking changes
  • Test theme features after major updates

Further Reading