Add enable_merge_pipeline_check() to enforce pipelines-must-succeed via API

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: Jonathan Mucha

instructions/gitlab-commit-status/uat.md

@@ -39,8 +39,16 @@
 1. Run: `socketcli --scm github --enable-commit-status`
 2. **Expected**: Flag is accepted but commit status is not posted (GitHub not yet supported)
 
-## Configuring Protected Branch Requirement
-1. Go to **Settings > Repository > Protected branches**
-2. Edit the target branch
-3. Under **Status checks**, add `socket-security` as a required external status check
-4. MRs targeting that branch will now require Socket's `success` status to merge
+## Blocking Merges on Failure
+
+### Option A: Pipelines must succeed (all GitLab tiers)
+Since `socketcli` exits with code 1 when blocking alerts are found, the pipeline fails automatically.
+1. Go to **Settings > General > Merge requests**
+2. Under **Merge checks**, enable **"Pipelines must succeed"**
+3. Save — GitLab will now prevent merging when the pipeline fails
+
+### Option B: External status checks (GitLab Ultimate only)
+Use the `socket-security` commit status as a required external check.
+1. Go to **Settings > General > Merge requests > Status checks**
+2. Add an external status check with name `socket-security`
+3. MRs will require Socket's `success` status to merge

socketsecurity/core/scm/gitlab.py

@@ -267,6 +267,32 @@ def add_socket_comments(
                 log.debug("No Previous version of Security Issue comment, posting")
                 self.post_comment(security_comment)
 
+    def enable_merge_pipeline_check(self) -> None:
+        """Enable 'only_allow_merge_if_pipeline_succeeds' on the MR target project."""
+        if not self.config.mr_project_id:
+            return
+        url = f"{self.config.api_url}/projects/{self.config.mr_project_id}"
+        try:
+            resp = requests.put(
+                url,
+                json={"only_allow_merge_if_pipeline_succeeds": True},
+                headers=self.config.headers,
+            )
+            if resp.status_code == 401:
+                fallback = self._get_fallback_headers(self.config.headers)
+                if fallback:
+                    resp = requests.put(
+                        url,
+                        json={"only_allow_merge_if_pipeline_succeeds": True},
+                        headers=fallback,
+                    )
+            if resp.status_code >= 400:
+                log.error(f"GitLab enable merge check API {resp.status_code}: {resp.text}")
+            else:
+                log.info("Enabled 'pipelines must succeed' merge check on project")
+        except Exception as e:
+            log.error(f"Failed to enable merge pipeline check: {e}")
+
     def set_commit_status(self, state: str, description: str, target_url: str = '') -> None:
         """Post a commit status to GitLab. state should be 'success' or 'failed'.
 

socketsecurity/socketcli.py

@@ -645,6 +645,7 @@ def main_code():
     if config.enable_commit_status and scm is not None:
         from socketsecurity.core.scm.gitlab import Gitlab
         if isinstance(scm, Gitlab) and scm.config.mr_project_id:
+            scm.enable_merge_pipeline_check()
             passed = output_handler.report_pass(diff)
             state = "success" if passed else "failed"
             blocking_count = sum(1 for a in diff.new_alerts if a.error)

tests/unit/test_gitlab_commit_status.py

@@ -43,7 +43,7 @@ def test_calls_correct_url_and_json_payload(self, mock_post):
             "https://gitlab.example.com/api/v4/projects/99/statuses/abc123def456",
             json={
                 "state": "success",
-                "context": "socket-security",
+                "context": "socket-security-commit-status",
                 "description": "No blocking issues",
                 "ref": "feature",
                 "target_url": "https://app.socket.dev/report/123",
@@ -111,6 +111,57 @@ def test_auth_fallback_on_401(self, mock_post):
         assert "PRIVATE-TOKEN" in fallback_headers
 
 
+class TestEnableMergePipelineCheck:
+    """Test Gitlab.enable_merge_pipeline_check()"""
+
+    @patch("socketsecurity.core.scm.gitlab.requests.put")
+    def test_calls_correct_url_and_payload(self, mock_put):
+        mock_put.return_value = MagicMock(status_code=200)
+        config = _make_gitlab_config()
+        gl = Gitlab(client=MagicMock(), config=config)
+
+        gl.enable_merge_pipeline_check()
+
+        mock_put.assert_called_once_with(
+            "https://gitlab.example.com/api/v4/projects/99",
+            json={"only_allow_merge_if_pipeline_succeeds": True},
+            headers=config.headers,
+        )
+
+    @patch("socketsecurity.core.scm.gitlab.requests.put")
+    def test_skipped_when_no_mr_project_id(self, mock_put):
+        config = _make_gitlab_config(mr_project_id=None)
+        gl = Gitlab(client=MagicMock(), config=config)
+
+        gl.enable_merge_pipeline_check()
+
+        mock_put.assert_not_called()
+
+    @patch("socketsecurity.core.scm.gitlab.requests.put")
+    def test_auth_fallback_on_401(self, mock_put):
+        resp_401 = MagicMock(status_code=401)
+        resp_200 = MagicMock(status_code=200)
+        mock_put.side_effect = [resp_401, resp_200]
+
+        config = _make_gitlab_config()
+        gl = Gitlab(client=MagicMock(), config=config)
+
+        gl.enable_merge_pipeline_check()
+
+        assert mock_put.call_count == 2
+        fallback_headers = mock_put.call_args_list[1].kwargs["headers"]
+        assert "PRIVATE-TOKEN" in fallback_headers
+
+    @patch("socketsecurity.core.scm.gitlab.requests.put")
+    def test_graceful_error_handling(self, mock_put):
+        mock_put.side_effect = Exception("connection error")
+        config = _make_gitlab_config()
+        gl = Gitlab(client=MagicMock(), config=config)
+
+        # Should not raise
+        gl.enable_merge_pipeline_check()
+
+
 class TestEnableCommitStatusCliArg:
     """Test --enable-commit-status CLI argument parsing"""