Skip to content

Improve Patcher documentation: clarify use cases and add simplified GitHub Actions guide #2723

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 13 commits into
base: main
Choose a base branch
from
Open

Improve Patcher documentation: clarify use cases and add simplified GitHub Actions guide #2723

wants to merge 13 commits into from

Conversation

devin-ai-integration[bot]
Copy link

Improve Patcher documentation: clarify use cases and add simplified GitHub Actions guide

Summary

This PR addresses the confusion around Patcher's two primary use cases by creating clearer documentation paths:

  1. New guide: "GitHub Actions for Continuous Updates" - A simplified workflow that scans the entire repository and creates PRs for all outdated dependencies. Ideal for teams who want to keep their codebase current without environment-specific promotion.

  2. Updated existing guide: Enhanced "Setting up Promotion Workflows" to clearly explain it's for teams needing dev → stage → prod promotion with environment-specific validation.

Key changes:

  • Created /docs/2.0/docs/patcher/guides/github-actions-continuous-updates.md (171 lines) with a simplified GitHub Actions workflow
  • Updated promotion workflows guide to clarify when to use each approach
  • Added the new guide to sidebar navigation as the first option in Guides section
  • Added cross-references between the two guides to help users choose the right approach

The new workflow removes the include_dirs filtering and environment-specific logic from the promotion workflow examples, making it suitable for scanning entire repositories.

Review & Testing Checklist for Human

  • Verify docs site builds and renders correctly - Test that the new markdown file renders properly and doesn't break the documentation site
  • Validate GitHub Actions YAML syntax - Check that the workflow in the new guide has correct YAML syntax and valid patcher-action parameters
  • Test all internal links - Confirm cross-references between the new continuous updates guide and promotion workflows guide work correctly
  • Review user experience flow - Ensure the distinction between the two approaches is clear and users can easily choose the right path
  • Check sidebar navigation - Verify the new guide appears correctly in the sidebar and doesn't break navigation

Notes

  • The new workflow is based on the existing promotion workflow examples but simplified to remove environment-specific scanning
  • Cross-references were added in both directions to help users navigate between the two approaches
  • The new guide was positioned first in the Guides section since it's the simpler use case

Link to Devin run: https://app.devin.ai/sessions/fc64367622e64e1d8f29fddec6441a64
Requested by: Josh Padnick (@josh-padnick)

@devin-ai-integration @josh-padnick
Improve Patcher documentation: clarify use cases and add simplified G…
12b5898 
…itHub Actions guide

- Add new 'GitHub Actions for Continuous Updates' guide for teams wanting to keep entire codebase current
- Update promotion workflows guide to clarify it's for environment-specific promotion (dev → stage → prod)
- Add clear distinction between two primary Patcher use cases: upgrading out-of-date code vs maintaining current code
- Update sidebar navigation to include new guide as first option in Guides section
- Add cross-references between the two approaches to help users choose the right workflow

Co-Authored-By: Josh Padnick <[email protected]>
@devin-ai-integration Devin.ai Integration
Copy link
Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@vercel Vercel
Copy link

vercel bot commented Aug 29, 2025 •
edited
Loading

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Preview Comments Updated (UTC)
docs Error Error Sep 4, 2025 1:49am

@coderabbitai coderabbitai
Copy link
Contributor

coderabbitai bot commented Aug 29, 2025

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

  • Review comments: Directly reply to a review comment made by CodeRabbit. Example:
    • I pushed a fix in commit <commit_id>, please review it.
    • Open a follow-up GitHub issue for this discussion.
  • Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
  • PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
    • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
    • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Join our Discord community for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

  • Add @coderabbitai ignore or @coderabbit ignore anywhere in the PR description to prevent this PR from being reviewed.
  • Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
  • Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (.coderabbit.yaml)

  • You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
  • Please see the configuration documentation for more information.
  • If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Status, Documentation and Community

  • Visit our Status Page to check the current availability of CodeRabbit.
  • Visit our Documentation for detailed information on how to use CodeRabbit.
  • Join our Discord Community to get help, request features, and share feedback.
  • Follow us on X/Twitter for updates and announcements.

