Skip to main content

​
The Problem

User management across multiple systems is a constant source of friction and security risk:
  • Multiple sources of truth: GitHub org membership in one place, AWS IAM users in another, SSO groups somewhere else. When someone joins or leaves, you’re updating multiple systems.
  • Permission drift: Over time, permissions accumulate. Temporary access grants become permanent without regular audits.
  • Audit complexity: Answering “who has access to production?” requires checking multiple systems and correlating information manually.
  • Onboarding/offboarding overhead: New hires need accounts created in multiple places. Departures require remembering all the places to revoke access.

​
How Kube Starter Kit Addresses This

I’ve built a unified user management system where a single YAML file drives both GitHub and AWS access: Single source of truth: One users.yaml file defines who has access to what. GitHub org membership, team assignments, AWS SSO users, and group memberships all flow from this one file. Declarative and auditable: Because it’s in version control, you have a complete history of access changes. Who added that user? Check the git log. What permissions did they have last month? Check the commit history. Consistent group model: The same logical groups (Admin, ReadOnly, etc.) map to both GitHub teams and AWS SSO groups by default. This keeps things simple initially, but the model is extensible to any set of permissions across platforms as your needs evolve. PR-based access changes: Adding a user or changing permissions is a pull request. It gets reviewed, approved, and automatically applied via Terraform.

​
What’s Included

​
User Definition Format

Users are defined in a single YAML file with both GitHub and AWS configuration: 
users:
  - github:
      username: jsmith
      role: member          # GitHub org role: admin or member
      teams:
        Admin:
          role: maintainer  # GitHub team role: maintainer or member
    aws:
      user_name: jane.smith
      email: jane@company.com
      group_membership: [Admin]
      given_name: Jane
      family_name: Smith

​
GitHub Resources

The Terraform configuration manages:
ResourceDescription
Org membershipAdds users to your GitHub organization
TeamsCreates teams (Admin, ReadOnly, etc.)
Team membershipAssigns users to teams with appropriate roles
Repository permissionsGrants teams access to the repository

​
AWS IAM Identity Center

The configuration creates:
Creates users in IAM Identity Center with email, name, and group assignments.
Pre-configured groups that map to permission levels:
  • Admin: Full administrative access
  • PowerUser: Developer access without IAM management
  • ReadOnly: View-only access for auditing
AWS-managed policies attached to groups:
  • AdministratorAccess: Full AWS access
  • PowerUserAccess: Full access except IAM
  • ViewOnlyAccess: Read-only across services
Groups are assigned to permission sets across all accounts (staging, production, shared, etc.).

​
Workflow

1

Edit users.yaml

Add a new user or modify permissions in the YAML file.
2

Open a PR

Terramate detects the changed stacks and runs terraform plan, showing exactly what will change.
3

Review

Team members review the access change. Clear diff of who’s getting what.
4

Merge

Changes are applied to both GitHub and AWS automatically.

​
Example: Adding a New Team Member

# Add to users.yaml
- github:
    username: newdev
    role: member
    teams:
      Admin:
        role: member
  aws:
    user_name: new.developer
    email: new@company.com
    group_membership: [Admin]
    given_name: New
    family_name: Developer
This single addition:
  • Invites newdev to your GitHub organization
  • Adds them to the Admin team with member permissions
  • Creates an AWS SSO user
  • Adds them to the Admin group with AdministratorAccess across all accounts

​
Key Design Decisions

DecisionRationale
YAML over UIVersion control, audit history, and code review for access changes.
IAM Identity Center over IAM usersCentralized identity, no long-lived credentials, integrates with external IdPs if needed later.
Matching group namesCognitive simplicity: “Admin” means the same thing in GitHub and AWS.
PR-based workflowAccess changes get the same review process as code changes. No shadow IT.