Fix #11: Refactor GitLab tasks into 'core' package for documentation visibility by hariomch1 · Pull Request #12 · kestra-io/plugin-gitlab

hariomch1 · 2025-10-27T16:08:23Z

fixes #11

What changes are being made and why?

The primary goal is to resolve a documentation visibility issue where the automatic documentation generator failed to discover all tasks when they were spread across the root package and sub-packages.

This PR implements the requested refactoring:

Refactor Code Structure: All core task files (AbstractGitLabTask.java, MergeRequest.java, and the entire issues sub-package) were moved from the root package (io.kestra.plugin.gitlab) into a new standardized sub-package: io.kestra.plugin.gitlab.core.
Update Metadata: The original @PluginSubGroup annotation was moved to the new core package (package io.kestra.plugin.gitlab.core;).
Add Missing Metadata: A package-info.java file was added to the nested issues package (io.kestra.plugin.gitlab.core.issues) to ensure proper documentation of that task group.

This structural change ensures the Kestra documentation system correctly recognizes and displays all GitLab tasks.

Closes #11

How the changes have been QAed?

This change is a structural refactor (moving code) and metadata update, not a feature addition. QA was performed by verifying code integrity and functionality:

Build Verification: Successfully executed ./gradlew shadowJar to confirm the Java code compiles in the new package structure.
Functional Verification: Successfully executed ./gradlew test to confirm all unit tests pass (15 passing), ensuring no existing functionality was broken by the file moves.

Setup Instructions

No external setup (API keys, accounts, etc.) is required, as this change only affects the internal packaging of the plugin.

Contributor Checklist ✅

PR Title and commits follows conventional commits (Using fix(plugin-gitlab): ...)
Add a closes #ISSUE_ID or fixes #ISSUE_ID in the description if the PR relates to an opened issue. (Included Closes #11)
Documentation updated (plugin docs from @Schema for properties and outputs, @Plugin with examples, README.md file with basic knowledge and specifics). (N/A for this refactor, but package-info.java was updated).
Setup instructions included if needed (API keys, accounts, etc.).
Prefix all rendered properties by r not rendered (eg: rHost).
Use runContext.logger() to log enough important infos where it's needed and with the best level (DEBUG, INFO, WARN or ERROR).

⚙️ Properties

Properties are declared with Property<T> carrier type, do not use @PluginProperty.
Mandatory properties must be annotated with @NotNull and checked during the rendering.
You can model a JSON thanks to a simple Property<Map<String, Object>>.

🌐 HTTP

Must use Kestra’s internal HTTP client from io.kestra.core.http.client

📦 JSON

If you are serializing response from an external API, you may have to add a @JsonIgnoreProperties(ignoreUnknown = true) at the mapped class level. So that we will avoid to crash the plugin if the provider add a new field suddenly.
Must use Jackson mappers provided by core (io.kestra.core.serializers)

✨ New plugins / subplugins

