GCSS-1135: Add support for GitHub environment with deployment policy

README.md

@@ -43,4 +43,4 @@ To import a **forked** repository into the organization:
 > 📝 We are working on improving this so that the user has the same experience as when creating a new repo
 
 > [!IMPORTANT]
-> All important attributes are documented in the [Developer's Guide](DEVELOPERS_GUIDE.md).
+> All important attributes are documented in the [Developer's Guide](docs/DEVELOPERS_GUIDE.md).

DEVELOPERS_GUIDE.md → docs/DEVELOPERS_GUIDE.md

@@ -90,8 +90,43 @@ These are the primary configuration options for each repository.
 
 - **`vulnerability_alerts_enabled`**: *(optional, boolean)* If `true`, vulnerability alerts are enabled.
 
+- **`environments`**: *(optional, object[] [Environment](#environment-configuration))* Configuration for repository environments. Requires `feature_github_environment: true` in import config. When imported, environments are automatically managed by Terraform.
+
 - **`branch_protections_v4`**: *(optional, object[] [BranchProtectionV4](#branch-protection-configuration-v4))* Configuration for branch protection rules.
 
+## Environment Configuration
+
+Configure GitHub deployment environments with protection rules and reviewers.
+
+**Import Control**: Set `feature_github_environment: true` in `import-config.yaml` to import environments.
+
+### Environment Fields
+
+- **`environment`**: *(required, string)* Environment name
+- **`wait_timer`**: *(optional, int)* Delay in seconds (max 43200)
+- **`can_admins_bypass`**: *(optional, bool)* Admin bypass allowed (default: true)
+- **`prevent_self_review`**: *(optional, bool)* Prevent self-approval (default: false)
+- **`reviewers`**: *(optional, object)*
+  - **`users`**: *(string[])* GitHub usernames (max 6 total)
+  - **`teams`**: *(string[])* Team slugs (max 6 total)
+
+  > ⚠️ **IMPORTANT: Team Access Requirement**
+  >
+  > Teams specified as reviewers MUST have repository access first!
+  > - Manually grant access at: `https://github.com/{org}/{repo}/settings/access`
+  > - Verify team access at: `https://github.com/orgs/{org}/teams/{team}/repositories`
+  >
+  > **Without repository access, Terraform will apply successfully but teams won't be added as reviewers and next plan/apply will show them as proposed changes**
+
+- **`deployment_policy`**: *(optional, object)* Controls which branches/tags can deploy to this environment
+  - **`policy_type`**: *(required, string)* Must be one of:
+    - `"protected_branches"` - Only protected branches can deploy
+    - `"selected_branches_and_tags"` - Specific branch/tag patterns can deploy
+  - **`branch_patterns`**: *(optional, string[])* Branch patterns (e.g., `["main", "release/*"]`). Only used when `policy_type` is `"selected_branches_and_tags"`. Set to `null` or omit when using `"protected_branches"`
+  - **`tag_patterns`**: *(optional, string[])* Tag patterns (e.g., `["v*"]`). Only used when `policy_type` is `"selected_branches_and_tags"`. Set to `null` or omit when using `"protected_branches"`
+
+**📖 For complete guide with examples, see [FEATURE_GITHUB_ENVIRONMENT.md](FEATURE_GITHUB_ENVIRONMENT.md)**
+
 ## Template Configuration
 
 Options for configuring a repository from a template.
@@ -330,4 +365,4 @@ Options for configuring required status checks in V4.
 
 - **`strict`**: *(optional, boolean)* If `true`, strict status checks are enforced.
 
-- **`contexts`**: *(optional, string[])* A list of required status check contexts.
+- **`contexts`**: *(optional, string[])* A list of required status check contexts.

docs/FEATURE_GITHUB_ENVIRONMENT.md

@@ -0,0 +1,144 @@
+# GitHub Environments Configuration Guide
+
+This guide explains how to configure GitHub repository environments using the YAML → Terraform workflow.
+
+## Quick Start
+
+### Enable Environment Import
+```yaml
+# gcss-config-repo/config/import-config.yaml
+feature_github_environment: true  # Required to import environments
+```
+
+### Environment Configuration
+
+```yaml
+# repos/my-app.yaml
+environments:
+  # Option 1: Protected branches only
+  - environment: production
+    wait_timer: 300               # 5 minutes wait before deployment
+    can_admins_bypass: false      # Admins cannot bypass
+    prevent_self_review: true     # Cannot approve own deployments
+    reviewers:
+      users: ["octocat"]
+      teams: ["platform-team"]
+    deployment_policy:
+      policy_type: protected_branches
+
+  # Option 2: Custom branch/tag patterns
+  - environment: staging
+    deployment_policy:
+      policy_type: selected_branches_and_tags
+      branch_patterns:
+        - "release/*"
+        - "main"
+      tag_patterns:
+        - "v*"
+
+  # Option 3: Any branch can deploy (no restrictions)
+  - environment: development
+    # No deployment_policy = any branch can deploy
+```
+
+## ⚠️ Critical Rule: Deployment Policy Types
+
+**You MUST choose ONE of these options:**
+
+| Option | Configuration | Use Case |
+|--------|--------------|----------|
+| **Protected Branches** | `policy_type: protected_branches` | Production - only protected branches |
+| **Custom Patterns** | `policy_type: selected_branches_and_tags` + patterns | Staging - specific branches/tags |
+| **Any Branch** | Omit `deployment_policy` entirely | Development - no restrictions |
+
+**The `policy_type` field determines which patterns are used.**
+
+## Field Reference
+
+| Field | Type | Description | Default |
+|-------|------|-------------|---------|
+| `environment` | string | **Required** - Environment name | - |
+| `wait_timer` | int | Wait time in seconds (max 43200) | 0 |
+| `can_admins_bypass` | bool | Admins can bypass protections | true |
+| `prevent_self_review` | bool | Prevent self-approval | false |
+| `reviewers.users` | string[] | GitHub usernames (max 6 total with teams) | [] |
+| `reviewers.teams` | string[] | Team slugs (max 6 total with users) | [] |
+| `deployment_policy.*` | object | Deployment restrictions | - |
+| ↳ `policy_type` | string | `protected_branches` or `selected_branches_and_tags` | - |
+| ↳ `branch_patterns` | string[] | Branch patterns (only for `selected_branches_and_tags`) | [] |
+| ↳ `tag_patterns` | string[] | Tag patterns (only for `selected_branches_and_tags`) | [] |
+
+## Pattern Matching
+
+Patterns support wildcards:
+- `main` - Exact match
+- `release/*` - Matches `release/1.0`, `release/2.0`
+- `v*` - Matches `v1.0.0`, `v2.0.0`
+- `*-final` - Matches `1.0-final`, `2.0-final`
+
+## Generated Terraform Resources
+
+The YAML configuration generates:
+
+1. **Environment Resource**
+```hcl
+resource "github_repository_environment" "environment" {
+  environment = "production"
+  repository  = "my-app"
+  # ... other settings
+
+  deployment_branch_policy {
+    protected_branches     = true/false
+    custom_branch_policies = true/false
+  }
+}
+```
+
+2. **Deployment Policies** (for custom patterns)
+```hcl
+resource "github_repository_environment_deployment_policy" "branch_policies" {
+  repository     = "my-app"
+  environment    = "staging"
+  branch_pattern = "release/*"
+}
+
+resource "github_repository_environment_deployment_policy" "tag_policies" {
+  repository  = "my-app"
+  environment = "staging"
+  tag_pattern = "v*"
+}
+```
+
+## Complete Example
+
+```yaml
+environments:
+  - environment: production
+    wait_timer: 300
+    can_admins_bypass: false
+    prevent_self_review: true
+    reviewers:
+      teams: ["platform-team"]
+    deployment_policy:
+      policy_type: protected_branches
+
+  - environment: staging
+    prevent_self_review: true
+    deployment_policy:
+      policy_type: selected_branches_and_tags
+      branch_patterns: ["release/*", "main"]
+      tag_patterns: ["v*", "rc-*"]
+
+  - environment: development
+    # No restrictions - any branch can deploy
+```
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "reviewers: must be 6 or fewer" | Combined users + teams must be ≤ 6 |
+| Custom policies not working | Ensure `policy_type: selected_branches_and_tags` |
+| Deployment policies not created | Check `custom_branch_policies = true` in Terraform |
+
+For more configuration options, see [DEVELOPERS_GUIDE.md](DEVELOPERS_GUIDE.md)