GitHub + AWS User Management

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:

Resource	Description
Org membership	Adds users to your GitHub organization
Teams	Creates teams (Admin, ReadOnly, etc.)
Team membership	Assigns users to teams with appropriate roles
Repository permissions	Grants teams access to the repository

AWS IAM Identity Center

The configuration creates:

SSO Users

Creates users in IAM Identity Center with email, name, and group assignments.

SSO Groups

Pre-configured groups that map to permission levels:

Admin: Full administrative access
PowerUser: Developer access without IAM management
ReadOnly: View-only access for auditing

Permission Sets

AWS-managed policies attached to groups:

AdministratorAccess: Full AWS access
PowerUserAccess: Full access except IAM
ViewOnlyAccess: Read-only across services

Account Assignments

Groups are assigned to permission sets across all accounts (staging, production, shared, etc.).

Workflow

Edit users.yaml

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

Open a PR

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

Review

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

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

Decision	Rationale
YAML over UI	Version control, audit history, and code review for access changes.
IAM Identity Center over IAM users	Centralized identity, no long-lived credentials, integrates with external IdPs if needed later.
Matching group names	Cognitive simplicity: “Admin” means the same thing in GitHub and AWS.
PR-based workflow	Access changes get the same review process as code changes. No shadow IT.

About

Usage

The Problem

How Kube Starter Kit Addresses This

What’s Included

User Definition Format

GitHub Resources

AWS IAM Identity Center

Workflow

Example: Adding a New Team Member

Key Design Decisions

​The Problem

​How Kube Starter Kit Addresses This

​What’s Included

​User Definition Format

​GitHub Resources

​AWS IAM Identity Center

​Workflow

​Example: Adding a New Team Member

​Key Design Decisions

The Problem

How Kube Starter Kit Addresses This

What’s Included

User Definition Format

GitHub Resources

AWS IAM Identity Center

Workflow

Example: Adding a New Team Member

Key Design Decisions