docs: add documentation

Signed-off-by: Benjamin Janssens <benji.janssens@gmail.com>
2025-12-11 16:59:36 +01:00
parent 2cb930fe8e
commit ef1596f49a
2 changed files with 86 additions and 0 deletions
@@ -468,3 +468,61 @@ repoUrl:
 The supported `additionalScopes` values are `gerrit`, `github`, `gitlab`, `bitbucket`, and `azure`.

 If you're also using the `RepoUrlPicker` field extension, you should simply duplicate this part from there.
+
+## RepoOwnerPicker
+
+The input props that can be specified under `ui:options` for the `RepoOwnerPicker` field extension.
+
+### `host`
+
+The SCM integration host that owners should be fetched from for autocompletion.
+
+- Fetch owners from `github.com`
+
+```yaml
+repoUrl:
+  title: Repository Owner
+  type: string
+  ui:field: RepoOwnerPicker
+  ui:options:
+    host: github.com
+```
+
+This value will be overriden if a different host is specified in a `RepoUrlPicker` field extension.
+
+### `excludedOwners`
+
+List of owners that should be excluded from autocompletion.
+
+- Exclude owner `owner_1` from autocompletion
+
+```yaml
+repoUrl:
+  title: Repository Owner
+  type: string
+  ui:field: RepoOwnerPicker
+  ui:options:
+    excludedOwners:
+      - owner_1
+```
+
+### `requestUserCredentials`
+
+If defined will request user credentials to auth against the given SCM platform.
+
+```yaml
+repoUrl:
+  title: Repository Owner
+  type: string
+  ui:field: RepoOwnerPicker
+  ui:options:
+    requestUserCredentials:
+      secretsKey: USER_OAUTH_TOKEN
+      additionalScopes:
+        github:
+          - workflow:write
+```
+
+`secretsKey` is the key used within the template secrets context to store the credential and `additionalScopes` is any additional permission scopes to request.
+
+The supported `additionalScopes` values are `gerrit`, `github`, `gitlab`, `bitbucket`, and `azure`.
@@ -555,6 +555,34 @@ The `RepoBranchPicker` is a custom field that we provide part of the
 `plugin-scaffolder`. You can provide your own custom fields by
 [writing your own Custom Field Extensions](./writing-custom-field-extensions.md)

+### The Repository Owner Picker
+
+Similar to the repository picker, there is a picker for owners to support autocompletion. A full example could look like this:
+
+```yaml
+- title: Choose an owner
+  required:
+    - repoOwner
+  properties:
+    repoOwner:
+      title: Repository Owner
+      type: string
+      ui:field: RepoOwnerPicker
+      ui:options:
+        host: github.com
+        requestUserCredentials:
+          secretsKey: USER_OAUTH_TOKEN
+```
+
+Passing the `requestUserCredentials` and `host` properties is required for autocompletion to work. Only if the template contains a `RepoUrlPicker` field extension, `host` can be omitted as it will use the host specified in the field extension.
+For more information regarding the `requestUserCredentials` object, please refer to the [Using the Users `oauth` token](#using-the-users-oauth-token) section under [The Repository Picker](#the-repository-picker).
+
+For a list of all possible `ui:options` input props for `RepoOwnerPicker`, please visit [here](./ui-options-examples.md#repoownerpicker).
+
+The `RepoOwnerPicker` is a custom field that we provide part of the
+`plugin-scaffolder`. You can provide your own custom fields by
+[writing your own Custom Field Extensions](./writing-custom-field-extensions.md)
+
 ### Accessing the signed-in users details

 Sometimes when authoring templates, you'll want to access the user that is running the template, and get details from the profile or the users `Entity` in the Catalog.