@josh-padnick josh-padnick mentioned this pull request Aug 30, 2025
Open
5 tasks
@devin-ai-integration @josh-padnick
Fix spellcheck error and add GitHub fine-grained token setup document…
5f7bb89 
…ation

- Fix typo 'leasat' -> 'least' in accountfactory drift remediation guide
- Add comprehensive GitHub Enterprise fine-grained token setup section to Patcher continuous updates guide
- Include step-by-step instructions for token creation with required permissions
- Focus on organization's patcher-cli and terrapatch-cli repositories only

Co-Authored-By: Josh Padnick <[email protected]>
devin-ai-integration bot and others added 2 commits September 2, 2025 16:52
@devin-ai-integration @josh-padnick
Add patcher-action v2 to v3 migration documentation
b4b5fe8 
- Document key breaking changes: token consolidation, parameter renames
- Add before/after workflow examples for easy migration
- Include custom organization setup instructions for v3
- Update existing workflow examples to use v3 syntax
- Provide migration checklist for systematic upgrade process

Co-Authored-By: Josh Padnick <[email protected]>
@devin-ai-integration
Merge branch 'devin/1756506141-improve-patcher-docs' of https://git-m…
59d533b 
…anager.devin.ai/proxy/github.com/gruntwork-io/docs into devin/1756506141-improve-patcher-docs
@devin-ai-integration @josh-padnick
docs(patcher): align ongoing-updates guide with patcher-action v3 cus…
76347b1 
…tom-org inputs/outputs and workflow setup

Co-Authored-By: Josh Padnick <[email protected]>
@devin-ai-integration Devin.ai Integration
Copy link
Author

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.

2 similar comments
@devin-ai-integration Devin.ai Integration
Copy link
Author

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.

@devin-ai-integration Devin.ai Integration
Copy link
Author

Devin is archived and cannot be woken up. Please unarchive Devin if you want to continue using it.

@devin-ai-integration @josh-padnick
docs(patcher): clarify step-by-step setup and authentication for GitH…
8c6bad7 
…ub Action ongoing updates

Co-Authored-By: Josh Padnick <[email protected]>
yhakbar
yhakbar requested changes Sep 3, 2025
View reviewed changes
docs/2.0/docs/patcher/concepts/index.md

Manually identifying updates and assessing whether they can be safely applied can consume significant engineering time for each module dependency. Patcher eliminates this inefficiency by streamlining the update process.

You can use Gruntwork Patcher to manage dependencies on the Gruntwork IaC Library, which includes patches for recent breaking changes to Gruntwork modules. Patcher also supports updating dependencies for your own modules or open-source projects, using semantic versioning to identify safe updates and highlight those that need manual review.
Patcher supports keeping any set of OpenTofu/Terraform modules up to date, whether they be your inhouse modules, third-party open source modules, or modules from the [Gruntwork IaC Library](library/concepts/overview).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Patcher supports keeping any set of OpenTofu/Terraform modules up to date, whether they be your inhouse modules, third-party open source modules, or modules from the [Gruntwork IaC Library](library/concepts/overview).
Patcher supports keeping any set of OpenTofu/Terraform modules up to date, whether they be your inhouse modules, third-party open source modules, or modules from the [Gruntwork IaC Library](library/concepts/overview).

docs/2.0/docs/patcher/concepts/index.md
You can use Gruntwork Patcher to manage dependencies on the Gruntwork IaC Library, which includes patches for recent breaking changes to Gruntwork modules. Patcher also supports updating dependencies for your own modules or open-source projects, using semantic versioning to identify safe updates and highlight those that need manual review.
Patcher supports keeping any set of OpenTofu/Terraform modules up to date, whether they be your inhouse modules, third-party open source modules, or modules from the [Gruntwork IaC Library](library/concepts/overview).

