Feat: Improved Structure

.checkov.yaml

@@ -0,0 +1,14 @@
+# Checkov configuration for GitLab Groups Terraform Module
+framework:
+  - terraform
+
+# Skip checks that conflict with Terraform Registry best practices
+skip-check:
+  - CKV_TF_1  # Allow semantic versioning for registry modules
+
+# Only run relevant checks for this module
+check:
+  - CKV_TF_2   # Ensure Terraform module sources use a tag
+  - CKV_TF_3   # Ensure Terraform module sources do not use HTTP
+  - CKV_GLB_*  # GitLab specific checks
+  - CKV_GIT_*  # Git security checks

.github/contributing.md

@@ -0,0 +1,67 @@
+# Contributing to GitLab Groups Terraform Module
+
+Thank you for your interest in contributing to the GitLab Groups Terraform module! We welcome contributions that help improve the module's functionality, documentation, and examples.
+
+## Getting Started
+
+Before making changes, please:
+
+1. Open an issue to discuss your proposed changes
+2. Fork the repository and create a feature branch
+3. Ensure you have Terraform >= 1.3.0 installed
+4. Have access to a GitLab instance for testing
+
+## Development Setup
+
+```bash
+# Clone your fork
+git clone https://github.com/YOUR_USERNAME/terraform-gitlab-groups
+cd tf-gitlab-groups
+
+# Create a feature branch
+git checkout -b feat/your-feature-name
+
+# Test the module
+cd examples
+terraform init
+terraform plan
+```
+
+## Pull Request Process
+
+1. **Update Documentation**: Ensure `README.md` reflects any changes to variables, outputs, or usage examples
+2. **Test Changes**: Verify your changes work with both basic and complex group configurations
+3. **Update Examples**: Add or modify examples in the `examples/` directory if relevant
+4. **Version Updates**: Update `CHANGELOG.md` with your changes
+5. **Run Validation**: Ensure `terraform validate` and `terraform fmt` pass
+
+## Contribution Checklist
+
+- [ ] Semantic commit messages (see below)
+- [ ] Documentation updated for any variable/output changes
+- [ ] Examples updated if functionality changes
+- [ ] Terraform validation passes (`terraform validate`)
+- [ ] Code formatting applied (`terraform fmt`)
+- [ ] GitLab group features tested against live GitLab instance
+
+## Semantic Commit Messages
+
+Use conventional commit format:
+
+- `feat:` - New features or GitLab group capabilities
+- `fix:` - Bug fixes
+- `docs:` - Documentation and example updates
+- `refactor:` - Code restructuring without feature changes
+- `test:` - Testing improvements
+- `chore:` - Maintenance tasks
+
+## Testing Guidelines
+
+- Test against GitLab CE/EE (specify which version)
+- Verify nested group structures work correctly
+- Test security features (2FA, IP restrictions, etc.)
+- Ensure examples in `examples/` directory are functional
+
+## Questions?
+
+Open an issue for discussion or reach out to the maintainers. We appreciate your contributions!

.github/workflows/main.yml

@@ -22,6 +22,7 @@ jobs:
         uses: bridgecrewio/checkov-action@master
         with:
           directory: ./
+          config_file: .checkov.yaml # Use our custom configuration
           quiet: true # optional: display only failed checks
           soft_fail: false # optional: do not return an error code if there are failed checks
           framework: terraform # optional: run only on a specific infrastructure {cloudformation,terraform,kubernetes,all}

.gitignore

@@ -4,6 +4,9 @@
 # .tfstate files
 *.tfstate
 *.tfstate.*
