From f19cf5be47113497e4ab9fbc8bbe3675eb17ba44 Mon Sep 17 00:00:00 2001 From: Ross Gustafson Date: Sat, 11 Jun 2022 00:20:19 +0100 Subject: [PATCH] initial docs (#1180) --- .../d/dependabot_public_key.html.markdown | 28 +++++++ ...pendabot_organization_secret.html.markdown | 83 +++++++++++++++++++ ...nization_secret_repositories.html.markdown | 47 +++++++++++ .../docs/r/dependabot_secret.html.markdown | 54 ++++++++++++ 4 files changed, 212 insertions(+) create mode 100644 website/docs/d/dependabot_public_key.html.markdown create mode 100644 website/docs/r/dependabot_organization_secret.html.markdown create mode 100644 website/docs/r/dependabot_organization_secret_repositories.html.markdown create mode 100644 website/docs/r/dependabot_secret.html.markdown diff --git a/website/docs/d/dependabot_public_key.html.markdown b/website/docs/d/dependabot_public_key.html.markdown new file mode 100644 index 0000000000..80163172d7 --- /dev/null +++ b/website/docs/d/dependabot_public_key.html.markdown @@ -0,0 +1,28 @@ +--- +layout: "github" +page_title: "GitHub: github_dependabot_public_key" +description: |- + Get information on a GitHub Dependabot Public Key. +--- + +# github_dependabot_public_key + +Use this data source to retrieve information about a GitHub Dependabot public key. This data source is required to be used with other GitHub secrets interactions. +Note that the provider `token` must have admin rights to a repository to retrieve it's Dependabot public key. + +## Example Usage + +```hcl +data "github_dependabot_public_key" "example" { + repository = "example_repo" +} +``` + +## Argument Reference + +* `repository` - (Required) Name of the repository to get public key from. + +## Attributes Reference + +* `key_id` - ID of the key that has been retrieved. +* `key` - Actual key retrieved. diff --git a/website/docs/r/dependabot_organization_secret.html.markdown b/website/docs/r/dependabot_organization_secret.html.markdown new file mode 100644 index 0000000000..50510dee56 --- /dev/null +++ b/website/docs/r/dependabot_organization_secret.html.markdown @@ -0,0 +1,83 @@ +--- +layout: "github" +page_title: "GitHub: github_dependabot_organization_secret" +description: |- + Creates and manages an Dependabot Secret within a GitHub organization +--- + +# github_dependabot_organization_secret + +This resource allows you to create and manage GitHub Dependabot secrets within your GitHub organization. +You must have write access to a repository to use this resource. + +Secret values are encrypted using the [Go '/crypto/box' module](https://godoc.org/golang.org/x/crypto/nacl/box) which is +interoperable with [libsodium](https://libsodium.gitbook.io/doc/). Libsodium is used by GitHub to decrypt secret values. + +For the purposes of security, the contents of the `plaintext_value` field have been marked as `sensitive` to Terraform, +but it is important to note that **this does not hide it from state files**. 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. + +## Example Usage + +```hcl +resource "github_dependabot_organization_secret" "example_secret" { + secret_name = "example_secret_name" + visibility = "private" + plaintext_value = var.some_secret_string +} + +resource "github_dependabot_organization_secret" "example_secret" { + secret_name = "example_secret_name" + visibility = "private" + encrypted_value = var.some_encrypted_secret_string +} +``` + +```hcl +data "github_repository" "repo" { + full_name = "my-org/repo" +} + +resource "github_dependabot_organization_secret" "example_secret" { + secret_name = "example_secret_name" + visibility = "selected" + plaintext_value = var.some_secret_string + selected_repository_ids = [data.github_repository.repo.repo_id] +} + +resource "github_dependabot_organization_secret" "example_secret" { + secret_name = "example_secret_name" + visibility = "selected" + encrypted_value = var.some_encrypted_secret_string + selected_repository_ids = [data.github_repository.repo.repo_id] +} +``` + +## Argument Reference + +The following arguments are supported: + +* `secret_name` - (Required) Name of the secret +* `encrypted_value` - (Optional) Encrypted value of the secret using the Github public key in Base64 format. +* `plaintext_value` - (Optional) Plaintext value of the secret to be encrypted +* `visibility` - (Required) Configures the access that repositories have to the organization secret. + Must be one of `all`, `private`, `selected`. `selected_repository_ids` is required if set to `selected`. +* `selected_repository_ids` - (Optional) An array of repository ids that can access the organization secret. + +## Attributes Reference + +* `created_at` - Date of dependabot_secret creation. +* `updated_at` - Date of dependabot_secret update. + +## Import + +This resource can be imported using an ID made up of the secret name: + +``` +terraform import github_dependabot_organization_secret.test_secret test_secret_name +``` + +NOTE: the implementation is limited in that it won't fetch the value of the +`plaintext_value` or `encrypted_value` fields when importing. You may need to ignore changes for these as a workaround. diff --git a/website/docs/r/dependabot_organization_secret_repositories.html.markdown b/website/docs/r/dependabot_organization_secret_repositories.html.markdown new file mode 100644 index 0000000000..f92ec2d8cd --- /dev/null +++ b/website/docs/r/dependabot_organization_secret_repositories.html.markdown @@ -0,0 +1,47 @@ +--- +layout: "github" +page_title: "GitHub: github_dependabot_organization_secret_repositories" +description: |- + Manages repository allow list for an Dependabot Secret within a GitHub organization +--- + +# github_dependabot_organization_secret_repositories + +This resource allows you to manage the repository allow list for existing GitHub Dependabot secrets within your GitHub organization. +You must have write access to an organization secret to use this resource. + +This resource is only applicable when `visibility` of the existing organization secret has been set to `selected`. + +## Example Usage + +```hcl +data "github_repository" "repo" { + full_name = "my-org/repo" +} + +resource "github_dependabot_organization_secret" "example_secret" { + secret_name = "example_secret_name" + visibility = "private" + plaintext_value = var.some_secret_string +} + +resource "github_dependabot_organization_secret_repositories" "org_secret_repos" { + secret_name = github_dependabot_organization_secret.example_secret.secret_name + selected_repository_ids = [data.github_repository.repo.repo_id] +} +``` + +## Argument Reference + +The following arguments are supported: + +* `secret_name` - (Required) Name of the existing secret +* `selected_repository_ids` - (Required) An array of repository ids that can access the organization secret. + +## Import + +This resource can be imported using an ID made up of the secret name: + +``` +terraform import github_dependabot_organization_secret_repositories.test_secret_repos test_secret_name +``` diff --git a/website/docs/r/dependabot_secret.html.markdown b/website/docs/r/dependabot_secret.html.markdown new file mode 100644 index 0000000000..6539a8ac8f --- /dev/null +++ b/website/docs/r/dependabot_secret.html.markdown @@ -0,0 +1,54 @@ +--- +layout: "github" +page_title: "GitHub: github_dependabot_secret" +description: |- + Creates and manages an Dependabot Secret within a GitHub repository +--- + +# github_dependabot_secret + +This resource allows you to create and manage GitHub Dependabot secrets within your GitHub repositories. +You must have write access to a repository to use this resource. + +Secret values are encrypted using the [Go '/crypto/box' module](https://godoc.org/golang.org/x/crypto/nacl/box) which is +interoperable with [libsodium](https://libsodium.gitbook.io/doc/). Libsodium is used by GitHub to decrypt secret values. + +For the purposes of security, the contents of the `plaintext_value` field have been marked as `sensitive` to Terraform, +but it is important to note that **this does not hide it from state files**. 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. + +## Example Usage + +```hcl +data "github_dependabot_public_key" "example_public_key" { + repository = "example_repository" +} + +resource "github_dependabot_secret" "example_secret" { + repository = "example_repository" + secret_name = "example_secret_name" + plaintext_value = var.some_secret_string +} + +resource "github_dependabot_secret" "example_secret" { + repository = "example_repository" + secret_name = "example_secret_name" + encrypted_value = var.some_encrypted_secret_string +} +``` + +## Argument Reference + +The following arguments are supported: + +* `repository` - (Required) Name of the repository +* `secret_name` - (Required) Name of the secret +* `encrypted_value` - (Optional) Encrypted value of the secret using the Github public key in Base64 format. +* `plaintext_value` - (Optional) Plaintext value of the secret to be encrypted + +## Attributes Reference + +* `created_at` - Date of actions_secret creation. +* `updated_at` - Date of actions_secret update.