Plan: Entra ID & GitHub Teams Integration

Version: 1.0 Date: 2026-02-23 Status: Ready for Execution Related:

• Plan 01 Governance Model & Content Structure
• Plan 08 Automated Content Scaffolding
• CODEOWNERS Deferred
• Operating Model

NOTE

This file is a historical planning artifact, not the canonical current-state reference. The active ownership and review configuration is documented in docs/OWNERSHIP_MODEL.md. The rationale for separating plans from current-state governance docs is recorded in content/00 Governance/Decisions/09 Governance Documentation Separation.md.

1. Executive Summary

This plan implements the Phase 2 work deferred from Plan 01 — the creation of Microsoft Entra ID security groups, their synchronisation to GitHub Teams in the calab-ai organisation, and the activation of the .github/CODEOWNERS file for path-based code review enforcement.

Additionally, this plan:

• Establishes a Security Mgmt Practice (TECH-SEC-01) under GL04 Technology Guild
• Introduces product-level governance teams for Agent Primitives and NeuralOps
• Completes the full set of 6 Value Stream teams (Plan 01 originally listed only 3)
• Creates a reusable naming convention for Entra ID security groups across all governance levels

The Entra ID security groups are intentionally not GitHub-specific — they follow a sg-[governance-level]-[group-name] convention so the same groups can govern access to other systems (Azure DevOps, SharePoint, etc.) in the future.

Key Outcomes:

• 17 Entra ID security groups created and synced to GitHub Teams
• CODEOWNERS file activated with full path-based enforcement
• Security Mgmt Practice scaffolded with clear accountability boundaries
• Product-specific governance teams established
• All Plan 01 Phase 2 items completed

Critical Dependencies:

• Microsoft Entra ID tenant with admin access (Tylor Bunting / Ambit Kumar)
• GitHub Organisation admin access (calab-ai)
• Entra ID ↔ GitHub EMU or SCIM sync configured
• Executive Guild approval for team structure

2. Architecture / Context Overview

Governance Hierarchy → Entra Group Mapping

The Operating Model defines 5 governance levels. Each level maps to a distinct Entra ID security group prefix:

Naming Convention

sg-[governance-level]-[group-name]

Design Rationale: The sg- prefix identifies the object as a security group in Entra ID. The governance level makes it immediately clear what scope the group controls. The group name is the kebab-case version of the team’s human-readable name. This convention is system-agnostic — the same groups can be reused for Azure DevOps, SharePoint, Conditional Access, and other Entra-integrated systems.

Accountability Model (Security ↔ Platform Architecture)

A key architectural decision in this plan is the relationship between Security Mgmt and Platform Architecture:

┌─────────────────────────────┐     ┌──────────────────────────────────┐
│   Security Mgmt       │     │   Solution Eng Mgmt      │
│   (TECH-SEC-01)             │     │   (TECH-SOLARCH-01)              │
│                             │     │                                  │
│   Accountable for:          │     │   Accountable for:               │
│   - Security controls       │     │   - Solutions meeting business   │
│   - Security posture        │     │     use case requirements        │
│   - Security assessments    │     │                                  │
└───────────┬─────────────────┘     └──────────────┬───────────────────┘
            │                                      │
            │ Raises security concerns             │ Raises when solution
            │ requiring platform changes           │ requires new platform
            │                                      │ components
            ▼                                      ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                     Platform Architecture                    │
│                     (TECH-PLATARCH-01)                                   │
│                                                                         │
│   Accountable for:                                                      │
│   - Platform integrity when changes are required                        │
│   - Making everything work together                                     │
│   - Ensuring platform continues to operate after security/solution      │
│     engineering changes                                                 │
└─────────────────────────────────────────────────────────────────────────┘

Key Principle: Security Mgmt owns lower-level security controls and implementation. When a security concern requires changes to the platform, Security Mgmt raises it to Platform Architecture for guidance — similar to how Solution Eng raises platform component needs. Platform Architecture is accountable for ensuring the platform continues to operate when changes arise from either security or solution engineering.

3. Complete Team Registry

3.1 Company-Level Groups (3)

3.2 Guild-Level Groups (5)

3.3 Value Stream-Level Groups (6)

3.4 Product-Level Groups (2)

3.5 Practice-Level Groups (1)

Note: Additional practice-level groups (e.g., sg-practice-release-mgmt, sg-practice-architecture) should be created as needed when practices are staffed. The guild-level team provides fallback ownership until practice-specific teams are created.