+examples/*tfstate
+examples/*.*lock.hcl
+examples/*.terraform
 
 # Crash log files
 crash.log

README.md

@@ -21,7 +21,8 @@ A comprehensive Terraform module for creating and managing GitLab groups with fu
 
 ```hcl
 module "basic_group" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   name        = "development-team"
   path        = "dev-team"
@@ -33,7 +34,8 @@ module "basic_group" {
 
 ```hcl
 module "secure_group" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   # Basic Configuration
   name        = "security-team"
@@ -77,7 +79,8 @@ module "secure_group" {
 ```hcl
 # Parent group
 module "engineering_group" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   name        = "Engineering"
   path        = "engineering"
@@ -89,7 +92,8 @@ module "engineering_group" {
 
 # Child subgroup
 module "backend_team" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   name        = "Backend Team"
   path        = "backend"
@@ -102,7 +106,8 @@ module "backend_team" {
 
 ```hcl
 module "cicd_group" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   name        = "CI/CD Projects"
   path        = "cicd-projects"
@@ -213,12 +218,20 @@ For a complete list of all outputs, see the [outputs.tf](./outputs.tf) file.
 
 ## Examples
 
+For comprehensive usage examples including enterprise setups, nested subgroups, and specialized configurations, see the [examples directory](https://github.com/sudo-terraform-modules/terraform-gitlab-groups/tree/main/examples).
+
+The examples include:
+
+- **Complete Configuration** (`main.tf`) - Full organizational structure with DevOps teams, SAP subgroups, and security configurations
+- **Variables and Documentation** - Complete variable examples and setup instructions
+
 ### Creating a Project in the Group
 
 ```hcl
 # Create the group
 module "my_group" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   name        = "my-team"
   path        = "my-team"
@@ -239,7 +252,8 @@ resource "gitlab_project" "my_project" {
 
 ```hcl
 module "enterprise_group" {
-  source = "./modules/gitlab-groups"
+  source  = "sudo-terraform-modules/groups/gitlab"
+  version = "0.2.0"
 
   name        = "Enterprise Applications"
   path        = "enterprise-apps"
@@ -288,7 +302,7 @@ module "enterprise_group" {
 
 ## Module Structure
 
-```
+```text
 ├── .github/
 │   └── workflows/          # CI/CD pipeline configurations
 ├── .gitignore              # Git ignore patterns
@@ -316,22 +330,7 @@ The module includes comprehensive input validation:
 
 ## Contributing
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes following the existing code style
-4. Add or update tests as needed
-5. Update documentation
-6. Commit your changes (`git commit -m 'feat: add amazing feature'`)
-7. Push to the branch (`git push origin feature/amazing-feature`)
-8. Open a Pull Request
-
-### Development Guidelines
-
-- Follow Terraform best practices and style guidelines
-- Add validation for new variables where appropriate
-- Update documentation for any new features or changes
-- Test with multiple GitLab provider versions
-- Ensure backward compatibility when possible
+We welcome contributions! Please see our [Contributing Guide](.github/contributing.md) for details on how to contribute to this module, including development setup, testing guidelines, and submission requirements.
 
 ## Security Considerations
 
@@ -346,12 +345,16 @@ When using this module in production:
 
 ## License
 
-This module is licensed under the MIT License. See [LICENSE](./LICENSE) file for details.
+This module is licensed under the Apache 2.0 License. See [LICENSE](./LICENSE) file for details.
 
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md) for version history and changes.
 
+## Maintainer
+
+This module is maintained by [Amaan Ul Haq Siddiqui](https://github.com/amaan-igs).
+
 ---
 
 **Note**: This module requires GitLab 13.0+ for full feature compatibility. Some advanced features may require GitLab Premium or Ultimate subscriptions.

examples/README.md

@@ -0,0 +1,112 @@
+# GitLab Groups Configuration
+
+This directory contains Terraform configuration for creating and managing GitLab groups using the `sudo-terraform-modules/groups/gitlab` module.
+
+## Overview
+
+The `main.tf` configuration creates a comprehensive organizational structure in GitLab with security-focused groups, specialized teams, and hierarchical subgroups.
+
+## GitLab Group Structure
+
+The following GitLab groups and subgroups are created:
+
+```text
+GitLab Instance
+├── Engineering
+│   └── DevOps Team
+│       ├── Migrations Team
+│       ├── Infrastructure Team
+│       ├── Automation Team
+│       ├── Compute Team
+│       └── SAP BASIS Team
+│           ├── SAP S4 HANA
+│           ├── SAP B1
+│           └── SAP NetWeaver
+├── Security Team
+├── Production Operations
+├── Open Source Projects
+└── Documentation
+```
+
+## Group Details
+
+### Top-Level Groups
+
+| Group Name | Path | Description | Features |
+|------------|------|-------------|----------|
+| **Engineering** | `engineering` | Main engineering organization | Internal visibility, developer project creation |
+| **Security Team** | `security` | Information security and compliance | Maximum security settings, 2FA required, IP restrictions |
+| **Production Operations** | `production` | Production systems and operations | 2FA required, controlled CI/CD access |
+| **Open Source Projects** | `opensource` | Public open source projects | Public visibility, external collaboration enabled |
+| **Documentation** | `docs` | Technical documentation and knowledge base | Wiki enabled, lightweight configuration |
+
+### Engineering Subgroups
+
+#### DevOps Team (`devops`)
+
+Central DevOps operations with enhanced CI/CD access and specialized subteams:
+
+- **Migrations Team** (`migrations`) - Database and application migration projects
+- **Infrastructure Team** (`infrastructure`) - Cloud and on-premises infrastructure management
+- **Automation Team** (`automation`) - DevOps automation and CI/CD pipeline development
+- **Compute Team** (`compute`) - Server and container compute infrastructure
+- **SAP BASIS Team** (`sap-basis`) - SAP system administration and BASIS management
+
+#### SAP BASIS Subgroups
+
+Specialized SAP teams under the BASIS team:
+
+- **SAP S4 HANA** (`sap-s4hana`) - S/4HANA system administration and development
+- **SAP B1** (`sap-b1`) - Business One system administration and customization
+- **SAP NetWeaver** (`sap-netweaver`) - NetWeaver platform and ABAP development
+
+## Security Configuration
+
+### High-Security Groups
+
+- **Security Team**: 2FA required, IP restrictions, comprehensive push rules
+- **Production Operations**: 2FA required, controlled access, production-grade security
+- **All SAP Groups**: 2FA enforced, custom runners only, enterprise security standards
+
+### Access Controls
+
+- **Project Creation**: Restricted to maintainer level or higher for sensitive groups
+- **Subgroup Creation**: Limited to owners and maintainers
+- **Shared Runners**: Configured based on team requirements and security needs
+
+## Usage
+
+1. **Configure Variables**: Update `terraform.tfvars` with your GitLab token and organization details
+2. **Initialize**: Run `terraform init` to download the required modules
+3. **Plan**: Execute `terraform plan` to review the changes
+4. **Apply**: Run `terraform apply` to create the GitLab groups
+
+## Prerequisites
+
+- Terraform >= 1.3.0
+- GitLab instance access with group creation permissions
+- Valid GitLab personal access token with required scopes
+
+## Module Source
+
+This configuration uses the official Terraform Registry module:
+
+- **Source**: `sudo-terraform-modules/groups/gitlab`
+- **Version**: `0.2.0`
+
+## Files
+
+- `main.tf` - Main configuration with all group definitions
+- `variables.tf` - Input variable definitions
+- `terraform.tfvars.example` - Example variable values
+- `simple.tf` - Simplified configuration for basic usage
+
+## Outputs
+
+The configuration provides comprehensive outputs including:
+
+- Group IDs and URLs for each created group
+- Hierarchical structure mapping
+- Access settings and configuration details
+
+For complete output reference, run `terraform output` after applying the configuration.