github_organization

The github-organization is a generic Terraform module within the pippi.io family, maintained by pippiio. The pippi.io modules are built to support common use cases for pippiio users. They are created with best practices in mind and battle tested at scale. All modules are free and open-source under the Apache License 2.0.

The github-organization module is made to provision and manage a GitHub organization for common pippiio use cases. This includes, creating repositories, secrets, and more.

Examples

module "github" {
  source = "github.com/pippiio/github-organization?ref=HEAD"

  organization = {
    billing_email = "hello@pippi.io"
    public_email  = "hello@pippi.io"
    name          = "pippiio"
    display_name  = "Pippi io"
    description   = "Battle tested Terraform modules"
    location      = "Denmark"
    website       = "https://pippi.io"
    twitter       = null
    members       = {}
  }

  teams = {
    pippiio = {
      description = "Maintainers of the pippiio organization"
      members     = {}
    }
  }

  repositories = {
    "github_organization" = {
      description     = "Terraform module for managing a GitHub organization"
      team_permission = { pippiio = "read_write" }
      rules = {
        # Repository admins have no automatic bypass.
        # Include "repositoryadmin" in a bypass role list to grant it explicitly.
        create_tag_teams        = ["pippiio"]
        dot_github_bypass_teams = ["pippiio"]
        default_branch = {
          rule_bypass_teams = ["pippiio"]
          rule_bypass_mode  = "pull_request"
        }
      }
    }
  }
}

Requirements

Name	Version
terraform	~>1.14
github	~>6.9

Providers

Name	Version
github	6.13.0

Inputs