4. Implementation Steps

All steps are sequential within each phase. Phase 1 is a manual prerequisite for Phases 2 and 3.

Phase 1 — Entra ID & GitHub Team Setup (Manual)

Owner: Tylor Bunting and Ambit Kumar Approval: Executive Guild

Step 1.1 — Create Entra ID Security Groups

Create all 17 security groups in Microsoft Entra ID using the naming convention sg-[governance-level]-[group-name].

Tasks:

1. Create the following security groups in Entra ID:

   Company-Level:

   • sg-guild-executive
   • sg-company-value-stream-owners
   • sg-company-product-owners

   Guild-Level:

   • sg-guild-executive
   • sg-guild-sales
   • sg-guild-delivery
   • sg-guild-technology
   • sg-guild-administration

   Value Stream-Level:

   • sg-vs-team-vs01-hthp
   • sg-vs-team-vs02-dtdp
   • sg-vs-team-vs03-rtrl
   • sg-vs-team-vs04-itrs
   • sg-vs-team-vs06-ctmk
   • sg-vs-team-vs07-stex

   Product-Level:

   • sg-product-pd02-agtp
   • sg-product-pd01-nlps

   Practice-Level:

   • sg-practice-security

2. For each group, set the description to match the GitHub Team purpose (see Section 3)

3. Add initial members to each group based on current organisational assignments

Deliverable: All 17 Entra ID security groups created and populated.

Verification:

• Each group appears in Entra ID portal with correct naming
• Group descriptions match governance purpose
• At least one member assigned to each active group

Step 1.2 — Sync Entra Groups to GitHub Teams

Configure Entra ID ↔ GitHub synchronisation and verify all 17 teams appear in the calab-ai GitHub organisation.

Tasks:

1. Ensure Entra ID → GitHub EMU/SCIM sync is configured for the calab-ai organisation

2. Map each Entra security group to its corresponding GitHub Team:

   Entra Security Group	GitHub Team Slug
   sg-guild-executive	guild-executive
   sg-company-value-stream-owners	owners-value-stream
   sg-company-product-owners	owners-product
   sg-guild-executive	guild-executive
   sg-guild-sales	guild-sales
   sg-guild-delivery	guild-delivery
   sg-guild-technology	guild-technology
   sg-guild-administration	guild-administration
   sg-vs-team-vs01-hthp	vs-team-vs01-hthp
   sg-vs-team-vs02-dtdp	vs-team-vs02-dtdp
   sg-vs-team-vs03-rtrl	vs-team-vs03-rtrl
   sg-vs-team-vs04-itrs	vs-team-vs04-itrs
   sg-vs-team-vs06-ctmk	vs-team-vs06-ctmk
   sg-vs-team-vs07-stex	vs-team-vs07-stex
   sg-product-pd02-agtp	product-pd02-agtp
   sg-product-pd01-nlps	product-pd01-nlps
   sg-practice-security	practice-team-security

3. Grant each team Write permission on the calab-handbook repository

4. Verify team membership syncs correctly from Entra ID

Deliverable: All 17 GitHub Teams visible in calab-ai organisation with synced membership.

Verification:

• Run gh api orgs/calab-ai/teams --paginate | jq '.[].slug' and verify all 17 slugs appear
• Spot-check 3-4 teams to verify membership matches Entra ID group membership
• Verify teams appear in repository Settings → Collaborators & teams

Phase 2 — Security Mgmt Practice (Automated/Build Agent)

Owner: Build Agent Prerequisite: None (can run in parallel with Phase 1)

Step 2.1 — Scaffold Security Mgmt Practice

Create the Security Mgmt Practice under GL04 Technology Guild using the standard practice folder structure.

Practice Specification:

Tasks:

1. Create the standard practice folder structure:

   content/02 Guilds/GL04 Technology Guild/Practices/Security Mgmt/
   ├── README.md
   ├── 01 Policies/
   │   └── .gitkeep
   ├── 02 Processes/
   │   └── .gitkeep
   ├── 03 Procedures/
   │   └── .gitkeep
   ├── 04 Guides/
   │   └── .gitkeep
   ├── 05 Templates/
   │   └── .gitkeep
   └── metadata/
       ├── diagrams/
       │   └── .gitkeep
       ├── plans/
       │   └── .gitkeep
       └── specs/
           └── .gitkeep
   

