Feature team_permission, EnvironmentVariable, EnvironmentSecret, and Team extended by team-sync and external-groups

docs/reference/organization/repository/branch-or-tag.md

@@ -1,4 +1,4 @@
-A BranchOrTag represents either a branch or tag pattern to use within an [Environment](environment.md).
+A BranchOrTag represents either a branch or tag pattern to use within an [Environment](environment/index.md).
 The following format is used to distinguish between tags and branches:
 
 | Type   | Format          | Example                                 |

docs/reference/organization/repository/environment/index.md

@@ -0,0 +1,46 @@
+Definition of an `Environment` on repository level, the following properties are supported:
+
+| Key                        | Value                                      | Description                                                                           | Notes                                                              |
+|----------------------------|--------------------------------------------|---------------------------------------------------------------------------------------|--------------------------------------------------------------------|
+| _name_                     | string                                     | The name of the environment                                                           |                                                                    |
+| _wait_timer_               | int                                        | The amount of time to wait before allowing deployments to proceed                     |                                                                    |
+| _reviewers_                | list\[[Actor](../actor.md)\]               | Users or Teams that may approve workflow runs that access this environment            |                                                                    |
+| _deployment_branch_policy_ | string                                     | Limit which branches can deploy to this environment based on rules or naming patterns | `all`, `protected` or `selected`                                   |
+| _branch_policies_          | list\[[BranchOrTag](../branch-or-tag.md)\] | List of branch or tag patterns which can deploy to this environment                   | only applicable if `deployment_branch_policy` is set to `selected` |
+
+## Jsonnet Function
+
+``` jsonnet
+orgs.newEnvironment('<name>') {
+  <key>: <value>
+}
+```
+
+## Validation rules
+
+- specifying a non-empty list of `branch_policies` while `deployment_branch_policy` is not set to `selected` triggers a warning
+
+## Example usage
+
+=== "jsonnet"
+    ``` jsonnet
+    orgs.newOrg('OtterdogTest') {
+      ...
+      _repositories+:: [
+        ...
+        orgs.newRepo('test-repo') {
+          ...
+          environments: [
+            orgs.newEnvironment('linux') {
+              deployment_branch_policy: "protected",
+              reviewers+: [
+                "@OtterdogTest/eclipsefdn-security",
+                "@netomi"
+              ],
+              wait_timer: 30,
+            },
+          ]
+        }
+      ]
+    }
+    ```

docs/reference/organization/repository/environment/secret.md

@@ -0,0 +1,64 @@
+Definition of a `Secret` on repository environment level, the following properties are supported:
+
+| Key                     | Value          | Description                                    | Note |
+|-------------------------|----------------|------------------------------------------------|------|
+| _name_                  | string         | The name of the secret                         |      |
+| _value_                 | string         | The secret value                               |      |
+
+The secret value can be resolved via a credential provider. The supported format is `<credential_provider>:<provider specific data>`.
+
+- Bitwarden: `bitwarden:<bitwarden item id>@<custom_field_key>`
+
+    ``` json
+    "secret": "bitwarden:118276ad-158c-4720-b68d-af8c00fe3481@secret"
+    ```
+
+- Pass: `pass:<path/to/secret>`
+
+    ``` json
+    "secret": "pass:path/to/repo/secret"
+    ```
+
+!!! note
+
+    After executing an `import` operation, the secret will be set to `********` as GitHub will not disclose the
+    secret value anymore via its API. You will need to update the configuration with the real secret value, either
+    by entering the secret value (not advised), or referencing it via a credential provider.
+
+    Secrets which have a redacted value defined will be skipped during processing.
+
+## Jsonnet Function
+
+``` jsonnet
+orgs.newEnvSecret('<name>') {
+  <key>: <value>
+}
+```
+
+## Validation rules
+
+- redacted secret values (`********`) trigger a validation info and will skip the secret during processing
+
+## Example usage
+
+=== "jsonnet"
+    ``` jsonnet
+    orgs.newOrg('OtterdogTest') {
+      ...
+      _repositories+:: [
+        ...
+        orgs.newRepo('test-repo') {
+          ...
+          environments: [
+            orgs.newEnvironment('Environment') {
+              secrets: [
+                orgs.newEnvSecret('TEST_SECRET') {
+                    value: "pass:path/to/secret",
+                },
+              ],
+            },
+          ],
+        }
+      ]
+    }
+    ```

docs/reference/organization/repository/environment/variable.md