Make sure your new plugin is configured like mentioned here.
Add a package-info.java under each sub package respecting this format and choosing the right category. (Added to .core and .core.issues)
Icons added in src/main/resources/icons in SVG format and not in thumbnail (keep it big):
- plugin-icon.svg
- One icon per package, e.g. io.kestra.plugin.aws.svg
- For subpackages, e.g. io.kestra.plugin.aws.s3, add io.kestra.plugin.aws.s3.svg
See example here.
Use "{{ secret('YOUR_SECRET') }}" in the examples for sensible infos such as an API KEY.
If you are fetching data (one, many or too many), you must add a Property<FetchType> fetchType to be able to use FETCH_ONE, FETCH and even STORE to store big amount of data in the internal storage.
Align the """ to close examples blocks with the flow id.

🧪 Tests

Unit Tests added or updated to cover the change (using the RunContext to actually run tasks). (Existing tests confirmed passing)
Add sanity checks if possible with a YAML flow inside src/test/resources/flows.
Avoid disabling tests for CI. Instead, configure a local environment whenever it's possible with .github/setup-unit.sh (which can be executed locally and in the CI) all along with a new docker-compose-ci.yml file (do not edit the existing docker-compose.yml).
Provide screenshots from your QA / tests locally in the PR description. The goal here is to use the JAR of the plugin and directly test it locally in Kestra UI to ensure it integrates well.

📤 Outputs

Do not send back as outputs the same infos you already have in your properties.
If you do not have any output use VoidOutput.
Do not output twice the same infos (eg: a status code, an error code saying the same thing...).

fdelbrayelle · 2025-10-28T07:57:58Z

allure-results/00d39e44-4ea5-4998-9c54-48696a007e22-result.json

@@ -0,0 +1 @@
+{"uuid":"00d39e44-4ea5-4998-9c54-48696a007e22","historyId":"ea0d4a0042ac13ecffc6105bcb30012a","testCaseId":"[engine:junit-jupiter]/[class:io.kestra.plugin.gitlab.CreateIssueTest]/[method:testCreateIssue()]","testCaseName":"testCreateIssue()","fullName":"io.kestra.plugin.gitlab.CreateIssueTest.testCreateIssue","labels":[{"name":"junit.platform.uniqueid","value":"[engine:junit-jupiter]/[class:io.kestra.plugin.gitlab.CreateIssueTest]/[method:testCreateIssue()]"},{"name":"host","value":"fedora"},{"name":"thread","value":"106662@fedora.Test worker(1)"},{"name":"framework","value":"junit-platform"},{"name":"language","value":"java"},{"name":"package","value":"io.kestra.plugin.gitlab.CreateIssueTest"},{"name":"testClass","value":"io.kestra.plugin.gitlab.CreateIssueTest"},{"name":"testMethod","value":"testCreateIssue"},{"name":"suite","value":"io.kestra.plugin.gitlab.CreateIssueTest"}],"links":[],"name":"testCreateIssue()","status":"passed","stage":"finished","description":"","steps":[],"attachments":[],"parameters":[],"start":1761580197201,"stop":1761580198341}


Can you remove allure-results from the changes please?

please check it

fdelbrayelle · 2025-10-28T07:58:35Z

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

@@ -0,0 +1,4 @@
+/**


Remove this comment and add a @PluginSubGroup annotation like the other package-info.java.

fdelbrayelle · 2025-10-28T07:59:26Z

@hariomch1 You also have to rename the package in the examples in the tasks.

fdelbrayelle · 2025-10-28T08:00:09Z

The tests also have to be moved to the core package.
And you forgot to add the aliases as asked in the issue.

fdelbrayelle · 2025-10-30T09:23:16Z

Did you have time to check my last feedback @hariomch1?

In addition, could you duplicate the icon(s) in src/main/resources/icons for the new .core package please? 🙏

hariomch1 · 2025-11-02T15:09:54Z

yes i made some changes but it fails all checks please review

fdelbrayelle · 2025-11-03T14:16:07Z

allure-results/00d8eeae-c77f-4494-9f27-35afe7785f4a-result.json

@@ -0,0 +1 @@
+{"uuid":"00d8eeae-c77f-4494-9f27-35afe7785f4a","historyId":"6aee8db7e21f7172305178a6239aa033","testCaseId":"[engine:junit-jupiter]/[class:io.kestra.plugin.gitlab.CreateIssueTest]/[method:testCreateIssueWithMinimalData()]","testCaseName":"testCreateIssueWithMinimalData()","fullName":"io.kestra.plugin.gitlab.CreateIssueTest.testCreateIssueWithMinimalData","labels":[{"name":"junit.platform.uniqueid","value":"[engine:junit-jupiter]/[class:io.kestra.plugin.gitlab.CreateIssueTest]/[method:testCreateIssueWithMinimalData()]"},{"name":"host","value":"fedora"},{"name":"thread","value":"106662@fedora.Test worker(1)"},{"name":"framework","value":"junit-platform"},{"name":"language","value":"java"},{"name":"package","value":"io.kestra.plugin.gitlab.CreateIssueTest"},{"name":"testClass","value":"io.kestra.plugin.gitlab.CreateIssueTest"},{"name":"testMethod","value":"testCreateIssueWithMinimalData"},{"name":"suite","value":"io.kestra.plugin.gitlab.CreateIssueTest"}],"links":[],"name":"testCreateIssueWithMinimalData()","status":"passed","stage":"finished","description":"","steps":[],"attachments":[],"parameters":[],"start":1761580198352,"stop":1761580198514}


Could you remove the allure-results folder from the diff please?

Could you remove the allure-results folder from the diff please?

"Confirmed, I've removed the file and added allure-results/ to .gitignore. Ready for final review!"

fdelbrayelle · 2025-11-03T14:17:06Z

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

 @NoArgsConstructor
+
+@Aliases({
+    // Alias points to the old package path


Hmm no aliases = {"..."} on each core task inside the @Plugin annotation, not here 🙏

fdelbrayelle · 2025-11-03T14:17:24Z

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

    protected String buildApiEndpoint(String resource, RunContext runContext) throws IllegalVariableEvaluationException {
        String renderedApiPath = runContext.render(this.apiPath).as(String.class).orElse("/api/v4/projects");
-        String renderedProjectId = runContext.render(this.getProjectId()).as(String.class).orElseThrow();
+        String renderedProjectId = runContext.render(this.projectId).as(String.class).orElseThrow();


Unrelated change to remove from the PR

fdelbrayelle · 2025-11-03T14:17:47Z

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

            """
    )
 })
