📚 Sync docs from alaudadevops/connectors-operator on bc90488f076b70de1ee82abef9dcb93c4305c567

edge-katanomi-app2[bot] · edge-katanomi-app2[bot] · commit a0891ca15fd1 · 2025-12-12T01:40:40.000Z
Source: docs: add docs to describe how to add dynamic forms for resource interface (#434) Author: edge-katanomi-app2[bot] Ref: refs/heads/main Commit: bc90488f076b70de1ee82abef9dcb93c4305c567 This commit automatically syncs documentation changes from the source-docs repository. 🔗 View source commit: https://github.com/alaudadevops/connectors-operator/commit/bc90488f076b70de1ee82abef9dcb93c4305c567 🤖 Synced on 2025-12-12 01:40:40 UTC
diff --git a/.github/SYNC_INFO.md b/.github/SYNC_INFO.md
@@ -1,10 +1,10 @@
 # Documentation Sync Information
 
-- **Last synced**: 2025-12-11 06:06:47 UTC
+- **Last synced**: 2025-12-12 01:40:40 UTC
 - **Source repository**: alaudadevops/connectors-operator
-- **Source commit**: [f6ac686740365cb80e5714c63be8b7228b23a885](https://github.com/alaudadevops/connectors-operator/commit/f6ac686740365cb80e5714c63be8b7228b23a885)
-- **Triggered by**: chengjingtao
-- **Workflow run**: [#60](https://github.com/alaudadevops/connectors-operator/actions/runs/20123703939)
+- **Source commit**: [bc90488f076b70de1ee82abef9dcb93c4305c567](https://github.com/alaudadevops/connectors-operator/commit/bc90488f076b70de1ee82abef9dcb93c4305c567)
+- **Triggered by**: edge-katanomi-app2[bot]
+- **Workflow run**: [#62](https://github.com/alaudadevops/connectors-operator/actions/runs/20153396588)
 
 ## Files synced:
 - docs/
diff --git a/docs/en/connectors/concepts/resource_interface.mdx b/docs/en/connectors/concepts/resource_interface.mdx
@@ -102,6 +102,20 @@ metadata:
     cpaas.io/description: "GitCodeRepository is a resource interface for Git code repository"
 ```
 
+you can also use `style.tekton.dev/descriptors` annotation to describe the params for dynamic form.
+
+```yaml
+metadata:
+  annotations:
+    style.tekton.dev/descriptors: |-
+      - path: params.revision
+        x-descriptors:
+          - urn:alm:descriptor:widgets:select
+          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs
+```
+
+more details please refer to [dynamic-form](#dynamic-form).
+
 ### Resource Categories \{#categories}
 
 ResourceInterface organizes resources into categories that define common contracts and behaviors. Categories are marked using the label `resourceinterface.connectors.cpaas.io/category`.
@@ -280,6 +294,199 @@ This enables the system to match compatible connectors with ResourceInterfaces a
 
 More about ConnectorClass please refer to [Concept of ConnectorClass](./connectorclass.mdx)
 
+## Dynamic Form \{#dynamic-form}
+
+Dynamic forms provide a declarative way to configure interactive UI components for Pipeline Integration. With dynamic forms, users can browse and select resources such as Git repositories and revisions directly through the connector.
+
+### Overview
+
+Use the `style.tekton.dev/descriptors` annotation to define dynamic form behavior for parameters. Here is an example:
+
+```yaml
+metadata:
+  annotations:
+    style.tekton.dev/descriptors: >-
+      - path: params.repository
+        x-descriptors:
+          - urn:alm:descriptor:com.tectonic.ui:select:repository
+          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
+          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
+          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
+          - urn:alm:descriptor:label:en:Repository
+          - urn:alm:descriptor:label:zh:Repository
+          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
+          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.
+```
+
+The syntax follows the <ExternalSiteLink name="pipelines" href="/pipelines/how_to/configure_dynamic_forms.html" children="Pipeline Dynamic Forms" /> specification. Familiarity with that documentation is recommended before proceeding.
+
+In addition to the standard capabilities, dynamic forms in ResourceInterface support:
+
+- **Extended context variables** for accessing connector and ResourceInterface data
+- **Reference OpenAPI display schema** definitions in ConnectorClass for centralized API configuration and reference the api definition when using dynamic form
+
+### Extended Context Variables
+
+The following context variables are available in ResourceInterface dynamic forms:
+
+| Variable | Description |
+| -------- | ----------- |
+| `context.connector` | The Connector object. Access any field, e.g., `context.connector.status.api.path` |
+| `context.connectorClass` | The ConnectorClass object. Access any field, e.g., `context.connectorClass.spec.api.openapi` |
+| `context.params` | Parameter values in `Pipeline Integration` UI form, e.g., `context.params.repository` |
+| `context.resourceInterface` | The ResourceInterface object. Access any field as needed |
+
+### Dynamic Form Configuration Approaches
+
+There are two approaches to configure dynamic forms in ResourceInterface:
+
+1. **Direct API Configuration**: Call connector APIs directly using descriptor expressions. This approach is straightforward and easy to understand. The Connectors System provides [Connector API](./connector_api.mdx) endpoints for listing repositories, git references, and more.
+
+2. **Reference OpenAPI Display Schema in ConnectorClass**: Define API calls and display mappings in the ConnectorClass using `spec.api.openapi`. This approach centralizes API definitions and display configurations, avoiding duplication across multiple ResourceInterfaces. When using dynamic form, you can reference the API definition in the ConnectorClass directly.
+
+You can use either approach independently or combine them as needed.
+
+### Direct API Configuration
+
+**Example: Listing GitLab Repositories**
+
+GitLab connectors expose the native GitLab API, which can be used to populate a repository selector:
+
+```yaml
+kind: ResourceInterface
+metadata:
+  name: gitlabcoderepository
+  annotations:
+    style.tekton.dev/descriptors: >-
+      - path: params.repository
+        x-descriptors:
+          - urn:alm:descriptor:com.tectonic.ui:select:repository
+          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/api/v4/projects?simple=true
+          - urn:alm:descriptor:expression:props.options:label:path:path_with_namespace
+          - urn:alm:descriptor:expression:props.options:value:path:path_with_namespace
+          - urn:alm:descriptor:label:en:Repository
+          - urn:alm:descriptor:label:zh:Repository
+          - urn:alm:descriptor:description:zh:Repository path including group name or username, e.g. mygroup/my-app.
+          - urn:alm:descriptor:description:en:Repository path including group name or username, e.g. mygroup/my-app.
+```
+
+**Example: Listing Git References**
+
+Git connector provides a `gitrefs` endpoint for listing branches and tags:
+
+```yaml
+kind: ResourceInterface
+metadata:
+  name: gitcoderepository
+  annotations:
+    style.tekton.dev/descriptors: >-
+      - path: params.revision
+        x-descriptors:
+          - urn:alm:descriptor:com.tectonic.ui:select:revision
+          - urn:alm:descriptor:expression:props.options:api:/clusters-rewrite/${context.cluster}${context.connector.status.api.path}/git/gitrefs?repositoryUrl=${context.connector.spec.address + "/" + context.params.repository + ".git"}&search=${current.search}
+          - urn:alm:descriptor:expression:props.options:path:items
+          - urn:alm:descriptor:expression:props.options:label:path:name
+          - urn:alm:descriptor:expression:props.options:value:path:name
+          - urn:alm:descriptor:label:en:Revision
+          - urn:alm:descriptor:label:zh:Revision
+          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
+          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)
+```
+
+### Reference OpenAPI Display Schema \{#reference-openapi-display-schema-in-connectorclass}
+
+To centralize API definitions and display configurations, define them in the ConnectorClass using `spec.api.openapi`. Dynamic forms can then reference these definitions directly, eliminating redundant configurations across ResourceInterfaces.
+
+**Prerequisites**
+
+1. Define the OpenAPI specification in the ConnectorClass. See [ConnectorClass OpenAPI Description](./connectorclass.mdx#api_openapi) for details.
+2. Add the `x-display-schema` extension to define how the API integrates with dynamic forms.
+
+**Display Schema Structure**
+
+The `x-display-schema` extension contains:
+
+- `parameters[]`: Defines how to populate API parameters at runtime.
+  - `name`: Parameter name (must match the API parameter name)
+  - `value`: Parameter value expression. Syntax follows <ExternalSiteLink name="pipelines" href="pipelines/how_to/configure_dynamic_forms.html#api-dynamic-options-configuration" children="Pipeline Dynamic Forms" />.
+- `descriptors`: Defines how API response data maps to form options. Syntax follows <ExternalSiteLink name="pipelines" href="pipelines/how_to/configure_dynamic_forms.html" children="Pipeline Dynamic Forms" />.
+
+**Example: Git References API**
+
+The following ConnectorClass configuration defines the `GET /git/gitrefs` API with display schema:
+
+- The `repositoryUrl` parameter is set to `${context.connector.spec.address + "/" + context.params.repository + ".git"}` and passed as a query parameter
+- The `search` parameter is set to `${current.search}` for filtering results
+- The response `items` array is mapped to select options, using `name` for both label and value
+
+``` yaml
+kind: ConnectorClass
+spec:
+  api:
+    openapi:
+      openapi: 3.0.3
+      info:
+        title: Git API
+        version: v1alpha1
+      paths:
+        /git/gitrefs:
+          get:
+            x-provider-type: api
+            x-display-schema:
+              parameters:
+              - name: repositoryUrl
+                value: ${context.connector.spec.address + "/" + context.params.repository + ".git"}
+              - name: search
+                value: ${current.search}
+              descriptors:
+              - urn:alm:descriptor:expression:props.options:path:items
+              - urn:alm:descriptor:expression:props.options:label:path:name
+              - urn:alm:descriptor:expression:props.options:value:path:name
+            operationId: listGitRefs
+            parameters:
+            - name: repositoryUrl
+              in: query
+              description: "Cloneable URL of the repository (e.g., https://github.com/mygroup/my-app.git)"
+              required: true
+              schema:
+                type: string
+            - name: search
+              in: query
+              description: "Return list of git references containing the search string"
+              required: false
+              schema:
+                type: string
+            responses:
+              '200':
+                description: "All git references for a repository"
+                content:
+                  application/json: {}
+```
+
+**Referencing OpenAPI in ResourceInterface**
+
+Once the API is defined in ConnectorClass, reference it in your ResourceInterface using the following syntax:
+
+- `urn:alm:descriptor:widgets:select` to specify the widget type
+- `schema:openapi:context.connectorClass.spec.api.openapi:<operationId>` to reference the API definition in the ConnectorClass
+
+```yaml
+kind: ResourceInterface
+metadata:
+  name: gitcoderepository
+  annotations:
+    style.tekton.dev/descriptors: >-
+      - path: params.revision
+        x-descriptors:
+          - urn:alm:descriptor:widgets:select
+          - urn:alm:descriptor:expression:props.options:schema:openapi:context.connectorClass.spec.api.openapi:listGitRefs
+          - urn:alm:descriptor:label:en:Revision
+          - urn:alm:descriptor:label:zh:Revision
+          - urn:alm:descriptor:description:zh:Git revision reference, e.g. refs/heads/main.
+          - urn:alm:descriptor:description:en:Git revision reference (e.g., refs/heads/main for branches)
+```
+
+With this configuration, the `revision` field in Pipeline Integration renders as a dropdown that fetches options from the `listGitRefs` API.
 
 ## Examples \{#examples}
 
@@ -397,3 +604,4 @@ spec:
 - [Concept of Connector](./connector.mdx)
 - [Concept of ConnectorClass](./connectorclass.mdx)
 - <ExternalSiteLink name="pipelines" href="/pipelines/concepts/integrate_with_connector.html" children="Pipeline Integration" />
+- <ExternalSiteLink name="pipelines" href="/pipelines/how_to/configure_dynamic_forms.html" children="Pipeline Dynamic Forms" />
diff --git a/docs/en/overview/release_notes.mdx b/docs/en/overview/release_notes.mdx
@@ -29,25 +29,45 @@ The following table shows the compatibility and support matrix between the Alaud
 
 ### Features and Enhancements
 
-- Provides out-of-the-box definitions for `GitCodeRepository`, `OCIArtifact`, and `MavenArtifact` resources, enabling seamless integration of external resources (Git repositories, OCI artifacts, Maven artifacts) into TektonCD pipelines through a unified UI interface. For more details, see
-  * [ResourceInterface](../connectors/concepts/resource_interface.mdx)
-  * <ExternalSiteLink name="pipelines" href="/pipelines/concepts/integrate_with_connector.html" children="Pipeline Integration" />
-- Add docs to explain credential permissions required for each connector. more details: [Credential Permissions Required](../connectors-git/concepts/git_connectorclass.mdx#credential_permissions_required)
+**More Connectors**
+
 - Support integration with GitLab Server by using GitLab Connector. more details:
   - [GitLab Connector Quick Start](../connectors-gitlab/quick_start.mdx)
 - Support integration with NPM Registries by using NPM Connector. more details:
   - [NPM Connector Quick Start](../connectors-npm/quick_start.mdx)
 - Support integration with Harbor Registries by using Harbor Connector. more details:
   - [Harbor Connector Quick Start](../connectors-harbor/quick_start.mdx)
-- Support accessing tool's original API through the Connector API when the ConnectorClass provides Proxy Service capabilities. The system now supports two ways to access tool resources: using the tool's original API via Proxy Service, or using custom APIs provided for the ConnectorClass. For more details, see
-  * [Connector API](../connectors/concepts/connector_api.mdx)
+
+**ResourceInterface for Pipeline Integration**
+
+- Provides out-of-the-box definitions for `GitCodeRepository`, `OCIArtifact`, and `MavenArtifact` resources, enabling seamless integration of external resources (Git repositories, OCI artifacts, Maven artifacts) into TektonCD pipelines through a unified UI interface. For more details, see
+  * [ResourceInterface](../connectors/concepts/resource_interface.mdx)
+  * <ExternalSiteLink name="pipelines" href="/pipelines/concepts/integrate_with_connector.html" children="Pipeline Integration" />
+- Support Dynamic Form in ResourceInterface for Pipeline Integration. For more details, see [ResourceInterface Dynamic Form](../connectors/concepts/resource_interface.mdx#dynamic-form).
+
+**Connector API Enhancement**
+
+- Support accessing tool's original API through the Connector API when the ConnectorClass provides Proxy Service capabilities. The system now supports two ways to access tool resources: using the tool's original API via Proxy Service, or using custom APIs provided for the ConnectorClass. For more details, see [Connector API](../connectors/concepts/connector_api.mdx).
+
+**ConnectorClass Customization Flexibility**
+
 - Support using Rego rules to extract tokens from client requests when using the built-in HTTP reverse proxy. Combined with the existing ability to inject authentication credentials into backend requests through Rego rules, you can now extend the built-in reverse proxy's capabilities to support tools with non-standard HTTP authentication mechanisms.
   - For token extraction configuration, see [Custom Rego-based Authentication](../connectors/concepts/connectors_proxy.mdx#custom-rego-based-authentication).
   - For authentication injection configuration, see [Injecting Authentication Credentials into Backend Request when using built-in Reverse Proxy](../connectors/concepts/connectors_proxy.mdx#injecting-authentication-when-using-built-in-reverse-proxy).
 - Support using request variables in `spec.auth.types[].generator.rego` to inject authentication credentials into backend requests. more details: [Variables Available in Rego](../connectors/concepts/connectorclass.mdx#variables-available-in-rego).
-- OCI Connector supports using forward proxy for image operations. For more details, see [OCI Connector Forward Proxy](../connectors-oci/concepts/oci_connectorclass.mdx#forward-proxy)
+
+**OCI Connector Forward Proxy**
+
+- OCI Connector supports using forward proxy for image operations. For more details, see [OCI Connector Forward Proxy](../connectors-oci/concepts/oci_connectorclass.mdx#forward-proxy).
+
+**CSI Driver Built-in Configurations**
+
 - `Connectors CSI Driver` provides built-in configuration files that are always mounted into Pods. For more details, see [Built-in Configurations](../connectors/concepts/connectors_csi.mdx#built-in-configurations).
 
+**Other Enhancements**
+
+- Add docs to explain credential permissions required for each connector. more details: [Credential Permissions Required](../connectors-git/concepts/git_connectorclass.mdx#credential_permissions_required).
+
 ### Breaking Changes
 
 - Remove the `input.xxx` variable from `spec.auth.types[].generator.rego`. Use `input.data.xxx` instead.
