atmos icon indicating copy to clipboard operation
atmos copied to clipboard
verified publisher icon cloudposse

Update auth docs and implement GitHub providers

Open osterman opened this issue 4 months ago • 5 comments

what

This PR implements GitHub User and GitHub App authentication providers, enhancing Atmos's capabilities for secure credential management in various workflows. It also refactors the authentication documentation to improve organization and discoverability.

why

  • Enhance Security: Provide secure, short-lived tokens for GitHub interactions, reducing risks associated with long-lived Personal Access Tokens.
  • Improve Developer Experience: Seamlessly integrate GitHub authentication into local development and CI/CD pipelines.
  • Centralize Credential Management: Allow users to manage GitHub credentials via Atmos, storing tokens securely in OS keychains.
  • Modular Documentation: Create dedicated documentation pages for each GitHub provider (github/user, github/app, github/oidc) for better maintainability and discoverability.
  • Increase Test Coverage: Achieve 80.7% test coverage for the new providers using mocks for external dependencies.

references

  • GitHub User Provider: Implements OAuth Device Flow, inspired by ghtkn. User tokens are cached in OS keychains with an 8-hour lifetime.
  • GitHub App Provider: Uses JWT signing for installation tokens, offering granular permissions and 1-hour token lifetimes.
  • Git Credential Helper: Integrated via atmos auth git-credential for seamless Git operations.
  • Logout Command: Added atmos auth logout for keychain cleanup and guidance on token revocation.
  • Documentation Refactor:
    • Created dedicated pages for github/user, github/app, and github/oidc.
    • Integrated Mermaid diagrams for authentication flows and architecture.
    • Updated usage.mdx to link to new pages and deduplicate OIDC content.
  • Provider Kinds: Introduced constants (KindUser, KindApp, KindOIDC) for all GitHub providers.
  • Test Coverage: Achieved 80.7% statement coverage across new provider implementations.

closes #XXX (Placeholder for actual issue number)

Summary by CodeRabbit

Release Notes

  • New Features

    • Added GitHub User authentication via OAuth Device Flow for personal development workflows
    • Added GitHub App authentication via JWT for automation and CI/CD pipelines
    • Added atmos auth git-credential command for seamless Git integration
    • Added atmos auth logout command to revoke GitHub credentials
    • Improved authentication success message styling

  • Documentation

    • Added comprehensive GitHub authentication provider guides
    • Updated authentication usage documentation

  • Chores

    • Updated dependencies to support JWT signing
    • Added implementation tracking documentation

osterman avatar Oct 20 '25 20:10 osterman

[!WARNING]

This PR exceeds the recommended limit of 1,000 lines.

Large PRs are difficult to review and may be rejected due to their size.

Please verify that this PR does not address multiple issues. Consider refactoring it into smaller, more focused PRs to facilitate a smoother review process.

mergify[bot] avatar Oct 20 '25 20:10 mergify[bot]

[!WARNING]

Rate limit exceeded

@osterman has exceeded the limit for the number of commits or files that can be reviewed per hour. Please wait 20 minutes and 23 seconds before requesting another review.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

📥 Commits

Reviewing files that changed from the base of the PR and between cd7cc6c44f019b3ddc590a30991a8eeb2ec0de7b and 70c0fb21a90d893bf3ee3b0ce019b88a177d52b2.

📒 Files selected for processing (18)
  • .github/workflows/test-github-oidc.yml (1 hunks)
  • cmd/auth_git_credential.go (1 hunks)
  • cmd/auth_login.go (2 hunks)
  • cmd/auth_logout.go (1 hunks)
  • debug_plan_diff_windows.md (0 hunks)
  • errors/errors.go (1 hunks)
  • pkg/auth/identities/github/token.go (1 hunks)
  • pkg/auth/providers/github/app.go (1 hunks)
  • pkg/auth/providers/github/constants.go (1 hunks)
  • pkg/auth/providers/github/device_flow_client.go (1 hunks)
  • pkg/auth/providers/github/user.go (1 hunks)
  • pkg/auth/providers/github/user_test.go (1 hunks)
  • pkg/auth/providers/github/web_flow_client.go (1 hunks)
  • tests/test-cases/auth-github-oidc/README.md (1 hunks)
  • tests/test-cases/auth-github-oidc/atmos.yaml (1 hunks)
  • tests/test-cases/auth-github-oidc/stacks/example.yaml (1 hunks)
  • website/blog/2025-10-20-github-authentication-providers.md (1 hunks)
  • website/docs/cli/commands/auth/providers/github-user.mdx (1 hunks)
