GCSS-1135: Add support for GitHub environments with deployment policies

.github/workflows/tf-apply.yaml

@@ -58,8 +58,4 @@ jobs:
         env:
           TF_CLOUD_ORGANIZATION: ${{ inputs.tfc_org }}
           TF_WORKSPACE: ${{ vars.WORKSPACE }}
-        run: terraform apply -no-color -input=false ${{ steps.graformer.outputs.plan-file }}
-
-      - name: Clean up plan file
-        if: always() && steps.graformer.outputs.plan-file != ''
-        run: rm -f "${{ steps.graformer.outputs.plan-file }}"
+        run: terraform apply -no-color -input=false -auto-approve

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

@@ -100,29 +100,38 @@ These are the primary configuration options for each repository.
 
 - **`vulnerability_alerts_enabled`**: *(optional, boolean)* If `true`, vulnerability alerts are enabled.
 
-- **`branch_protections_v4`**: *(optional, object[] [BranchProtectionV4](#branch-protection-configuration-v4))* Configuration for branch protection rules.
-
-- **`high_integrity`**: *(optional, object [HighIntegrity](#high-integrity-configuration))* Expansion directives for high-integrity repositories. This field is consumed by the `expand` command and is **not** passed to Terraform — it is removed from the output after expansion.
+- **`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.
 
-## High Integrity Configuration
-
-Options for enabling high-integrity mode on a repository. This block is a pre-processing directive consumed by the `expand` command — it is **not** forwarded to Terraform.
+- **`branch_protections_v4`**: *(optional, object[] [BranchProtectionV4](#branch-protection-configuration-v4))* Configuration for branch protection rules.
 
-When `enabled` is `true`, the `expand` command automatically appends two rulesets to the repository's `rulesets` list:
+## Environment Configuration
 
-- **Protect main branch** — an active branch ruleset targeting `~DEFAULT_BRANCH` that enforces deletion protection, no fast-forward pushes, linear history, and a pull request review policy (1 approver, stale review dismissal on push, last-push approval required).
-- **Make tags immutable** — an active tag ruleset targeting `~ALL` that prevents deletion, non-fast-forward updates, and tag updates.
+### Environment Fields
 
-The `high_integrity` block is then removed from the expanded output.
+- **`environment`**: *(required, string)* Environment name
+- **`wait_timer`**: *(optional, int)* Delay in minutes (max 43200 or 30 days)
+- **`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)
 
-- **`enabled`**: *(required, boolean)* If `true`, the two high-integrity rulesets are injected during expansion.
+  > ⚠️ **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**
 
-Example:
+- **`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"`
 
-```yaml
-high_integrity:
-  enabled: true
-```
+**📖 For complete guide with examples, see [FEATURE_GITHUB_ENVIRONMENT.md](FEATURE_GITHUB_ENVIRONMENT.md)**
 
 ## Template Configuration
 
@@ -366,4 +375,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)