docs: Breaking down installation guide to avoid assuming AWS #2759
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the You can disable this status message by setting the ✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
yhakbar
changed the title
yhakbar
force-pushed
the
yousif/dev-1100-break-down-setup-installation-to-avoid-assuming-aws
branch
from
d4aa2e7 to
14a3786
Compare
yhakbar
force-pushed
the
yousif/dev-1096-break-down-architecture-to-avoid-assuming-aws
branch
from
dba5367 to
5c77938
Compare
yhakbar
force-pushed
the
yousif/dev-1100-break-down-setup-installation-to-avoid-assuming-aws
branch
from
a9bfa94 to
7a28fbb
Compare
yhakbar
force-pushed
the
yousif/dev-1100-break-down-setup-installation-to-avoid-assuming-aws
branch
from
20a0f47 to
0216063
Compare
yhakbar
changed the base branch from
yousif/dev-1096-break-down-architecture-to-avoid-assuming-aws
to
pipelines-v4
yhakbar
force-pushed
the
yousif/dev-1100-break-down-setup-installation-to-avoid-assuming-aws
branch
from
0216063 to
df85b9e
Compare
ZachGoldberg
reviewed
Oct 6, 2025
|
|
||
| By default, Account Factory includes the following components: | ||
|
|
||
| - 📋 An HTML form for generating workflow inputs: `.github/workflows/account-factory-inputs.html` |
Contributor
There was a problem hiding this comment.
nit: I think these icons are a bit of an AI-callsign, and is not a pattern mirrored elsewhere in our docs. Whilst I like a good emoji, I'm not sure these help
Contributor
There was a problem hiding this comment.
Also, I know you didn't add these! Just a whilst-your-in-there thing
ZachGoldberg
reviewed
Oct 6, 2025
| 6. **Create `.gitlab-ci.yml`** to configure your GitLab CI/CD pipeline. | ||
| 7. **Commit and push** your changes to activate Pipelines. | ||
|
|
||
| ## Ensure OIDC configuration and JWKS are publicly accessible |
Contributor
There was a problem hiding this comment.
It's a bit odd to have this headline come BEFORE the next headline of "prerequisites" - feels like this belongs under that headline?
ZachGoldberg
reviewed
Oct 6, 2025
|
|
||
| This step only applies if you are using a self-hosted GitLab instance that is not accessible from the public internet. If you are using GitLab.com or a self-hosted instance that is publicly accessible, you can skip this step. | ||
|
|
||
| 1. [Follow GitLab's instructions](https://docs.gitlab.com/ci/cloud_services/aws/#configure-a-non-public-gitlab-instance) for hosting your OIDC configuration and JWKS in a public location (e.g. S3 Bucket). This is necessary for both Gruntwork and the AWS OIDC provider to access the GitLab OIDC configuration and JWKS when authenticating JWT's generated by your custom instance. |
Contributor
There was a problem hiding this comment.
There are some AWS-specific assumptions in this section
ZachGoldberg
reviewed
Oct 6, 2025
|
|
||
| ::: | ||
|
|
||
| ## Configuring SCM Access |
Contributor
There was a problem hiding this comment.
Since this page is now specific to GitLab and doesn't have to cater to both github and gitlab, maybe we just say GitLab here?
Suggested change
| ## Configuring SCM Access | |
| ## Configuring GitLab Access |
ZachGoldberg
reviewed
Oct 6, 2025
|
|
||
| ## Configuring SCM Access | ||
|
|
||
| Pipelines needs the ability to interact with Source Control Management (SCM) platforms to fetch resources (e.g. IaC code, reusable CI/CD code and the Pipelines binary itself). |
Contributor
There was a problem hiding this comment.
Suggested change
| Pipelines needs the ability to interact with Source Control Management (SCM) platforms to fetch resources (e.g. IaC code, reusable CI/CD code and the Pipelines binary itself). | |
| Pipelines needs the ability to interact with GitLab to fetch resources (e.g. IaC code, reusable CI/CD code and the Pipelines binary itself). |
Contributor
There was a problem hiding this comment.
This section also feels like something got lost - we say "we need machine users" with a link to the doc, but nothing else. Maybe something more concrete like "To create machine users, follow our guide [here]" (or similar)
ZachGoldberg
reviewed
Oct 6, 2025
|
|
||
| If you don't have a `root.hcl` file, you might need to customize the bootstrapping process, as the Terragrunt scale catalog expects a `root.hcl` file in the root of the project. Please contact [Gruntwork support](/support) for assistance if you need help. | ||
|
|
||
| For each AWS account that needs bootstrapping, we'll use Boilerplate to scaffold the necessary content. |
Contributor
There was a problem hiding this comment.
Might be missing an instruction here to tell the user to run this boilerplate command in each account folder or similar?
ZachGoldberg
reviewed
Oct 6, 2025
ZachGoldberg
reviewed
Oct 6, 2025
| For each environment, you'll want to define a [`filter` block](/2.0/reference/pipelines/configurations-as-code/api#filter-block) that tells Pipelines which units are part of that environment. You'll also want to define an [`authentication` block](/2.0/reference/pipelines/configurations-as-code/api#authentication-block) that tells Pipelines how to authenticate with your cloud provider(s) for that environment. | ||
|
|
||
| <Tabs> | ||
| <TabItem value="aws" label="AWS" default> |
Contributor
There was a problem hiding this comment.
I suggest using a groupId here so the choice of cloud is synced across the doc
ZachGoldberg
reviewed
Oct 6, 2025
| @@ -0,0 +1,867 @@ | |||
| # Bootstrap Pipelines in an Existing Repository | |||
Contributor
There was a problem hiding this comment.
There's a significant amount of duplicated content between GitHub/GitLab pages. What do you think of factoring that out?
Contributor
Author
There was a problem hiding this comment.
I started digging into this here, but it's proving annoying because the code snippets are interfering with MDX component parsing, and I don't want to have to put every code block in a separate file.
#2784
Will do what I can, but I'd like to defer that work in the interest of getting this merged.
Contributor
Author
There was a problem hiding this comment.
We discussed the issues involved in abstracting away logic into components, requiring work to avoid issues related to backticks and curly braces interfering with MDX parsing.
ZachGoldberg
approved these changes
Oct 7, 2025
yhakbar
deleted the
yousif/dev-1100-break-down-setup-installation-to-avoid-assuming-aws
branch
Resonance1584
added a commit
that referenced
this pull request
Oct 23, 2025
* chore: Start of Pipelines v4 * docs: Breaking down Pipelines authentication concepts (#2745) * docs: Nested AWS into `Authenticating to the Cloud` * docs: Adding Azure docs * docs: Adding custom auth * Fix build issues. * Add custom page to sidebar * Update docs/2.0/docs/pipelines/concepts/cloud-auth/aws.mdx Co-authored-by: Josh Padnick <[email protected]> * Update docs/2.0/docs/pipelines/concepts/cloud-auth/aws.mdx Co-authored-by: Josh Padnick <[email protected]> * fix: Use active voice for custom auth * fix: Add examples of secret managers * fix: Explicitly say 'at the root of your repository' * fix: Add callout for risk of custom auth * fix: Shuffle order of tabs for configuration options * fix: Adding a bit of cleanup * fix: Adding preamble for best practices --------- Co-authored-by: Josh Padnick <[email protected]> * fix: Adding `Entra` as custom word * DEV-799 Add GitLab drift detection docs (#2747) * Add GitLab drift detection docs * Add infrachanges to dictionary * Make gov cloud docs work with referenced templates (#2749) * GitLab Account factory docs (#2677) * Initial docs for GitLab devops-foundations template * Additional gitlab account factory update * Rest of account-factory setup * Fix build * Update sidebar and page titles * Review suggestions * Update account vending instructions * docs: Breaking down Pipelines architecture concepts (#2753) * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * fix: Addressing markdown lints * fix: Refactored out the architecture portion of Pipelines into an Account Factory page * feat: Reworked `Repository Topology` as an Account Factory page * fix: Reworked components page into execution flow page * fix: Adding some architecture diagrams * docs: Migrating out AWS specific security controls for Pipelines to Account Factory * docs: Updating `ci-workflows.md` with call outs for Account Factory stuff * docs: Markdown linting `Usage Data` docs * fix: Adjusting URL for account factory link * Apply suggestion from @josh-padnick Co-authored-by: Josh Padnick <[email protected]> * Apply suggestion from @josh-padnick Co-authored-by: Josh Padnick <[email protected]> * Apply suggestion from @josh-padnick Co-authored-by: Josh Padnick <[email protected]> * Apply suggestion from @josh-padnick Co-authored-by: Josh Padnick <[email protected]> * docs: Addressing PR feedback * Update docs/2.0/docs/pipelines/architecture/index.md Co-authored-by: Josh Padnick <[email protected]> * Update docs/2.0/docs/pipelines/architecture/index.md Co-authored-by: Josh Padnick <[email protected]> * Update docs/2.0/docs/pipelines/architecture/execution-flow.md Co-authored-by: Josh Padnick <[email protected]> --------- Co-authored-by: Josh Padnick <[email protected]> * docs: Breaking down installation guide to avoid assuming AWS (#2759) * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * fix: Addressing markdown lints * fix: Reworked components page into execution flow page * docs: Migrating out AWS specific security controls for Pipelines to Account Factory * docs: Updating `ci-workflows.md` with call outs for Account Factory stuff * docs: Addressing PR feedback * fix: Adding abbreviation to dictionary * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * docs: Moving AWS Landing Zone prereq to Account Factory docs: Adjusting redirects for moving AWS Landing Zone to Account Factory * docs: Restructured initial setup to avoid assuming AWS docs: Splitting up different cloud providers wip: Progress on stacks * feat: Set up full Azure installation guide * fix: Fixing the checkbox ids * fix: Fixing up some paper cuts in the top-level setup & installation docs * fix: Fixing path to new prerequisites for Account Factory * chore: Making sure this is pinned to `v4` before I forget * fix: Cleaning up Azure guide * docs: Adding AWS docs * fix: Cleaning up language for sidebar on GitHub * docs: WIP progress on adding Pipelines to an existing repo * docs: More troubleshooting guidance * docs: Adjusting language in `Setup & Installation` * docs: Adjusting logic for repo setup * fix: Cutting down on steps for adding a new repo * feat: Adding instructions for additional accounts and subscriptions * fix: Preventing ToC from breaking by using h3 tags * fix: Adding existing guide docs * fix: Redoing GitLab install instructions for parity with GitHub * fix: Removing unnecessary GitLab content * docs: Adding existing repository instructions for GitLab * docs: Adding note for self-hosted GitLab instance * fix: Fixing URL for pipelines machine users install * fix: Satisfying spellcheck * fix: Fixing auth links * fix: Addressing easy to address PR feedback --------- Co-authored-by: Josh Padnick <[email protected]> * docs: Adding HCL configuration reference for Azure and Custom auth (#2781) * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * fix: Addressing markdown lints * fix: Reworked components page into execution flow page * docs: Migrating out AWS specific security controls for Pipelines to Account Factory * docs: Updating `ci-workflows.md` with call outs for Account Factory stuff * docs: Addressing PR feedback * fix: Adding abbreviation to dictionary * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * docs: Moving AWS Landing Zone prereq to Account Factory docs: Adjusting redirects for moving AWS Landing Zone to Account Factory * docs: Restructured initial setup to avoid assuming AWS docs: Splitting up different cloud providers wip: Progress on stacks * feat: Set up full Azure installation guide * fix: Fixing the checkbox ids * fix: Fixing up some paper cuts in the top-level setup & installation docs * fix: Fixing path to new prerequisites for Account Factory * chore: Making sure this is pinned to `v4` before I forget * fix: Cleaning up Azure guide * docs: Adding AWS docs * fix: Cleaning up language for sidebar on GitHub * docs: WIP progress on adding Pipelines to an existing repo * docs: More troubleshooting guidance * docs: Adjusting language in `Setup & Installation` * docs: Adjusting logic for repo setup * fix: Cutting down on steps for adding a new repo * feat: Adding instructions for additional accounts and subscriptions * fix: Preventing ToC from breaking by using h3 tags * fix: Adding existing guide docs * fix: Redoing GitLab install instructions for parity with GitHub * fix: Removing unnecessary GitLab content * docs: Adding existing repository instructions for GitLab * docs: Adding note for self-hosted GitLab instance * fix: Fixing URL for pipelines machine users install * fix: Satisfying spellcheck * fix: Fixing auth links * fix: Addressing easy to address PR feedback * fix: Adding HCL configuration reference for Azure and Custom auth * fix: Fixing some links --------- Co-authored-by: Josh Padnick <[email protected]> * docs: Breaking down tutorials to avoid assuming AWS (#2782) * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * fix: Reworked components page into execution flow page * docs: Migrating out AWS specific security controls for Pipelines to Account Factory * docs: Updating `ci-workflows.md` with call outs for Account Factory stuff * docs: Addressing PR feedback * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * docs: Restructured initial setup to avoid assuming AWS docs: Splitting up different cloud providers wip: Progress on stacks * fix: Fixing the checkbox ids * docs: Adding AWS docs * docs: WIP progress on adding Pipelines to an existing repo * docs: More troubleshooting guidance * fix: Cutting down on steps for adding a new repo * fix: Redoing GitLab install instructions for parity with GitHub * fix: Updating `deploying-your-first-infrastructure-change` extension to `mdx` * fix: Update to address Azure as well * fix: Update extension for `destroying-infrastructure` to `mdx` * fix: Updating infrastructure destruction docs to support Azure * fix: Fixing broken links and spellcheck * fix: Fixing accidental merge error * fix: Use `groupId` --------- Co-authored-by: Josh Padnick <[email protected]> * docs: Breaking down guides to avoid assuming AWS (#2783) * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * fix: Reworked components page into execution flow page * docs: Migrating out AWS specific security controls for Pipelines to Account Factory * docs: Updating `ci-workflows.md` with call outs for Account Factory stuff * docs: Addressing PR feedback * docs: Nested AWS into `Authenticating to the Cloud` * Fix build issues. * docs: Restructured initial setup to avoid assuming AWS docs: Splitting up different cloud providers wip: Progress on stacks * fix: Fixing the checkbox ids * docs: Adding AWS docs * docs: WIP progress on adding Pipelines to an existing repo * docs: More troubleshooting guidance * fix: Cutting down on steps for adding a new repo * fix: Redoing GitLab install instructions for parity with GitHub * fix: Update extension for `managing-secrets` to `mdx` * docs: Making it so that managing secrets doesn't assume AWS * docs: Moving delegated repo setup to Account Factory * docs: Fixing handling broken IaC * fix: Resolving merge conflicts * fix: Avoiding adding whitespace here --------- Co-authored-by: Josh Padnick <[email protected]> * fix: Fixing reference to catalog (#2792) * Empty commit * Add Account factory HCL configuration docs (#2791) * Add Account factory HCL configuration docs * Fix broken link * Review suggestions * Add unlock workflows docs (#2793) * Add unlock workflows docs * Review suggestions --------- Co-authored-by: Oreoluwa Agunbiade <[email protected]> * docs: Adding callout for branch protection security improvements (#2798) * GitHub Pipelines v3 -> v4 migration guide (#2794) * WIP migration guide * More WIP * More WIP guide * Updates * Fix broken links * PR suggestions --------- Co-authored-by: Oreoluwa Agunbiade <[email protected]> * Update migration doc with fallback token permissions (#2802) * WIP migration guide * More WIP * More WIP guide * Updates * Fix broken links * Update migration doc with fallback token permissions * Fix formatting * Fix lint * Apply suggestion from @odgrim Co-authored-by: Brian T <[email protected]> --------- Co-authored-by: Lewis Christie <[email protected]> Co-authored-by: Brian T <[email protected]> * Add Gitlab pipelines v1 to v2 upgrade docs (#2806) * WIP migration guide * More WIP * More WIP guide * Updates * Fix broken links * Update migration doc with fallback token permissions * Fix formatting * Fix lint * Add Gitlab pipelines v1 to v2 upgrade docs --------- Co-authored-by: Lewis Christie <[email protected]> * fix: Add callout for permissions of tutorial (#2809) * fix: Adding some basic fixes for AWS first infra change docs * docs: Adding permissions callout for AWS and Azure * docs: Adding callout for permissions that are required for tutorials * fix: Including `--backend-bootstrap` to instructions for initial plan in AWS (#2808) * feat: Adding GitLab Azure support (#2807) * feat: Adding GitLab Azure support * Update docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx Co-authored-by: Oreoluwa Agunbiade <[email protected]> * Update docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx Co-authored-by: Oreoluwa Agunbiade <[email protected]> * Update docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx Co-authored-by: Oreoluwa Agunbiade <[email protected]> * Update docs/2.0/docs/pipelines/installation/addinggitlabrepo.mdx Co-authored-by: Oreoluwa Agunbiade <[email protected]> --------- Co-authored-by: Oreoluwa Agunbiade <[email protected]> * copy updates to v4 migration guide * More copy updates in migration guide * Copy updates * update feature flags table for v4 * consistent casing * consistency * Update compatibility table * Add whats new * Update terragrunt-version-compatibility.md * Whats new for GitLab * Include v1's max as well * Update HCL Beta labels * Add GitLab account factory setup docs (#2811) * Add GitLab account factory setup docs * Update tabs and group ID --------- Co-authored-by: Zach Goldberg <[email protected]> * Update custom dictionary * Add custom-actions gruntwork_context section --------- Co-authored-by: Josh Padnick <[email protected]> Co-authored-by: Lewis Christie <[email protected]> Co-authored-by: Oreoluwa Agunbiade <[email protected]> Co-authored-by: Oreoluwa Agunbiade <[email protected]> Co-authored-by: Brian T <[email protected]> Co-authored-by: Zach Goldberg <[email protected]> Co-authored-by: Zach Goldberg <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Breaking down installation guide to avoid assuming AWS usage.