📝 Walkthrough

Walkthrough

This PR implements GitHub authentication with OAuth Device Flow (user authentication) and JWT-based GitHub App flows, adding new CLI commands for git-credential helper and logout, creating provider and identity implementations, defining new credential types, integrating storage support, and providing comprehensive documentation and tests.

Changes

Cohort / File(s) Summary
Documentation & Planning
DOCUMENTATION_STRUCTURE_PROPOSAL.md, GITHUB_IDENTITY_PLAN.md, GITHUB_MERMAID_DIAGRAMS.md, IMPLEMENTATION_STATUS.md, IMPLEMENTATION_COMPLETE.md		 New planning and design documentation for GitHub authentication structure, implementation plan with phases, architecture diagrams, and completion status tracking.
GitHub Provider Implementation
pkg/auth/providers/github/constants.go, pkg/auth/providers/github/device_flow_client.go, pkg/auth/providers/github/user.go, pkg/auth/providers/github/app.go, pkg/auth/providers/github/oidc.go		 New provider kinds (github/user, github/app), Device Flow client implementation for OAuth polling, user provider with Device Flow support, GitHub App provider with JWT generation, and OIDC refactor to use constants.
Provider Tests
pkg/auth/providers/github/user_test.go, pkg/auth/providers/github/app_test.go, pkg/auth/providers/github/mock_device_flow_client_test.go, pkg/auth/providers/github/oidc_test.go		 Comprehensive test coverage for device flow client mocking, user provider lifecycle, GitHub App authentication and key management, credentials expiration, and environment setup.
Credential Types
pkg/auth/types/github_user_credentials.go, pkg/auth/types/github_app_credentials.go		 New credential types with expiration tracking, environment variable population (GITHUB_TOKEN, GH_TOKEN), and whoami info building.
Identity Implementation
pkg/auth/identities/github/token.go		 GitHub token identity supporting github/token kind with provider credential pass-through and environment variable mapping.
Factory & Storage
pkg/auth/factory/factory.go, pkg/auth/credentials/store.go		 Factory registration for new GitHub providers and identities; keyring store support for GitHubUserCredentials and GitHubAppCredentials persistence.
CLI Commands
cmd/auth_login.go, cmd/auth_logout.go, cmd/auth_git_credential.go		 Enhanced login output formatting with styled UI; new logout command with identity and all-logout support; new git-credential helper for Git integration.
Website Documentation
website/docs/cli/commands/auth/providers/github-user.mdx, website/docs/cli/commands/auth/providers/github-app.mdx, website/docs/cli/commands/auth/providers/github-oidc.mdx, website/docs/cli/commands/auth/usage.mdx		 New provider-specific documentation for Device Flow (github/user), JWT-based (github/app), and OIDC flows; updated usage overview with provider grouping.
PRD & Dependencies
docs/prd/github-authentication-providers.md, go.mod		 Product requirements document for GitHub authentication; Go toolchain bump to 1.25.1 and addition of JWT signing dependency.
Test Snapshots
tests/snapshots/TestCLICommands_atmos_auth_invalid-command.stderr.golden		 Updated command help text to include new git-credential and logout subcommands.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant CLI as Atmos CLI
    participant DeviceFlow as Device Flow<br/>Client
    participant GitHub as GitHub API
    participant Store as Credential<br/>Store
    
    User->>CLI: atmos auth login
    CLI->>DeviceFlow: StartDeviceFlow()
    DeviceFlow->>GitHub: POST /device/code
    GitHub-->>DeviceFlow: device_code, user_code, verification_uri
    DeviceFlow-->>CLI: DeviceFlowResponse
    CLI->>User: Display user_code & verification_uri
    
    User->>GitHub: Visit verification_uri<br/>Enter user_code
    
    CLI->>DeviceFlow: PollForToken(device_code)
    loop Poll with backoff
        DeviceFlow->>GitHub: POST /token (with device_code)
        alt Authorization pending
            GitHub-->>DeviceFlow: authorization_pending
        else Token ready
            GitHub-->>DeviceFlow: access_token, expires_in
            DeviceFlow-->>CLI: token
        end
    end
    
    CLI->>Store: Store credentials
    Store-->>CLI: Success
    CLI->>User: Success message