+@Aliases({


No it's to add inside the @Plugin annotation in aliases

src/main/java/io/kestra/plugin/gitlab/core/MergeRequest.java

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

fdelbrayelle · 2025-11-04T08:29:02Z

allure-results/05469e84-3317-4c8e-b6fb-0e4799750840-result.json

@@ -0,0 +1 @@
+{"uuid":"05469e84-3317-4c8e-b6fb-0e4799750840","historyId":"fd2df4c6f1fed89b5fc7de49dccffb7c","testCaseId":"[engine:junit-jupiter]/[class:io.kestra.plugin.gitlab.MergeRequestTest]/[method:testCreateMergeRequestNotFound()]","testCaseName":"testCreateMergeRequestNotFound()","fullName":"io.kestra.plugin.gitlab.MergeRequestTest.testCreateMergeRequestNotFound","labels":[{"name":"junit.platform.uniqueid","value":"[engine:junit-jupiter]/[class:io.kestra.plugin.gitlab.MergeRequestTest]/[method:testCreateMergeRequestNotFound()]"},{"name":"host","value":"fedora"},{"name":"thread","value":"106662@fedora.Test worker(1)"},{"name":"framework","value":"junit-platform"},{"name":"language","value":"java"},{"name":"package","value":"io.kestra.plugin.gitlab.MergeRequestTest"},{"name":"testClass","value":"io.kestra.plugin.gitlab.MergeRequestTest"},{"name":"testMethod","value":"testCreateMergeRequestNotFound"},{"name":"suite","value":"io.kestra.plugin.gitlab.MergeRequestTest"}],"links":[],"name":"testCreateMergeRequestNotFound()","status":"passed","stage":"finished","description":"","steps":[],"attachments":[],"parameters":[],"start":1761580202472,"stop":1761580202573}


@hariomch1 Could you remove allure-results folder from the changes 🙏 ?

check @fdelbrayelle

i added this to gitignore and remove also from git tracking index

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

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

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

fdelbrayelle · 2025-11-04T09:22:22Z

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

@@ -1,5 +1,6 @@
-package io.kestra.plugin.gitlab.issues;
+package io.kestra.plugin.gitlab.core.issues;


No... You have to keep the tasks that were in the issues package...

The target tasks to move in io.kestra.plugin.gitlab.core are ONLY the one in the root package io.kestra.plugin.gitlab.

fdelbrayelle · 2025-11-04T09:23:11Z

src/main/java/io/kestra/plugin/gitlab/core/MergeRequest.java

@@ -1,5 +1,6 @@
-package io.kestra.plugin.gitlab;
+package io.kestra.plugin.gitlab.core;


Only this class must be moved to core package

src/main/java/io/kestra/plugin/gitlab/core/MergeRequest.java

…entation visibility

fdelbrayelle · 2025-11-06T11:01:31Z

I'm closing this PR, I'm taking back this part because you deleted tasks in your changes... 👍

kestrabot bot added this to Pull Requests Oct 27, 2025

github-project-automation bot moved this to To review in Pull Requests Oct 27, 2025

MilosPaunovic added kind/external Pull requests raised by community contributors area/plugin Plugin-related issue or feature request labels Oct 28, 2025

MilosPaunovic requested review from a team and fdelbrayelle October 28, 2025 06:44

fdelbrayelle assigned hariomch1 Oct 28, 2025

fdelbrayelle reviewed Oct 28, 2025

View reviewed changes

hariomch1 force-pushed the fix/gitlab-core-package-11 branch 2 times, most recently from 60375af to bdaa176 Compare October 28, 2025 13:48

fdelbrayelle reviewed Nov 3, 2025

View reviewed changes

src/main/java/io/kestra/plugin/gitlab/core/MergeRequest.java Outdated Show resolved Hide resolved

fdelbrayelle reviewed Nov 3, 2025

View reviewed changes

src/main/java/io/kestra/plugin/gitlab/core/Search.java Outdated Show resolved Hide resolved

hariomch1 force-pushed the fix/gitlab-core-package-11 branch 2 times, most recently from d817aa9 to d67d670 Compare November 4, 2025 08:04