Project Branches API

README.md

@@ -155,6 +155,7 @@ The API has been broken up into sub APIs classes to make it easier to learn and
 &nbsp;&nbsp;[SessionApi](#sessionapi)<br/>
 &nbsp;&nbsp;[SystemHooksApi](#systemhooksapi)<br/>
 &nbsp;&nbsp;[UserApi](#userapi)
+&nbsp;&nbsp;[ProtectedBranchesApi](#protectedbranchesapi)
 
 
 ### Sub API Examples
@@ -296,3 +297,8 @@ List<SystemHook> hooks = gitLabApi.getSystemHooksApi().getSystemHooks();
 // Get the User info for user_id 1
 User user = gitLabApi.getUserApi().getUser(1);
 ```
+
+#### ProtectedBranchesApi
+```java
+List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+```

src/main/java/org/gitlab4j/api/GitLabApi.java

@@ -62,6 +62,7 @@ public String getApiNamespace() {
     private LabelsApi labelsApi;
     private NotesApi notesApi;
     private EventsApi eventsApi;
+    private ProtectedBranchesApi protectedBranchesApi;
 
     /**
      * Create a new GitLabApi instance that is logically a duplicate of this instance, with the exception off sudo state.
@@ -1020,6 +1021,25 @@ public UserApi getUserApi() {
         return (userApi);
     }
 
+    /**
+     * Gets the ProtectedBranchesApi instance owned by this GitLabApi instance. The ProtectedBranchesApi is used
+     * to perform all protection related actions on a branch of a project.
+     *
+     * @return the ProtectedBranchesApi instance owned by this GitLabApi instance
+     */
+    public ProtectedBranchesApi getProtectedBranchesApi() {
+
+        if (this.protectedBranchesApi == null) {
+            synchronized (this) {
+                if (this.protectedBranchesApi == null) {
+                    this.protectedBranchesApi = new ProtectedBranchesApi(this);
+                }
+            }
+        }
+
+        return (this.protectedBranchesApi);
+    }
+
     /**
      * Create and return an Optional instance associated with a GitLabApiException.
      *

src/main/java/org/gitlab4j/api/ProtectedBranchesApi.java

@@ -0,0 +1,79 @@
+package org.gitlab4j.api;
+
+import org.gitlab4j.api.models.AccessLevel;
+import org.gitlab4j.api.models.ProtectedBranch;
+
+import javax.ws.rs.core.Form;
+import javax.ws.rs.core.GenericType;
+import javax.ws.rs.core.Response;
+import java.util.List;
+
+public class ProtectedBranchesApi extends AbstractApi {
+    public ProtectedBranchesApi(GitLabApi gitLabApi) {
+        super(gitLabApi);
+    }
+
+    /**
+     * Gets a list of protected branches from a project.
+     *
+     * GET /projects/:id/protected_branches
+     *
+     * @param projectId the ID of the project to protect
+     * @return the list of protected branches for the project
+     * @throws GitLabApiException if any exception occurs
+     */
+    public List<ProtectedBranch> getProtectedBranches(Integer projectId) throws GitLabApiException {
+        Response response = get(Response.Status.OK, null, "projects", projectId, "protected_branches");
+        return (response.readEntity(new GenericType<List<ProtectedBranch>>() {
+        }));
+    }
+
+    /**
+     * Unprotects the given protected branch or wildcard protected branch.
+     *
+     * DELETE /projects/:id/protected_branches/:name
+     *
+     * @param projectId  the ID of the project to un-protect
+     * @param branchName the name of the branch to un-protect
+     * @throws GitLabApiException if any exception occurs
+     */
+    public void unprotectBranch(Integer projectId, String branchName) throws GitLabApiException {
+        delete(Response.Status.NO_CONTENT, null, "projects", projectId, "protected_branches", urlEncode(branchName));
+    }
+
+    /**
+     * Protects a single repository branch or several project repository branches using a wildcard protected branch.
+     *
+     * POST /projects/:id/protected_branches
+     *
+     * @param projectId  the ID of the project to protect
+     * @param branchName the name of the branch to protect
+     * @return the branch info for the protected branch
+     * @throws GitLabApiException if any exception occurs
+     */
+    public ProtectedBranch protectBranch(Integer projectId, String branchName) throws GitLabApiException {
+        return protectBranch(projectId, branchName, AccessLevel.MASTER, AccessLevel.MASTER);
+    }
+
+    /**
+     * Protects a single repository branch or several project repository branches using a wildcard protected branch.
+     *
+     * POST /projects/:id/protected_branches
+     *
+     * @param projectId        the ID of the project to protect
+     * @param branchName       the name of the branch to protect
+     * @param pushAccessLevel  Access levels allowed to push (defaults: 40, master access level)
+     * @param mergeAccessLevel Access levels allowed to merge (defaults: 40, master access level)
+     * @return the branch info for the protected branch
+     * @throws GitLabApiException if any exception occurs
+     */
+    public ProtectedBranch protectBranch(Integer projectId, String branchName, AccessLevel pushAccessLevel, AccessLevel mergeAccessLevel) throws GitLabApiException {
+        Form formData = new GitLabApiForm()
+                .withParam("id", projectId, true)
+                .withParam("name", branchName, true)
+                .withParam("push_access_level", pushAccessLevel.toValue(), false)
+                .withParam("merge_access_level", mergeAccessLevel.toValue(), false);
+        Response response = post(Response.Status.CREATED, formData.asMap(), "projects", projectId, "protected_branches");
+        return (response.readEntity(ProtectedBranch.class));
+    }
+}

src/main/java/org/gitlab4j/api/RepositoryApi.java

@@ -15,6 +15,7 @@
 import javax.ws.rs.core.Response;
 
 import org.gitlab4j.api.GitLabApi.ApiVersion;
+import org.gitlab4j.api.models.AccessLevel;
 import org.gitlab4j.api.models.Branch;
 import org.gitlab4j.api.models.CompareResults;
 import org.gitlab4j.api.models.Tag;
@@ -110,7 +111,6 @@ public Branch createBranch(Integer projectId, String branchName, String ref) thr
         return (response.readEntity(Branch.class));
     }
 
-
     /**
      * Delete a single project repository branch.
      *
@@ -463,7 +463,7 @@ public File getRepositoryArchive(Integer projectId, String sha, File directory)
     /**
      * Compare branches, tags or commits. This can be accessed without authentication
      * if the repository is publicly accessible.
-     * 
+     *
      * @param projectId the ID of the project owned by the authenticated user
      * @param from the commit SHA or branch name
      * @param to the commit SHA or branch name
@@ -479,7 +479,7 @@ public CompareResults compare(Integer projectId, String from, String to) throws
     /**
      * Compare branches, tags or commits. This can be accessed without authentication
      * if the repository is publicly accessible.
-     * 
+     *
      * @param projectPath the path of the project owned by the authenticated user
      * @param from the commit SHA or branch name
      * @param to the commit SHA or branch name

src/main/java/org/gitlab4j/api/models/BranchAccessLevelDetails.java

@@ -0,0 +1,28 @@
+package org.gitlab4j.api.models;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlRootElement;
+
+@XmlRootElement
+@XmlAccessorType(XmlAccessType.FIELD)
+public class BranchAccessLevelDetails {
+    private String accessLevel;
+    private String accessLevelDescription;
+
+    public String getAccessLevel() {
+        return this.accessLevel;
+    }
+
+    public void setAccessLevel(String accessLevel) {
+        this.accessLevel = accessLevel;
+    }
+
+    public String getAccessLevelDescription() {
+        return this.accessLevelDescription;
+    }
+
+    public void setAccessLevelDescription(String accessLevelDescription) {
+        this.accessLevelDescription = accessLevelDescription;
+    }
+}

src/main/java/org/gitlab4j/api/models/ProtectedBranch.java

@@ -0,0 +1,43 @@
+
+package org.gitlab4j.api.models;
+
+import javax.xml.bind.annotation.XmlAccessType;
+import javax.xml.bind.annotation.XmlAccessorType;
+import javax.xml.bind.annotation.XmlRootElement;
+import java.util.List;
+
+@XmlRootElement
+@XmlAccessorType(XmlAccessType.FIELD)
+public class ProtectedBranch {
+    private String name;
+    private List<BranchAccessLevelDetails> pushAccessLevels;
+    private List<BranchAccessLevelDetails> mergeAccessLevels;
+
+    public String getName() {
+        return this.name;
+    }
+
+    public void setName(String name) {
+        this.name = name;
+    }
+
+    public List<BranchAccessLevelDetails> getPushAccessLevels() {
+        return this.pushAccessLevels;
+    }
+
+    public void setPushAccessLevels(List<BranchAccessLevelDetails> pushAccessLevels) {
+        this.pushAccessLevels = pushAccessLevels;
+    }
+
+    public List<BranchAccessLevelDetails> getMergeAccessLevels() {
+        return this.mergeAccessLevels;
+    }
+
+    public void setMergeAccessLevels(List<BranchAccessLevelDetails> mergeAccessLevels) {
+        this.mergeAccessLevels = mergeAccessLevels;
+    }
+
+    public static final boolean isValid(ProtectedBranch branch) {
+        return (branch != null && branch.getName() != null);
+    }
+}

src/test/java/org/gitlab4j/api/TestProtectedBranchesApi.java

@@ -0,0 +1,160 @@
+package org.gitlab4j.api;
+
+import org.gitlab4j.api.models.Branch;
+import org.gitlab4j.api.models.Project;
+import org.gitlab4j.api.models.ProtectedBranch;
+import org.junit.AfterClass;
+import org.junit.Before;
+import org.junit.BeforeClass;
+import org.junit.FixMethodOrder;
+import org.junit.Test;
+import org.junit.runners.MethodSorters;
+
+import java.util.List;
+
+import static org.junit.Assert.assertFalse;
+import static org.junit.Assert.assertNotNull;
+import static org.junit.Assert.assertTrue;
+import static org.junit.Assume.assumeTrue;
+
+/**
+ * In order for these tests to run you must set the following properties in test-gitlab4j.properties
+ *
+ * TEST_NAMESPACE
+ * TEST_PROJECT_NAME
+ * TEST_HOST_URL
+ * TEST_PRIVATE_TOKEN
+ *
+ * If any of the above are NULL, all tests in this class will be skipped.
+ *
+ * NOTE: &FixMethodOrder(MethodSorters.NAME_ASCENDING) is very important to insure that testCreate() is executed first.
+ */
+@FixMethodOrder(MethodSorters.NAME_ASCENDING)
+public class TestProtectedBranchesApi {
+    // The following needs to be set to your test repository
+    private static final String TEST_PROJECT_NAME;
+    private static final String TEST_NAMESPACE;
+    private static final String TEST_HOST_URL;
+    private static final String TEST_PRIVATE_TOKEN;
+
+    static {
+        TEST_NAMESPACE = TestUtils.getProperty("TEST_NAMESPACE");
+        TEST_PROJECT_NAME = TestUtils.getProperty("TEST_PROJECT_NAME");
+        TEST_HOST_URL = TestUtils.getProperty("TEST_HOST_URL");
+        TEST_PRIVATE_TOKEN = TestUtils.getProperty("TEST_PRIVATE_TOKEN");
+    }
+
+    private static GitLabApi gitLabApi;
+
+    private static final String TEST_BRANCH_REF = "master";
+    private static final String TEST_BRANCH_NAME = "feature/test_branch";
+    private static final String TEST_PROTECT_BRANCH_NAME = "feature/protect_branch";
+
+    @BeforeClass
+    public static void setup() {
+
+        String problems = "";
+        if (TEST_NAMESPACE == null || TEST_NAMESPACE.trim().length() == 0) {
+            problems += "TEST_NAMESPACE cannot be empty\n";
+        }
+
+        if (TEST_PROJECT_NAME == null || TEST_PROJECT_NAME.trim().length() == 0) {
+            problems += "TEST_PROJECT_NAME cannot be empty\n";
+        }
+
+        if (TEST_HOST_URL == null || TEST_HOST_URL.trim().length() == 0) {
+            problems += "TEST_HOST_URL cannot be empty\n";
+        }
+
+        if (TEST_PRIVATE_TOKEN == null || TEST_PRIVATE_TOKEN.trim().length() == 0) {
+            problems += "TEST_PRIVATE_TOKEN cannot be empty\n";
+        }
+
+        if (problems.isEmpty()) {
+            gitLabApi = new GitLabApi(GitLabApi.ApiVersion.V4, TEST_HOST_URL, TEST_PRIVATE_TOKEN);
+        } else {
+            System.err.print(problems);
+        }
+    }
+
+    @AfterClass
+    public static void teardown() throws GitLabApiException {
+        if (gitLabApi != null) {
+
+            try {
+                Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+
+                try {
+                    gitLabApi.getRepositoryApi().deleteBranch(project.getId(), TEST_BRANCH_NAME);
+                } catch (GitLabApiException ignore) {
+                }
+
+                try {
+                    gitLabApi.getRepositoryApi().deleteBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+                } catch (GitLabApiException ignore) {
+                }
+            } catch (GitLabApiException ignore) {
+            }
+        }
+    }
+
+    @Before
+    public void beforeMethod() throws GitLabApiException {
+        assumeTrue(gitLabApi != null);
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        Branch protectedBranch;
+        try {
+            protectedBranch = gitLabApi.getRepositoryApi().getBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+        } catch (GitLabApiException e) {
+            protectedBranch = gitLabApi.getRepositoryApi().createBranch(project.getId(), TEST_PROTECT_BRANCH_NAME, TEST_BRANCH_REF);
+        }
+        assertNotNull(protectedBranch);
+        gitLabApi.getRepositoryApi().protectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+
+        Branch branch;
+        try {
+            branch = gitLabApi.getRepositoryApi().getBranch(project.getId(), TEST_BRANCH_NAME);
+        } catch (GitLabApiException e) {
+            branch = gitLabApi.getRepositoryApi().createBranch(project.getId(), TEST_BRANCH_NAME, TEST_BRANCH_REF);
+        }
+        assertNotNull(branch);
+    }
+
+    @Test
+    public void testGetProtectedBranches() throws GitLabApiException {
+
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        assertNotNull(project);
+
+        List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+        assertNotNull(branches);
+        assertTrue(branches.stream()
+                .anyMatch((branch) -> branch.getName().equals(TEST_PROTECT_BRANCH_NAME)));
+    }
+
+    @Test
+    public void testUnprotectBranch() throws GitLabApiException {
+
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        assertNotNull(project);
+
+        gitLabApi.getProtectedBranchesApi().unprotectBranch(project.getId(), TEST_PROTECT_BRANCH_NAME);
+        List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+        assertNotNull(branches);
+        assertTrue(branches.stream()
+                .noneMatch((branch) -> branch.getName().equals(TEST_PROTECT_BRANCH_NAME)));
+    }
+
+    @Test
+    public void testProtectBranch() throws GitLabApiException {
+
+        Project project = gitLabApi.getProjectApi().getProject(TEST_NAMESPACE, TEST_PROJECT_NAME);
+        assertNotNull(project);
+
+        ProtectedBranch branch = gitLabApi.getProtectedBranchesApi().protectBranch(project.getId(), TEST_BRANCH_NAME);
+        List<ProtectedBranch> branches = gitLabApi.getProtectedBranchesApi().getProtectedBranches(project.getId());
+        assertNotNull(branches);
+        assertTrue(branches.stream()
+                .anyMatch((protectedBranch) -> protectedBranch.getName().equals(TEST_BRANCH_NAME)));
+    }
+}