auth docs improvement - account.id vs account.name in type aws/permissionset

[Ben (Benbentwo)]

what

This pull request updates documentation for specifying AWS account references in identity configurations, improving clarity and flexibility for users. The most important changes provide guidance on using either account names or IDs when configuring AWS identities, and update examples to reflect these options.

Documentation improvements for AWS account specification:

• Added explanations in pkg/auth/docs/PRD/PRD-Atmos-Auth.md about specifying AWS accounts using either account.name (recommended) or account.id, with examples for both methods. [1] [2]
• Updated example configurations in pkg/auth/docs/ARCHITECTURE.md and pkg/auth/docs/UserGuide.md to use descriptive account names (e.g., "sandbox", "production", "development") instead of numeric IDs, and included comments showing how to use the account ID directly. [1] [2] [3] [4]

Minor documentation adjustments:

• Minor formatting and clarification changes in pkg/auth/docs/PRD/PRD-Atmos-Auth.md to improve readability of the auth: section.

why

• Improve docs for better getting started experience

references

• Atmos Auth Implementation #1475

Summary by CodeRabbit

• Documentation
  • Updated authentication guides to use environment-based account names (e.g., “production”, “development”) instead of numeric IDs in examples.
  • Added explicit guidance for configuring AWS Permission Set identities.
  • Provided parallel example configurations for specifying accounts by name or by ID (with an alternative commented option).
  • Restored environment variable blocks in relevant examples and refined example formatting.
  • Minor text/whitespace cleanups.
  • No functional or behavioral changes.

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation-only updates to identity configuration examples across architecture, PRD, and user guide docs, adding/clarifying account.name vs. account.id usage and replacing numeric AWS account IDs with environment-style names. No code or API changes.

Changes

Cohort / File(s)	Summary
Architecture Doc examples pkg/auth/docs/ARCHITECTURE.md	Updated example identity: account name changed from numeric ID to "sandbox"; added commented alternative using account ID.
PRD guidance for AWS identities pkg/auth/docs/PRD/PRD-Atmos-Auth.md	Clarified AWS Permission Set identity options (account.name and account.id); added two example configurations (by name and by ID); minor formatting tweaks and env block adjustments.
User Guide examples pkg/auth/docs/UserGuide.md	Replaced numeric account IDs with environment names (e.g., production/development); added commented alternative to specify account by ID; no behavioral changes.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Suggested labels

no-release

Suggested reviewers

• osterman
• aknysh

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly summarizes the primary change by indicating that the pull request improves the AWS permissionset documentation to explain the difference between account.id and account.name, directly matching the updated examples and explanatory content.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch bugfix/auth-docs-permissionset

---

📜 Recent review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 0b22825 and 3e6f623.

📒 Files selected for processing (3)

• pkg/auth/docs/ARCHITECTURE.md (1 hunks)
• pkg/auth/docs/PRD/PRD-Atmos-Auth.md (3 hunks)
• pkg/auth/docs/UserGuide.md (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (6)

• GitHub Check: Analyze (go)
• GitHub Check: Lint (golangci)
• GitHub Check: Build (windows-latest, windows)
• GitHub Check: Build (macos-latest, macos)
• GitHub Check: Run pre-commit hooks
• GitHub Check: Summary

🔇 Additional comments (3)

pkg/auth/docs/ARCHITECTURE.md (1)

169-171: Nice clarity boost.

Switching to the named account plus the ID comment nails the intent.

pkg/auth/docs/UserGuide.md (1)

101-150: Examples read cleaner now.

Using named accounts with the ID fallback explains both paths well.

pkg/auth/docs/PRD/PRD-Atmos-Auth.md (1)

986-1019: Good callout.

Documenting both account selectors plus the recommendation removes ambiguity.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.91%. Comparing base (0b22825) to head (3e6f623).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1632      +/-   ##
==========================================
+ Coverage   64.87%   64.91%   +0.03%     
==========================================
  Files         337      337              
  Lines       37448    37448              
==========================================
+ Hits        24296    24308      +12     
+ Misses      11205    11191      -14     
- Partials     1947     1949       +2     

Flag	Coverage Δ
unittests	64.91% <ø> (+0.03%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[github-actions]

These changes were released in v1.195.0-test.0.