sequenceDiagram
    participant App as Atmos CLI
    participant GitHub as GitHub API
    participant Store as Credential<br/>Store
    
    App->>App: Load GitHub App config<br/>(app_id, installation_id, private_key)
    App->>App: Generate JWT<br/>(RS256, 10-min expiry)
    App->>GitHub: GET /app/installations/{installation_id}/access_tokens<br/>with JWT + permissions
    GitHub-->>App: access_token, expires_at (1-hour)
    App->>Store: Store credentials<br/>(token, app_id, installation_id, expiry)
    Store-->>App: Success
    App->>App: Use token in requests
    
    Note over App: Token auto-refreshes<br/>on next command if expired

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The implementation spans multiple authentication flows (Device Flow, JWT, OIDC refactor), introduces new credential types and storage integration, adds CLI commands with UI components, and includes substantial test coverage across provider, identity, and credential lifecycles. While the changes are well-organized by cohort and documentation is thorough, each authentication provider requires independent reasoning around token lifecycle, error handling, and security considerations (key management, token expiration, scope validation). The heterogeneity of changes—mixing providers, identities, types, factories, CLI, and tests—requires distributed review attention across distinct subsystems.

Possibly related PRs

  • cloudposse/atmos#1475 — Directly overlaps in the auth subsystem, implementing and modifying GitHub providers, auth CLI commands, schema/auth types, and provider/identity code paths.

Suggested reviewers

  • aknysh
  • Benbentwo
  • milldr

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%. You can run @coderabbitai generate docstrings to improve docstring coverage.
✅ Passed checks (2 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check ✅ Passed The PR title "Update auth docs and implement GitHub providers" directly reflects the two major aspects of this changeset. The documentation updates are evident across multiple new files (DOCUMENTATION_STRUCTURE_PROPOSAL.md, GITHUB_IDENTITY_PLAN.md, GITHUB_MERMAID_DIAGRAMS.md, and new provider MDX documentation pages). The GitHub provider implementation is clearly present with new provider code (user.go, app.go, constants.go, device_flow_client.go), credential types, CLI commands (auth_git_credential.go, auth_logout.go), factory updates, and comprehensive test coverage. The title is specific and clear enough that a teammate scanning history would immediately understand this PR concerns GitHub authentication infrastructure and documentation, without being misleading or overly vague.

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

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

coderabbitai[bot] avatar Oct 20 '25 20:10 coderabbitai[bot]

[!WARNING]

Changelog Entry Required

This PR is labeled minor or major but doesn't include a changelog entry.

Action needed: Add a new blog post in website/blog/ to announce this change.

Example filename: website/blog/2025-10-20-feature-name.mdx

Alternatively: If this change doesn't require a changelog entry, remove the minor or major label.

github-actions[bot] avatar Oct 20 '25 22:10 github-actions[bot]

[!IMPORTANT]

Cloud Posse Engineering Team Review Required

This pull request modifies files that require Cloud Posse's review. Please be patient, and a core maintainer will review your changes.

To expedite this process, reach out to us on Slack in the #pr-reviews channel.

mergify[bot] avatar Oct 21 '25 00:10 mergify[bot]

💥 This pull request now has conflicts. Could you fix it @osterman? 🙏

mergify[bot] avatar Oct 21 '25 15:10 mergify[bot]