Name	Description	Type	Default	Required
organization	GitHub organization configuration: billing_email : The billing email address for the organization name : The GitHub name for the organization display_name : Organization display name description : An organization description public_email : Organization e-mail (will be public) location : The organization location or country website : The company website enable_scanning : Enable GitHub managed code security scanning enable_pages : Wether to enable GitHub pages on organization level members : A list of GitHub usernames to join organization as members	object({ billing_email = string name = string display_name = string description = string public_email = string location = string website = string enable_scanning = optional(bool, false) enable_pages = optional(bool, false) members = map(string) })	n/a	yes
repositories	A map of GitHub repositories in the organization. Key : The name of the repository Value : description : A description of the repository visibility : Can be public or private. Defaults to private homepage : URL of a page describing the project enable_projects : Set to true to enable the GitHub Projects features on the repository enable_wiki : Set to true to enable the GitHub Wiki features on the repository enable_issues : Set to true to enable the GitHub Issues features on the repository enable_discussions : Set to true to enable the GitHub Discussions features on the repository allow_merge_commit : Set to true to enable merge commits on the repository allow_squash_merge : Set to false to disable squash merges on the repository allow_rebase_merge : Set to true to enable rebase merges on the repository delete_branch_on_merge : Set to false to disable automatically deletion of head branch after a pull request is merged team_permission : A map of GitHub organization teams to grant access Key : The name of GitHub them team Value : Set to 'read_write' to grant write access and 'read' to grant read-only access collaborator_permission : A map of GitHub collaborators to grant access Key : The collaborator's GitHub username Value : Set to true to grant write access and false to grant read-only access template_repository : The name of the template repository. This must be loctaed within the same organization. is_template : Wether the repository is enabled as template repository. topics : The list of topics of the repository. environments : A map of actions environments Key : The name of the actions environment Value : A map of env vars and secrets within the action environment Key : The name of the env var or secret Value : description : A description of the env var value : The value of the env var or secret sensitive : Wether the value if sensitive and should be treated as a secret rules : Configuration of repository rulesets default_branch : Ruleset protecting default branch required_approvals : Required number of approvals to satisfy default branch protection requirements require_code_owner_review : Require an approved review in pull requests including files with a designated code owner required_status_checks : The list of status checks to require in order to merge into main branch rule_bypass_teams : A set of team names that may bypass the default branch ruleset. rule_bypass_roles : Roles that may bypass the default branch ruleset using rule_bypass_mode. Defaults to []; include "repositoryadmin" to grant repository admins bypass. rule_bypass_mode : Bypass mode for configured apps, teams, and roles on the default branch. Set to "pull_request" to require a pull request when bypassing, or "always" (the default) to also allow direct pushes. Other rulesets are unaffected. bypass_apps : A set of GitHub app ids that may bypass rulesets conventional_branch_names : Set to true to allow conventional commits branch naming allowed_branch_name_patterns : A set of string patterns defining allowed branch naming imutable_tags : Set to true to deny changing tags sem_ver_tags : Set to true to allow semantic version tags allowed_tag_patterns : A set of string patterns defining allowed tag naming create_tag_teams : A set of team names that may create tags. create_tag_roles : Roles that may create tags. Defaults to []; include "repositoryadmin" to grant repository admins tag creation bypass. dot_github_bypass_teams : A set of team names that may push to .github folder. dot_github_bypass_roles : Roles that may push to .github folder. Defaults to []; include "repositoryadmin" to grant repository admins bypass for this protection.	map(object({ description = string visibility = optional(string, "private") homepage = optional(string) enable_projects = optional(bool, false) enable_wiki = optional(bool, false) enable_issues = optional(bool, false) enable_discussions = optional(bool, false) allow_merge_commit = optional(bool, false) allow_squash_merge = optional(bool, true) allow_rebase_merge = optional(bool, false) delete_branch_on_merge = optional(bool, true) team_permission = map(string) collaborator_permission = optional(map(bool), {}) template_repository = optional(string) is_template = optional(bool, false) topics = optional(list(string), []) environments = optional(map(map(object({ description = string value = string sensitive = bool }))), {}) rules = optional(object({ default_branch = optional(object({ required_approvals = optional(number, 1) require_code_owner_review = optional(bool, false) required_status_checks = optional(set(string), []) rule_bypass_teams = optional(set(string), []) rule_bypass_roles = optional(set(string), []) rule_bypass_mode = optional(string, "always") }), {}) bypass_apps = optional(set(string), []) conventional_branch_names = optional(bool, true) allowed_branch_name_patterns = optional(set(string), []) imutable_tags = optional(bool, true) sem_ver_tags = optional(bool, true) allowed_tag_patterns = optional(set(string), []) create_tag_teams = optional(set(string), []) create_tag_roles = optional(set(string), []) dot_github_bypass_teams = optional(set(string), []) dot_github_bypass_roles = optional(set(string), []) }), {}) }))	n/a	yes
teams	A map of GitHub team configuration to be added to the organization: Key : Name of team Value : description : Team description code_review_count : The number of team members to assign to a pull request code_review_notify : Whether to notify the entire team when at least one member is also assigned to the pull request members : A map of members to join the team Key : member's GitHub username Value : member role in team	map(object({ description = string code_review_count = optional(number, 1) code_review_notify = optional(bool, true) members = map(string) }))	n/a	yes
hosted_runner_groups	A map of GitHub hosted runner groups to be added to the organization: Key : Name of runner group Value : description : Runner group description repositories : An optional set of repository names to limit the runner group access. If not provided, the runner group will have access to all repositories in the organization.	map(object({ repositories = optional(set(string), []) allow_all_repositories = bool }))	{}	no

Resources

Name	Type
github_actions_environment_secret.this	resource
github_actions_environment_variable.this	resource
github_actions_runner_group.this	resource
github_membership.this	resource
github_organization_settings.this	resource
github_repository.this	resource
github_repository_collaborator.this	resource
github_repository_environment.this	resource
github_repository_ruleset.enforce_branches_naming	resource
github_repository_ruleset.enforce_tag_naming	resource
github_repository_ruleset.immutable_tags	resource
github_repository_ruleset.protect_default_branch	resource
github_repository_ruleset.protect_dot_github	resource
github_repository_ruleset.sensitive_files	resource
github_repository_ruleset.sign_all_branches	resource
github_repository_ruleset.tag_actors	resource
github_team.this	resource
github_team_membership.this	resource
github_team_repository.this	resource
github_team_settings.this	resource
github_actions_organization_registration_token.this	data source

Outputs

Name	Description
members	A map of GitHub organization members.
repositories	A map of organization repositories
runner_groups	Runner group object with token, expiration and group ids.
teams	A map of GitHub organization teams including memberpriviledges.