Gherkin Infrastructure Documentation

📋 Define infrastructure requirements using Gherkin, automatically generate documentation

Overview

This project enables cloud migration teams to document infrastructure requirements and security rules using Gherkin notation (Given/When/Then). The requirements are automatically validated and converted into comprehensive Markdown documentation through CI/CD pipelines.

Why Gherkin for Infrastructure?

• Human-Readable: Architects and implementation teams share a common language
• Testable: Requirements can later be validated against actual IaC implementations
• Version Controlled: Track changes to requirements over time
• Auto-Documentation: Generate compliance documentation automatically

Project Structure

gherkin-docs-handling/
├── .forgejo/
│   └── workflows/
│       ├── generate-docs.yml           # Documentation pipeline
│       ├── pr-review.yml               # PR validation workflow
│       └── infrastructure-validation.yml # IaC testing pipeline
├── features/
│   └── infrastructure/
│       ├── network-security.feature    # Network security requirements
│       ├── identity-access.feature     # IAM requirements
│       ├── kubernetes.feature          # K8s cluster requirements
│       └── storage-security.feature    # Storage security requirements
├── iac/
│   └── terraform/
│       └── network-security/
│           └── main.tf                 # Terraform implementation
├── tests/
│   ├── test_infrastructure.py          # Gherkin-based IaC tests
│   └── steps/
│       ├── environment.py              # Test environment setup
│       └── network_security_steps.py   # Step definitions
├── scripts/
│   ├── generate_docs.py                # Documentation generator
│   └── validate_features.py            # Feature file validator
├── docs/
│   ├── WRITING_GUIDE.md                # Feature writing guide
│   └── IAC_TESTING.md                  # IaC testing guide
└── README.md

# Generated as CI/CD Artifacts (not in repo):
# - infrastructure-bundle-{run#}/     # Complete bundle
#   ├── docs/                         # All generated documentation
#   └── reports/                      # All test and validation reports

Note: Generated documentation and test reports are NOT stored in the repository. They are created as pipeline artifacts and can be downloaded from Forgejo Actions.

Quick Start

1. Write Infrastructure Requirements

Create .feature files in the features/ directory:

# language: en
@infrastructure @security @network
Feature: Network Security Requirements
  As a Cloud Migration Team
  I want to define network security requirements
  So that our infrastructure meets compliance standards

  @firewall @critical
  Scenario: Restrict SSH access to bastion hosts only
    Given a virtual network "vnet-prod-001"
    And a network security group "nsg-prod-servers"
    When I define inbound security rules
    Then SSH port 22 should only be accessible from subnet "bastion-subnet"
    And all other SSH traffic should be denied

2. Generate Documentation Locally

# Validate feature files
python scripts/validate_features.py features/

# Generate documentation
python scripts/generate_docs.py features/ -o docs/generated -v

3. Write IaC to Fulfill Requirements

Create Terraform (or other IaC) code that implements the requirements:

# Example: Implementing network security requirement
resource "azurerm_network_security_group" "prod_servers" {
  name = "nsg-production-servers"
  
  # Requirement: SSH only from bastion subnet
  security_rule {
    name                       = "Allow-SSH-From-Bastion"
    priority                   = 100  # < 1000 as required
    direction                  = "Inbound"
    access                     = "Allow"
    protocol                   = "Tcp"
    destination_port_range     = "22"
    source_address_prefix      = "10.0.1.0/24"  # bastion-subnet
  }
  
  # Requirement: Deny all other SSH
  security_rule {
    name                       = "Deny-SSH-All"
    priority                   = 200
    access                     = "Deny"
    destination_port_range     = "22"
    source_address_prefix      = "*"
  }
}

4. Test IaC Against Requirements

# Run infrastructure tests
python tests/test_infrastructure.py

The tests validate your IaC against the Gherkin specifications:

• ✅ Passed - IaC meets requirement
• ❌ Failed - IaC doesn't meet requirement

5. Push to Trigger CI/CD

The Forgejo pipeline will automatically:

1. ✅ Validate all feature files
2. 📝 Generate Markdown documentation
3. 📤 Commit documentation to repository (on main branch)

Feature File Conventions

Tags

Use tags to categorize and prioritize requirements:

Tag Type	Examples	Purpose
Category	@infrastructure, @security	High-level classification
Domain	@network, @identity, @storage	Technical domain
Severity	@critical, @high, @medium, @low	Priority level
Specific	@firewall, @rbac, @encryption	Detailed classification