@@ -0,0 +1,42 @@
+Definition of a `Variable` on repository environment level, the following properties are supported:
+
+| Key                     | Value          | Description              | Note |
+|-------------------------|----------------|--------------------------|------|
+| _name_                  | string         | The name of the variable |      |
+| _value_                 | string         | The variable value       |      |
+
+## Jsonnet Function
+
+``` jsonnet
+orgs.newEnvVariable('<name>') {
+  <key>: <value>
+}
+```
+
+## Validation rules
+
+- None
+
+## Example usage
+
+=== "jsonnet"
+    ``` jsonnet
+    orgs.newOrg('OtterdogTest') {
+      ...
+      _repositories+:: [
+        ...
+        orgs.newRepo('test-repo') {
+          ...
+          environments: [
+            orgs.newEnvironment('Environment') {
+              variables: [
+                orgs.newEnvVariable('TEST_VARIABLE') {
+                  value: "TESTVALUE",
+                },
+              ],
+            },
+          ],
+        }
+      ]
+    }
+    ```

docs/reference/organization/repository/index.md

@@ -51,8 +51,9 @@ Definition of a Repository for a GitHub organization, the following properties a
 | _webhooks_                                | list\[[Webhook](webhook.md)\]                             | webhooks defined for this repo, see section above for details                           |                                                                                                                                                                                            |
 | _secrets_                                 | list\[[RepositorySecret](secret.md)\]                     | secrets defined for this repo, see section below for details                            |                                                                                                                                                                                            |
 | _variables_                               | list\[[RepositoryVariable](variable.md)\]                 | variables defined for this repo, see section below for details                          |                                                                                                                                                                                            |
-| _environments_                            | list\[[Environment](environment.md)\]                     | environments defined for this repo, see section below for details                       |                                                                                                                                                                                            |
+| _environments_                            | list\[[Environment](environment/index.md)\]               | environments defined for this repo, see section below for details                       |                                                                                                                                                                                            |
 | _branch_protection_rules_                 | list\[[BranchProtectionRule](branch-protection-rule.md)\] | branch protection rules of the repo, see section below for details                      |                                                                                                                                                                                            |
+| _team_permissions_                        | list\[[TeamPermission](team-permission.md)\]              | team permissions defined for this repo, see section below for details                   | allowed are the following: `pull`, `triage`, `push`, `maintain`, `admin` or `READ`, `WRITE`, `MAINTAIN`, `TRIAGE`, `ADMIN` (The latter values come from github graphql)                    |
 
 ## Embedded Models
 
@@ -139,6 +140,12 @@ Definition of a Repository for a GitHub organization, the following properties a
           branch_protection_rules: [
             orgs.newBranchProtectionRule('main'),
           ],
+          team_permissions: [
+            orgs.newTeamPermission('team') {
+              permission: "maintain",
+            },
+          ],
         },
