From e6d253b18572f394a388aedfb8bf09c227f1f395 Mon Sep 17 00:00:00 2001
From: Jean-Michel Leclercq <jean.michel.lec@gmail.com>
Date: Sat, 4 Oct 2025 15:58:46 +0200
Subject: [PATCH] Add environment filters #1129

---
 .../org/gitlab4j/api/EnvironmentsApi.java     | 25 ++++++++++++
 .../org/gitlab4j/api/TestEnvironmentsApi.java | 19 +++++++++
 .../api/models/EnvironmentFilter.java         | 40 +++++++++++++++++++
 3 files changed, 84 insertions(+)
 create mode 100644 gitlab4j-models/src/main/java/org/gitlab4j/api/models/EnvironmentFilter.java

diff --git a/gitlab4j-api/src/main/java/org/gitlab4j/api/EnvironmentsApi.java b/gitlab4j-api/src/main/java/org/gitlab4j/api/EnvironmentsApi.java
index 0858b69e..9a4e09c3 100644
--- a/gitlab4j-api/src/main/java/org/gitlab4j/api/EnvironmentsApi.java
+++ b/gitlab4j-api/src/main/java/org/gitlab4j/api/EnvironmentsApi.java
@@ -7,6 +7,7 @@
 import jakarta.ws.rs.core.Response;
 
 import org.gitlab4j.api.models.Environment;
+import org.gitlab4j.api.models.EnvironmentFilter;
 
 /**
  * This class provides an entry point to all the GitLab API Environments API calls.
@@ -65,6 +66,30 @@ public Pager<Environment> getEnvironments(Object projectIdOrPath, int itemsPerPa
                 "environments"));
     }
 
+    /**
+     * Get a Pager of all environments for a given project.
+     *
+     * <pre><code>GitLab Endpoint: GET /projects/:id/environments</code></pre>
+     *
+     * @param projectIdOrPath id, path of the project, or a Project instance holding the project ID or path
+     * @param itemsPerPage the number of Environment instances that will be fetched per page
+     * @param filter Environment filters
+     * @return a Pager of Environment instances
+     * @throws GitLabApiException if any exception occurs
+     */
+    public Pager<Environment> getEnvironments(Object projectIdOrPath, int itemsPerPage, EnvironmentFilter filter)
+            throws GitLabApiException {
+        GitLabApiForm formData = new GitLabApiForm(filter.getQueryParams());
+        return (new Pager<Environment>(
+                this,
+                Environment.class,
+                itemsPerPage,
+                formData.asMap(),
+                "projects",
+                getProjectIdOrPath(projectIdOrPath),
+                "environments"));
+    }
+
     /**
      * Get a specific environment.
      *
diff --git a/gitlab4j-api/src/test/java/org/gitlab4j/api/TestEnvironmentsApi.java b/gitlab4j-api/src/test/java/org/gitlab4j/api/TestEnvironmentsApi.java
index 35b88344..da25d2c7 100644
--- a/gitlab4j-api/src/test/java/org/gitlab4j/api/TestEnvironmentsApi.java
+++ b/gitlab4j-api/src/test/java/org/gitlab4j/api/TestEnvironmentsApi.java
@@ -12,6 +12,7 @@
 import java.util.stream.Stream;
 
 import org.gitlab4j.api.models.Environment;
+import org.gitlab4j.api.models.EnvironmentFilter;
 import org.gitlab4j.api.models.Project;
 import org.junit.jupiter.api.AfterAll;
 import org.junit.jupiter.api.BeforeAll;
@@ -136,4 +137,22 @@ public void testOptionalEnvironment() throws GitLabApiException {
         gitLabApi.getEnvironmentsApi().stopEnvironment(testProject, env.getId());
         gitLabApi.getEnvironmentsApi().deleteEnvironment(testProject, env.getId());
     }
+
+    @Test
+    public void testFilterEnvironmentsByName() throws GitLabApiException {
+
+        final String uniqueName = getUniqueName();
+        final Environment env =
+                gitLabApi.getEnvironmentsApi().createEnvironment(testProject, uniqueName, EXTERNAL_URL, TIER);
+        final String uniqueName2 = getUniqueName();
+        final Environment env2 =
+                gitLabApi.getEnvironmentsApi().createEnvironment(testProject, uniqueName2, EXTERNAL_URL, TIER);
+
+        EnvironmentFilter filter = new EnvironmentFilter().withName(uniqueName);
+        Pager<Environment> envs = gitLabApi.getEnvironmentsApi().getEnvironments(testProject, 1, filter);
+        assertEquals(envs.first().get(0).getName(), uniqueName2);
+
+        gitLabApi.getEnvironmentsApi().stopEnvironment(testProject, env.getId());
+        gitLabApi.getEnvironmentsApi().deleteEnvironment(testProject, env.getId());
+    }
 }
diff --git a/gitlab4j-models/src/main/java/org/gitlab4j/api/models/EnvironmentFilter.java b/gitlab4j-models/src/main/java/org/gitlab4j/api/models/EnvironmentFilter.java
new file mode 100644
index 00000000..f7f11e1f
--- /dev/null
+++ b/gitlab4j-models/src/main/java/org/gitlab4j/api/models/EnvironmentFilter.java
@@ -0,0 +1,40 @@
+package org.gitlab4j.api.models;
+
+import java.io.Serializable;
+
+import org.gitlab4j.models.GitLabForm;
+
+public class EnvironmentFilter implements Serializable {
+    private static final long serialVersionUID = 1L;
+
+    private String name;
+    private String search;
+    private String states;
+
+    public EnvironmentFilter withName(String name) {
+        this.name = name;
+        return this;
+    }
+
+    public EnvironmentFilter withSearch(String search) {
+        this.search = search;
+        return this;
+    }
+
+    public EnvironmentFilter withStates(String states) {
+        this.states = states;
+        return this;
+    }
+
+    /**
+     * Get the query params specified by this filter.
+     *
+     * @return a GitLabApiForm instance holding the query parameters for this EnvironmentFilter instance
+     */
+    public GitLabForm getQueryParams() {
+        return new GitLabForm()
+                .withParam("name", name)
+                .withParam("search", search)
+                .withParam("states", states);
+    }
+}