2. Populate README.md with the following content:

   Frontmatter:

   ---
   publish: false
   page-status: draft
   created: 2026-02-23
   owner: security-lead
   practice-id: TECH-SEC-01
   guild: GL04 Technology Guild
   type: practice-overview
   ---

   Scope — In Scope:

   • Security controls design, implementation, and monitoring
   • Security risk assessments and vulnerability management
   • Access control policies and identity governance
   • Security incident response procedures and playbooks
   • Compliance controls and audit readiness
   • Security awareness training and phishing simulations
   • Application security review and secure coding standards
   • Third-party security assessments and vendor risk management

   Scope — Out of Scope:

   • Platform architecture changes required by security findings (escalate to Platform Architecture)
   • Solution design decisions with security implications (coordinate with Solution Eng)
   • Day-to-day infrastructure operations (owned by operations teams)
   • Business continuity planning (owned by Strategy Mgmt, GL01)

   Dependencies (Practices We Depend On):

   • Platform Architecture (TECH-PLATARCH-01) — When security concerns require platform-level changes, Security Mgmt raises to Platform Architecture for guidance on implementation
   • Software Eng (TECH-SE-01) — Secure coding standards, code review security requirements, SAST/DAST integration

   Dependents (Practices That Depend On Us):

   • Solution Eng (TECH-SOLARCH-01) — Security requirements and constraints for solution designs
   • Platform Architecture (TECH-PLATARCH-01) — Security architecture patterns and compliance requirements
   • All practices — Security policies apply organisation-wide

   KPIs:

   • KPI 1: Mean time to remediate critical vulnerabilities (Target: ≤72 hours)
   • KPI 2: Security assessment coverage of active products (Target: ≥90%)
   • KPI 3: Security incidents per quarter (Target: 0 critical, ≤2 high)
   • KPI 4: Security training completion rate (Target: 100% annually)

Deliverable: Fully scaffolded Security Mgmt practice with populated README.

Verification:

• All 10 files/folders exist per the standard schema
• README.md contains all required sections
• Practice ID TECH-SEC-01 is unique (no collision with existing practice IDs)
• Frontmatter has page-status: draft and correct practice-id

Step 2.2 — Update Platform Architecture Interface

Update the Platform Architecture README to reference the new Security Mgmt practice and clarify the accountability boundary.

Tasks:

1. In content/02 Guilds/GL04 Technology Guild/Practices/Platform Architecture/README.md:

   • Update In Scope to clarify that “Security architecture and implementation” means platform-level security architecture integration (not security controls ownership)
   • Add Security Mgmt (TECH-SEC-01) to the Dependents section
   • Add Security Mgmt to the Dependencies section (security requirements inform platform architecture)
   • Add Security Mgmt to Related Practices
   • Add a cross-reference note in the Key Processes section

2. Update the change log to reflect the interface addition

Deliverable: Platform Architecture README updated with Security Mgmt cross-references.

Verification:

• README mentions Security Mgmt in Dependencies, Dependents, and Related Practices
• In Scope wording clarifies the boundary (platform-level security architecture vs. security controls)
• Change log entry added

Step 2.3 — Update GL04 Technology Guild Overview

Add Security Mgmt to the GL04 overview’s list of practices and related resources.

Tasks:

1. The page-list component in content/02 Guilds/GL04 Technology Guild/README.md auto-discovers practices — verify Security Mgmt appears after scaffolding
2. Add VS04 Incident to Resolution as a related resource (security is closely tied to incident management)

Deliverable: GL04 Overview reflects the new Security Mgmt practice.

Verification:

• page-list component will auto-include Security Mgmt (no manual list update needed)
• Related Resources section includes VS04 link

Phase 3 — CODEOWNERS & Documentation Updates (Automated/Build Agent)

Owner: Build Agent Prerequisite: Phase 1 complete (teams must exist in GitHub for CODEOWNERS to function)

Step 3.1 — Create CODEOWNERS File

Create .github/CODEOWNERS with all 17 teams mapped to their content paths.

Tasks:

