From 21c7b23c1974d348d2a923182ed260d0130af9c3 Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Thu, 12 Nov 2026 22:05:37 +0100 Subject: [PATCH] Add branch protection and branch management to Repositories\Branches Extends Repositories\Branches with rename, merge-upstream (fork sync) and all branch protection operations: protection, admin enforcement, pull request review and commit signature protection, required status checks and contexts, and app/team/user push restrictions. Adds docs/branch-protection.md. Co-Authored-By: Claude Opus 5.5 --- Tests/Package/Repositories/BranchesTest.php | 1355 +++++++++++++++++++ docs/branch-protection.md | 84 ++ src/Package/Repositories/Branches.php | 852 ++++++++++++ 3 files changed, 2291 insertions(+) create mode 100644 docs/branch-protection.md diff --git a/Tests/Package/Repositories/BranchesTest.php b/Tests/Package/Repositories/BranchesTest.php index c2b29391..487436d3 100644 --- a/Tests/Package/Repositories/BranchesTest.php +++ b/Tests/Package/Repositories/BranchesTest.php @@ -9,6 +9,8 @@ use Joomla\Github\Package\Repositories\Branches; use Joomla\Github\Tests\Stub\GitHubTestCase; +use Joomla\Http\Exception\UnexpectedResponseException; +use PHPUnit\Framework\Attributes\CoversClass; /** * Test class. @@ -17,6 +19,7 @@ * * @since 1.0 */ +#[CoversClass(Branches::class)] class BranchesTest extends GitHubTestCase { /** @@ -78,4 +81,1356 @@ public function testGet() $this->equalTo(json_decode($this->sampleString)) ); } + + /** + * Tests the rename method. + * + * @return void + */ + public function testRename() + { + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/rename', '{"new_name":"feature\\/y"}', [], 0) + ->willReturn($this->getResponseObject($this->sampleString, 201)); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->rename('joomla', 'joomla-cms', 'feature/x', 'feature/y') + ); + } + + /** + * Tests the rename method - failure. + * + * @return void + */ + public function testRenameFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/rename', '{"new_name":"feature\\/y"}', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->rename('joomla', 'joomla-cms', 'feature/x', 'feature/y'); + } + + /** + * Tests the mergeUpstream method. + * + * @return void + */ + public function testMergeUpstream() + { + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/merge-upstream', '{"branch":"4.x-dev"}', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->mergeUpstream('joomla', 'joomla-cms', '4.x-dev') + ); + } + + /** + * Tests the mergeUpstream method - failure. + * + * @return void + */ + public function testMergeUpstreamFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/merge-upstream', '{"branch":"4.x-dev"}', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->mergeUpstream('joomla', 'joomla-cms', '4.x-dev'); + } + + /** + * Tests the getProtection method. + * + * @return void + */ + public function testGetProtection() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getProtection('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getProtection method - failure. + * + * @return void + */ + public function testGetProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the editProtection method. + * + * @return void + */ + public function testEditProtection() + { + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection', + '{"allow_deletions":false,"required_status_checks":{"strict":true,"contexts":["ci"]},"enforce_admins":true,"required_pull_request_reviews":null,"restrictions":null}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->editProtection('joomla', 'joomla-cms', 'feature/x', ['strict' => true, 'contexts' => ['ci']], true, null, null, ['allow_deletions' => false]) + ); + } + + /** + * Tests the editProtection method - failure. + * + * @return void + */ + public function testEditProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection', + '{"required_status_checks":null,"enforce_admins":false,"required_pull_request_reviews":null,"restrictions":null}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->editProtection('joomla', 'joomla-cms', 'feature/x', null, false, null, null); + } + + /** + * Tests the deleteProtection method. + * + * @return void + */ + public function testDeleteProtection() + { + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection', [], 0) + ->willReturn($this->getResponseObject('', 204)); + + $this->assertNull($this->object->deleteProtection('joomla', 'joomla-cms', 'feature/x')); + } + + /** + * Tests the deleteProtection method - failure. + * + * @return void + */ + public function testDeleteProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->deleteProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the getAdminEnforcement method. + * + * @return void + */ + public function testGetAdminEnforcement() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/enforce_admins', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getAdminEnforcement('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getAdminEnforcement method - failure. + * + * @return void + */ + public function testGetAdminEnforcementFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/enforce_admins', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getAdminEnforcement('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the setAdminEnforcement method. + * + * @return void + */ + public function testSetAdminEnforcement() + { + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/enforce_admins', '', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->setAdminEnforcement('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the setAdminEnforcement method - failure. + * + * @return void + */ + public function testSetAdminEnforcementFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/enforce_admins', '', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->setAdminEnforcement('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the deleteAdminEnforcement method. + * + * @return void + */ + public function testDeleteAdminEnforcement() + { + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/enforce_admins', [], 0) + ->willReturn($this->getResponseObject('', 204)); + + $this->assertNull($this->object->deleteAdminEnforcement('joomla', 'joomla-cms', 'feature/x')); + } + + /** + * Tests the deleteAdminEnforcement method - failure. + * + * @return void + */ + public function testDeleteAdminEnforcementFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/enforce_admins', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->deleteAdminEnforcement('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the getPullRequestReviewProtection method. + * + * @return void + */ + public function testGetPullRequestReviewProtection() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_pull_request_reviews', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getPullRequestReviewProtection('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getPullRequestReviewProtection method - failure. + * + * @return void + */ + public function testGetPullRequestReviewProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_pull_request_reviews', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getPullRequestReviewProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the editPullRequestReviewProtection method. + * + * @return void + */ + public function testEditPullRequestReviewProtection() + { + $this->client->expects($this->once()) + ->method('patch') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_pull_request_reviews', + '{"required_approving_review_count":2}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->editPullRequestReviewProtection('joomla', 'joomla-cms', 'feature/x', ['required_approving_review_count' => 2]) + ); + } + + /** + * Tests the editPullRequestReviewProtection method - failure. + * + * @return void + */ + public function testEditPullRequestReviewProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('patch') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_pull_request_reviews', + '{}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->editPullRequestReviewProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the deletePullRequestReviewProtection method. + * + * @return void + */ + public function testDeletePullRequestReviewProtection() + { + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_pull_request_reviews', [], 0) + ->willReturn($this->getResponseObject('', 204)); + + $this->assertNull($this->object->deletePullRequestReviewProtection('joomla', 'joomla-cms', 'feature/x')); + } + + /** + * Tests the deletePullRequestReviewProtection method - failure. + * + * @return void + */ + public function testDeletePullRequestReviewProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_pull_request_reviews', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->deletePullRequestReviewProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the getCommitSignatureProtection method. + * + * @return void + */ + public function testGetCommitSignatureProtection() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_signatures', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getCommitSignatureProtection('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getCommitSignatureProtection method - failure. + * + * @return void + */ + public function testGetCommitSignatureProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_signatures', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getCommitSignatureProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the createCommitSignatureProtection method. + * + * @return void + */ + public function testCreateCommitSignatureProtection() + { + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_signatures', '', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->createCommitSignatureProtection('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the createCommitSignatureProtection method - failure. + * + * @return void + */ + public function testCreateCommitSignatureProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_signatures', '', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->createCommitSignatureProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the deleteCommitSignatureProtection method. + * + * @return void + */ + public function testDeleteCommitSignatureProtection() + { + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_signatures', [], 0) + ->willReturn($this->getResponseObject('', 204)); + + $this->assertNull($this->object->deleteCommitSignatureProtection('joomla', 'joomla-cms', 'feature/x')); + } + + /** + * Tests the deleteCommitSignatureProtection method - failure. + * + * @return void + */ + public function testDeleteCommitSignatureProtectionFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_signatures', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->deleteCommitSignatureProtection('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the getRequiredStatusChecks method. + * + * @return void + */ + public function testGetRequiredStatusChecks() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getRequiredStatusChecks('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getRequiredStatusChecks method - failure. + * + * @return void + */ + public function testGetRequiredStatusChecksFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getRequiredStatusChecks('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the editRequiredStatusChecks method. + * + * @return void + */ + public function testEditRequiredStatusChecks() + { + $this->client->expects($this->once()) + ->method('patch') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks', + '{"strict":true}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->editRequiredStatusChecks('joomla', 'joomla-cms', 'feature/x', ['strict' => true]) + ); + } + + /** + * Tests the editRequiredStatusChecks method - failure. + * + * @return void + */ + public function testEditRequiredStatusChecksFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('patch') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks', '{}', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->editRequiredStatusChecks('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the removeRequiredStatusChecks method. + * + * @return void + */ + public function testRemoveRequiredStatusChecks() + { + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks', [], 0) + ->willReturn($this->getResponseObject('', 204)); + + $this->assertNull($this->object->removeRequiredStatusChecks('joomla', 'joomla-cms', 'feature/x')); + } + + /** + * Tests the removeRequiredStatusChecks method - failure. + * + * @return void + */ + public function testRemoveRequiredStatusChecksFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->removeRequiredStatusChecks('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the getStatusCheckContexts method. + * + * @return void + */ + public function testGetStatusCheckContexts() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getStatusCheckContexts('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getStatusCheckContexts method - failure. + * + * @return void + */ + public function testGetStatusCheckContextsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getStatusCheckContexts('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the addStatusCheckContexts method. + * + * @return void + */ + public function testAddStatusCheckContexts() + { + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', + '{"contexts":["ci","lint"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->addStatusCheckContexts('joomla', 'joomla-cms', 'feature/x', ['ci', 'lint']) + ); + } + + /** + * Tests the addStatusCheckContexts method - failure. + * + * @return void + */ + public function testAddStatusCheckContextsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', + '{"contexts":["ci","lint"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->addStatusCheckContexts('joomla', 'joomla-cms', 'feature/x', ['ci', 'lint']); + } + + /** + * Tests the setStatusCheckContexts method. + * + * @return void + */ + public function testSetStatusCheckContexts() + { + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', + '{"contexts":["ci","lint"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->setStatusCheckContexts('joomla', 'joomla-cms', 'feature/x', ['ci', 'lint']) + ); + } + + /** + * Tests the setStatusCheckContexts method - failure. + * + * @return void + */ + public function testSetStatusCheckContextsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', + '{"contexts":["ci","lint"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->setStatusCheckContexts('joomla', 'joomla-cms', 'feature/x', ['ci', 'lint']); + } + + /** + * Tests the removeStatusCheckContexts method. + * + * @return void + */ + public function testRemoveStatusCheckContexts() + { + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', + [], + null, + '{"contexts":["ci","lint"]}' + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->removeStatusCheckContexts('joomla', 'joomla-cms', 'feature/x', ['ci', 'lint']) + ); + } + + /** + * Tests the removeStatusCheckContexts method - failure. + * + * @return void + */ + public function testRemoveStatusCheckContextsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/required_status_checks/contexts', + [], + null, + '{"contexts":["ci","lint"]}' + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->removeStatusCheckContexts('joomla', 'joomla-cms', 'feature/x', ['ci', 'lint']); + } + + /** + * Tests the getAccessRestrictions method. + * + * @return void + */ + public function testGetAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getAccessRestrictions('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getAccessRestrictions method - failure. + * + * @return void + */ + public function testGetAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getAccessRestrictions('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the deleteAccessRestrictions method. + * + * @return void + */ + public function testDeleteAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions', [], 0) + ->willReturn($this->getResponseObject('', 204)); + + $this->assertNull($this->object->deleteAccessRestrictions('joomla', 'joomla-cms', 'feature/x')); + } + + /** + * Tests the deleteAccessRestrictions method - failure. + * + * @return void + */ + public function testDeleteAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->deleteAccessRestrictions('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the getAppAccessRestrictions method. + * + * @return void + */ + public function testGetAppAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getAppAccessRestrictions method - failure. + * + * @return void + */ + public function testGetAppAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the addAppAccessRestrictions method. + * + * @return void + */ + public function testAddAppAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', + '{"apps":["octoapp"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->addAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octoapp']) + ); + } + + /** + * Tests the addAppAccessRestrictions method - failure. + * + * @return void + */ + public function testAddAppAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', + '{"apps":["octoapp"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->addAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octoapp']); + } + + /** + * Tests the setAppAccessRestrictions method. + * + * @return void + */ + public function testSetAppAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', + '{"apps":["octoapp"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->setAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octoapp']) + ); + } + + /** + * Tests the setAppAccessRestrictions method - failure. + * + * @return void + */ + public function testSetAppAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', + '{"apps":["octoapp"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->setAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octoapp']); + } + + /** + * Tests the removeAppAccessRestrictions method. + * + * @return void + */ + public function testRemoveAppAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', + [], + null, + '{"apps":["octoapp"]}' + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->removeAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octoapp']) + ); + } + + /** + * Tests the removeAppAccessRestrictions method - failure. + * + * @return void + */ + public function testRemoveAppAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/apps', + [], + null, + '{"apps":["octoapp"]}' + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->removeAppAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octoapp']); + } + + /** + * Tests the getTeamAccessRestrictions method. + * + * @return void + */ + public function testGetTeamAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getTeamAccessRestrictions method - failure. + * + * @return void + */ + public function testGetTeamAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the addTeamAccessRestrictions method. + * + * @return void + */ + public function testAddTeamAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', + '{"teams":["justice-league"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->addTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['justice-league']) + ); + } + + /** + * Tests the addTeamAccessRestrictions method - failure. + * + * @return void + */ + public function testAddTeamAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', + '{"teams":["justice-league"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->addTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['justice-league']); + } + + /** + * Tests the setTeamAccessRestrictions method. + * + * @return void + */ + public function testSetTeamAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', + '{"teams":["justice-league"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->setTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['justice-league']) + ); + } + + /** + * Tests the setTeamAccessRestrictions method - failure. + * + * @return void + */ + public function testSetTeamAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', + '{"teams":["justice-league"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->setTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['justice-league']); + } + + /** + * Tests the removeTeamAccessRestrictions method. + * + * @return void + */ + public function testRemoveTeamAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', + [], + null, + '{"teams":["justice-league"]}' + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->removeTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['justice-league']) + ); + } + + /** + * Tests the removeTeamAccessRestrictions method - failure. + * + * @return void + */ + public function testRemoveTeamAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/teams', + [], + null, + '{"teams":["justice-league"]}' + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->removeTeamAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['justice-league']); + } + + /** + * Tests the getUserAccessRestrictions method. + * + * @return void + */ + public function testGetUserAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x') + ); + } + + /** + * Tests the getUserAccessRestrictions method - failure. + * + * @return void + */ + public function testGetUserAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', [], 0) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->getUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x'); + } + + /** + * Tests the addUserAccessRestrictions method. + * + * @return void + */ + public function testAddUserAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', + '{"users":["octocat"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->addUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octocat']) + ); + } + + /** + * Tests the addUserAccessRestrictions method - failure. + * + * @return void + */ + public function testAddUserAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('post') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', + '{"users":["octocat"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->addUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octocat']); + } + + /** + * Tests the setUserAccessRestrictions method. + * + * @return void + */ + public function testSetUserAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', + '{"users":["octocat"]}', + [], + 0 + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->setUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octocat']) + ); + } + + /** + * Tests the setUserAccessRestrictions method - failure. + * + * @return void + */ + public function testSetUserAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('put') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', + '{"users":["octocat"]}', + [], + 0 + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->setUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octocat']); + } + + /** + * Tests the removeUserAccessRestrictions method. + * + * @return void + */ + public function testRemoveUserAccessRestrictions() + { + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', + [], + null, + '{"users":["octocat"]}' + ) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->removeUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octocat']) + ); + } + + /** + * Tests the removeUserAccessRestrictions method - failure. + * + * @return void + */ + public function testRemoveUserAccessRestrictionsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->client->expects($this->once()) + ->method('delete') + ->with( + '/repos/joomla/joomla-cms/branches/feature%2Fx/protection/restrictions/users', + [], + null, + '{"users":["octocat"]}' + ) + ->willReturn($this->getResponseObject($this->errorString, 500)); + + $this->object->removeUserAccessRestrictions('joomla', 'joomla-cms', 'feature/x', ['octocat']); + } } diff --git a/docs/branch-protection.md b/docs/branch-protection.md new file mode 100644 index 00000000..9247f443 --- /dev/null +++ b/docs/branch-protection.md @@ -0,0 +1,84 @@ +# Branches and Branch Protection + +The `Repositories\Branches` package covers the [branches](https://docs.github.com/rest/branches/branches) and +[branch protection](https://docs.github.com/rest/branches/branch-protection) endpoints of the GitHub REST API. It is +reached as `$github->repositories->branches`, for example +`$github->repositories->branches->getProtection('joomla', 'joomla-cms', '5.4-dev')`. + +```php +use Joomla\Github\Github; + +$github = new Github($options); + +// Require one approving review and a passing "ci" check, for administrators too; no push restrictions. +$github->repositories->branches->editProtection( + 'joomla', + 'joomla-cms', + '5.4-dev', + ['strict' => true, 'contexts' => ['ci']], + true, + ['required_approving_review_count' => 1], + null, + ['allow_force_pushes' => false] +); + +// Add another required status check. +$github->repositories->branches->addStatusCheckContexts('joomla', 'joomla-cms', '5.4-dev', ['lint']); +``` + +`$options` holds optional request-body fields. Required fields are explicit parameters and win over `$options`. The +branch name is URL-encoded in the new methods, so names such as `feature/x` work as they are. + +## Repositories\Branches + +| Method | Endpoint | +|--------|----------| +| getList($owner, $repo) | GET /repos/{owner}/{repo}/branches | +| get($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch} | +| rename($owner, $repo, $branch, $newName) | POST /repos/{owner}/{repo}/branches/{branch}/rename | +| mergeUpstream($owner, $repo, $branch) | POST /repos/{owner}/{repo}/merge-upstream | +| getProtection($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection | +| editProtection($owner, $repo, $branch, $requiredStatusChecks, $enforceAdmins, $requiredPullRequestReviews, $restrictions, $options) | PUT /repos/{owner}/{repo}/branches/{branch}/protection | +| deleteProtection($owner, $repo, $branch) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection | +| getAdminEnforcement($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins | +| setAdminEnforcement($owner, $repo, $branch) | POST /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins | +| deleteAdminEnforcement($owner, $repo, $branch) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/enforce_admins | +| getPullRequestReviewProtection($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews | +| editPullRequestReviewProtection($owner, $repo, $branch, $options) | PATCH /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews | +| deletePullRequestReviewProtection($owner, $repo, $branch) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_pull_request_reviews | +| getCommitSignatureProtection($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures | +| createCommitSignatureProtection($owner, $repo, $branch) | POST /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures | +| deleteCommitSignatureProtection($owner, $repo, $branch) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_signatures | +| getRequiredStatusChecks($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks | +| editRequiredStatusChecks($owner, $repo, $branch, $options) | PATCH /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks | +| removeRequiredStatusChecks($owner, $repo, $branch) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks | +| getStatusCheckContexts($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts | +| addStatusCheckContexts($owner, $repo, $branch, $contexts) | POST /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts | +| setStatusCheckContexts($owner, $repo, $branch, $contexts) | PUT /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts | +| removeStatusCheckContexts($owner, $repo, $branch, $contexts) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/required_status_checks/contexts | +| getAccessRestrictions($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions | +| deleteAccessRestrictions($owner, $repo, $branch) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions | +| getAppAccessRestrictions($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps | +| addAppAccessRestrictions($owner, $repo, $branch, $apps) | POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps | +| setAppAccessRestrictions($owner, $repo, $branch, $apps) | PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps | +| removeAppAccessRestrictions($owner, $repo, $branch, $apps) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/apps | +| getTeamAccessRestrictions($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams | +| addTeamAccessRestrictions($owner, $repo, $branch, $teams) | POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams | +| setTeamAccessRestrictions($owner, $repo, $branch, $teams) | PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams | +| removeTeamAccessRestrictions($owner, $repo, $branch, $teams) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/teams | +| getUserAccessRestrictions($owner, $repo, $branch) | GET /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users | +| addUserAccessRestrictions($owner, $repo, $branch, $users) | POST /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users | +| setUserAccessRestrictions($owner, $repo, $branch, $users) | PUT /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users | +| removeUserAccessRestrictions($owner, $repo, $branch, $users) | DELETE /repos/{owner}/{repo}/branches/{branch}/protection/restrictions/users | + +`editProtection()` replaces the whole protection. The API always needs the four settings `required_status_checks`, +`enforce_admins`, `required_pull_request_reviews` and `restrictions`; pass `null` to turn one of them off. + +## Left out + +- `POST /repos/{owner}/{repo}/merges` (merge a branch) is already available as + `$github->repositories->merging->perform()`. +- `getList()` and `get()` are unchanged from earlier versions: `getList()` does not take the `protected` filter or + pagination, and `get()` does not URL-encode the branch name. +- The status-check-contexts and team-restrictions endpoints also accept a bare JSON array as body; the methods always + send the documented object form (`{"contexts": [...]}`, `{"teams": [...]}`). diff --git a/src/Package/Repositories/Branches.php b/src/Package/Repositories/Branches.php index ce6ab844..70f254e0 100644 --- a/src/Package/Repositories/Branches.php +++ b/src/Package/Repositories/Branches.php @@ -10,6 +10,7 @@ namespace Joomla\Github\Package\Repositories; use Joomla\Github\AbstractPackage; +use Joomla\Http\Exception\UnexpectedResponseException; /** * GitHub API Repositories Branches class for the Joomla Framework. @@ -62,4 +63,855 @@ public function get($owner, $repo, $branch) $this->client->get($this->fetchUrl($path)) ); } + + /** + * Rename a branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch The current name of the branch. + * @param string $newName The new name of the branch. + * + * @return object The renamed branch. + * + * @link https://docs.github.com/rest/branches/branches#rename-a-branch + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function rename(string $owner, string $repo, string $branch, string $newName) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/branches/' . rawurlencode($branch) . '/rename'; + + // Send the request. + return $this->processResponse( + $this->client->post($this->fetchUrl($path), json_encode(['new_name' => $newName])), + 201 + ); + } + + /** + * Sync a branch of a forked repository with the upstream repository. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch The name of the branch to update. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branches#sync-a-fork-branch-with-the-upstream-repository + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function mergeUpstream(string $owner, string $repo, string $branch) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/merge-upstream'; + + // Send the request. + return $this->processResponse( + $this->client->post($this->fetchUrl($path), json_encode(['branch' => $branch])), + 200 + ); + } + + /** + * Get branch protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#get-branch-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getProtection(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->protectionPath($owner, $repo, $branch))), + 200 + ); + } + + /** + * Update (replace) branch protection. + * + * The four required settings must always be sent; pass null to disable one of them. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array|null $requiredStatusChecks Required status checks (keys: strict, contexts, checks) or null. + * @param boolean $enforceAdmins Enforce all configured restrictions for administrators. + * @param array|null $requiredPullRequestReviews Pull request review settings (keys: dismissal_restrictions, + * dismiss_stale_reviews, require_code_owner_reviews, + * required_approving_review_count, require_last_push_approval, + * bypass_pull_request_allowances) or null. + * @param array|null $restrictions Push restrictions (keys: users, teams, apps) or null. + * @param array $options Optional body fields: required_linear_history, allow_force_pushes, + * allow_deletions, block_creations, + * required_conversation_resolution, lock_branch, allow_fork_syncing. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#update-branch-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function editProtection( + string $owner, + string $repo, + string $branch, + ?array $requiredStatusChecks, + bool $enforceAdmins, + ?array $requiredPullRequestReviews, + ?array $restrictions, + array $options = [] + ) { + $data = array_merge( + $options, + [ + 'required_status_checks' => $requiredStatusChecks, + 'enforce_admins' => $enforceAdmins, + 'required_pull_request_reviews' => $requiredPullRequestReviews, + 'restrictions' => $restrictions, + ] + ); + + return $this->processResponse( + $this->client->put($this->fetchUrl($this->protectionPath($owner, $repo, $branch)), json_encode($data)), + 200 + ); + } + + /** + * Delete branch protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return void + * + * @link https://docs.github.com/rest/branches/branch-protection#delete-branch-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deleteProtection(string $owner, string $repo, string $branch) + { + $this->processResponse( + $this->client->delete($this->fetchUrl($this->protectionPath($owner, $repo, $branch))), + 204 + ); + } + + /** + * Get admin branch protection (whether the protection is enforced for administrators). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#get-admin-branch-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getAdminEnforcement(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/enforce_admins'))), + 200 + ); + } + + /** + * Set admin branch protection (enforce the protection for administrators). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#set-admin-branch-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function setAdminEnforcement(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->post($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/enforce_admins')), ''), + 200 + ); + } + + /** + * Delete admin branch protection (stop enforcing the protection for administrators). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return void + * + * @link https://docs.github.com/rest/branches/branch-protection#delete-admin-branch-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deleteAdminEnforcement(string $owner, string $repo, string $branch) + { + $this->processResponse( + $this->client->delete($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/enforce_admins'))), + 204 + ); + } + + /** + * Get pull request review protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#get-pull-request-review-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getPullRequestReviewProtection(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_pull_request_reviews')) + ), + 200 + ); + } + + /** + * Update pull request review protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $options Optional body fields: dismissal_restrictions, dismiss_stale_reviews, + * require_code_owner_reviews, required_approving_review_count, + * require_last_push_approval, bypass_pull_request_allowances. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#update-pull-request-review-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function editPullRequestReviewProtection(string $owner, string $repo, string $branch, array $options = []) + { + $data = (object) $options; + + return $this->processResponse( + $this->client->patch( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_pull_request_reviews')), + json_encode($data) + ), + 200 + ); + } + + /** + * Delete pull request review protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return void + * + * @link https://docs.github.com/rest/branches/branch-protection#delete-pull-request-review-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deletePullRequestReviewProtection(string $owner, string $repo, string $branch) + { + $this->processResponse( + $this->client->delete( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_pull_request_reviews')) + ), + 204 + ); + } + + /** + * Get commit signature protection (whether signed commits are required). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#get-commit-signature-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getCommitSignatureProtection(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_signatures'))), + 200 + ); + } + + /** + * Create commit signature protection (require signed commits). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#create-commit-signature-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function createCommitSignatureProtection(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->post( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_signatures')), + '' + ), + 200 + ); + } + + /** + * Delete commit signature protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return void + * + * @link https://docs.github.com/rest/branches/branch-protection#delete-commit-signature-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deleteCommitSignatureProtection(string $owner, string $repo, string $branch) + { + $this->processResponse( + $this->client->delete($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_signatures'))), + 204 + ); + } + + /** + * Get status checks protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#get-status-checks-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getRequiredStatusChecks(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks'))), + 200 + ); + } + + /** + * Update status check protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $options Optional body fields: strict, contexts, checks. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#update-status-check-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function editRequiredStatusChecks(string $owner, string $repo, string $branch, array $options = []) + { + $data = (object) $options; + + return $this->processResponse( + $this->client->patch( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks')), + json_encode($data) + ), + 200 + ); + } + + /** + * Remove status check protection. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return void + * + * @link https://docs.github.com/rest/branches/branch-protection#remove-status-check-protection + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function removeRequiredStatusChecks(string $owner, string $repo, string $branch) + { + $this->processResponse( + $this->client->delete($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks'))), + 204 + ); + } + + /** + * Get all status check contexts. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return array List of context names. + * + * @link https://docs.github.com/rest/branches/branch-protection#get-all-status-check-contexts + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getStatusCheckContexts(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks/contexts')) + ), + 200 + ); + } + + /** + * Add status check contexts. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $contexts The names of the status checks to add. + * + * @return array List of context names. + * + * @link https://docs.github.com/rest/branches/branch-protection#add-status-check-contexts + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function addStatusCheckContexts(string $owner, string $repo, string $branch, array $contexts) + { + return $this->processResponse( + $this->client->post( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks/contexts')), + json_encode(['contexts' => $contexts]) + ), + 200 + ); + } + + /** + * Set (replace) status check contexts. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $contexts The names of the status checks. + * + * @return array List of context names. + * + * @link https://docs.github.com/rest/branches/branch-protection#set-status-check-contexts + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function setStatusCheckContexts(string $owner, string $repo, string $branch, array $contexts) + { + return $this->processResponse( + $this->client->put( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks/contexts')), + json_encode(['contexts' => $contexts]) + ), + 200 + ); + } + + /** + * Remove status check contexts. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $contexts The names of the status checks to remove. + * + * @return array List of the remaining context names. + * + * @link https://docs.github.com/rest/branches/branch-protection#remove-status-check-contexts + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function removeStatusCheckContexts(string $owner, string $repo, string $branch, array $contexts) + { + return $this->processResponse( + $this->client->delete( + $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/required_status_checks/contexts')), + [], + null, + json_encode(['contexts' => $contexts]) + ), + 200 + ); + } + + /** + * Get access restrictions (who may push to the branch). + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return object + * + * @link https://docs.github.com/rest/branches/branch-protection#get-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getAccessRestrictions(string $owner, string $repo, string $branch) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/restrictions'))), + 200 + ); + } + + /** + * Delete access restrictions. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return void + * + * @link https://docs.github.com/rest/branches/branch-protection#delete-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function deleteAccessRestrictions(string $owner, string $repo, string $branch) + { + $this->processResponse( + $this->client->delete($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/restrictions'))), + 204 + ); + } + + /** + * Get the GitHub Apps with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#get-apps-with-access-to-the-protected-branch + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getAppAccessRestrictions(string $owner, string $repo, string $branch) + { + return $this->getRestrictions($owner, $repo, $branch, 'apps'); + } + + /** + * Grant GitHub Apps push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $apps The slugs of the GitHub Apps. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#add-app-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function addAppAccessRestrictions(string $owner, string $repo, string $branch, array $apps) + { + return $this->changeRestrictions('post', $owner, $repo, $branch, 'apps', $apps); + } + + /** + * Replace the GitHub Apps with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $apps The slugs of the GitHub Apps. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#set-app-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function setAppAccessRestrictions(string $owner, string $repo, string $branch, array $apps) + { + return $this->changeRestrictions('put', $owner, $repo, $branch, 'apps', $apps); + } + + /** + * Remove push access to the protected branch from GitHub Apps. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $apps The slugs of the GitHub Apps. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#remove-app-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function removeAppAccessRestrictions(string $owner, string $repo, string $branch, array $apps) + { + return $this->changeRestrictions('delete', $owner, $repo, $branch, 'apps', $apps); + } + + /** + * Get the teams with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#get-teams-with-access-to-the-protected-branch + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getTeamAccessRestrictions(string $owner, string $repo, string $branch) + { + return $this->getRestrictions($owner, $repo, $branch, 'teams'); + } + + /** + * Grant teams push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $teams The slugs of the teams. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#add-team-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function addTeamAccessRestrictions(string $owner, string $repo, string $branch, array $teams) + { + return $this->changeRestrictions('post', $owner, $repo, $branch, 'teams', $teams); + } + + /** + * Replace the teams with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $teams The slugs of the teams. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#set-team-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function setTeamAccessRestrictions(string $owner, string $repo, string $branch, array $teams) + { + return $this->changeRestrictions('put', $owner, $repo, $branch, 'teams', $teams); + } + + /** + * Remove push access to the protected branch from teams. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $teams The slugs of the teams. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#remove-team-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function removeTeamAccessRestrictions(string $owner, string $repo, string $branch, array $teams) + { + return $this->changeRestrictions('delete', $owner, $repo, $branch, 'teams', $teams); + } + + /** + * Get the users with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#get-users-with-access-to-the-protected-branch + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getUserAccessRestrictions(string $owner, string $repo, string $branch) + { + return $this->getRestrictions($owner, $repo, $branch, 'users'); + } + + /** + * Grant users push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $users The user logins. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#add-user-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function addUserAccessRestrictions(string $owner, string $repo, string $branch, array $users) + { + return $this->changeRestrictions('post', $owner, $repo, $branch, 'users', $users); + } + + /** + * Replace the users with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $users The user logins. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#set-user-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function setUserAccessRestrictions(string $owner, string $repo, string $branch, array $users) + { + return $this->changeRestrictions('put', $owner, $repo, $branch, 'users', $users); + } + + /** + * Remove push access to the protected branch from users. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param array $users The user logins. + * + * @return array + * + * @link https://docs.github.com/rest/branches/branch-protection#remove-user-access-restrictions + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function removeUserAccessRestrictions(string $owner, string $repo, string $branch, array $users) + { + return $this->changeRestrictions('delete', $owner, $repo, $branch, 'users', $users); + } + + /** + * Build the path of a branch protection resource. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param string $suffix Path below `/protection`, starting with a slash. + * + * @return string + * + * @since __DEPLOY_VERSION__ + */ + private function protectionPath(string $owner, string $repo, string $branch, string $suffix = ''): string + { + return '/repos/' . $owner . '/' . $repo . '/branches/' . rawurlencode($branch) . '/protection' . $suffix; + } + + /** + * Get the apps, teams or users with push access to the protected branch. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param string $type One of apps, teams, users. + * + * @return array + * + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + private function getRestrictions(string $owner, string $repo, string $branch, string $type) + { + return $this->processResponse( + $this->client->get($this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/restrictions/' . $type))), + 200 + ); + } + + /** + * Add, set or remove apps, teams or users with push access to the protected branch. + * + * @param string $method The HTTP method: post (add), put (set) or delete (remove). + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $branch Branch name. + * @param string $type One of apps, teams, users (also the name of the body field). + * @param array $items App slugs, team slugs or user logins. + * + * @return array + * + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + private function changeRestrictions(string $method, string $owner, string $repo, string $branch, string $type, array $items) + { + $url = $this->fetchUrl($this->protectionPath($owner, $repo, $branch, '/restrictions/' . $type)); + $body = json_encode([$type => $items]); + + if ($method === 'delete') { + $response = $this->client->delete($url, [], null, $body); + } else { + $response = $this->client->$method($url, $body); + } + + return $this->processResponse($response, 200); + } }