+
     }
     ```

docs/reference/organization/repository/team-permission.md

@@ -0,0 +1,38 @@
+Definition of a `Team Permission`, the following properties are supported:
+
+| Key                        | Value                                   | Description                                                                           | Notes                                                                                                                                                                   |
+|----------------------------|-----------------------------------------|---------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| _name_                     | string                                  | The name of the team in the organization.                                             |                                                                                                                                                                         |
+| _permission_               | string                                  | The name of the permission.                                                           | allowed are the following: `pull`, `triage`, `push`, `maintain`, `admin` or `READ`, `WRITE`, `MAINTAIN`, `TRIAGE`, `ADMIN` (The latter values come from github graphql) |
+
+## Jsonnet Function
+
+``` jsonnet
+orgs.newTeamPermission('<name>') {
+  <key>: <value>
+}
+```
+
+## Validation rules
+
+- allowed values are the following `pull`, `triage`, `push`, `maintain`, `admin` or `READ`, `WRITE`, `MAINTAIN`, `TRIAGE`, `ADMIN`.
+
+## Example usage
+
+=== "jsonnet"
+    ``` jsonnet
+    orgs.newOrg('OtterdogTest') {
+      ...
+      _repositories+:: [
+        ...
+        orgs.newRepo('test-repo') {
+          ...
+          team_permissions: [
+            orgs.newTeamPermission('team') {
+              permission: "maintain",
+            },
+          ],
+        }
+      ]
+    }
+    ```

docs/reference/organization/team.md

@@ -9,6 +9,8 @@ Definition of an organization `Team`, the following properties are supported:
 | _members_                       | list[string] | List of users that should be a member of the team                                    |                       |
 | _skip_members_                  | boolean      | If `true`, team members will be ignored                                              |                       |
 | _skip_non_organization_members_ | boolean      | If `true`, users which are not yet organization members can not be added to the team |                       |
+| _team_sync_                     | string       | The id of an IdP group which is connected to a team on Github Enterprise Cloud       |                       |
+| _external_groups_               | string       | The id of an external group which is provisioned on the enterprise                   |                       |
 
 
 ## Jsonnet Function

examples/template/otterdog-defaults.libsonnet

@@ -109,7 +109,10 @@ local newRepo(name) = {
   branch_protection_rules: [],
 
   # rulesets
-  rulesets: []
+  rulesets: [],
+
+  # team permissions
+  team_permissions: []
 };
 
 # Function to extend an existing repo with the same name.
@@ -223,6 +226,12 @@ local newOrgWebhook(url) = {
 # Function to create a new repository webhook with default settings.
 local newRepoWebhook(url) = newOrgWebhook(url);
 
+# Function to create a new environment secret with default settings.
+local newEnvSecret(name) = {
+  name: name,
+  value: null
+};
+
 # Function to create a new repository secret with default settings.
 local newRepoSecret(name) = {
   name: name,
@@ -235,6 +244,12 @@ local newOrgSecret(name) = newRepoSecret(name) {
   selected_repositories: [],
 };
 
+# Function to create a new environment variable with default settings.
+local newEnvVariable(name) = {
+  name: name,
+  value: null
+};
+
 # Function to create a new repository variable with default settings.
 local newRepoVariable(name) = {
   name: name,
@@ -261,9 +276,19 @@ local newTeam(name) = {
   description: "",
   privacy: "visible",
   notifications: true,
-  members: [],
+  #members: [],
   skip_members: false,
   skip_non_organization_members: false,
+  team_sync_id: null,
+  team_sync_name: null,
+  team_sync_description: null,
+  external_groups: null,
+};
+
+# Function to create a new term permission with default settings.
+local newTeamPermission(name) = {
+  name: name,
+  permission: "pull",
 };
 
 # Function to create a new environment with default settings.
@@ -274,6 +299,10 @@ local newEnvironment(name) = {
   # Can be one of: all, protected_branches, branch_policies
   deployment_branch_policy: "all",
   branch_policies: [],
+  # environment secrets
+  secrets: [],
+  # environment variables
+  variables: [],
 };
 
 # Function to create a new custom property with default settings.
@@ -423,7 +452,6 @@ local newOrg(name, id=name) = {
 {
   newOrg:: newOrg,
   newOrgRole:: newOrgRole,
-  newTeam:: newTeam,
   newOrgWebhook:: newOrgWebhook,
   newOrgSecret:: newOrgSecret,
   newOrgVariable:: newOrgVariable,
@@ -434,10 +462,14 @@ local newOrg(name, id=name) = {
   newRepoWebhook:: newRepoWebhook,
   newRepoSecret:: newRepoSecret,
   newRepoVariable:: newRepoVariable,
+  newEnvSecret:: newEnvSecret,
+  newEnvVariable:: newEnvVariable,
   newBranchProtectionRule:: newBranchProtectionRule,
   newRepoRuleset:: newRepoRuleset,
   newEnvironment:: newEnvironment,
   newPullRequest:: newPullRequest,
   newStatusChecks:: newStatusChecks,
+  newTeam:: newTeam,
+  newTeamPermission:: newTeamPermission,
   newMergeQueue:: newMergeQueue,
 }

mkdocs.yml

@@ -58,16 +58,20 @@ nav:
           - Repository Webhook: reference/organization/repository/webhook.md
           - Repository Secret: reference/organization/repository/secret.md
           - Repository Variable: reference/organization/repository/variable.md
-          - Environment: reference/organization/repository/environment.md
           - Branch Protection Rule: reference/organization/repository/branch-protection-rule.md
           - Repository Ruleset: reference/organization/repository/ruleset.md
+          - Environment:
+            - reference/organization/repository/environment/index.md
+            - Environment Secret: reference/organization/repository/environment/secret.md
+            - Environment Variable: reference/organization/repository/environment/variable.md
         - Referenced Types:
            - Actor: reference/organization/repository/actor.md
            - Branch or Tag: reference/organization/repository/branch-or-tag.md
            - Bypass Actor: reference/organization/repository/bypass-actor.md
            - Repo Name Matcher: reference/organization/repo-name-matcher.md
            - Ref Matcher: reference/organization/repository/ref-matcher.md
            - Status Check: reference/organization/repository/status-check.md
+           - Team Permission: reference/organization/repository/team-permission.md
     - Policies:
         - reference/policies/index.md
         - Upload SBOM data to dependency track: reference/policies/dependency-track-upload.md