feat: Add GitHub Environments support with feature flag architecture

[ljuboops257]

Add GitHub Environment Support with Improved Deployment Policy Structure

This PR adds support for GitHub repository environments and introduces a cleaner, more intuitive deployment policy structure throughout the codebase.

Key Changes

🚀 New Feature: GitHub Environments

• Terraform Module: Added support for managing GitHub environments with deployment policies, reviewers, and protection rules
• Importer Tool: Can now import existing GitHub environment configurations when enabled
• Deployment Policies: Three supported modes:
  • protected_branches - Only protected branches can deploy
  • selected_branches_and_tags - Specific branch/tag patterns can deploy
  • No policy - Any branch can deploy

🎛️ Feature Flag System

• New Configuration: import-config.yaml now supports feature flags
• Enable with: feature_github_environment: true
• Default: All features disabled (backward compatible)
• Architecture: Config-driven, no CLI changes needed

  # gcss-config-repo/config/import-config.yaml
  feature_github_environment: true  # Enable environment import

📝 Environment Configuration Structure

  environments:
    - environment: production
      wait_timer: 300
      can_admins_bypass: false
      prevent_self_review: true
      reviewers:
        users: ["octocat"]
        teams: ["platform-team"]  # ⚠️ Teams must have repo access
      deployment_policy:
        policy_type: protected_branches

    - environment: staging
      deployment_policy:
        policy_type: selected_branches_and_tags
        branch_patterns: ["main", "release/*"]
        tag_patterns: ["v*"]

🔧 Implementation Details

Importer Changes:

• Added FeatureGithubEnvironment constant
• Feature check: cfg.IsFeatureEnabled(FeatureGithubEnvironment)
• Fetches environment data from GitHub API including deployment policies
• Generates YAML with new deployment_policy structure

Terraform Changes:

• Dynamic environment resources based on YAML configuration
• Handles deployment branch policies via separate resources
• Import blocks for existing environments

📚 Documentation

• feature_github_environment.md: Complete guide for environment configuration
• ADDING_FEATURES.md: How to add new feature-flagged functionality
• LOCAL_DEVELOPMENT_SETUP.md: Updated with environment examples
• GITHUB_ACTIONS_WORKFLOWS.md: New comprehensive workflow documentation
• DEVELOPERS_GUIDE.md: Environment field reference

How to Use

  1. Enable the feature:
    # import-config.yaml
    feature_github_environment: true
  2. Import existing repos with environments:
    just import-repo org/repo
  3. Or add environments to new repos:
    # repos/my-repo.yaml
    environments:
      - environment: production
        deployment_policy:
          policy_type: protected_branches

🔄 Migration

• All existing YAML configurations updated to new structure
• Backward compatibility not required (clean implementation)
• Feature flag feature_github_environment: true controls environment import

Testing

• ✅ Feature flag system working (disabled by default)
• ✅ Environment import from GitHub API
• ✅ Terraform resource creation and management
• ✅ All documentation updated

Important Notes

• Feature is opt-in via feature_github_environment: true
• Teams in reviewers must have repository access first
• Maximum 6 combined users + teams as reviewers (GitHub limitation)

---

This PR adds GitHub environment support as a new, feature-flagged capability that can be gradually rolled out without affecting existing workflows.

References

• Terraform GitHub Provider - Environments
• Terraform GitHub provider - Deployment policy
• GitHub API - Environments
• GitHub Actions - Deployment Environments