Skip to content

Latest commit

 

History

History
218 lines (155 loc) · 13 KB

README.md

File metadata and controls

218 lines (155 loc) · 13 KB
Raw

terraform-github-repositories

Terraform Module to Manage GitHub Repositories

This Terraform module is designed to manage GitHub repositories. It provides a way to create and configure repositories in a declarative manner, using Infrastructure as Code (IaC) principles.

Key features of this module include:

  1. Repository Creation: The module allows you to create a new GitHub repository by specifying the repository name.

  2. Repository Configuration: You can configure various aspects of the repository, such as whether it's private or public, whether it has issues, projects, wiki, and downloads enabled, and whether it should be auto-initialized with a README.

  3. Advanced Settings: The module supports advanced repository settings like setting a gitignore template, a license template, merge settings, and repository topics.

  4. Security Settings: You can enable or disable vulnerability alerts for the repository.

To use this module, you need to provide the repository name as an input. All other inputs have default values, but you can override them if needed. After setting up the module, you can apply it with Terraform to create and configure your GitHub repository.

Remember that to use this module, you need to authenticate with GitHub. You can do this by providing a GitHub token with the necessary permissions.

Example CICD with BitBucket and Codefresh:

Image

Notes

Here are some notes about this Terraform module for managing GitHub repositories:

  1. Purpose: This module is designed to create and manage GitHub repositories. It allows you to specify various settings for a repository in a declarative manner.

  2. Inputs: The only required input is the repository name. All other inputs, such as description, private, has_issues, has_projects, has_wiki, has_downloads, auto_init, gitignore_template, license_template, allow_merge_commit, allow_squash_merge, allow_rebase_merge, delete_branch_on_merge, archived, topics, and vulnerability_alerts, have default values but can be overridden.

  3. Outputs: The module does not currently define any outputs. If needed, outputs can be added to return information about the created resources.

  4. Authentication: The module requires a GitHub token with appropriate permissions. This should be provided through the GITHUB_TOKEN environment variable or the token argument in the GitHub provider configuration.

  5. Usage: To use the module, call it in your Terraform configuration, provide the required inputs, and run terraform init and terraform apply.

  6. Versioning and State Management: If you're using a remote module, consider using versioning to ensure consistent behavior. Also, consider using remote state storage and state locking if you're working in a team.

  7. Error Handling and Security: Be aware of potential errors, such as conflicts in repository names. Also, avoid hardcoding sensitive data like tokens in your configuration files.

  8. Customization: The module can be customized to suit your needs. For example, you can add more inputs or outputs, or modify the resource configuration.

Usage

The following includes some examples on how you can use this module.

Minimal Usage

Minimal usage using the default values:

module "github_repository_test" {
  source = "../.."  # path to the module
  name   = "test"
}

The only input that does not have a default value is name, this allows you to specify a public repository name and use the module downstream

Basic Usage

module "github_repository_test" {
  source = "../.."  # path to the module
  name   = "test"
}

In this example, we're using the module located at ./modules/github_repository. We're creating a new GitHub repository named my-repo. The repository will have the description "This is my repository" and it will be private.

Remember to replace "./modules/github_repository" with the actual path to the module if it's located elsewhere.

After setting up the module, you can initialize your Terraform configuration with terraform init and then apply it with terraform apply.

Advanced Usage with All Inputs Plus Options

module "github_repository" {
  source = "./modules/github_repository"  # path to the module

  name                   = "my-repo"
  description            = "My awesome repo"
  homepage_url           = "https://my-awesome-repo.info"
  private                = false
  has_issues             = true
  has_projects           = true
  has_wiki               = true
  has_downloads          = true
  auto_init              = false
  gitignore_template     = ""
  license_template       = ""
  allow_merge_commit     = true
  allow_squash_merge     = true
  allow_rebase_merge     = true
  delete_branch_on_merge = false
  archived               = false
  topics                 = ["topic1", "topic2"]
  vulnerability_alerts   = false
}

Here's an advanced usage example of the Terraform module where we override more default values:

module "github_repository" {
  source = "./modules/github_repository"  # path to the module
  name   = "my-advanced-repo"
  description = "This is my advanced repository"
  homepage_url = "https://my-advanced-repo.info"
  private = true
  has_issues = false
  has_projects = false
  has_wiki = false
  has_downloads = false
  auto_init = true
  gitignore_template = "Python"
  license_template = "mit"
  allow_merge_commit = false
  allow_squash_merge = true
  allow_rebase_merge = false
  delete_branch_on_merge = true
  archived = false
  topics = ["terraform", "github", "advanced"]
  vulnerability_alerts = true
}

