A Terraform module to manage GitHub Repositories. https://github.com/
terraform-github-repository
A [Terraform] module for creating a public or private repository on [Github].
This module supports Terraform v1.x and is compatible with the Official Terraform GitHub Provider v4.20 and above from integrations/github.
Attention: This module is incompatible with the Hashicorp GitHub Provider! The latest version of this module supporting hashicorp/github provider is ~> 0.10.0
Note: Versions 5.3.0, 5.4.0, and 5.5.0 of the Terraform Github Provider have broken branch protections support and should not be used.
- Main Resource Configuration - Extended Resource Configuration - Repository Creation Configuration - Teams Configuration - Collaborator Configuration - Branches Configuration - Deploy Keys Configuration - Branch Protections v3 Configuration - Branch Protections v4 Configuration - Issue Labels Configuration - Projects Configuration - Webhooks Configuration - Secrets Configuration - Autolink References Configuration - App Installations - Module Configuration - Terraform Github Provider Documentation - Backwards compatibility in0.0.z and 0.y.z version
GitHub as Code
[GitHub as Code][github-as-code] is a commercial solution built on top of our open-source Terraform modules for GitHub. It helps our customers to manage their GitHub organization more efficiently by enabling anyone in their organization to self-service manage on- and offboarding of users, repositories, and settings such as branch protections, secrets, and more through code. GitHub as Code comes with **pre-configured GitHub Actions pipelines for change pre-view in Pull Requests, fully automated rollouts and rollbacks**. It's a comprehensive, ready-to-use blueprint maintained by our team of platform engineering experts and saves companies such as yours tons of time by building on top of a pre-configured solution instead of building and maintaining it yourself.
For details please see [https://mineiros.io/github-as-code][github-as-code].
Module Features
In contrast to the plain github_repository resource this module enables various other features like Branch Protection or Collaborator Management.
- Default Security Settings:
private repository by default,
Deploy keys are read-only by default
- Standard Repository Features:
- Extended Repository Features:
- Features not yet implemented:
Getting Started
Most basic usage creating a new private github repository.
module "repository" {
source = "mineiros-io/repository/github"
version = "~> 0.18.0"
name = "terraform-github-repository" license_template = "apache-2.0" gitignore_template = "Terraform" }
Module Argument Reference
See [variables.tf] and [examples/] for details and use-cases.
Main Resource Configuration
name: (Requiredstring)
defaults: (Optionalobject(defaults))
Default is {}.
pages: (Optionalobject(pages))
Default is {}.
The pages object accepts the following attributes:
- branch: (Required string)
The repository branch used to publish the site's source files.
- path: (Optional string)
The repository directory from which the site publishes.
- cname: (Optional string)
The custom domain for the repository. This can only be set after the repository has been created.
allowmergecommit: (Optionalbool)
false to disable merge commits on the repository.
If you set this to false you have to enable either allowsquashmerge
or allowrebasemerge.
Default is true.
allowsquashmerge: (Optionalbool)
true to enable squash merges on the repository.
Default is false.
allowrebasemerge: (Optionalbool)
true to enable rebase merges on the repository.
Default is false.
allowautomerge: (Optionalbool)
true to allow auto-merging
pull requests on the repository. If you enable auto-merge for a pull
request, the pull request will merge automatically when all required
reviews are met and status checks have passed.
Default is false.
description: (Optionalstring)
Default is "".
deletebranchonmerge: (Optionalbool)
false to disable the automatic deletion of head branches after pull requests are merged.
Default is true.
homepageurl: (Optionalstring)
Default is "".
private: (Optionalbool)
visibility instead and update your code. parameter will be removed in a future version
visibility: (Optionalstring)
public or private.
If your organization is associated with an enterprise account using GitHub Enterprise Cloud or GitHub Enterprise Server 2.20+, visibility can also be internal.
The visibility parameter overrides the deprecated private parameter.
Default is "private".
hasissues: (Optionalbool)
Default is false.
hasprojects: (Optionalbool)
Default is false.
haswiki: (Optionalbool)
Default is false.
hasdownloads: (Optionalbool)
true to enable the (deprecated) downloads features on the repository.
Default is false.
istemplate: (Optionalbool)
true to tell GitHub that this is a template repository.
Default is false.
defaultbranch: (Optionalstring)
branches
variable, which will cause Terraform to create it for you.
Default is "".
archived: (Optionalbool)
Default is false.
topics: (Optionallist(string))
Default is [].
extratopics: (Optionallist(string))
topics. This is useful if default.topics are used and the list should be extended with more topics.
Default is [].
vulnerabilityalerts: (Optionalbool)
false to disable security alerts for vulnerable dependencies.
Enabling requires alerts to be enabled on the owner level.
archiveondestroy: (Optionalbool)
false to not archive the repository instead of deleting on destroy.
Default is true.
Extended Resource Configuration
Repository Creation Configuration
The following four arguments can only be set at repository creation and changes will be ignored for repository updates and will not show a diff in plan or apply phase.
autoinit: (Optionalbool)
false to not produce an initial commit in the repository.
Default is true.
gitignoretemplate: (Optionalstring)
Default is "".
licensetemplate: (Optionalstring)
Default is "".
template: (Optionalobject(template))
Default is {}.
The template object accepts the following attributes:
- owner: (Required string)
The GitHub organization or user the template repository is owned by.
- repository: (Required string)
The name of the template repository.
Teams Configuration
Your can use non-computed (known at terraform plan) team names or slugs (*_teams Attributes) or computed (only known in terraform apply phase) team IDs (*teamids Attributes). When using non-computed names/slugs teams need to exist before running plan. This is due to some terraform limitation and we will update the module once terraform removed this limitation.
pullteams: (Optionallist(string))
pullteamids. A list of teams to grant pull (read-only) permission.
Recommended for non-code contributors who want to view or discuss your project.
Default is [].
triageteams: (Optionallist(string))
triageteamids. A list of teams to grant triage permission.
Recommended for contributors who need to proactively manage issues and pull requests
without write access.
Default is [].
pushteams: (Optionallist(string))
pushteamids. A list of teams to grant push (read-write) permission.
Recommended for contributors who actively push to your project.
Default is [].
maintainteams: (Optionallist(string))
maintainteamids. A list of teams to grant maintain permission.
Recommended for project managers who need to manage the repository without access to sensitive or destructive actions.
Default is [].
adminteams: (Optionallist(string))
adminteamids. A list of teams to grant admin (full) permission.
Recommended for people who need full access to the project, including sensitive and destructive actions like managing security or deleting a repository.
Default is [].
Collaborator Configuration
pullcollaborators: (Optionallist(string))
Default is [].
triagecollaborators: (Optionallist(string))
Default is [].
pushcollaborators: (Optionallist(string))
Default is [].
maintaincollaborators: (Optionallist(string))
Default is [].
admincollaborators: (Optionallist(string))
Default is [].
Branches Configuration
branches: (Optionallist(branch))
Default is [].
Each branch object in the list accepts the following attributes:
- name: (Required string)
The name of the branch to create.
- sourcebranch: (Optional string)
The branch name to start from. Uses the configured default branch per default.
- sourcesha: (Optional bool)
The commit hash to start from. Defaults to the tip of sourcebranch. If provided, sourcebranch is ignored.
Default is true.
Deploy Keys Configuration
deploykeys: (Optionallist(deploykey))
list(string). Specifies deploy keys and access-level of deploy keys used in this repository.
Every string in the list will be converted internally into the object representation with the key argument being set to the string. object details are explained below.
Default is [].
Each deploy_key object in the list accepts the following attributes:
- key: (Required string)
The SSH public key.
- title: (Optional string)
A Title for the key. Default is the comment field of SSH public key if it is not empty else it defaults to md5(key).
- readonly: (Optional bool)
Specifies the level of access for the key.
Default is true.
- id: (Optional string)
Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. The ID must be unique between deploykeys and deploykeys_computed.
Default is "md5(key)".
deploykeyscomputed: (Optionallist(deploykey))
string. Same as deploy_keys argument with the following differences:
Use this argument if you depend on computed keys that terraform can not use in resource foreach execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. Prefer deploykeys whenever possible.
This argument does not conflict with deploy_keys and should exclusively be used for computed resources.
Default is [].
Each deploy_key object in the list accepts the following attributes:
- key: (Required string)
The SSH public key.
- title: (Optional string)
A Title for the key. Default is the comment field of SSH public key if it is not empty else it defaults to md5(key).
- readonly: (Optional bool)
Specifies the level of access for the key.
Default is true.
- id: (Optional string)
Specifies an ID which is used to prevent resource recreation when the order in the list of deploy keys changes. The ID must be unique between deploykeys and deploykeys_computed.
Default is "md5(key)".
Branch Protections v3 Configuration
branchprotectionsv3: (Optionallist(branchprotectionv3))
Default is [].
Each branchprotectionv3 object in the list accepts the following attributes:
- branch: (Required string)
The Git branch to protect.
- enforceadmins: (Optional bool)
Setting this to true enforces status checks for repository administrators.
Default is false.
- requireconversationresolution: (Optional bool)
Setting this to true requires all conversations to be resolved.
Default is false.
- requiresignedcommits: (Optional bool)
Setting this to true requires all commits to be signed with GPG.
Default is false.
- requiredstatuschecks: (Optional object(requiredstatuschecks))
Enforce restrictions for required status checks. See Required Status Checks below for details.
Default is {}.
The requiredstatuschecks object accepts the following attributes:
- strict: (Optional bool)
Require branches to be up to date before merging.
Default is false.
- contexts: (Optional list(string))
The list of status checks to require in order to merge into this branch. If default is [] no status checks are required.
Default is [].
- requiredpullrequestreviews: (Optional object(requiredpullrequestreviews))
Enforce restrictions for pull request reviews.
Default is {}.
The requiredpullrequest_reviews object accepts the following attributes:
- dismissstalereviews: (Optional bool)
Dismiss approved reviews automatically when a new commit is pushed.
Default is true.
- dismissalusers: (Optional list(string))
The list of user logins with dismissal access
Default is [].
- dismissalteams: (Optional list(string))
The list of team slugs with dismissal access. Always use slug of the team, not its name. Each team already has to have access to the repository.
Default is [].
- requirecodeownerreviews: (Optional bool)
Require an approved review in pull requests including files with a designated code owner.
Default is false.
- restrictions: (Optional object(restrictions))
Enforce restrictions for the users and teams that may push to the branch - only available for organization-owned repositories. See Restrictions below for details.
Default is {}.
The restrictions object accepts the following attributes:
- users: (Optional list(string))
The list of user logins with push access.
Default is [].
- teams: (Optional list(string))
The list of team slugs with push access. Always use slug of the team, not its name. Each team already has to have access to the repository.
Default is [].
- apps: (Optional list(string))
The list of app slugs with push access.
Default is [].
Branch Protections v4 Configuration
branchprotectionsv4: (Optionallist(branchprotectionv4))
Each element in the list is a branch to be protected and the value the corresponding to the desired configuration for the branch.
When applied, the branch will be protected from forced pushes and deletion. Additional constraints, such as required status checks or restrictions on users and teams, can also be configured.
NOTE: May conflict with v3 branch protections if used for the same branch.
Default is [].
Each branchprotectionv4 object in the list accepts the following attributes:
- pattern: (Required string)
Identifies the protection rule pattern.
- key: (Optional string)
An alternative key to use in for_each resource creation. Defaults to the value of var.pattern.
- allowsdeletions: (Optional bool)
Setting this to true to allow the branch to be deleted.
Default is false.
- allowsforcepushes: (Optional bool)
Setting this to true to allow force pushes on the branch.
Default is false.
- blockscreations: (Optional bool)
Setting this to true will block creating the branch.
Default is false.
- enforceadmins: (Optional bool)
Keeping this as true enforces status checks for repository administrators.
Default is true.
- pushrestrictions: (Optional list(string))
The list of actor Names/IDs that may push to the branch. Actor names must either begin with a "/" for users or the organization name followed by a "/" for teams.
Default is [].
- requireconversationresolution: (Optional bool)
Setting this to true requires all conversations on code must be resolved before a pull request can be merged.
Default is false.
- requiresignedcommits: (Optional bool)
Setting this to true requires all commits to be signed with GPG.
Default is false.
- requiredlinearhistory: (Optional bool)
Setting this to true enforces a linear commit Git history, which prevents anyone from pushing merge commits to a branch.
Default is false.
- requiredpullrequestreviews: (Optional object(requiredpullrequestreviews))
Enforce restrictions for pull request reviews.
The requiredpullrequest_reviews object accepts the following attributes:
- dismissstalereviews: (Optional bool)
Dismiss approved reviews automatically when a new commit is pushed.
Default is true.
- restrictdismissals: (Optional bool)
Restrict pull request review dismissals.
- dismissalrestrictions: (Optional list(string))
The list of actor Names/IDs with dismissal access. If not empty, restrict_dismissals is ignored Actor names must either begin with a / for users or the organization name followed by a / for teams.
Default is [].
- pullrequestbypassers: (Optional list(string))
The list of actor Names/IDs that are allowed to bypass pull request requirements. Actor names must either begin with a / for users or the organization name followed by a / for teams.
Default is [].
- requirecodeownerreviews: (Optional bool)
Require an approved review in pull requests including files with a designated code owner.
Default is true.
- requiredapprovingreviewcount: (Optional number)
Require x number of approvals to satisfy branch protection requirements. If this is specified it must be a number between 0-6.
Default is 0.
- requiredstatuschecks: (Optional object(requiredstatuschecks))
Enforce restrictions for required status checks. See Required Status Checks below for details.
The requiredstatuschecks object accepts the following attributes:
- strict: (Optional bool)
Require branches to be up to date before merging.
Default is false.
- contexts: (Optional list(string))
The list of status checks to require in order to merge into this branch. If default is [] no status checks are required.
Default is [].
Issue Labels Configuration
issuelabels: (Optionallist(issuelabel))
Default is [].
Each issue_label object in the list accepts the following attributes:
- name: (Required string)
The name of the label.
- color: (Required string)
A 6 character hex code, without the leading #, identifying the color of the label.
- description: (Optional string)
A short description of the label.
Default is "".
- id: (Optional string)
Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes.
Default is "name".
issuelabelsmergewithgithublabels: (Optionalbool)
issue_labels argument.
issuelabelscreate: (Optionalbool)
true if hasissues is true or issuelabels is non-empty.
Projects Configuration
projects: (Optionallist(project))
Default is [].
Each project object in the list accepts the following attributes:
- name: (Required string)
The name of the project.
- body: (Optional string)
The body of the project.
Default is "".
- id: (Optional string)
Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes.
Default is "name".
Webhooks Configuration
webhooks: (Optionallist(webhook))
Default is [].
Each webhook object in the list accepts the following attributes:
- events: (Required list(string))
A list of events which should trigger the webhook. See a list of available events.
- url: (Required string)
The URL to which the payloads will be delivered.
- active: (Optional bool)
Indicate if the webhook should receive events. Defaults to true.
- contenttype: (Optional string)
The media type used to serialize the payloads. Supported values include json and form.
Default is "form".
- secret: (Optional string)
If provided, the secret will be used as the key to generate the HMAC hex digest value in the X-Hub-Signature header.
- insecuressl: (Optional bool)
Determines whether the SSL certificate of the host for url will be verified when delivering payloads. Supported values include 0 (verification is performed) and 1 (verification is not performed). The default is 0. We strongly recommend not setting this to 1 as you are subject to man-in-the-middle and other attacks.
Secrets Configuration
plaintextsecrets: (Optionalmap(string))
Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding secret in plain text:
When applied, a secret with the given key and value will be created in the repositories.
The value of the secrets must be given in plain text, GitHub provider is in charge of encrypting it.
Attention: You should treat state as sensitive always. It is also advised that you do not store plaintext values in your code but rather populate the encrypted_value using fields from a resource, data source or variable as, while encrypted in state, these will be easily accessible in your code. See below for an example of this abstraction.
Default is {}.
Example:
plaintext_secrets = {
SECRETNAME1 = "plaintextsecretvalue_1"
SECRETNAME2 = "plaintextsecretvalue_2"
}encryptedsecrets: (Optionalmap(string))
Each element in the map is considered a secret to be managed, being the key map the secret name and the value the corresponding encrypted value of the secret using the Github public key in Base64 format.b
When applied, a secret with the given key and value will be created in the repositories.
Default is {}.
Example:
encrypted_secrets = {
SECRETNAME1 = "c2VjcmV0X3ZhbHVlXzE="
SECRETNAME2 = "c2VjcmV0X3ZhbHVlXzI="
}requiredapprovingreviewcount: (Optionalnumber)
Autolink References Configuration
autolinkreferences: (Optionallist(autolinkreference))
Default is [].
Each autolink_reference object in the list accepts the following attributes:
- keyprefix: (Required string)
This prefix appended by a number will generate a link any time it is found in an issue, pull request, or commit.
- targeturltemplate: (Required string)
The template of the target URL used for the links; must be a valid URL and contain <num> for the reference number.
App Installations
appinstallations: (Optionalset(string))
Default is {}.
Example:
app_installations = ["05405144", "12556423"]Module Configuration
moduledependson: (Optionallist(dependency))
depends_on on modules as of today (v0.12.24)
we might hit race conditions when dealing with team names instead of ids.
So when using the feature of adding teams by slug/name to the repository when creating it,
make sure to add all teams to this list as indirect dependencies.
Default is [].
Module Outputs
The following attributes are exported by the module:
repository: (object(repository))
github_repository]
resource containing all arguments as specified above and the other
attributes as specified below.
branches: (object(branches))
github_branch]
resource containing all arguments as specified above and the other
attributes as specified below.
fullname: (string)
htmlurl: (string)
sshcloneurl: (string)
httpcloneurl: (string)
gitcloneurl: (string)
collaborators: (object(collaborators))
name of the collaborator as
returned by the [githubrepositorycollaborator] resource.
deploykeys: (object(deploykeys))
deploykeys and deploykeys_computed as returned by the
[githubrepositorydeploy_key] resource keyed by the input id of the
key.
projects: (object(project))
id of the project as returned by
the [githubrepositoryproject] resource
issuelabels: (object(issuelabel))
webhooks: (object(webhook))
githubrepositorywebhook resource.
secrets: (object(secret))
appinstallations: (set(number))
External Documentation
Terraform Github Provider Documentation
- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository
- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/branch
- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_collaborator
- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repositorydeploykey
- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository_project
- https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repositoryautolinkreference
Module Versioning
This Module follows the principles of [Semantic Versioning (SemVer)].
Given a version number MAJOR.MINOR.PATCH, we increment the:
MAJORversion when we make incompatible changes,MINORversion when we add functionality in a backwards compatible manner, andPATCHversion when we make backwards compatible bug fixes.
Backwards compatibility in 0.0.z and 0.y.z version
- Backwards compatibility in versions
0.0.zis not guaranteed whenzis increased. (Initial development) - Backwards compatibility in versions
0.y.zis not guaranteed whenyis increased. (Pre-release)
About Mineiros
[Mineiros][homepage] is a remote-first company headquartered in Berlin, Germany that solves development, automation and security challenges in cloud infrastructure.
Our vision is to massively reduce time and overhead for teams to manage and deploy production-grade and secure cloud infrastructure.
We offer commercial support for all of our modules and encourage you to reach out if you have any questions or need help. Feel free to email us at [hello@mineiros.io] or join our [Community Slack channel][slack].
Reporting Issues
We use GitHub [Issues] to track community reported issues and missing features.
Contributing
Contributions are always encouraged and welcome! For the process of accepting changes, we use [Pull Requests]. If you'd like more information, please see our [Contribution Guidelines].
Makefile Targets
This repository comes with a handy [Makefile]. Run make help to see details on each available target.
License
[![license][badge-license]][apache20]
This module is licensed under the Apache License Version 2.0, January 2004. Please see [LICENSE] for full details.
Copyright © 2020-2022 [Mineiros GmbH][homepage]
[github]: https://github.com/ [github_repository]: https://www.terraform.io/docs/providers/github/r/repository.html#attributes-reference [githubrepositorycollaborator]: https://www.terraform.io/docs/providers/github/r/repository_collaborator.html#attribute-reference [githubrepositorydeploykey]: https://www.terraform.io/docs/providers/github/r/repositorydeploy_key.html#attributes-reference [githubrepositoryproject]: https://www.terraform.io/docs/providers/github/r/repository_project.html#attributes-reference [githubrepositoryautolinkreference]: https://www.terraform.io/docs/providers/github/r/repositoryautolink_reference.html#attributes-reference [homepage]: https://mineiros.io/?ref=terraform-github-repository [github-as-code]: https://mineiros.io/github-as-code?ref=terraform-github-repository [hello@mineiros.io]: mailto:hello@mineiros.io [badge-build]: https://github.com/mineiros-io/terraform-github-repository/workflows/CI/CD%20Pipeline/badge.svg [badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-github-repository.svg?label=latest&sort=semver [badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg [badge-terraform]: https://img.shields.io/badge/terraform-1.x-623CE4.svg?logo=terraform [badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack [badge-tf-gh]: https://img.shields.io/badge/GH-4.10+-F8991D.svg?logo=terraform [releases-github-provider]: https://github.com/terraform-providers/terraform-provider-github/releases [build-status]: https://github.com/mineiros-io/terraform-github-repository/actions [releases-github]: https://github.com/mineiros-io/terraform-github-repository/releases [releases-terraform]: https://github.com/hashicorp/terraform/releases [apache20]: https://opensource.org/licenses/Apache-2.0 [slack]: https://join.slack.com/t/mineiros-community/shared_invite/zt-ehidestg-aLGoIENLVs6tvwJ11w9WGg [terraform]: https://www.terraform.io [aws]: https://aws.amazon.com/ [semantic versioning (semver)]: https://semver.org/ [variables.tf]: https://github.com/mineiros-io/terraform-github-repository/blob/main/variables.tf [examples/]: https://github.com/mineiros-io/terraform-github-repository/blob/main/examples [issues]: https://github.com/mineiros-io/terraform-github-repository/issues [license]: https://github.com/mineiros-io/terraform-github-repository/blob/main/LICENSE [makefile]: https://github.com/mineiros-io/terraform-github-repository/blob/main/Makefile [pull requests]: https://github.com/mineiros-io/terraform-github-repository/pulls [contribution guidelines]: https://github.com/mineiros-io/terraform-github-repository/blob/main/CONTRIBUTING.md
