From 1d5e4e4a9c8a62d75ac689fda014a92f80838e1b Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 21:50:12 +0000 Subject: [PATCH 1/5] Add Patcher self-hosting documentation - Create comprehensive self-hosting guide at docs/2.0/docs/patcher/guides/self-hosting.md - Document repo-copier as primary recommended approach for self-hosting binaries - Explain current patcher-action limitations with hardcoded GitHub organizations - Include GitHub Enterprise and GitLab CI configuration examples - Add link to self-hosting guide in installation documentation - Update sidebar navigation to include new self-hosting guide Addresses DEV-1044 Co-Authored-By: Josh Padnick --- docs/2.0/docs/patcher/guides/self-hosting.md | 163 +++++++++++++++++++ docs/2.0/docs/patcher/installation/index.md | 4 + sidebars/docs.js | 5 + 3 files changed, 172 insertions(+) create mode 100644 docs/2.0/docs/patcher/guides/self-hosting.md diff --git a/docs/2.0/docs/patcher/guides/self-hosting.md b/docs/2.0/docs/patcher/guides/self-hosting.md new file mode 100644 index 000000000..2598e9612 --- /dev/null +++ b/docs/2.0/docs/patcher/guides/self-hosting.md @@ -0,0 +1,163 @@ +# Self-hosting Patcher + +## Introduction to Patcher self-hosting + +Patcher runs in GitHub Actions or GitLab CI environments to automate dependency updates for your Terraform and Terragrunt infrastructure. While the Patcher service itself runs in CI/CD pipelines, you might want to self-host the Patcher and Terrapatch binaries rather than downloading them directly from github.com/gruntwork-io. + +You might want to self-host Patcher binaries because: + +- **Security requirements**: Your organization requires all external dependencies to be vetted and hosted internally +- **Air-gapped environments**: Your infrastructure operates in environments without direct internet access +- **Compliance policies**: Internal policies mandate that all tools must be sourced from approved internal repositories +- **Network restrictions**: Corporate firewalls or proxy configurations prevent direct access to GitHub releases + +:::info + +Only the Patcher and Terrapatch binaries need to be self-hosted. The Patcher service itself continues to run within your existing CI/CD infrastructure (GitHub Actions or GitLab CI). + +::: + +## Self-hosting options + +### Repo-copier + GitHub Actions (Recommended) + +The primary recommended approach for self-hosting Patcher binaries is to use Gruntwork's [repo-copier](https://github.com/gruntwork-io/repo-copier) tool in combination with GitHub Actions or GitHub Enterprise. + +Repo-copier automatically copies all content from Gruntwork's private repositories—including releases and binary assets—to your internal version control system. This ensures that Patcher binaries are available in your environment while maintaining automatic updates. + +For detailed setup instructions, see the [IaC Library self-hosting guide](/2.0/docs/library/guides/self-hosting). + +**Supported with repo-copier:** +- Your own GitHub.com organization +- GitHub Enterprise Server +- GitLab.com +- BitBucket Server + +### Forking repositories (Alternative) + +You can manually fork the [patcher-cli](https://github.com/gruntwork-io/patcher-cli) and [terrapatch-cli](https://github.com/gruntwork-io/terrapatch-cli) repositories to your internal GitHub organization or GitHub Enterprise instance. + +However, manual forking has limitations: +- Updates from Gruntwork do not propagate automatically +- You must manually sync releases and binary assets +- Cross-references may need manual updates + +### Alternative approaches + +For organizations with specific requirements, you can: + +1. **Download and host binaries manually**: Download releases from Gruntwork repositories and host them in your internal artifact storage +2. **Build from source**: Clone the repositories and build binaries using your internal build systems +3. **Mirror releases**: Set up automated mirroring of GitHub releases to your internal systems + +:::caution + +These alternative approaches require significant manual maintenance and may not receive automatic security updates. + +::: + +## GitHub Actions parameters for self-hosted binaries + +### Current limitations + +The current patcher-action implementation hardcodes the GitHub organization and repository names for binary downloads. The action downloads binaries from: + +- `gruntwork-io/patcher-cli` +- `gruntwork-io/terrapatch-cli` +- `minamijoyo/tfupdate` +- `minamijoyo/hcledit` + +### Custom SCM parameters + +Currently, the patcher-action does not support custom SCM parameters for specifying alternative binary sources. The action would require modifications to support: + +- Custom GitHub organizations +- Alternative GitHub Enterprise instances +- Custom binary repository URLs + +### Authentication requirements + +When using GitHub Enterprise or custom GitHub organizations, ensure your GitHub Actions have appropriate authentication: + +```yaml +- name: Run Patcher + uses: gruntwork-io/patcher-action@v2 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + read_token: ${{ secrets.CUSTOM_GITHUB_TOKEN }} # For accessing your internal repos + update_token: ${{ secrets.CUSTOM_GITHUB_TOKEN }} +``` + +## Code examples + +### GitHub Enterprise configuration + +If you're using repo-copier with GitHub Enterprise, your workflow might look like this: + +```yaml +name: Patcher Update +on: + schedule: + - cron: '0 9 * * MON' # Run weekly on Mondays + workflow_dispatch: + +jobs: + patcher-update: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + token: ${{ secrets.GITHUB_ENTERPRISE_TOKEN }} + + - name: Run Patcher Update + uses: gruntwork-io/patcher-action@v2 + with: + patcher_command: update + github_token: ${{ secrets.GITHUB_ENTERPRISE_TOKEN }} + read_token: ${{ secrets.GITHUB_ENTERPRISE_TOKEN }} + update_token: ${{ secrets.GITHUB_ENTERPRISE_TOKEN }} + pull_request_branch: patcher-updates-${{ github.run_number }} + pull_request_title: "[Patcher] Update dependencies" + working_dir: "infrastructure-live/dev" +``` + +### GitLab CI support + +Patcher supports GitLab CI environments, but this integration is newer and may require additional configuration. + +:::info + +For GitLab CI setup and configuration, please contact our support team at [support@gruntwork.io](mailto:support@gruntwork.io) for the latest guidance and best practices. + +::: + +## Unsupported methods and limitations + +### Artifactory status + +Artifactory and similar artifact management tools are **not currently supported** for hosting Patcher binaries. These tools lack the metadata and release management features that Patcher relies on, such as: + +- GitHub release tags and versioning +- Release assets and checksums +- API compatibility for automated downloads + +### Version management considerations + +When self-hosting Patcher binaries: + +- **Pin specific versions**: Use the `patcher_version` parameter to ensure consistent behavior across environments +- **Test updates**: Validate new Patcher versions in development environments before promoting to production +- **Monitor compatibility**: Ensure your self-hosted binaries remain compatible with your Terraform and Terragrunt versions + +```yaml +- name: Run Patcher with pinned version + uses: gruntwork-io/patcher-action@v2 + with: + patcher_version: "v0.15.1" # Pin to specific version + # ... other parameters +``` + +### Current action limitations + +The patcher-action currently requires modifications to support fully custom binary sources. If you need this functionality, please contact [support@gruntwork.io](mailto:support@gruntwork.io) to discuss your requirements and potential solutions. diff --git a/docs/2.0/docs/patcher/installation/index.md b/docs/2.0/docs/patcher/installation/index.md index 5f9ccebd7..deef41492 100644 --- a/docs/2.0/docs/patcher/installation/index.md +++ b/docs/2.0/docs/patcher/installation/index.md @@ -21,6 +21,10 @@ $ echo $PATH $ mv patcher /usr/local/bin ``` +## Self-hosting Patcher + +If your organization requires hosting Patcher binaries internally rather than downloading them directly from GitHub, see our [self-hosting guide](/2.0/docs/patcher/guides/self-hosting) for detailed instructions on using repo-copier and other self-hosting approaches. + ## Before running Patcher ### GitHub Personal Access Token diff --git a/sidebars/docs.js b/sidebars/docs.js index 5831b4a4c..cb8fa9461 100644 --- a/sidebars/docs.js +++ b/sidebars/docs.js @@ -591,6 +591,11 @@ const sidebar = [ type: "doc", id: "2.0/docs/patcher/guides/upgrade", }, + { + label: "Self-hosting Patcher", + type: "doc", + id: "2.0/docs/patcher/guides/self-hosting", + }, { label: "Disable Telemetry", type: "doc", From aa9b539f0a477b0631451693b73fa21c5a8d1b88 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 22:01:23 +0000 Subject: [PATCH 2/5] Fix spellcheck errors by adding technical terms to custom dictionary - Add gruntwork-io, minamijoyo, tfupdate, hcledit, self-hosting to custom-dictionary.txt - These are legitimate technical terms used in the Patcher self-hosting documentation - Resolves CircleCI validate_build spellcheck failure Co-Authored-By: Josh Padnick --- custom-dictionary.txt | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/custom-dictionary.txt b/custom-dictionary.txt index 198a8ef4b..ae96dd0ae 100644 --- a/custom-dictionary.txt +++ b/custom-dictionary.txt @@ -54,4 +54,9 @@ projectprefix GOVCLOUD rollouts myvars -myfile \ No newline at end of file +myfile +gruntwork-io +minamijoyo +tfupdate +hcledit +self-hosting From 0dec3801af2dcb9bd0e0c5f952bfb9ac1e9fd095 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 22:13:15 +0000 Subject: [PATCH 3/5] Fix typo: change 'leasat' to 'least' in account factory documentation This resolves the spellcheck error causing the validate_build CI failure. Co-Authored-By: Josh Padnick --- .../guides/drift-remediation-with-async-module.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/docs/accountfactory/guides/drift-remediation-with-async-module.md b/docs/2.0/docs/accountfactory/guides/drift-remediation-with-async-module.md index 5870c1670..b46975469 100644 --- a/docs/2.0/docs/accountfactory/guides/drift-remediation-with-async-module.md +++ b/docs/2.0/docs/accountfactory/guides/drift-remediation-with-async-module.md @@ -134,7 +134,7 @@ For `_envcommon/landingzone/root-pipelines-apply-role.hcl`, ensure that you have } ``` -For `_envcommon/landingzone/root-pipelines-plan-role.hcl`, ensure that you have at leasat the following permissions: +For `_envcommon/landingzone/root-pipelines-plan-role.hcl`, ensure that you have at least the following permissions: ```hcl "CloudWatchEventsReadOnlyAccess" = { From 3001fcd06ac0a8d269fc7d16b7e3bdc0952a8b08 Mon Sep 17 00:00:00 2001 From: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com> Date: Fri, 29 Aug 2025 23:52:30 +0000 Subject: [PATCH 4/5] Add specific repo-copier configuration for Patcher self-hosting - Add required repositories: patcher-cli, patcher-action, terrapatch-cli - Include GitHub Actions permissions configuration instructions - Specify access settings for organization and enterprise levels - Provide actionable steps for users to configure repo-copier properly Co-Authored-By: Josh Padnick --- docs/2.0/docs/patcher/guides/self-hosting.md | 23 +++++++++++++++++++- 1 file changed, 22 insertions(+), 1 deletion(-) diff --git a/docs/2.0/docs/patcher/guides/self-hosting.md b/docs/2.0/docs/patcher/guides/self-hosting.md index 2598e9612..021a8da0e 100644 --- a/docs/2.0/docs/patcher/guides/self-hosting.md +++ b/docs/2.0/docs/patcher/guides/self-hosting.md @@ -25,7 +25,28 @@ The primary recommended approach for self-hosting Patcher binaries is to use Gru Repo-copier automatically copies all content from Gruntwork's private repositories—including releases and binary assets—to your internal version control system. This ensures that Patcher binaries are available in your environment while maintaining automatic updates. -For detailed setup instructions, see the [IaC Library self-hosting guide](/2.0/docs/library/guides/self-hosting). +#### Required repositories for Patcher self-hosting + +You need to configure repo-copier to copy the following Patcher-related repositories: + +- [`gruntwork-io/patcher-cli`](https://github.com/gruntwork-io/patcher-cli) - The main Patcher binary +- [`gruntwork-io/patcher-action`](https://github.com/gruntwork-io/patcher-action) - GitHub Action for running Patcher +- [`gruntwork-io/terrapatch-cli`](https://github.com/gruntwork-io/terrapatch-cli) - Terrapatch binary for Terraform patching + +#### GitHub Actions permissions configuration + +After copying these repositories to your internal GitHub organization or GitHub Enterprise instance, you must configure GitHub Actions permissions for each repository to allow other repositories to access them. + +For each of the three repositories above, navigate to the repository's Actions settings: +- Go to `https://your-github-instance.com/your-org/REPO_NAME/settings/actions` +- Scroll down to the "Access" section +- Select one of the following options (do **not** select "Not accessible"): + - **"Accessible from repositories in the 'your-org' organization"** - Allows access from repositories within your organization + - **"Accessible from repositories in the 'Your-Enterprise' enterprise"** - Allows access from repositories across your entire GitHub Enterprise + +This configuration ensures that your other repositories can use the self-hosted Patcher actions and download the necessary binaries during CI/CD workflows. + +For detailed repo-copier setup instructions, see the [IaC Library self-hosting guide](/2.0/docs/library/guides/self-hosting). **Supported with repo-copier:** - Your own GitHub.com organization From 5556ec3799588357da8b288149a67841966e65b0 Mon Sep 17 00:00:00 2001 From: Josh Padnick Date: Sun, 14 Sep 2025 19:13:30 -0700 Subject: [PATCH 5/5] Update docs/2.0/docs/patcher/guides/self-hosting.md Co-authored-by: Yousif Akbar <11247449+yhakbar@users.noreply.github.com> --- docs/2.0/docs/patcher/guides/self-hosting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2.0/docs/patcher/guides/self-hosting.md b/docs/2.0/docs/patcher/guides/self-hosting.md index 021a8da0e..40075d4df 100644 --- a/docs/2.0/docs/patcher/guides/self-hosting.md +++ b/docs/2.0/docs/patcher/guides/self-hosting.md @@ -2,7 +2,7 @@ ## Introduction to Patcher self-hosting -Patcher runs in GitHub Actions or GitLab CI environments to automate dependency updates for your Terraform and Terragrunt infrastructure. While the Patcher service itself runs in CI/CD pipelines, you might want to self-host the Patcher and Terrapatch binaries rather than downloading them directly from github.com/gruntwork-io. +Patcher runs in GitHub Actions or GitLab CI environments to automate dependency updates for your OpenTofu/Terraform and Terragrunt infrastructure. While the Patcher service itself runs in CI/CD pipelines, you might want to self-host the Patcher and Terrapatch binaries rather than downloading them directly from github.com/gruntwork-io. You might want to self-host Patcher binaries because: