Skip to content

Latest commit

 

History

History
115 lines (81 loc) · 71.8 KB

README.md

File metadata and controls

115 lines (81 loc) · 71.8 KB
Raw

GitHub Repositories Component

This repository contains a collection of Terraform configurations tailored for managing GitHub repositories, including permissions, webhooks, pages, and more.

Usage

Prerequsites

This Terraform module makes extensive use of the integrations/github Terraform Provider to manage resources within a GitHub organization or user account. This requires setting up the GitHub provider with appropriate credentials to interact with the GitHub API.

The following ways to authenticate with GitHub API are supported:

  • OAuth / Personal Access Token
  • GitHub App Installation

We use terraform-secrets-helper to retrieve sensitive data, such as tokens or pem file content. At the moment, we support SOPS encrypted files as a source, so before using this component:

Example

You can start with the configuration below to use the GitHub component module.

⚠️ the key of each item in the repos map matches the repository's name. This is to ensure consistent naming and referencing throughout your Terraform configuration.

module "gh_repos" {
  source = "git::https://github.com/masterpointio/terraform-components.git//github-repositories?ref=<TAG_OR_COMMIT_SHA>"

  # GitHub provider
  gh_owner             = "myorg"
  gh_token_secret_name = "gh_token"

  # SOPS secrets
  secret_mapping = [{
    name = "gh_token"
    file = "./config/secrets/global.yaml"
    type = "sops"
  }]

  # GitHub repositories
  repos = {
    "best-pet-project" = {
      description = "This is a private repo for the Best Pet Project."
      # ... other configurations
    },
    "demo" = {
      visibility = public
      # ... other configurations
    }
  }
}

Known Issues

You may encounter the following error during import:

Cannot import non-existent remote object

To overcome this, set the required environment variables to authenticate with GitHub API depending on the way you've chosen, e.g. GITHUB_TOKEN and GITHUB_OWNER.

Corresponding integrations/terraform-provider-github GitHub issue: #647.

Requirements

Name Version
terraform >= 1.0
github >= 5.0
sops >= 0.7

Providers

Name Version
github >= 5.0

Modules

Name Source Version
repos mineiros-io/repository/github 0.18.0
secrets masterpointio/helper/secrets 0.2.0

Resources

Name Type
github_actions_repository_access_level.this resource

Inputs