Patcher specializes in keeping infrastructure code up to date and currently supports automatic udpates for:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Patcher specializes in keeping infrastructure code up to date and currently supports automatic udpates for:
Patcher specializes in keeping infrastructure code up to date and currently supports automatic updates for:

docs/2.0/docs/patcher/concepts/index.md

## Two update modes

When most teams think about updating their infrastructure mode, there are two core use cases they look to solve:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When most teams think about updating their infrastructure mode, there are two core use cases they look to solve:
When most teams think about updating their infrastructure code, there are two core use cases they look to solve:

docs/2.0/docs/patcher/concepts/index.md

Patcher can help with both of these use cases.

For legacy upgrades, the Patcher CLI offers an [interactive mode[(guides/update)] where you can browse all modules in the current working directory and below, request available updates, and upgrade modules one at a time. We've found this approach works well with a modest set of updates, however for significantly out of date repos or files or a large number of files, you may wish to consider alternative approaches.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For legacy upgrades, the Patcher CLI offers an [interactive mode[(guides/update)] where you can browse all modules in the current working directory and below, request available updates, and upgrade modules one at a time. We've found this approach works well with a modest set of updates, however for significantly out of date repos or files or a large number of files, you may wish to consider alternative approaches.
For legacy upgrades, the Patcher CLI offers an [interactive mode[(guides/update)] where you can browse all modules in the current working directory and below, browse available updates, and upgrade modules one at a time. We've found this approach works well with a modest set of updates, however for significantly out of date repos or files or a large number of files, you may wish to consider alternative approaches.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are those alternative approaches? Should we cut this?

docs/2.0/docs/patcher/concepts/index.md

Gruntwork Patcher provides a clear, README-driven workflow for breaking changes without available patches. When Patcher detects breaking changes, it updates the relevant dependency to the version containing those changes and generates a README file in the folder with the updated file. This README outlines the release notes and details the breaking changes. Users must review the README, address any necessary actions, and remove the file before rerunning Patcher.
For breaking changes, Patcher offers a systematic approach to doing code transformations -- we call these "patches" -- so that module consumers can automatically apply breaking changes to their modules. Or if Patcher detects a breaking change but a patch does not exist, Patcher updates the relevant module to the next breaking change and generates a README file in the folder with the updated file that outlines the release notes and details the breaking changes. Users review the README, address any necessary actions, and remove the file before rerunning Patcher.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
For breaking changes, Patcher offers a systematic approach to doing code transformations -- we call these "patches" -- so that module consumers can automatically apply breaking changes to their modules. Or if Patcher detects a breaking change but a patch does not exist, Patcher updates the relevant module to the next breaking change and generates a README file in the folder with the updated file that outlines the release notes and details the breaking changes. Users review the README, address any necessary actions, and remove the file before rerunning Patcher.
For breaking changes, Patcher offers a systematic approach to doing code transformations -- we call these "patches" -- so that module consumers can automatically apply breaking changes to their modules. Or if Patcher detects a breaking change but a patch does not exist, Patcher updates the relevant module to the next breaking change and generates a README file in the folder with the updated file that outlines the release notes and details the breaking changes. Users review the README, address any necessary actions, and remove the file before re-running Patcher.

docs/2.0/docs/patcher/guides/ongoing-updates.md
### Step-by-step setup for GitHub.com users

#### 1. Create a GitHub token
- Create a token that can read patcher-cli and terrapatch-cli releases in your org (see [GitHub Personal Access Token Setup](#github-personal-access-token-setup) below).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- Create a token that can read patcher-cli and terrapatch-cli releases in your org (see [GitHub Personal Access Token Setup](#github-personal-access-token-setup) below).
- Create a token that can read patcher-cli and terrapatch-cli releases in your org (or `gruntwork-io`) (see [GitHub Personal Access Token Setup](#github-personal-access-token-setup) below).

?

@josh-padnick josh-padnick mentioned this pull request Sep 4, 2025
Open
5 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@yhakbar yhakbar yhakbar requested changes

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@yhakbar @josh-padnick