GitHub Repository

This Terraform Module manages the lifecycle of GitHub Repositories and associated resources.

Table of Contents

• GitHub Repository
  • Table of Contents
  • Requirements
  • Dependencies
  • Usage
    • Inputs
    • Outputs
  • Notes
  • Author Information
  • License

Requirements

• GitHub Account
• Terraform 1.0.x or newer.

Dependencies

This module depends on a correctly configured GitHub Provider in your Terraform codebase.

Usage

Add the module to your Terraform resources like so:

module "simple_example" {
  source  = "ksatirli/repository/github"
  version = "4.0.0"

  name       = "simple-example"
  visibility = false
}

Then, fetch the module from the Terraform Registry using terraform get.

Additional usage examples are available in the examples directory via GitHub.

Inputs

Outputs

Notes

Upgrades from 3.0.0 to 4.x.x

As part of the updates and upgrades that were made for the 4.x.x release, all Terraform resource identifiers were renamed from this to main. See ./moved.tf and the Terraform documentation for more information.

Branch for GitHub Pages

Prior to 4.0.0, the branch for the GitHub Pages feature was sourced from the default_branch variable.

From 4.0.0 onwards, the branch for GitHub Pages can be set through the pages_branch variable. The default is gh-pages.

Upgrading from 2.0.0 to 3.x.x

The 3.0.0 version of this module introduced support for the github_branch_default resource, a property that was initially handled through the github_repository resource.

For a better upgrade experience, it is advised to manually import this resource, using the import command:

terraform import module.my_repository.github_branch_default.this "my_repository"

Replace module.my_repository with the Module identifier in use and replace "my_repository" with the name of the repository the data is imported from.

For github_repository resources

• Resources that are created with the template option enabled will be re-created (that is: destroyed, then created again) when the template stub is removed

• Resources that are archived using the archive option cannot be unarchived, as the GitHub API does not currently support this

• Starting with 3.0.0 of this Module, the default branch option is no longer set through the github_repository resource

For github_repository_deploy_key resources

• Deploy Key resources expect a string for the deploy_key.key variable. Use the file function if key material is not available as a Terraform-variable already

• For a step-by-step guide on how to generate SSH Keys, see this article on GitHub

For github_branch_protection resources

• Branch Protection resources that set the required_approving_review_count variable must be in a range of >= 1 and <= 6

For github_repository_project resources

• Project resources require GitHub Projects to be enabled for the Organization as well as the has_projects variable set to true

For github_repository_file resources

• File resources require an (already existing) main branch, or an explicitly defined branch for the files.branch variable to avoid errors

• File resources expect a string for the files.content variable. Use the file function if file data is not available as a Terraform-variable already

• File resources that are removed from Terraform will also be removed from the Repository. This is visible in the Repository History

Author Information

This module is maintained by the contributors listed on GitHub.

License

Licensed under the Apache License, Version 2.0 (the "License").

You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" basis, without WARRANTIES or conditions of any kind, either express or implied.

See the License for the specific language governing permissions and limitations under the License.