feat(branch): optional environment list on branch create (DX-31560)

changelog.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## v1.16.0
+
+### Oct 28, 2026
+
+- Feat: Branch create accepts an optional `branch.publish_config.environments` list of environment names, so a branch can clone only the environments it needs. `[]` clones none; omitting `publish_config` clones all environments, as before. The list is sent unchanged, the SDK adds no length limit, and an unknown name (or a mix) returns the API's 422 error body unchanged with no branch created.
+
 ## v1.15.0
 
 ### Oct 21, 2026

pom.xml

@@ -7,7 +7,7 @@
     <artifactId>cms</artifactId>
     <packaging>jar</packaging>
     <name>contentstack-management-java</name>
-    <version>1.15.0</version>
+    <version>1.16.0</version>
     <description>Contentstack Java Management SDK for Content Management API, Contentstack is a headless CMS with an
         API-first approach
     </description>

src/main/java/com/contentstack/cms/stack/Branch.java

@@ -159,6 +159,32 @@ public Call<ResponseBody> fetch() {
     /**
      * The Create a branch request creates a new branch in a particular stack of
      * your organization.
+     * <p>
+     * Optionally set {@code branch.publish_config.environments} to a list of
+     * environment <b>names</b> (not UIDs) to choose which environments the branch
+     * clones:
+     * <ul>
+     * <li>a list of names clones only those environments;</li>
+     * <li>an empty list {@code []} clones none;</li>
+     * <li>omitting {@code publish_config} clones all environments, as before.</li>
+     * </ul>
+     * The list is sent unchanged. The SDK does not validate the names or limit the
+     * list length. An unknown name, or a mix of known and unknown names, is
+     * rejected by the API with a 422; the API's error body is returned unchanged
+     * and no branch is created.
+     * <p>
+     * Example body:
+     * <pre>{@code
+     * JSONObject publishConfig = new JSONObject();
+     * publishConfig.put("environments", Arrays.asList("development", "staging"));
+     * JSONObject branch = new JSONObject();
+     * branch.put("uid", "branch_uid");
+     * branch.put("source", "main");
+     * branch.put("publish_config", publishConfig);
+     * JSONObject body = new JSONObject();
+     * body.put("branch", branch);
+     * stack.branch().create(body).execute();
+     * }</pre>
      *
      * @param body the request body
      * @return Call

src/test/java/com/contentstack/cms/TestClient.java

@@ -39,6 +39,12 @@ public class TestClient {
     public static final String ENTRY_VARIANT_LOCALE =
             isBlank(env.get("entryVariantLocale")) ? "en-us" : env.get("entryVariantLocale").trim();
 
+    /** Login email for tests that log in with a real account (null when {@code EMAIL} is not set in {@code .env}). */
+    public static final String EMAIL = env.get("EMAIL");
+
+    /** Login password for tests that log in with a real account (null when {@code PASSWORD} is not set in {@code .env}). */
+    public static final String PASSWORD = env.get("PASSWORD");
+
     /** {@code true} if {@code value} is null, empty, or whitespace-only. */
     private static boolean isBlank(String value) {
         return value == null || value.trim().isEmpty();
@@ -51,6 +57,11 @@ public static boolean isUsingDefaultStackCredentials() {
         return env.get("apiKey") == null || env.get("managementToken") == null;
     }
 
+    /** {@code true} when {@code apiKey} is set to a non-blank value in {@code .env}. */
+    public static boolean isApiKeyConfigured() {
+        return !isBlank(env.get("apiKey"));
+    }
+
     private static Contentstack instance;
     private static Stack stackInstance;
 

src/test/java/com/contentstack/cms/UnitTestSuite.java

@@ -3,6 +3,7 @@
 import com.contentstack.cms.core.AuthInterceptorTest;
 import com.contentstack.cms.core.EndpointTest;
 import com.contentstack.cms.stack.AssetUnitTest;
+import com.contentstack.cms.stack.BranchUnitTest;
 import com.contentstack.cms.stack.EntryVariantUnitTest;
 import com.contentstack.cms.stack.EnvironmentUnitTest;
 import com.contentstack.cms.stack.GlobalFieldUnitTests;
@@ -33,6 +34,7 @@
         AssetUnitTest.class,
         EntryVariantUnitTest.class,
         EnvironmentUnitTest.class,
+        BranchUnitTest.class,
         GlobalFieldUnitTests.class,
         LocaleUnitTest.class,
         ReleaseUnitTest.class,

src/test/java/com/contentstack/cms/stack/APISanityTestSuite.java

@@ -11,6 +11,7 @@
          EndpointAPITest.class,
         TaxonomyAPITest.class,
          AssetAPITest.class,
+         BranchAPITest.class,
          ContentTypeAPITest.class,
          EntryFieldsAPITest.class,
          EnvironmentAPITest.class,