docs(examples): update property descriptions (#24)

* fix: update properties

* fix: descriptions

* fix: generic token

Author: wrussell1999

src/main/java/io/kestra/plugin/gitlab/AbstractGitLabTask.java

@@ -21,15 +21,15 @@
 @NoArgsConstructor
 public abstract class AbstractGitLabTask extends Task {
 
-    @Schema(title = "GitLab URL", description = "GitLab URL")
+    @Schema(title = "GitLab host name", description = "The host name of the GitLab instance.")
     @Builder.Default
     private Property<String> url = Property.ofValue("https://gitlab.com");
 
-    @Schema(title = "Personal Access Token", description = "GitLab Personal Access Token")
+    @Schema(title = "Personal, Project or Group Access Token", description = "GitLab Personal, Project or Group Access Token. More information on the [GitLab documentation](https://docs.gitlab.com/api/rest/authentication/).")
     @NotNull
     private Property<String> token;
 
-    @Schema(title = "Project ID", description = "GitLab project ID")
+    @Schema(title = "Project ID", description = "The global ID or URL-encoded path of the project.")
     @NotNull
     private Property<String> projectId;
 

src/main/java/io/kestra/plugin/gitlab/issues/Create.java

@@ -28,11 +28,11 @@
 @Schema(
     title = "Create a GitLab issue.",
     description = "Create a new issue in a GitLab project. " +
-        "You need to provide a valid GitLab project ID and a personal access token with the necessary permissions."
+        "You need to provide a valid GitLab project ID and an access token with the necessary permissions."
 )
 @Plugin(examples = {
     @Example(
-        title = "Create an issue in a GitLab project using a project access token.",
+        title = "Create an issue in a GitLab project using an access token.",
         full = true,
         code = """
             id: gitlab_create_issue
@@ -41,7 +41,6 @@
             tasks:
               - id: create_issue
                 type: io.kestra.plugin.gitlab.issues.Create
-                url: https://gitlab.example.com
                 token: "{{ secret('GITLAB_TOKEN') }}"
                 projectId: "123"
                 title: "Bug report"
@@ -55,7 +54,7 @@
         title = "Create an issue with custom API path for self-hosted GitLab.",
         full = true,
         code = """
-            id: gitlab_create_issue_custom
+            id: gitlab_create_issue_self_hosted
             namespace: company.team
 
             tasks:
@@ -121,10 +120,10 @@ public Output run(RunContext runContext) throws Exception {
     @Builder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "Created issue ID")
+        @Schema(title = "Issue ID")
         private String issueId;
 
-        @Schema(title = "Issue web URL")
+        @Schema(title = "Issue URL")
         private String webUrl;
 
         @Schema(title = "HTTP status code")

src/main/java/io/kestra/plugin/gitlab/issues/Search.java

@@ -27,11 +27,11 @@
 @Schema(
     title = "Search GitLab issues.",
     description = "Search for issues in a GitLab project. " +
-        "You need to provide a valid GitLab project ID and a personal access token with the necessary permissions."
+        "You need to provide a valid GitLab project ID and an access token with the necessary permissions."
 )
 @Plugin(examples = {
     @Example(
-        title = "Search for issues in a GitLab project using a project access token.",
+        title = "Search for issues in a GitLab project using an access token.",
         full = true,
         code = """
             id: gitlab_search_issues
@@ -40,7 +40,6 @@
             tasks:
               - id: search_issues
                 type: io.kestra.plugin.gitlab.issues.Search
-                url: https://gitlab.example.com
                 token: "{{ secret('GITLAB_TOKEN') }}"
                 projectId: "123"
                 search: "bug"
@@ -49,6 +48,27 @@
                   - bug
                   - critical
             """
+    ),
+    @Example(
+    title = "Search for issues in a GitLab project with custom API path for self-hosted GitLab.",
+    full = true,
+    code = """
+        id: gitlab_search_issues
+        namespace: company.team
+
+        tasks:
+            - id: search_issues
+            type: io.kestra.plugin.gitlab.issues.Search
+            url: https://gitlab.example.com
+            apiPath: /api/v4/projects
+            token: "{{ secret('GITLAB_TOKEN') }}"
+            projectId: "123"
+            search: "bug"
+            state: "opened"
+            labels:
+                - bug
+                - critical
+        """
     )
 })
 public class Search extends AbstractGitLabTask implements RunnableTask<Search.Output> {

src/main/java/io/kestra/plugin/gitlab/issues/package-info.java

@@ -1,6 +1,6 @@
 @PluginSubGroup(
     title = "Issues",
-    description = "This sub-group of plugins contains tasks for using GitLab.\nSet the GitLab host, project ID, and access token to file issues with title/description, add comments or updates, and list or retrieve issue details for triage workflows.",
+    description = "This sub-group of plugins contains tasks for using GitLab.\nSet the GitLab host name, project ID, and access token to file issues with title/description, add comments or updates, and list or retrieve issue details for triage workflows.",
     categories = PluginSubGroup.PluginCategory.TOOL
 )
 package io.kestra.plugin.gitlab.issues;

src/main/java/io/kestra/plugin/gitlab/mergerequests/Create.java

@@ -27,12 +27,12 @@
 @Schema(
     title = "Create a GitLab merge request.",
     description = "Create a new merge request in a GitLab project. " +
-        "You need to provide a valid GitLab project ID and a personal access token with the necessary permissions."
+        "You need to provide a valid GitLab project ID and an access token with the necessary permissions."
 )
 @Plugin(
     examples = {
         @Example(
-            title = "Create a merge request in a GitLab project using a project access token.",
+            title = "Create a merge request in a GitLab project using an access token.",
             full = true,
             code = """
                 id: gitlab_merge_request
@@ -41,14 +41,32 @@
                 tasks:
                   - id: create_merge_request
                     type: io.kestra.plugin.gitlab.mergerequests.Create
-                    url: https://gitlab.example.com
                     token: "{{ secret('GITLAB_TOKEN') }}"
                     projectId: "123"
                     title: "Feature: Add new functionality"
                     mergeRequestDescription: "This merge request adds new functionality to the project"
                     sourceBranch: "feat-testing"
                     targetBranch: "main"
                 """
+        ),
+        @Example(
+            title = "Create a merge request with custom API path for self-hosted GitLab.",
+            full = true,
+            code = """
+                id: gitlab_merge_request_self_hosted
+                namespace: company.team
+
+                tasks:
+                  - id: create_merge_request
+                    type: io.kestra.plugin.gitlab.mergerequests.Create
+                    url: https://gitlab.example.com
+                    apiPath: /api/v4/projects
+                    token: "{{ secret('GITLAB_TOKEN') }}"
+                    projectId: "123"
+                    title: "Hotfix: Critical bug fix"
+                    sourceBranch: "hotfix-branch"
+                    targetBranch: "main"
+                """
         )
     },
     aliases = "io.kestra.plugin.gitlab.MergeRequest"
@@ -111,10 +129,10 @@ public Output run(RunContext runContext) throws Exception {
     @Builder
     @Getter
     public static class Output implements io.kestra.core.models.tasks.Output {
-        @Schema(title = "Created merge request ID")
+        @Schema(title = "Merge Request ID")
         private String mergeReqID;
 
-        @Schema(title = "web URL")
+        @Schema(title = "Merge Request URL")
         private String webUrl;
 
         @Schema(title = "HTTP status code")

src/main/java/io/kestra/plugin/gitlab/mergerequests/package-info.java

@@ -1,6 +1,6 @@
 @PluginSubGroup(
     title = "Merge Requests",
-    description = "Tasks that create, update, and fetch GitLab Merge Requests.\nSet the GitLab host, project ID, and access token to handle Merge Requests.",
+    description = "Tasks that create, update, and fetch GitLab Merge Requests.\nSet the GitLab host name, project ID, and access token to handle Merge Requests.",
     categories = PluginSubGroup.PluginCategory.TOOL
 )
 package io.kestra.plugin.gitlab.mergerequests;

src/main/resources/metadata/index.yaml

@@ -2,7 +2,7 @@ group: io.kestra.plugin.gitlab
 name: "gitlab"
 title: "GitLab"
 description: "Tasks that interact with GitLab projects, commits, and issues via the API."
-body: "Provide a GitLab server URL and personal access token with project identifiers to search commits, create or update issues, and retrieve project metadata for CI/CD or governance workflows."
+body: "Provide a GitLab host name and access token with project identifiers to search commits, create or update issues, and retrieve project metadata for CI/CD or governance workflows."
 videos: []
 createdBy: "Kestra Core Team"
 managedBy: "Kestra Core Team"

src/main/resources/metadata/issues.yaml

@@ -2,7 +2,7 @@ group: io.kestra.plugin.gitlab.issues
 name: "issues"
 title: "Issues"
 description: "Tasks that create, update, and fetch GitLab issues."
-body: "Set the GitLab host, project ID, and access token to file issues with title/description, add comments or updates, and list or retrieve issue details for triage workflows."
+body: "Set the GitLab host name, project ID, and access token to file issues with title/description, add comments or updates, and list or retrieve issue details for triage workflows."
 videos: []
 createdBy: "Kestra Core Team"
 managedBy: "Kestra Core Team"

src/main/resources/metadata/mergerequests.yaml

@@ -2,7 +2,7 @@ group: io.kestra.plugin.gitlab.mergerequests
 name: "mergerequests"
 title: "Merge Requests"
 description: "Tasks that create, update, and fetch GitLab Merge Requests."
-body: "Set the GitLab host, project ID, and access token to handle Merge Requests."
+body: "Set the GitLab host name, project ID, and access token to handle Merge Requests."
 videos: []
 createdBy: "Kestra Core Team"
 managedBy: "Kestra Core Team"