From 8ab1bef9624d7fa5b02d1a9bb4367469594c5f33 Mon Sep 17 00:00:00 2001 From: Soren Martius Date: Tue, 23 Jun 2020 20:30:22 +0200 Subject: [PATCH] Align README.md and variables.tf with latest standard --- README.md | 36 +++++--- examples/README.md | 28 ++++++ examples/github-team/README.md | 89 +++++++++++++++++++ examples/github-team/main.tf | 69 ++++++++++++++ .../outputs.tf | 0 .../public-repositories-with-team/main.tf | 42 --------- .../variables.tf | 74 --------------- main.tf | 10 +-- outputs.tf | 17 ++-- test/README.md | 4 +- test/github_team_test.go | 2 +- test/module-enabled/main.tf | 12 --- test/module-enabled/outputs.tf | 10 --- test/module_enabled_test.go | 33 ------- variables.tf | 42 +-------- 15 files changed, 225 insertions(+), 243 deletions(-) create mode 100644 examples/README.md create mode 100644 examples/github-team/README.md create mode 100644 examples/github-team/main.tf rename examples/{public-repositories-with-team => github-team}/outputs.tf (100%) delete mode 100644 examples/public-repositories-with-team/main.tf delete mode 100644 examples/public-repositories-with-team/variables.tf delete mode 100644 test/module-enabled/main.tf delete mode 100644 test/module-enabled/outputs.tf delete mode 100644 test/module_enabled_test.go diff --git a/README.md b/README.md index edde9d5..da2a350 100644 --- a/README.md +++ b/README.md @@ -8,18 +8,23 @@ # terraform-github-team -A [Terraform] ~> 0.12 module that offers a more convenient and tested way to provision and manage [GitHub teams]. +A [Terraform] 0.12 module that offers a more convenient and tested way to provision and manage [GitHub teams]. - [Features](#features) - [Getting Started](#getting-started) - [Examples](#examples) -- [Makefile Targets](#makefile-targets) -- [Tests](#tests) +- [Module Argument Reference](#module-argument-reference) + - [Top-level Arguments](#top-level-arguments) + - [Module Configuration](#module-configuration) + - [Main Resource Configuration](#main-resource-configuration) +- [Module Attributes Reference](#module-attributes-reference) +- [External Documentation](#external-documentation) - [Module Versioning](#module-versioning) - [Backwards compatibility in `0.0.z` and `0.y.z` version](#backwards-compatibility-in-00z-and-0yz-version) - [About Mineiros](#about-mineiros) - [Reporting Issues](#reporting-issues) - [Contributing](#contributing) +- [Makefile Targets](#makefile-targets) - [License](#license) ## Features @@ -74,53 +79,58 @@ See [variables.tf] and [examples/] for details and use-cases. #### Module Configuration -- **`module_enabled`**: *(Optional `bool`)* - - Specifies whether resources in the module will be created. - Default is `true`. - - **`module_depends_on`**: *(Optional `list(any)`)* A list of dependencies. Any object can be _assigned_ to this list to define a hidden external dependency. #### Main Resource Configuration -- **`name`**: *(Required `string`)* +- **`name`**: **(Required `string`)** + The name of the team. - **`push_repositories`**: *(Optional `set(string)`)* + A list of repository names the current team should get push (read-write) permission to. Default is `[]`. - **`pull_repositories`**: *(Optional `set(string)`)* + A list of repository names the current team should get pull (read-only) permission to. Default is `[]`. - **`maintainers`**: *(Optional `set(string)`)* + A list of users that will be added to the current team with maintainer permissions. Default is `[]`. - **`members`**: *(Optional `set(string)`)* + A list of users that will be added to the current team with member permissions. Default is `[]`. - **`admin_repositories`**: *(Optional `set(string)`)* + A list of repository names the current team should get admin (full) permission to. Default is `[]`. - **`description`**: *(Optional `string`)* + A description of the team. Default is `""`. - **`privacy`**: *(Optional `string`)* + The level of privacy for the team. Must be one of `secret` or `closed`. - Default is `""`. + Default is `"secret"`. - **`parent_team_id`**: *(Optional `number`)* + The ID of the parent team, if this is a nested team. - Default is `null`. + Default is to create a root team without a parent. - **`ldap_dn`**: *(Optional `string`)* + The LDAP Distinguished Name of the group where membership will be synchronized. Only available in GitHub Enterprise. Default is `null`. @@ -128,9 +138,9 @@ See [variables.tf] and [examples/] for details and use-cases. The following attributes are exported by the module: -- **`module_enabled`** +- **`module_depends_on`** - Whether this module is enabled. + A list of external resources the module depends_on. ## External Documentation diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..1b277e7 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,28 @@ +[][homepage] + +[![GitHub tag (latest SemVer)][badge-semver]][releases-github] +[![license][badge-license]][apache20] +[![Terraform Version][badge-terraform]][releases-terraform] +[![Join Slack][badge-slack]][slack] + +# Examples for using this Mineiros module + +- [github-team/] Create a team with two repositories with different permissions. + + + + +[github-team/]: https://github.com/mineiros-io/terraform-github-team/blob/master/examples/github-team + + +[homepage]: https://mineiros.io/?ref=terraform-github-team + +[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg +[badge-terraform]: https://img.shields.io/badge/terraform-0.13%20and%200.12.20+-623CE4.svg?logo=terraform +[badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack +[badge-semver]: https://img.shields.io/github/v/tag/mineiros-io/terraform-github-team.svg?label=latest&sort=semver + +[releases-github]: https://github.com/mineiros-io/terraform-github-team/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 diff --git a/examples/github-team/README.md b/examples/github-team/README.md new file mode 100644 index 0000000..364b44c --- /dev/null +++ b/examples/github-team/README.md @@ -0,0 +1,89 @@ +[][homepage] + +[![license][badge-license]][apache20] +[![Terraform Version][badge-terraform]][releases-terraform] +[![Join Slack][badge-slack]][slack] + +# Create a team which has access to two newly created repositories + +This example shows how to create a team and two repositories. +The team will have pull permissions for one repository and push permissions +for the other. We also add lists of members and maintainers to the team. + +## Basic usage + +The code in [main.tf] defines two public GitHub repository and two nested +GitHub teams. The team will be granted pull permissions to the one repository +and push permissions to the other. + +```hcl +module "team" { + source = "mineiros-io/team/github" + version = "0.1.3" + + name = "Engineering" + description = "This team is created with terraform to test the terraformn-github-repository module." + privacy = "closed" + + members = ["alice"] + maintainers = ["bob"] + + pull_repositories = [ + github_repository.repository.name, + ] + + push_repositories = [ + github_repository.another_repository.name, + ] +} + +module "child_team" { + source = "mineiros-io/team/github" + version = "0.1.3" + + name = "DevOps" + parent_team_id = module.team.id + privacy = "closed" +} +``` + +## Running the example + +### Cloning the repository + +```bash +git clone https://github.com/mineiros-io/terraform-github-team.git +cd terraform-github-team/examples/github-team +``` + +### Initializing Terraform + +Run `terraform init` to initialize the example and download providers and the module. + +### Planning the example + +Run `terraform plan` to see a plan of the changes. + +### Applying the example + +Run `terraform apply` to create the resources. +You will see a plan of the changes and Terraform will prompt you for approval to actually apply the changes. + +### Destroying the example + +Run `terraform destroy` to destroy all resources again. + + + + +[main.tf]: https://github.com/mineiros-io/terraform-github-team/blob/master/examples/github-team/main.tf + +[homepage]: https://mineiros.io/?ref=terraform-github-team + +[badge-license]: https://img.shields.io/badge/license-Apache%202.0-brightgreen.svg +[badge-terraform]: https://img.shields.io/badge/terraform-0.13%20and%200.12.20+-623CE4.svg?logo=terraform +[badge-slack]: https://img.shields.io/badge/slack-@mineiros--community-f32752.svg?logo=slack + +[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 diff --git a/examples/github-team/main.tf b/examples/github-team/main.tf new file mode 100644 index 0000000..a93689d --- /dev/null +++ b/examples/github-team/main.tf @@ -0,0 +1,69 @@ +# ---------------------------------------------------------------------------------------------------------------------- +# CREATE A TEAM AND TWO REPOSITORIES +# +# We create a team and two repositories. The team will have pull permissions for one repository and push permissions +# for the other. We also add lists of members and maintainers to the team. +# ---------------------------------------------------------------------------------------------------------------------- + +# ---------------------------------------------------------------------------------------------------------------------- +# ENVIRONMENT VARIABLES: +# ---------------------------------------------------------------------------------------------------------------------- +# You can provide your credentials via the +# AWS_ACCESS_KEY_ID and +# AWS_SECRET_ACCESS_KEY, environment variables, +# representing your AWS Access Key and AWS Secret Key, respectively. +# Note that setting your AWS credentials using either these (or legacy) +# environment variables will override the use of +# AWS_SHARED_CREDENTIALS_FILE and +# AWS_PROFILE. +# The +# AWS_DEFAULT_REGION and +# AWS_SESSION_TOKEN environment variables are also used, if applicable. +# ---------------------------------------------------------------------------------------------------------------------- + +# ---------------------------------------------------------------------------------------------------------------------- +# Provider Setup +# ---------------------------------------------------------------------------------------------------------------------- + +provider "aws" { + version = "~> 2.0" + region = "eu-west-1" +} + + +resource "github_repository" "repository" { + name = "engineering-tools" +} + +resource "github_repository" "another_repository" { + name = "devops-tools" +} + +module "team" { + source = "mineiros-io/team/github" + version = "0.1.3" + + name = "Engineering" + description = "This team is created with terraform to test the terraformn-github-repository module." + privacy = "closed" + + members = ["alice"] + maintainers = ["bob"] + + pull_repositories = [ + github_repository.repository.name, + ] + + push_repositories = [ + github_repository.another_repository.name, + ] +} + +module "child_team" { + source = "mineiros-io/team/github" + version = "0.1.3" + + name = "DevOps" + parent_team_id = module.team.id + privacy = "closed" +} diff --git a/examples/public-repositories-with-team/outputs.tf b/examples/github-team/outputs.tf similarity index 100% rename from examples/public-repositories-with-team/outputs.tf rename to examples/github-team/outputs.tf diff --git a/examples/public-repositories-with-team/main.tf b/examples/public-repositories-with-team/main.tf deleted file mode 100644 index 3f8e4a1..0000000 --- a/examples/public-repositories-with-team/main.tf +++ /dev/null @@ -1,42 +0,0 @@ -# --------------------------------------------------------------------------------------------------------------------- -# CREATE A TEAM AND TWO REPOSITORIES -# -# We create a team and two repositories. The team will have pull permissions for one repository and push permissions -# for the other. We also add lists of members and maintainers to the team. -# --------------------------------------------------------------------------------------------------------------------- - -resource "github_repository" "repository" { - name = var.a-repository-name -} - -resource "github_repository" "another_repository" { - name = var.b-repository-name -} - -module "team" { - source = "../.." - - name = var.team_name - description = var.team_description - privacy = var.team_privacy - - members = var.members - maintainers = var.maintainers - - pull_repositories = [ - github_repository.repository.name, - ] - - push_repositories = [ - github_repository.another_repository.name, - ] -} - -# Create a child team -module "child_team" { - source = "../.." - - name = var.nested_team_name - parent_team_id = module.team.id - privacy = var.nested_team_privacy -} diff --git a/examples/public-repositories-with-team/variables.tf b/examples/public-repositories-with-team/variables.tf deleted file mode 100644 index ed2dc77..0000000 --- a/examples/public-repositories-with-team/variables.tf +++ /dev/null @@ -1,74 +0,0 @@ -# --------------------------------------------------------------------------------------------------------------------- -# ENVIRONMENT VARIABLES -# Define these secrets as environment variables. -# --------------------------------------------------------------------------------------------------------------------- - -# GITHUB_TOKEN -# GITHUB_ORGANIZATION - -# --------------------------------------------------------------------------------------------------------------------- -# REQUIRED VARIABLES -# These variables must be set when using this module. -# --------------------------------------------------------------------------------------------------------------------- - -# --------------------------------------------------------------------------------------------------------------------- -# OPTIONAL VARIABLES -# These variables have defaults, but may be overridden. -# --------------------------------------------------------------------------------------------------------------------- - -variable "a-repository-name" { - description = "The name of the first repository that we create." - type = string - default = "terraform-github-team-module-test-repository-1" -} -variable "b-repository-name" { - description = "The name of the second repository that we create." - type = string - default = "terraform-github-team-module-test-repository-2" -} - -variable "team_name" { - description = "The name of the team." - type = string - default = "test-team" -} - -variable "team_description" { - description = "The description of the team." - type = string - default = "This team is created with terraform to test the terraformn-github-repository module." -} - -variable "team_privacy" { - description = "The level of privacy for the team. Must be one of secret or closed." - type = string - default = "closed" -} - -variable "members" { - description = "A set of users that should be added to the team as members." - type = set(string) - default = [ - "terraform-test-user-1" - ] -} - -variable "maintainers" { - description = "A set of users that should be added to the team as maintainers." - type = set(string) - default = [ - "terraform-test-user-2" - ] -} - -variable "nested_team_name" { - description = "The description of the team." - type = string - default = "a-nested-team" -} - -variable "nested_team_privacy" { - description = "The level of privacy for the team." - type = string - default = "closed" -} diff --git a/main.tf b/main.tf index 78ef285..0c60ddc 100644 --- a/main.tf +++ b/main.tf @@ -9,8 +9,6 @@ # --------------------------------------------------------------------------------------------------------------------- resource "github_team" "team" { - count = var.module_enabled ? 1 : 0 - name = var.name description = var.description privacy = var.privacy @@ -28,9 +26,9 @@ locals { } resource "github_team_membership" "team_membership" { - for_each = var.module_enabled ? local.memberships : {} + for_each = local.memberships - team_id = github_team.team[0].id + team_id = github_team.team.id username = each.key role = each.value @@ -46,10 +44,10 @@ locals { } resource "github_team_repository" "team_repository" { - for_each = var.module_enabled ? local.repositories : {} + for_each = local.repositories repository = each.key - team_id = github_team.team[0].id + team_id = github_team.team.id permission = each.value depends_on = [var.module_depends_on] diff --git a/outputs.tf b/outputs.tf index 10825aa..a2caee9 100644 --- a/outputs.tf +++ b/outputs.tf @@ -4,17 +4,17 @@ output "id" { description = "The ID of the team." - value = try(github_team.team[0].id, null) + value = github_team.team.id } output "team_name" { description = "The name of the team." - value = try(github_team.team[0].name, null) + value = github_team.team.name } output "slug" { description = "The Slug of the team." - value = try(github_team.team[0].slug, null) + value = github_team.team.slug } # ------------------------------------------------------------------------------ @@ -23,17 +23,17 @@ output "slug" { output "team" { description = "The full team object." - value = try(github_team.team[0], {}) + value = github_team.team } output "team_memberships" { description = "A list of all team memberships." - value = try(github_team_membership.team_membership, null) + value = github_team_membership.team_membership } output "team_repositories" { description = "A list of all team repositories" - value = try(github_team_repository.team_repository, null) + value = github_team_repository.team_repository } # ------------------------------------------------------------------------------ @@ -93,8 +93,3 @@ output "pull_repositories" { # ------------------------------------------------------------------------------ # OUTPUT MODULE CONFIGURATION # ------------------------------------------------------------------------------ - -output "module_enabled" { - description = "Whether the module is enabled" - value = var.module_enabled -} diff --git a/test/README.md b/test/README.md index 51bf2c0..1137800 100644 --- a/test/README.md +++ b/test/README.md @@ -48,14 +48,14 @@ Alternatively, you can also run the tests without Docker. ### Run the tests with Docker 1. Install [Docker] -2. Set your AWS credentials as environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` +2. Set your Git credentials as environment variables: `GITHUB_TOKEN`, `GITHUB_ORGANIZATION` 3. Run `make docker-run-tests` ### Run the tests without Docker 1. Install the latest version of [Go]. 2. Install [Terraform]. -3. Set your AWS credentials as environment variables: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` +3. Set your Git credentials as environment variables: `GITHUB_TOKEN`, `GITHUB_ORGANIZATION` 4. Install go dependencies: `go mod download` 5. Run all tests: `go test -v -count 1 -timeout 45m -parallel 128 ./test/...` 6. Run a specific test: `go test -count 1 -v -timeout 45m -parallel 128 test/example_test.go` diff --git a/test/github_team_test.go b/test/github_team_test.go index 74fec34..01a58c6 100644 --- a/test/github_team_test.go +++ b/test/github_team_test.go @@ -34,7 +34,7 @@ func TestGithubTeam(t *testing.T) { terraformOptions := &terraform.Options{ // The path to where your Terraform code is located - TerraformDir: "public-repository-with-team", + TerraformDir: "public-repositories-with-team", Upgrade: true, Vars: map[string]interface{}{ "team_name": teamName, diff --git a/test/module-enabled/main.tf b/test/module-enabled/main.tf deleted file mode 100644 index 93e3a99..0000000 --- a/test/module-enabled/main.tf +++ /dev/null @@ -1,12 +0,0 @@ -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# UNIT TEST MODULE -# This module exists for the purpose of testing only and should not be -# considered as an example. -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -module "test" { - source = "../.." - - name = "test" - module_enabled = false -} diff --git a/test/module-enabled/outputs.tf b/test/module-enabled/outputs.tf deleted file mode 100644 index 1cb0f24..0000000 --- a/test/module-enabled/outputs.tf +++ /dev/null @@ -1,10 +0,0 @@ -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -# UNIT TEST MODULE -# This module exists for the purpose of testing only and should not be -# considered as an example. -# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -output "all" { - description = "All outputs of the module." - value = module.test -} diff --git a/test/module_enabled_test.go b/test/module_enabled_test.go deleted file mode 100644 index 58a61d1..0000000 --- a/test/module_enabled_test.go +++ /dev/null @@ -1,33 +0,0 @@ -package test - -import ( - "testing" - - "github.com/gruntwork-io/terratest/modules/terraform" - "github.com/stretchr/testify/assert" -) - -//TestModuleEnabled : Tests that no resources are being created -// when `module_enabled` is set to `false` -func TestModuleEnabled(t *testing.T) { - t.Parallel() - - terraformOptions := &terraform.Options{ - // The path to where your Terraform code is located - TerraformDir: "./module-enabled", - Vars: map[string]interface{}{}, - Upgrade: true, - } - - // At the end of the test, run `terraform destroy` to clean up any resources that were created - defer terraform.Destroy(t, terraformOptions) - - // This will run `terraform init` and `terraform apply` and fail the test if there are any errors - stdout := terraform.InitAndApplyAndIdempotent(t, terraformOptions) - - // Validate that Terraform didn't create, change or destroy any resources - resourceCount := terraform.GetResourceCount(t, stdout) - assert.Equal(t, 0, resourceCount.Add, "No resources should have been created. Found %d instead.", resourceCount.Add) - assert.Equal(t, 0, resourceCount.Change, "No resources should have been changed. Found %d instead.", resourceCount.Change) - assert.Equal(t, 0, resourceCount.Destroy, "No resources should have been destroyed. Found %d instead.", resourceCount.Destroy) -} diff --git a/variables.tf b/variables.tf index a8ae731..7c82253 100644 --- a/variables.tf +++ b/variables.tf @@ -48,49 +48,19 @@ variable "ldap_dn" { variable "maintainers" { description = "(Optional) A list of users that will be added to the current team with maintainer permissions." type = set(string) - - # - # Example: - # - # maintainers = [ - # "bob", - # "alice" - # ] - # - - default = [] + default = [] } variable "members" { description = "(Optional) A list of users that will be added to the current team with member permissions." type = set(string) - - # - # Example: - # - # members = [ - # "bob", - # "alice" - # ] - # - - default = [] + default = [] } variable "admin_repositories" { description = "(Optional) A list of repository names the current team should get admin (full) permission to." type = set(string) - - # - # Example: - # - # admin_repositories = [ - # "bob", - # "alice" - # ] - # - - default = [] + default = [] } variable "push_repositories" { @@ -111,12 +81,6 @@ variable "pull_repositories" { # See https://medium.com/mineiros/the-ultimate-guide-on-how-to-write-terraform-modules-part-1-81f86d31f024 # ------------------------------------------------------------------------------ -variable "module_enabled" { - type = bool - description = "(Optional) Whether to create resources within the module or not. Default is true." - default = true -} - variable "module_depends_on" { type = any description = "(Optional) A list of external resources the module depends_on. Default is []."