docs: Breaking down Pipelines authentication concepts

[yhakbar]

Breaking down Pipelines authentication concepts so that they aren't assuming AWS only.

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
docs	Ready	Preview	Comment	Sep 26, 2025 5:12pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. 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.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch yousif/dev-1088-break-down-authenticating-to-the-cloud-to-avoid-assuming-aws

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[josh-padnick]

The content of the docs is great, but one big surprise for me was that I was expecting more of a how-to, whereas these are written more like explanations (as those terms are defined in The 4 types of technical documentation).

I think our first priority is a how-to that specifically addresses how users can auth to AWS, Azure, or a custom provider. After all, that's what will enable users to install things, so I'd actually expect a new section under "Setup & Installation" called something like "Cloud", with each of AWS, Azure, and Custom listed there. Then maybe we re-word "Enable Auth for Pipelines" to "VCS/CI" and have one entry for each of GitHub and GitLab (or if you want to keep the scope of this PR contained, just to change the title and leave the content as is).

Would you be open to updating these to be how-to docs that focus on a step-by-step process users can follow to set up authentication? Then within those steps, perhaps we can link to explanation docs as needed.

For the explanation docs, I wonder if parts of them belong under a dedicated "Security" section in the Pipelines docs since they even include discussions on "Fundamentals of OIDC"?

[josh-padnick]

These are nice security practices, but we need more context. Are these best practices that the customer should do, or something Gruntwork has already baked in to Pipelines?

Alternatively, do we need this section at all in an overview page? Alternatively, maybe we should have a section called "Security principles" and write in slightly more depth about the steps we take to give customers a secure way to authenticate; not sure that's critical, though.

[yhakbar]

Both! If it's not critical to you, I will defer any addition of more pages to a subsequent PR.

[josh-padnick]

I think the issue is that it's not clear what we want the reader to do with this information. Are we teaching them what security best practices we adopted, or giving them guidelines on how they should use Pipelines? Either way, we should be more explicit about what we want them to take away from reading this section.

[yhakbar]

@josh-padnick

Would you be open to updating these to be how-to docs that focus on a step-by-step process users can follow to set up authentication? Then within those steps, perhaps we can link to explanation docs as needed.

I plan on doing that in a subsequent PR as I look to update the "Setup & Installation" and "Guides" sections of Pipelines docs, but this PR is focused on addressing the "Concepts" section, which is explicitly explanation docs. I'm going vertically down through the Pipelines docs, top-to-bottom and creating in-draft PRs for the functionality that we're introducing as part of the new authentication capabilities for Azure and Custom authentication.

[josh-padnick]

Ah, I see. If we're going to cover the how-to items soon, then, sure no issues with merging this.

More generally, my primary concern is that the detailed explanations of Azure, AWS, and Custom auth implementations feel out of place at the beginning of the Pipelines section. I'd suggest restructuring to prioritize what users need first:

Key concepts - limit to fundamental concepts users need to understand how to use Pipelines
Setup & installation
Security - Explanations go here

This gives users the essential information upfront, with implementation details available for those who need them. The current structure jumps into advanced technical details before establishing the fundamentals.