From 21ec51067e2129ed092d4575ae86dd91065434ab Mon Sep 17 00:00:00 2001 From: Thorsten Gilfert Date: Tue, 7 Jan 2025 09:05:00 +0100 Subject: [PATCH] Add examples and documentation Signed-off-by: Thorsten Gilfert --- README.md | 23 +++++++++++++++---- .../v1alpha1/organizationactionssecret.yaml | 16 ------------- .../v1alpha1/organizationactionsvariable.yaml | 13 ----------- .../organizationactionssecret.yaml | 1 + .../actions/organizationactionsvariable.yaml | 9 ++++++++ 5 files changed, 29 insertions(+), 33 deletions(-) delete mode 100644 examples-generated/actions/v1alpha1/organizationactionssecret.yaml delete mode 100644 examples-generated/actions/v1alpha1/organizationactionsvariable.yaml rename examples/{organization => actions}/organizationactionssecret.yaml (94%) create mode 100644 examples/actions/organizationactionsvariable.yaml diff --git a/README.md b/README.md index c16dd09..b746638 100644 --- a/README.md +++ b/README.md @@ -57,13 +57,13 @@ spec: name: provider-secret namespace: upbound-system key: credentials - ``` #### Provider config example with Github application based authentication Note that the PEM certificate needs to be wrapped in a non-multiline string, with the characters "\n" as newline. See Terraform provider doc for more information. + ```yaml --- apiVersion: v1 @@ -87,9 +87,24 @@ spec: name: provider-secret namespace: upbound-system key: credentials - ``` +### Provider config scope + +Most operations of the provider happen in the scope of the `owner` attribute in the `credentials` JSON structure. This means that the provider +will create resources in the context of the given owner. For example, if you want to create a repository in an organization, the `owner` attribute +must point to a GitHub organization. If you want to create a repository in a user account, the `owner` attribute must point to a GitHub user +account. + +Note that some resources like `OrganizationActionsSecret` and `OrganizationActionsVariable` require the `owner` attribute to point to the +organization as they are not supported at the user level. + +Administration of resources on the *organization* level requires a token with at least `admin:org` scope. + +There are a few endpoints in the GitHub API that operate on the *enterprise* level and can be used for GitHub customers that have an enterprise +account. One such resource is `Organization` which can be used to provision new organizations on the enterprise level. In this case, the token +or app authentication must have at least `admin:enterprise` scope. + ## Supported resources | Kind | Group | Terraform Resource Name | Notes | @@ -112,8 +127,8 @@ spec: | `TeamSyncGroupMapping` | `team` | `github_team_sync_group_mapping` | | | `EmuTeamMapping` | `team` | `github_emu_group_mapping` | | | `ActionsSecret` | `actions` | `github_actions_secret` | | -| `OrganizationActionsSecret` | `actions` | `github_organization_actions_secret` | | -| `OrganizationActionsVariable` | `actions` | `github_organization_actions_variable` | | +| `OrganizationActionsSecret` | `actions` | `github_organization_actions_secret` | The `owner` attribute in the `credentials` JSON structure must point to the organization. | +| `OrganizationActionsVariable` | `actions` | `github_organization_actions_variable` | The `owner` attribute in the `credentials` JSON structure must point to the organization. | | `OrganizationRuleset` | `organization` | `github_organization_ruleset` | | | `Membership` | `user` | `github_membership` | Works only with - GitHub App user access tokens - GitHub App installation access tokens - Fine-grained personal access tokens using a token with at least `members:read` | | `Organization` | `enterprise` | `github_enterprise_organization` | Works only with PAT based authentication using a token with at least `admin:enterprise` scope.
The following *GraphQL* query can be used to obtain the required `enterprise_id`:
`gh api graphql -f query='query ($slug: String!) { enterprise(slug: $slug) { id } }' -F slug='' --jq '.data.enterprise.id'` | diff --git a/examples-generated/actions/v1alpha1/organizationactionssecret.yaml b/examples-generated/actions/v1alpha1/organizationactionssecret.yaml deleted file mode 100644 index dc0e726..0000000 --- a/examples-generated/actions/v1alpha1/organizationactionssecret.yaml +++ /dev/null @@ -1,16 +0,0 @@ -apiVersion: actions.github.upbound.io/v1alpha1 -kind: OrganizationActionsSecret -metadata: - annotations: - meta.upbound.io/example-id: actions/v1alpha1/organizationactionssecret - labels: - testing.upbound.io/example-name: example_secret - name: example-secret -spec: - forProvider: - plaintextValueSecretRef: - key: example-key - name: example-secret - namespace: upbound-system - secretName: example_secret_name - visibility: private diff --git a/examples-generated/actions/v1alpha1/organizationactionsvariable.yaml b/examples-generated/actions/v1alpha1/organizationactionsvariable.yaml deleted file mode 100644 index df1b4a9..0000000 --- a/examples-generated/actions/v1alpha1/organizationactionsvariable.yaml +++ /dev/null @@ -1,13 +0,0 @@ -apiVersion: actions.github.upbound.io/v1alpha1 -kind: OrganizationActionsVariable -metadata: - annotations: - meta.upbound.io/example-id: actions/v1alpha1/organizationactionsvariable - labels: - testing.upbound.io/example-name: example_variable - name: example-variable -spec: - forProvider: - value: example_variable_value - variableName: example_variable_name - visibility: private diff --git a/examples/organization/organizationactionssecret.yaml b/examples/actions/organizationactionssecret.yaml similarity index 94% rename from examples/organization/organizationactionssecret.yaml rename to examples/actions/organizationactionssecret.yaml index 872979c..066c945 100644 --- a/examples/organization/organizationactionssecret.yaml +++ b/examples/actions/organizationactionssecret.yaml @@ -5,6 +5,7 @@ metadata: spec: forProvider: secretName: TEST_SECRET + visibility: private plaintextValueSecretRef: key: howdy name: organization-secret-secret diff --git a/examples/actions/organizationactionsvariable.yaml b/examples/actions/organizationactionsvariable.yaml new file mode 100644 index 0000000..0f4639c --- /dev/null +++ b/examples/actions/organizationactionsvariable.yaml @@ -0,0 +1,9 @@ +apiVersion: actions.github.upbound.io/v1alpha1 +kind: OrganizationActionsVariable +metadata: + name: organization-variable-test +spec: + forProvider: + value: 'My variable value' + variableName: TEST_VARIABLE + visibility: private