IAM-as-Code: Why Your GitHub Org Permissions Are a Liability If They're Not in Code

Your GitHub Org Is Probably Over-Permissioned Right Now

Here's a question most engineering leaders can't answer: Who has admin access to your production repositories, and why?

If that question makes you uncomfortable, you're not alone. Most GitHub organizations — even well-run ones — manage permissions through the UI. Someone needs access, an admin clicks a few buttons, and the change is made. No audit trail beyond GitHub's own logs. No review process. No way to detect when permissions drift from what they should be.

I managed a GitHub Enterprise platform serving 500+ developers at a Fortune 500 energy company. At that scale, UI-based permission management isn't just inconvenient — it's a genuine security liability. The Verizon Data Breach Investigations Report consistently finds that credential misuse and privilege abuse are among the top vectors in real-world breaches. Over-permissioned access is the silent risk that nobody audits until something goes wrong.

The fix isn't better UI workflows. It's treating permissions the same way we treat infrastructure: as code.

📬 Want the complete implementation? Newsletter Issue #3 has the real Terraform configs, GitHub Actions workflows, and IssueOps templates. Subscribe to the newsletter to get the step-by-step guide.

What IAM-as-Code Actually Means for GitHub

IAM-as-Code means your GitHub organization's permission model — teams, roles, repository access, branch protections, CODEOWNERS — lives in version-controlled configuration files. Not in someone's head. Not in a Confluence page that's six months stale. In code that's reviewed, tested, and applied through CI/CD.

The concept isn't new. We've been doing Infrastructure as Code with Terraform for years. The DORA State of DevOps Report consistently links IaC practices to higher-performing organizations. But most teams stop at cloud resources. They'll Terraform their AWS accounts, their Kubernetes clusters, their databases — then manage GitHub permissions by clicking around in the org settings UI.

That gap is where risk lives.

Here's what a codified permission model covers:

• Team structure — who belongs to which teams, mapped from your identity provider
• Repository access — which teams get read, write, or admin on each repo
• Branch protections — required reviews, status checks, merge restrictions
• Custom organization roles — GitHub's fine-grained role system lets you define exactly which permissions each role grants
• CODEOWNERS — automated review assignments tied to team ownership
• Approval workflows — IssueOps patterns where access changes go through a structured request-and-approve process

The Terraform GitHub provider makes most of this declarative. You define the desired state, Terraform figures out what to change. HashiCorp even has a tutorial on managing GitHub users and teams that walks through the basics.

The Three Problems This Solves

1. Permission Drift

Permissions drift constantly. Someone gets temporary admin access for a migration and never loses it. A contractor's team membership persists months after their engagement ends. A branch protection rule gets disabled for a hotfix and nobody re-enables it.

Without code as the source of truth, you have no baseline to drift from. With IAM-as-Code, drift detection is just terraform plan — if the actual state doesn't match the declared state, you see it immediately.

2. Audit and Compliance

When a security team asks "who had write access to repo X on March 15th?" you should be able to answer that from your git history. Every permission change is a commit. Every commit has an author, a reviewer, a timestamp, and a reason in the PR description.

This is the same principle I wrote about in cryptographic approval gates for AI agents — the audit trail isn't an afterthought, it's built into the change process. GitHub's own safe-settings tool demonstrates this pattern: policy-as-code for org-wide repository settings, enforced through a central admin repo.

3. The AI Agent Problem

This is the one nobody's talking about yet, and it's getting critical fast.

AI coding agents — including GitHub Copilot coding agent — now push commits, create branches, and open pull requests. They operate with whatever permissions their service account or token has. If your permission model is "everyone gets write access to everything," your AI agents inherit that sprawl.

I covered this in depth in my piece on governed git for AI agents — the core argument is that AI agents need more governance than humans, not less. The principle of least privilege isn't optional when non-human actors are making thousands of changes per week. Stripe's engineering team reported their AI agents producing 1,300+ PRs per week — imagine that volume with over-permissioned service accounts.

IAM-as-Code gives you the foundation to scope agent permissions tightly: specific repos, specific branches, specific actions. And because it's in code, you can evolve those permissions as your agent architecture matures.

🔒 Newsletter subscribers get the actual implementation — permission manifest files, drift detection CI configs, IssueOps approval templates, and the enterprise patterns I used across a 500-developer org. Subscribe to the newsletter to get Issue #3.

The Implementation Stack (Overview)

The full implementation involves four layers — I'm giving you the architecture here; the newsletter issue has the production configs.

1. Permission Manifests — YAML or HCL files declaring your team structure, repo access, and branch protections. These are your source of truth.

2. Terraform Modules — The GitHub Terraform provider translates those manifests into API calls. Resources like github_team, github_team_repository, github_branch_protection, and github_repository_collaborators cover the full surface area.

3. Drift Detection CI — A scheduled GitHub Actions workflow that runs terraform plan and alerts when actual state diverges from declared state. This is your continuous audit.

4. IssueOps Approval Flow — GitHub's own engineering team uses IssueOps for operational workflows. Permission requests come in as Issues, get approved via comments, and trigger Terraform applies through Actions.

This is the same spec-driven, test-first approach to Terraform I've written about before — your permission specs are your tests. If terraform plan shows unexpected changes, something drifted.

Why This Matters Now

The convergence of three trends makes IAM-as-Code urgent:

AI agents are multiplying. Every team adopting GitHub Copilot, coding agents, or custom automation is adding non-human actors to their org. Each one needs scoped, auditable permissions.

Compliance requirements are tightening. SOC 2, ISO 27001, FedRAMP — they all want evidence of access control. Git history is the cleanest evidence you can provide.

Scale breaks manual processes. The platform I built served 400+ repositories across dozens of teams. No human can manually audit that permission surface. Code can.

If you read yesterday's piece on why AI agents keep forgetting everything, you know I'm building toward a complete picture of production-grade agent infrastructure. IAM-as-Code is the security layer. Memory systems are the knowledge layer. Governed git is the workflow layer. They're all connected.

The Bottom Line

Your GitHub org permissions are either in code or they're a liability. There's no middle ground at enterprise scale.

The good news: the tooling exists today. Terraform, GitHub Actions, CODEOWNERS, custom org roles, IssueOps — the pieces are all there. What's been missing is a clear pattern for connecting them into a cohesive IAM-as-Code practice.

📬 This was the overview. Newsletter Issue #3 has the step-by-step implementation with production Terraform configs, CI workflows, and IssueOps templates. Subscribe now to get the complete guide.

If you're building agent systems and want the enterprise governance patterns, the Agentic Development Blueprint covers the full architecture — from agent harnesses to permission models. And if you're specifically interested in how memory and IAM intersect for AI agents, Blueprint #3: The 4-Tier Agent Memory System just got a new Chapter 10 on IAM-as-Code for agent platforms.

Your infrastructure is in code. Your CI/CD is in code. Your monitoring is in code. It's time your permissions caught up.