A Terraform module for creating a public or private repository on Github.
This module supports Terraform v0.13 as well as v0.12.9 and above and is compatible with the Terraform Github Provider v3 as well as v2.6 and above.
- Module Features
- Getting Started
- Module Argument Reference
- Top-level Arguments
- Module Configuration
- Repository Configuration
- Repository Creation Configuration
- Teams Configuration
- Collaborator Configuration
- Deploy Keys Configuration
- Branch Protections Configuration
- Issue Labels Configuration
- Projects Configuration
- Webhooks Configuration
defaults
Object Attributestemplate
Object Attributesdeploy_key
Object Attributesbranch_protection
Object Attributesissue_label
Object Attributesproject
Object Attributeswebhook
Object Attributes
- Top-level Arguments
- Module Attributes Reference
- External Documentation
- Module Versioning
- About Mineiros
- Reporting Issues
- Contributing
- Makefile Targets
- License
In contrast to the plain github_repository
resource this module enables various other
features like Branch Protection or Collaborator Management.
-
Default Security Settings: This module creates a
private
repository by default, Deploy keys areread-only
by default -
Standard Repository Features: Setting basic Metadata, Merge Strategy, Auto Init, License Template, Gitignore Template, Template Repository
-
Extended Repository Features: Branch Protection, Issue Labels, Handle Github Default Issue Labels, Collaborators, Teams, Deploy Keys, Projects, Repository Webhooks
-
Features not yet implemented: Project Columns support, Actions, Repository File
Most basic usage creating a new private github repository.
module "repository" {
source = "mineiros-io/repository/github"
version = "~> 0.5.0"
name = "terraform-github-repository"
license_template = "apache-2.0"
gitignore_template = "Terraform"
}
See variables.tf and examples/ for details and use-cases.
-
module_depends_on
: (Optionallist(any)
)Due to the fact, that terraform does not offer
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[]
.
-
name
: (Requiredstring
)The name of the repository.
-
defaults
: (Optionalobject
)A object of default settings to use instead of module defaults for top-level arguments. See below for a list of supported arguments. Default is
{}
- use module defaults as described in the README. -
allow_merge_commit
: (Optionalbool
)Set to
false
to disable merge commits on the repository. If you set this tofalse
you have to enable eitherallow_squash_merge
orallow_rebase_merge
. Default istrue
. -
allow_squash_merge
: (Optionalbool
)Set to
true
to enable squash merges on the repository. Default isfalse
. -
allow_rebase_merge
: (Optionalbool
)Set to
true
to enable rebase merges on the repository. Default isfalse
. -
description
: (Optionalstring
)A description of the repository. Default is
""
-
delete_branch_on_merge
: (Optionalstring
)Set to
false
to disable the automatic deletion of head branches after pull requests are merged. Default istrue
-
homepage_url
: (Optionalstring
)URL of a page describing the project. Default is
""
-
private
: (Optionalbool
)Set to false to create a public repository. Default is
true
-
has_issues
: (Optionalbool
)Set to true to enable the GitHub Issues features on the repository. Default is
false
-
has_projects
: (Optionalbool
)Set to true to enable the GitHub Projects features on the repository. Default is
false
-
has_wiki
: (Optionalbool
)Set to true to enable the GitHub Wiki features on the repository. Default is
false
-
has_downloads
: (Optionalbool
)Set to
true
to enable the (deprecated) downloads features on the repository. Default isfalse
. -
is_template
: (Optionalbool
)Set to
true
to tell GitHub that this is a template repository. Default isfalse
. -
default_branch
: (Optionalstring
)The name of the default branch of the repository. NOTE: This can only be set after a repository has already been created, and after a correct reference has been created for the target branch inside the repository. This means a user will have to omit this parameter from the initial repository creation and create the target branch inside of the repository prior to setting this attribute. Default is
""
-
archived
: (Optionalbool
)Specifies if the repository should be archived. NOTE: Currently, the API does not support unarchiving. Default is
false
. -
topics
: (Optionallist(string)
)The list of topics of the repository. Default is
[]
. -
extra_topics
: (Optionallist(string)
)A list of additional topics of the repository. Those topics will be added to the list of
topics
. This is useful ifdefault.topics
are used and the list should be extended with more topics. Default is[]
.
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.
-
auto_init
: (Optionalbool
)Set to
false
to not produce an initial commit in the repository. Default istrue
. -
gitignore_template
: (Optionalstring
)Use the name of the template without the extension. Default is
""
-
license_template
: (Optionalstring
)Use the name of the template without the extension. Default is
""
-
template
: (Optionalobject
)Use a template repository to create this resource. See Template Object Attributes below for details.
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
(*_team_ids
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 thislimitation.
-
pull_teams
orpull_team_ids
: (Optionallist(string)
)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
[]
. -
triage_teams
ortriage_team_ids
: (Optionallist(string)
)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
[]
. -
push_teams
orpush_team_ids
: (Optionallist(string)
)A list of teams to grant push (read-write) permission. Recommended for contributors who actively push to your project. Default is
[]
. -
maintain_teams
ormaintain_team_ids
: (Optionallist(string)
)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
[]
. -
admin_teams
oradmin_team_ids
: (Optionallist(string)
)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
[]
.
-
pull_collaborators
: (Optionallist(string)
)A list of user names to add as collaborators granting them pull (read-only) permission. Recommended for non-code contributors who want to view or discuss your project. Default is
[]
. -
triage_collaborators
: (Optionallist(string)
)A list of user names to add as collaborators granting them triage permission. Recommended for contributors who need to proactively manage issues and pull requests without write access. Default is
[]
. -
push_collaborators
: (Optionallist(string)
)A list of user names to add as collaborators granting them push (read-write) permission. Recommended for contributors who actively push to your project. Default is
[]
. -
maintain_collaborators
: (Optionallist(string)
)A list of user names to add as collaborators granting them maintain permission. Recommended for project managers who need to manage the repository without access to sensitive or destructive actions. Default is
[]
. -
admin_collaborators
: (Optionallist(string)
)A list of user names to add as collaborators granting them 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
[]
.
-
deploy_keys
: (Optionallist(deploy_key|string)
)Specifies deploy keys and access-level of deploy keys used in this repository. Every
string
in the list will be converted internally into theobject
representation with thekey
argument being set to thestring
.object
details are explained below. Default is[]
. -
deploy_keys_computed
: (Optionallist(deploy_key|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 resourcefor_each
execution. Downside of this is the recreation of deploy key resources whenever the order in the list changes. Preferdeploy_keys
whenever possible. This argument does not conflict withdeploy_keys
and should exclusively be used for computed resources. Default is[]
.
-
branch_protections
: (Optionallist(branch_protection)
)This resource allows you to configure branch protection for repositories in your organization. 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. Default is
[]
.
-
issue_labels
: (Optionallist(issue_label)
)This resource allows you to create and manage issue labels within your GitHub organization. Issue labels are keyed off of their "name", so pre-existing issue labels result in a 422 HTTP error if they exist outside of Terraform. Normally this would not be an issue, except new repositories are created with a "default" set of labels, and those labels easily conflict with custom ones. This resource will first check if the label exists, and then issue an update, otherwise it will create. Default is
[]
. -
issue_labels_merge_with_github_labels
: (Optionalbool
)Specify if github default labels will be handled by terraform. This should be decided on upon creation of the repository. If you later decide to disable this feature, github default labels will be destroyed if not replaced by labels set in
issue_labels
argument. Default istrue
. -
issue_labels_create
: (Optionalbool
)Specify whether you want to force or suppress the creation of issues labels. Default is
true
ifhas_issues
istrue
orissue_labels
is non-empty, otherwise default isfalse
.
-
projects
: (Optionallist(project)
)This resource allows you to create and manage projects for GitHub repository. Default is
[]
.
-
webhooks
: (Optionallist(webhook)
)This resource allows you to create and manage webhooks for repositories in your organization. When applied, a webhook will be created which specifies a URL to receive events and which events to receieve. Additional constraints, such as SSL verification, pre-shared secret and content type can also be configured Default is
[]
.
defaults
Object Attributes
This is a special argument to set various defaults to be reused for multiple repositories.
The following top-level arguments can be set as defaults:
homepage_url
,
private
,
has_issues
,
has_projects
,
has_wiki
,
allow_merge_commit
,
allow_rebase_merge
,
allow_squash_merge
,
has_downloads
,
auto_init
,
gitignore_template
,
license_template
,
default_branch
,
topics
,
issue_labels_create
,
issue_labels_merge_with_github_labels
.
Module defaults are used for all arguments that are not set in defaults
.
Using top level arguments override defaults set by this argument.
Default is {}
.
template
Object Attributes
-
owner
: (Requiredstring
)The GitHub organization or user the template repository is owned by.
-
repository
: (Requiredstring
)The name of the template repository.
deploy_key
Object Attributes
-
key
: (Requiredstring
)The SSH public key.
-
title
: (Optionalstring
)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)
. -
read_only
: (Optionalbool
)Specifies the level of access for the key. Default is
true
. -
id
: (Optionalstring
)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
deploy_keys
anddeploy_keys_computed
. Default ismd5(key)
.
branch_protection
Object Attributes
-
branch
: (Requiredstring
)The Git branch to protect.
-
enforce_admins
: (Optionalbool
)Setting this to true enforces status checks for repository administrators. Default is
false
. -
require_signed_commits
: (Optionalbool
)Setting this to true requires all commits to be signed with GPG. Default is
false
. -
required_status_checks
: (Optionalrequired_status_checks
)Enforce restrictions for required status checks. See Required Status Checks below for details. Default is
{}
. -
required_pull_request_reviews
: (Optionalrequired_pull_request_reviews
)Enforce restrictions for pull request reviews. See Required Pull Request Reviews below for details. Default is
{}
. -
restrictions
: (Optionalrestrictions
)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
{}
.
required_status_checks
Object Attributes
-
strict
: (Optionalbool
)Require branches to be up to date before merging. Defaults is
false
. -
contexts
: (Optionallist(string)
)The list of status checks to require in order to merge into this branch. Default is
[]
- No status checks are required.
required_pull_request_reviews
Object Attributes
-
dismiss_stale_reviews
: (Optionalbool
)Dismiss approved reviews automatically when a new commit is pushed. Default is
false
. -
dismissal_users
: (Optionallist(string)
)The list of user logins with dismissal access Default is
[]
. -
dismissal_teams
: (Optionallist(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
[]
. -
require_code_owner_reviews
: (Optionalbool
)Require an approved review in pull requests including files with a designated code owner. Defaults is
false
. -
required_approving_review_count
: (Optionalnumber
)Require x number of approvals to satisfy branch protection requirements. If this is specified it must be a number between 1-6. This requirement matches Github's API, see the upstream documentation for more information. Default is no approving reviews are required.
restrictions
Object Attributes
-
users
: (Optionallist(string)
)The list of user logins with push access. Default is
[]
. -
teams
: (Optionallist(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
: (Optionallist(string)
)The list of app slugs with push access. Default is
[]
.
issue_label
Object Attributes
-
name
: (Requiredstring
)The name of the label.
-
color
: (Requiredstring
)A 6 character hex code, without the leading #, identifying the color of the label.
-
description
: (Optionalstring
)A short description of the label. Default is
""
. -
id
: (Optionalstring
)Specifies an ID which is used to prevent resource recreation when the order in the list of issue labels changes. Default is
name
.
project
Object Attributes
-
name
: (Requiredstring
)The name of the project.
-
body
: (Optionalstring
)The body of the project. Default is
""
. -
id
: (Optionalstring
)Specifies an ID which is used to prevent resource recreation when the order in the list of projects changes. Default is
name
.
webhook
Object Attributes
-
events
: (Requiredlist(string)
)A list of events which should trigger the webhook. See a list of available events.
-
url
: (Requiredstring
)The URL to which the payloads will be delivered.
-
active
: (Optionalbool
)Indicate if the webhook should receive events. Defaults to
true
. -
content_type
: (Optionalstring
)The media type used to serialize the payloads. Supported values include
json
andform
. The default isform
. -
secret
: (Optionalstring
)If provided, the
secret
will be used as thekey
to generate the HMAC hex digest value in the[X-Hub-Signature](https://developer.github.com/webhooks/#delivery-headers)
header. -
insecure_ssl
: (Optionalbool
)Determines whether the SSL certificate of the host for
url
will be verified when delivering payloads. Supported values include0
(verification is performed) and1
(verification is not performed). The default is0
. We strongly recommend not setting this to1
as you are subject to man-in-the-middle and other attacks.
The following attributes are exported by the module:
-
repository
All repository attributes as returned by the
github_repository
resource containing all arguments as specified above and the other attributes as specified below.-
full_name
A string of the form "orgname/reponame".
-
html_url
URL to the repository on the web.
-
ssh_clone_url
URL that can be provided to git clone to clone the repository via SSH.
-
http_clone_url
URL that can be provided to git clone to clone the repository via HTTPS.
-
git_clone_url
URL that can be provided to git clone to clone the repository anonymously via the git protocol.
-
-
collaborators
A map of Collaborator objects keyed by the
name
of the collaborator as returned by thegithub_repository_collaborator
resource. -
deploy_keys
A merged map of deploy key objects for the keys originally passed via
deploy_keys
anddeploy_keys_computed
as returned by thegithub_repository_deploy_key
resource keyed by the inputid
of the key. -
projects
A map of Project objects keyed by the
id
of the project as returned by thegithub_repository_project
resource
- Terraform Github Provider Documentation:
This Module follows the principles of Semantic Versioning (SemVer).
Given a version number MAJOR.MINOR.PATCH
, we increment the:
MAJOR
version when we make incompatible changes,MINOR
version when we add functionality in a backwards compatible manner, andPATCH
version when we make backwards compatible bug fixes.
- Backwards compatibility in versions
0.0.z
is not guaranteed whenz
is increased. (Initial development) - Backwards compatibility in versions
0.y.z
is not guaranteed wheny
is increased. (Pre-release)
Mineiros is a DevOps as a Service company based in Berlin, Germany. We offer commercial support for all of our projects and encourage you to reach out if you have any questions or need help. Feel free to send us an email at hello@mineiros.io or join our Community Slack channel.
We can also help you with:
- Terraform modules for all types of infrastructure such as VPCs, Docker clusters, databases, logging and monitoring, CI, etc.
- Consulting & training on AWS, Terraform and DevOps
We use GitHub Issues to track community reported issues and missing features.
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.
This repository comes with a handy Makefile.
Run make help
to see details on each available target.
This module is licensed under the Apache License Version 2.0, January 2004. Please see LICENSE for full details.
Copyright © 2020 Mineiros GmbH