Severity Levels

• 🔴 @critical - Must be implemented before go-live
• 🟠 @high - Should be implemented before go-live
• 🟡 @medium - Can be implemented post-migration
• 🟢 @low - Nice to have

Scenario Structure

@firewall @critical
Scenario: Descriptive scenario name
  Given the preconditions (context)
  When the action is performed
  Then the expected outcome (requirement)
  And additional requirements

Generated Documentation

The pipeline generates:

Document	Description
README.md	Index with overview and quick stats
REQUIREMENTS_SUMMARY.md	Requirements grouped by category and severity
COMPLIANCE_MATRIX.md	Requirements mapped to CIS/NIST controls
<feature-name>.md	Detailed documentation for each feature

Workflow Integration

Complete Development Workflow

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Architects    │───▶│  Gherkin Specs   │───▶│   Auto-Docs     │
│  Write Specs    │    │  (.feature)      │    │  (Markdown)     │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                              │
                              ▼
┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Implement     │◀───│   Tests Check    │───▶│   CI/CD Pass    │
│   IaC Code      │    │   Requirements   │    │   Deploy        │
└─────────────────┘    └──────────────────┘    └─────────────────┘

For Architects

1. Create/update .feature files with infrastructure requirements
2. Submit PR for review
3. Pipeline validates syntax and generates preview docs
4. Merge to main triggers documentation update

For Implementation Team

1. Download latest documentation artifact from Forgejo Actions
2. Use scenarios as implementation checklists
3. Write IaC code in iac/terraform/ to fulfill requirements
4. Run python tests/test_infrastructure.py to validate
5. Reference compliance matrix for audit requirements
6. Implement IaC to satisfy requirements

For Security Team

1. Review COMPLIANCE_MATRIX.md for audit mapping
2. Verify severity classifications
3. Track implementation status

CI/CD Pipelines

All generated documentation and test reports are created as downloadable artifacts, not stored in the repository. This keeps the repo clean as these files change frequently with each pipeline run.

Accessing Pipeline Artifacts

1. Go to Forgejo Actions in the repository
2. Select a workflow run
3. Download artifacts from the Artifacts section:
   • documentation-bundle-{run_number} - Generated docs
   • infrastructure-bundle-{run_number} - Full validation bundle with docs + reports
   • pr-review-{pr_number} - PR validation results

Main Pipeline (generate-docs.yml)

Triggers on:

• Push to main or develop branches
• Changes to feature files or scripts
• Manual workflow dispatch

Produces Artifact: documentation-bundle-{run_number} (90-day retention)

• All generated Markdown documentation
• Requirements summary and compliance matrix

Infrastructure Validation Pipeline (infrastructure-validation.yml)

Triggers on:

• Push to main branch
• Changes to features/, iac/, or tests/
• Manual workflow dispatch

Produces Artifact: infrastructure-bundle-{run_number} (90-day retention)

• docs/ - All generated documentation
• reports/ - Test results, coverage reports, validation summaries

PR Review Pipeline (pr-review.yml)

Triggers on:

• Pull requests with feature file changes

Produces Artifact: pr-review-{pr_number} (14-day retention)

• Documentation preview
• Validation reports
• Change analysis

Local Development

Prerequisites

• Python 3.9+
• No external dependencies required

Commands

# Validate features (with warnings as errors)
python scripts/validate_features.py features/ --strict

# Generate documentation locally (for preview)
python scripts/generate_docs.py features/ -o output/docs -v

# Run infrastructure tests
python tests/test_infrastructure.py

Note: The output/ directory is gitignored. Generated files are only for local preview - the CI/CD pipeline produces the official artifacts.

Extending the Project

Adding New Feature Domains

1. Create new .feature file in features/infrastructure/
2. Add appropriate tags (domain, severity)
3. Follow Given/When/Then structure
4. Push to trigger documentation generation

Customizing Documentation

Edit scripts/generate_docs.py to:

• Add new compliance framework mappings
• Customize Markdown templates
• Add additional output formats

Adding IaC Validation

Future enhancement: Integrate with tools like:

• behave (Python) - Run Gherkin against actual infrastructure
• terratest - Validate Terraform implementations
• Custom validators using cloud provider APIs

License

MIT License - See LICENSE for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add/modify feature files
4. Submit a pull request

---

🏗️ Built for Cloud Migration Enablement Teams