In this example, we're creating a new GitHub repository named my-advanced-repo. The repository will have the description "This is my advanced repository", it will be private, and it will have a homepage URL. We're also disabling issues, projects, wiki, and downloads, but enabling auto-initialization and vulnerability alerts. We're setting the gitignore template to "Python" and the license template to "MIT". We're disabling merge commits and rebase merges, but enabling squash merges and deletion of branches on merge. Finally, we're setting the topics of the repository.

Remember to replace "./modules/github_repository" with the actual path to the module if it's located elsewhere.

After setting up the module, you can initialize your Terraform configuration with terraform init and then apply it with terraform apply.

Considerations

Here are some considerations when using this Terraform module:

  1. GitHub Authentication: This module requires a GitHub token with appropriate permissions to create and manage repositories. Make sure to provide it either through the GITHUB_TOKEN environment variable or the token argument in the GitHub provider configuration.
  2. Module Versioning: If you're using a remote module, consider using versioning to ensure consistent behavior. You can specify a particular version of a module by appending a version query parameter to the source URL.
  3. Sensitive Data: Be careful with sensitive data like tokens. Avoid hardcoding them in your configuration files. Use environment variables or input variables instead.
  4. Error Handling: Terraform will stop and roll back at the first error during apply. Make sure to handle potential errors in your configuration, such as invalid input values or lack of permissions.
  5. State Management: Terraform keeps track of your infrastructure's state. If you're working in a team, consider using remote state storage and state locking to prevent conflicts.
  6. Module Inputs and Outputs: Make sure to understand the inputs and outputs of the module. Inputs are the values you provide to the module, and outputs are the values the module returns. You can use outputs to pass information between modules or to get information about the resources created by the module.
  7. Resource Naming: Be aware that the name input must be unique across your GitHub account. If you try to create a repository with a name that already exists, Terraform will return an error.
  8. Repository Settings: Consider the settings of the repository you're creating. For example, if you set auto_init to true, GitHub will automatically create an initial commit with a README file in your repository. If you want to push an existing repository to GitHub, you should set auto_init to false.

Overview

  1. Repository Creation: The module allows you to create a new GitHub repository by specifying the repository name.

  2. Repository Configuration: You can configure various aspects of the repository, such as whether it's private or public, whether it has issues, projects, wiki, and downloads enabled, and whether it should be auto-initialized with a README.

  3. Advanced Settings: The module supports advanced repository settings like setting a gitignore template, a license template, merge settings, and repository topics.

  4. Security Settings: You can enable or disable vulnerability alerts for the repository.

To use this module, you need to provide the repository name as an input. All other inputs have default values, but you can override them if needed. After setting up the module, you can apply it with Terraform to create and configure your GitHub repository.

Remember that to use this module, you need to authenticate with GitHub. You can do this by providing a GitHub token with the necessary permissions.

Inputs

Requirements

Name Version
terraform >= 1.5.6
github 6.2.1

Providers

Name Version
github 6.2.1

Modules

No modules.

Resources

Name Type
github_repository.repository resource

Inputs

Name Description Type Default Required
allow_merge_commit Whether the repository should allow merge commits bool true no
allow_rebase_merge Whether the repository should allow rebase merges bool true no
allow_squash_merge Whether the repository should allow squash merges bool true no
allow_update_branch value to allow update branch bool true no
archived Whether the repository should be archived bool false no
auto_init Whether the repository should be automatically initialized bool false no
delete_branch_on_merge Whether the repository should delete branches on merge bool false no
description A description of the repository string "" no
gitignore_template A gitignore template for the repository string "" no
has_downloads Whether the repository should have downloads enabled bool true no
has_issues Whether the repository should have issues enabled bool true no
has_projects Whether the repository should have projects enabled bool true no
has_wiki Whether the repository should have a wiki enabled bool true no
homepage_url A URL with more information about the repository string "" no
is_template Whether the repository should be a template repository bool false no
license_template A license template for the repository string "" no
name The name of the repository string n/a yes
topics A list of topics for the repository list(string) [] no
visibility n/a string "public" no
vulnerability_alerts Whether the repository should have vulnerability alerts enabled bool false no

Outputs

No outputs.