Template Structure: Reusable vs Configurable¶

Understand what's generic (reusable for all orgs) vs what needs customization per organization

🟢 REUSABLE COMPONENTS (Same for all organizations)¶

These components are completely generic and work identically for any organization without modification.

PowerShell Scripts (`automation/` & `scripts/`)¶

✅ export_all_groups.ps1 - Export group configurations
✅ export_group_members.ps1 - Export group membership lists
✅ export_shared_drive_acls.ps1 - Export Shared Drive permissions
✅ generate_id_mapping.ps1 - Generate ID mapping files
✅ All GAM wrapper scripts - Reusable for any domain/org

Why reusable: These scripts use variables ({DOMAIN}, etc.) instead of hardcoded values. They work by accepting parameters or reading from environment.

GAM Commands (`docs/gam-commands.md`)¶

✅ User creation commands
✅ Group management commands
✅ Shared drive provisioning commands
✅ Email forwarding setup
✅ Security policy enforcement

Why reusable: GAM syntax is standardized. Commands reference placeholders like {DOMAIN}, {USER_EMAIL}, etc.

Documentation Structure (`docs/`)¶

✅ index.md - Main documentation page (customizable title/intro)
✅ migration-playbook.md - Generic migration steps
✅ gam-commands.md - GAM command reference
✅ troubleshooting.md - Generic troubleshooting
✅ TEMPLATE_*.md - Template documentation

Why reusable: Structure is the same; content is mostly generic with customizable sections.

MkDocs Setup (`mkdocs.yml`, `docs/` structure)¶

✅ MkDocs configuration (except site name/URL)
✅ Material theme configuration
✅ Navigation structure
✅ Build/deployment process

Why reusable: MkDocs setup is standard. Only the site name and org-specific URLs change.

GitHub Actions / Workflows (`.github/workflows/`)¶

✅ MkDocs deployment workflow
✅ GAM validation workflows
✅ Script testing workflows

Why reusable: Workflows are generic CI/CD patterns; they don't reference org-specific values.

Data Structure Template (`data/structure.json`)¶

✅ Folder hierarchy template
✅ Group definitions template
✅ User role structure

Why reusable: This is a template for structure. Each org customizes folder names, group names, etc.

🟡 PARTIALLY CONFIGURABLE (Template structure reusable, values customizable)¶

These need one-time customization per organization, but the approach is reusable.

User List & Group Definitions¶

Reusable: The process of creating users and groups
Customizable: - User names, emails, roles - Group names and members - Department/role definitions - Email forwarding rules

How: Templates with {PLACEHOLDER} values replaced during setup.

Email Group Setup¶

Reusable: GAM commands and scripts that create groups
Customizable: - Group email addresses (must match org domain) - Group membership - Group display names - Group descriptions

Shared Drive Configuration¶

Reusable: GAM provisioning scripts
Customizable: - Drive names - Drive structure (folder hierarchy) - Access permissions per role - Shared drive managers

Security Policies¶

Reusable: Policy templates and enforcement scripts
Customizable: - Password requirements (length, complexity) - 2FA enforcement level - Session timeout settings - IP restrictions (if any)

Documentation Content¶

Reusable: Documentation structure and style
Customizable: - Organization name in all docs - Contact information - Custom procedures - Organization-specific sections

🔴 NEVER IN REPOSITORY (Secrets & Credentials)¶

These should NEVER be committed to Git, ever.

Google Cloud Credentials¶

❌ gam.cfg - Contains OAuth2 tokens for GAM
❌ oauth2.json - Google API authentication
❌ oauth2.txt - GAM authentication tokens
❌ Service account keys
❌ Any .key or .pem files

Organization Secrets¶

❌ Real user passwords
❌ Admin account passwords
❌ API keys
❌ Service account credentials
❌ Encryption keys

Generated/Sensitive Data¶

❌ User lists with passwords
❌ Access control reports with sensitive info
❌ Any .csv files with personal data
❌ Audit logs
❌ Usage reports

See .gitignore for complete list of ignored files.

📋 Customization Checklist¶

When adapting this template for a new organization, modify ONLY:

Phase 1: Configuration (Required)¶

[ ] .env.example → Copy to .env with real values (don't commit .env)
[ ] {ORG_NAME} → Organization's actual name
[ ] {DOMAIN} → Organization's email domain
[ ] {ADMIN_EMAIL} → Primary admin email
[ ] {GCP_PROJECT_ID} → Google Cloud project ID

Phase 2: Documentation (Recommended)¶

[ ] docs/index.md - Update organization branding
[ ] README.md - Update org-specific sections
[ ] docs/ORGANIZATION_SETUP_GUIDE.md - Customize steps

Phase 3: User/Group Structure (Required)¶

[ ] Define users and roles
[ ] Define email groups
[ ] Define shared drive structure
[ ] Define security roles

Phase 4: Org-Specific Procedures (Optional)¶

[ ] Add organization-specific SOP documents
[ ] Add custom email templates
[ ] Add organization-specific security policies
[ ] Add custom workflows

What NOT to Modify¶

❌ GAM command syntax
❌ PowerShell script logic
❌ MkDocs structure
❌ GitHub workflow logic
❌ Core automation frameworks

📊 File-by-File Guide¶

File/Folder	Reusable?	How to Customize
`README.md`	Partially	Update org name, links
`docs/`	Partially	Replace placeholders, add org docs
`automation/`	✅ Fully	Use as-is; configure via .env
`scripts/`	✅ Fully	Use as-is; configure via .env
`data/structure.json`	Partially	Update folder/group names
`templates/`	Partially	Update email templates with org name
`mkdocs.yml`	Partially	Update site name, org URL
`.gitignore`	✅ Fully	Use as-is
`.env.example`	Partially	Copy & fill with real values
`examples/`	Reference	Use as setup reference

🔄 Workflow for Onboarding New Organizations¶

Clone template → git clone https://github.com/Golfklubb-IT/workspace-setup-template.git OrgName-workspace
Create new GitHub repo → Push to OrgName-workspace repository
Run setup script → .\scripts\setup-new-org.ps1 to replace all placeholders
Customize user/group structure → Update data/ files
Review documentation → Update docs/ for org-specific info
Test in staging → Verify all settings before production
Deploy → Execute automation scripts with validated configuration
Document handoff → Create org-specific runbooks and guides

🎯 Key Principle¶

Template code = 95% reusable
Template configuration = 100% customizable

All organization-specific values use placeholders. The setup script automates replacement, so you rarely edit code directly—you just fill in configuration values.