Skip to content
Documentation

GitHub Repositories Naming Conventions | Requirements

Loading...

Introduction

Consistent and meaningful repository names are crucial for maintaining an organized and easily navigable codebase. The following conventions provide guidelines for:

  • Terraform AWS Modules Blueprint: A blueprint for creating Terraform AWS modules handling common AWS resources and services. These modules should encapsulate specific functionalities or resource types, such as VPCs, IAM roles, or S3 buckets, making them reusable across different projects. Well-named modules simplify understanding and integration, enabling quicker setup and reducing configuration errors.
  • Terraform AWS Stack Blueprint: A blueprint for creating Terraform AWS stacks using multiple Terraform AWS modules to provision AWS resources and services. Stacks represent a combination of resources and modules orchestrated together to form a complete infrastructure solution. By adhering to these conventions, teams can ensure that stacks are modular, maintainable, and scalable.
  • Deployer AWS Infrastructure Blueprint: A blueprint for creating a deployer AWS infrastructure using multiple Terraform AWS stacks and modules to provision AWS resources and services. This blueprint focuses on the deployment process, ensuring a seamless and automated way to manage infrastructure across different environments. Consistent naming conventions aid in automation scripts and CI/CD pipelines, reducing the risk of errors during deployments.

Naming Conventions

Use Lowercase Letters:

  • All repository names should be in lowercase letters to maintain consistency and avoid confusion. This helps in environments where case sensitivity might be an issue, ensuring that repositories are always referenced correctly.
  • Example: tf-aws-modules-vpc instead of TF-AWS-Modules-VPC.

Use Dashes to Separate Words:

  • Separate words in the repository name with dashes (-) to improve readability. Do not use underscores (_) or spaces to separate words. Dashes make the names easier to read and type, particularly in command-line interfaces.
  • Example: tf-aws-ec2-instance instead of tf_aws_ec2_instance or tf aws ec2 instance.

Include “tf-” Prefix:

  • Begin the repository name with the prefix “tf-” to indicate that it’s a Terraform module. This helps in quickly identifying repositories related to Terraform, differentiating them from other types of projects or codebases.
  • Example: tf-aws-security-group.

Include “aws-” Prefix for AWS Modules:

  • After the “tf-” prefix, include “aws-” to signify that the module is specifically designed for AWS. This is useful for distinguishing between modules for different cloud providers.
  • Example: tf-aws-rds-instance.

Follow a Descriptive Naming Pattern:

  • Use a descriptive and concise name that reflects the purpose or functionality of the module. For example, a module that creates an AWS VPC should be named tf-aws-modules-vpc. Descriptive names help in understanding the module’s functionality at a glance, facilitating easier discovery and usage.
  • Ensure the name covers the main resource or service the module is managing.
  • Example: tf-aws-s3-bucket, tf-aws-iam-role.

Include Specificity for Complex Modules:

  • For more complex modules that handle multiple resources, include key resources or functionalities in the name.
  • Example: tf-aws-ecs-cluster-autoscaling.

Avoid Special Characters:

  • Avoid the use of special characters or symbols in repository names. This includes characters such as !, @, #, $, %, ^, &, *, (, ), +, =, {, }, [, ], \, |, ;, :, ', ", <, >, ,, ., ?, /, and `. Special characters can cause issues in various environments and tools, making it harder to work with the repositories. Stick to alphanumeric characters and dashes to ensure compatibility and ease of use.
  • Example: tf-aws-lambda-function instead of tf-aws-lambda_function!.

Include Versioning Information (if applicable):

  • If a module has different versions, include versioning information in the repository name to differentiate between major updates.
  • Example: tf-aws-vpc-v2.

Consider Organization and Team Naming Conventions:

  • Align with broader organization or team naming conventions to ensure coherence across the entire codebase and facilitate easier management and collaboration.
  • Example: companyname-tf-aws-module-name.

Include Purpose or Environment (if necessary):

  • If the repository is environment-specific or has a special purpose, include that information to make the repository’s role clear.
  • Example: tf-aws-vpc-prod for a production VPC module.

Examples

Good Examples

  • tf-aws-vpc: Clearly indicates a Terraform module for AWS that handles VPC creation.
  • tf-aws-ec2-instance: Specifies a module for managing EC2 instances in AWS.
  • tf-aws-s3-bucket: Describes a module for creating and managing S3 buckets in AWS.
  • tf-aws-iam-role: Identifies a module for IAM role creation and management.
  • tf-aws-rds-instance: Details a module for provisioning RDS instances in AWS.
  • companyname-tf-aws-module-name: Follows organization-specific conventions for easy identification and management.

Bad Examples

  • TF_AWS_VPC: Uses uppercase letters and underscores, making it less readable and consistent.
  • terraform-aws-s3: Missing the tf- prefix, which is essential for identifying Terraform modules.
  • tfawsinstance: Lacks dashes to separate words, reducing readability.
  • tf-aws-lambda_function!: Contains a special character, which can cause issues in various tools.
  • vpc-module: Does not indicate that it’s a Terraform module or that it’s specifically for AWS.
  • tf-aws-vpc-3.0: Using versioning directly in the name without a clear convention can lead to confusion.