1. Create .github/CODEOWNERS with the following content:

   # CODEOWNERS — Calab.ai Handbook
   # Managed in coordination with Entra ID security groups.
   # See: docs/CODEOWNERS_DEFERRED.md for governance context.
   # See: content/metadata/plans/10 Entra ID & GitHub Teams Integration/README.md
   
   # ─── Company Governance ─────────────────────────────────────────────
   # Executive Guild owns governance docs and archive
   /content/00 Governance/** @calab-ai/guild-executive
   
   # ─── Value Streams ──────────────────────────────────────────────────
   # Specific VS teams override the general owners-value-stream fallback
   /content/01 Value Streams/VS01 Hire to High Performer/** @calab-ai/vs-team-vs01-hthp
   /content/01 Value Streams/VS02 Discovery to Deployment/** @calab-ai/vs-team-vs02-dtdp
   /content/01 Value Streams/VS03 Request to Release/** @calab-ai/vs-team-vs03-rtrl
   /content/01 Value Streams/VS04 Incident to Resolution/** @calab-ai/vs-team-vs04-itrs
   /content/01 Value Streams/VS06 Capability to Market/** @calab-ai/vs-team-vs06-ctmk
   /content/01 Value Streams/VS07 Strategy to Execution/** @calab-ai/vs-team-vs07-stex
   /content/01 Value Streams/** @calab-ai/owners-value-stream
   
   # ─── Guilds ─────────────────────────────────────────────────────────
   # Guild teams own all content under their guild folder
   # Practice-specific teams can override (see below)
   /content/02 Guilds/GL01 Executive Guild/** @calab-ai/guild-executive
   /content/02 Guilds/GL02 Sales Guild/** @calab-ai/guild-sales
   /content/02 Guilds/GL03 Delivery Guild/** @calab-ai/guild-delivery
   /content/02 Guilds/GL04 Technology Guild/** @calab-ai/guild-technology
   /content/02 Guilds/GL05 Administration Guild/** @calab-ai/guild-administration
   
   # ─── Practice-Specific Overrides ────────────────────────────────────
   # These override the guild-level ownership for specific practices
   /content/02 Guilds/GL04 Technology Guild/Practices/Security Mgmt/** @calab-ai/practice-team-security
   
   # ─── Products ───────────────────────────────────────────────────────
   # Product-specific teams override the general owners-product fallback
   /content/03 Products/Agent Primitives/** @calab-ai/product-pd02-agtp
   /content/03 Products/NeuralOps/** @calab-ai/product-pd01-nlps
   /content/03 Products/** @calab-ai/owners-product
   
   # ─── Archive ────────────────────────────────────────────────────────
   # Executive Guild only — prevents accidental restoration
   /content/99 Archive/** @calab-ai/guild-executive
   

2. Update scripts/update-codeowners.mjs INITIAL_CODEOWNERS template to match the new structure (so future scaffolding operations remain consistent)

Rules:

• More specific paths take precedence (CODEOWNERS last-match-wins)
• Practice paths override Guild paths
• Product-specific paths override general owners-product
• VS-specific paths override general owners-value-stream
• Company Governance and Archive restricted to Executive Guild

Deliverable: CODEOWNERS file created with all 17 teams.

Verification:

• File passes GitHub CODEOWNERS syntax validation (no syntax errors on push)
• Test a PR touching content/02 Guilds/GL04 Technology Guild/Practices/Security Mgmt/README.md — reviewer should be @calab-ai/practice-team-security
• Test a PR touching content/01 Value Streams/VS02 Discovery to Deployment/README.md — reviewer should be @calab-ai/vs-team-vs02-dtdp
• Test a PR touching content/03 Products/Agent Primitives/README.md — reviewer should be @calab-ai/product-pd02-agtp

Step 3.2 — Update CODEOWNERS_DEFERRED.md

Update docs/CODEOWNERS_DEFERRED.md to reflect that Phase 2 is now in progress/complete.

Tasks:

1. Update status from “PARTIALLY ADDRESSED” to “IMPLEMENTED”
2. Add the 4 missing VS teams (VS02, VS04, VS06, VS07)
3. Add the 2 product-level teams (product-pd02-agtp, product-pd01-nlps)
4. Add the Security Mgmt practice team (practice-team-security)
5. Update the CODEOWNERS file structure section to match the actual file
6. Update the Next Steps section to reflect completion
7. Add reference to Plan 10

Deliverable: CODEOWNERS_DEFERRED.md fully updated.

Verification:

• All 17 teams listed
• Status reflects current implementation state
• References Plan 10

Step 3.3 — Update Plan 01 Documents

Update Plan 01’s README.md, DECISIONS_SUMMARY.md, and CLARIFICATIONS_NEEDED.md to reflect that the deferred CODEOWNERS/Teams work is now being addressed by Plan 10.

Tasks:

1. README.md — Update Step 5 status annotation to reference Plan 10:

   • Add note: “Implemented by Plan 10 — Entra ID & GitHub Teams Integration”
   • Update the Appendix C team list to note it’s now superseded by Plan 10’s complete registry

2. DECISIONS_SUMMARY.md — Update Decision #3 (GitHub Teams):

   • Change status from “Deferred to Separate Phase” to “Addressed by Plan 10”
   • Add cross-reference to Plan 10

3. CLARIFICATIONS_NEEDED.md — Update Question #3 (GitHub Teams):

   • Mark as resolved
   • Add note about Entra ID integration being implemented via Plan 10

Deliverable: Plan 01 documents updated with Plan 10 cross-references.

Verification:

• All references to “deferred” or “future phase” in context of CODEOWNERS/Teams now point to Plan 10
• No stale status indicators

Step 3.4 — Update Product Overview Files

Add product-specific governance team references to the Agent Primitives and NeuralOps overview files.

Tasks:

1. content/03 Products/Agent Primitives/README.md:

   • Add **GitHub Team:** \@calab-ai/product-pd02-agtp“ to the Current Status section
   • Add **Entra Group:** \sg-product-pd02-agtp“ below it

2. content/03 Products/README.md:

   • Update Governance section to mention product-specific teams
   • Add note about Entra ID group naming convention

Deliverable: Product overviews include team references.

Verification:

• Agent Primitives overview references @calab-ai/product-pd02-agtp
• Products overview mentions product-specific governance teams

Step 3.5 — Update Repository Structure Documentation

Update docs/REPOSITORY_STRUCTURE.md to reflect the active Entra ID integration and CODEOWNERS enforcement.

Tasks:

1. Update references to Entra ID from “future” to “active”
2. Document the security group naming convention
3. Add section on CODEOWNERS enforcement rules

Deliverable: Repository structure documentation reflects current state.

Verification:

• No references to Entra ID as “future” or “planned”
• Naming convention documented

5. Risk Assessment

6. Success Criteria

Implementation successful when:

• ✅ All 17 Entra ID security groups created with correct naming convention
• ✅ All 17 GitHub Teams synced from Entra ID and visible in calab-ai organisation
• ✅ .github/CODEOWNERS file created with all 17 teams mapped to content paths
• ✅ Test PR confirms correct reviewer assignment for at least 3 different content paths
• ✅ Security Mgmt Practice (TECH-SEC-01) scaffolded under GL04 with populated README
• ✅ Platform Architecture README updated with Security Mgmt cross-references
• ✅ docs/CODEOWNERS_DEFERRED.md updated to reflect implementation
• ✅ Plan 01 documents cross-reference Plan 10
• ✅ Product overview files reference product-specific teams
• ✅ scripts/update-codeowners.mjs template updated to match new CODEOWNERS structure
• ✅ No broken Obsidian links introduced

7. Appendices

A. Future Practice-Level Teams

When new practices are staffed, the following Entra security groups and GitHub Teams should be created following the same convention:

Process for adding new practice teams:

1. Create Entra ID security group following sg-practice-[name] convention
2. Sync to GitHub Team in calab-ai organisation
3. Add CODEOWNERS entry using scripts/update-codeowners.mjs or scaffolding automation
4. Update docs/CODEOWNERS_DEFERRED.md if relevant

B. Entra Group Naming Convention Reference

sg-company-*           → Company-level governance groups
sg-guild-*             → Guild-level groups (one per guild)
sg-vs-team-*                → Value Stream groups (one per VS)
sg-product-*           → Product groups (one per product)
sg-practice-*          → Practice-specific groups (created as needed)

Rules:

• Always lowercase
• Use hyphens for multi-word names
• Keep group names concise but descriptive
• Description field must explain the group’s governance purpose
• Groups are system-agnostic (not GitHub-specific)

C. Escalation Paths (from Operating Model)

D. CODEOWNERS Precedence Rules

GitHub CODEOWNERS uses last-match-wins semantics. The file is ordered so that:

1. Most specific paths (practice-level, product-specific) appear after their parent paths
2. Fallback paths (owners-value-stream, owners-product) appear after specific VS/product paths
3. This means a change to content/02 Guilds/GL04 Technology Guild/Practices/Security Mgmt/README.md will assign @calab-ai/practice-team-security as reviewer (not @calab-ai/guild-technology)

Important: When adding new CODEOWNERS entries, always place more-specific paths after less-specific ones.

Approved by: Tylor Bunting Date: 2026-02-23 Next Action: Phase 1 — Create Entra ID security groups (Tylor Bunting / Ambit Kumar)