docs: extend documentation

Signed-off-by: Benjamin Janssens <benji.janssens@gmail.com>
2024-06-28 13:16:50 +02:00
parent 7d82969f10
commit caf7fc23c3
2 changed files with 55 additions and 0 deletions
@@ -441,3 +441,30 @@ repoUrl:
 `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`.
+
+## RepoBranchPicker
+
+The input props that can be specified under `ui:options` for the `RepoBranchPicker` field extension.
+
+### `requestUserCredentials`
+
+If defined will request user credentials to auth against the given SCM platform.
+
+```yaml
+repoUrl:
+  title: Repository Branch
+  type: string
+  ui:field: RepoBranchPicker
+  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`.
+
+If you're also using the `RepoUrlPicker` field extension, you should simply duplicate this part from there.
@@ -477,6 +477,34 @@ template can be published to multiple providers.
 Note, that you will need to configure an [authentication provider](../../auth/index.md#configuring-authentication-providers), alongside the
 [`ScmAuthApi`](../../auth/index.md#scaffolder-configuration-software-templates) for your source code management (SCM) service to make this feature work.

+### The Repository Branch Picker
+
+Similar to the repository picker, there is a picker for branches to support autocompletion. A full example could look like this:
+
+```yaml
+- title: Choose a branch
+  required:
+    - repoBranch
+  properties:
+    repoBranch:
+      title: Repository Branch
+      type: string
+      ui:field: RepoBranchPicker
+      ui:options:
+        requestUserCredentials:
+          secretsKey: USER_OAUTH_TOKEN
+```
+
+Passing the `requestUserCredentials` object is required for autocompletion to work.
+If you're also using the repository picker, you should simply duplicate this part from there.
+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 `RepoBranchPicker`, please visit [here](./ui-options-examples.md#repobranchpicker).
+
+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)
+
 ### 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.