Name Description Type Default Required
gh_app_auth_id The ID of the GitHub App. string "" no
gh_app_auth_installation_id The ID of the GitHub App installation string "" no
gh_app_auth_pem_file_secret_name The name of the secret retrieved by secrets mixin that contains
the contents of the GitHub App private key PEM file.		 string null no
gh_base_url (Optional) This is the target GitHub base API endpoint.
Providing a value is a requirement when working with GitHub Enterprise.
It is optional to provide this value and it can also be sourced from the GITHUB_BASE_URL environment variable.
The value must end with a slash.		 string null no
gh_owner (Optional) This is the target GitHub organization or individual user account to manage.
For example, torvalds and github are valid owners. It is optional to provide this value
and it can also be sourced from the GITHUB_OWNER environment variable.
When not provided and a token is available, the individual user account owning the token will be used.
When not provided and no token is available, the provider may not function correctly.		 string null no
gh_token_secret_name The name of the secret retrieved by secrets mixin that contains the GitHub personal access token. string null no
repos The GitHub repositories for this organization. 
map(object({
 # Main Resource Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#main-resource-configuration
 allow_auto_merge = optional(bool, false)
 allow_merge_commit = optional(bool, false)
 allow_rebase_merge = optional(bool, false)
 allow_squash_merge = optional(bool, true)
 archive_on_destroy = optional(bool, true)
 archived = optional(bool, false)
 default_branch = optional(string, "main")
 delete_branch_on_merge = optional(bool, true)
 description = optional(string, "")
 extra_topics = optional(list(string), [])
 has_downloads = optional(bool, true)
 has_issues = optional(bool, true)
 has_projects = optional(bool, true)
 has_wiki = optional(bool, false)
 homepage_url = optional(string, "")
 is_template = optional(bool, false)
 pages = optional(object({
 branch = string
 cname = optional(string, null)
 path = optional(string, "/")
 }))
 topics = optional(list(string), [])
 visibility = optional(string, "private")
 vulnerability_alerts = optional(bool, true)

 # Extended Resource Configuration

 ## Repository Creation Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#repository-creation-configuration
 auto_init = optional(bool, true)
 gitignore_template = optional(string, "")
 license_template = optional(string, "")
 template = optional(object({
 owner = string
 repository = string
 }))

 ## Teams Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#teams-configuration
 admin_teams = optional(list(string), [])
 maintain_teams = optional(list(string), [])
 pull_teams = optional(list(string), [])
 push_teams = optional(list(string), [])
 triage_teams = optional(list(string), [])

 ## Collaborator Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#collaborator-configuration
 admin_collaborators = optional(list(string), [])
 maintain_collaborators = optional(list(string), [])
 pull_collaborators = optional(list(string), [])
 push_collaborators = optional(list(string), [])
 triage_collaborators = optional(list(string), [])

 ## Branches Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#branches-configuration
 branches = optional(list(object({
 name = string
 source_branch = optional(string, null)
 source_sha = optional(bool, null)
 })), [])

 ## Deploy Keys Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#deploy-keys-configuration
 deploy_keys = optional(list(object({
 id = optional(string, "md5(key)")
 key = string
 read_only = optional(bool, true)
 title = optional(string, null)
 })), [])
 deploy_keys_computed = optional(list(object({
 id = optional(string, "md5(key)")
 key = string
 read_only = optional(bool, true)
 title = optional(string, null)
 })), [])

 ## Branch Protections v4 Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#branch-protections-v4-configuration
 branch_protections_v4 = optional(list(object({
 pattern = string
 allows_deletions = optional(bool, false)
 allows_force_pushes = optional(bool, false)
 blocks_creations = optional(bool, false)
 enforce_admins = optional(bool, true)
 push_restrictions = optional(list(string), [])
 require_conversation_resolution = optional(bool, false)
 require_signed_commits = optional(bool, false)
 required_linear_history = optional(bool, false)
 required_pull_request_reviews = optional(object({
 dismiss_stale_reviews = optional(bool, true)
 restrict_dismissals = optional(bool, false)
 dismissal_restrictions = optional(list(string), [])
 pull_request_bypassers = optional(list(string), [])
 require_code_owner_reviews = optional(bool, true)
 required_approving_review_count = optional(number, 1)
 }), {})
 required_status_checks = optional(object({
 strict = optional(bool, false)
 contexts = optional(list(string), [])
 }), {})
 })), [])

 ## Issue Labels Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#issue-labels-configuration
 issue_labels = optional(list(object({
 color = string
 description = optional(string, null)
 id = optional(string, "name")
 name = string
 })), [])

 issue_labels_merge_with_github_labels = optional(bool)
 issue_labels_create = optional(bool)

 ## Projects Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#projects-configuration
 projects = optional(list(object({
 body = optional(string, "")
 id = optional(string, "name")
 name = string
 })), [])

 ## Webhooks Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#webhooks-configuration
 webhooks = optional(list(object({
 active = optional(bool, true)
 content_type = optional(string, "form")
 insecure_ssl = optional(bool, false)
 events = list(string)
 name = optional(string)
 secret = optional(string)
 url = string
 })), [])

 ## Secrets Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#secrets-configuration
 plaintext_secrets = optional(map(string), {})
 encrypted_secrets = optional(map(string), {})

 ## Autolink References Configuration
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#autolink-references-configuration
 autolink_references = optional(list(object({
 key_prefix = string
 target_url_template = string
 })), [])

 ## App Installations
 # https://github.com/mineiros-io/terraform-github-repository/tree/main#app-installations
 app_installations = optional(set(string), [])

 ## Managing Access
 # https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#managing-access-for-a-private-repository-in-an-organization
 access_level = optional(string, "")
 }))
 {} no
secret_mapping The list of secret mappings the application will need.
This creates secret values for the component to consume at local.secrets[name].		 
list(object({
 name = string
 type = string
 path = optional(string, null)
 file = string
 }))
 [] no

Outputs

No outputs.