feature #1143 Add API endpoints to interact with organization roles (…

…glaubinix)

This PR was merged into the 3.14-dev branch.

Discussion
----------

Organization roles were [introduced in July](https://github.blog/changelog/2024-07-10-pre-defined-organization-roles-that-grant-access-to-all-repositories/) and they have partial API support already https://docs.github.com/en/rest/orgs/organization-roles

Commits
-------

1f77a93 Add API endpoints to interact with organiztion roles

doc/README.md

@@ -44,6 +44,7 @@ v3 APIs:
  * [Secrets](organization/actions/secrets.md)
  * [Variables](organization/actions/variables.md)
  * [Secret Scanning Alert](organization/secret-scanning.md)
+ * [Organization Roles](organization/organization-roles.md)
 * [Projects](project/projects.md)
  * [Columns](project/columns.md)
  * [Cards](project/cards.md)

doc/organization/organization-roles.md

@@ -0,0 +1,108 @@
+## Organization / Webhooks API
+[Back to the navigation](../README.md)
+
+Listing, showing, assigning, and removing orgniazationroles.
+Wraps [GitHub Organization Roles API](https://docs.github.com/en/rest/orgs/organization-roles).
+
+Additional APIs:
+* [Organization](../doc/organization)
+
+### List all organizaton roles in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$roles = $client->organization()->organizationRoles()->all('acme');
+```
+
+Returns a counter and a list of organization roles in the organization.
+
+### Get an organization role in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$role = $client->organization()->organizationRoles()->show('acme', 123);
+```
+
+Returns a single organization role in the organization.
+
+### List all teams with role assigned in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$users = $client->organization()->organizationRoles()->listTeamsWithRole('acme', 1);
+```
+
+Returns a list of teams with the role assigned to them.
+
+### Assign a single role to a team in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$client->organization()->organizationRoles()->assignRoleToTeam('acme', 1, 'admin-user');
+```
+
+No content is returned.
+
+### Remove a single role from a team in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$client->organization()->organizationRoles()->removeRoleFromTeam('acme', 1, 'admin-team');
+```
+
+No content is returned.
+
+### Remove all roles from a team in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$client->organization()->organizationRoles()->removeAllRolesFromTeam('acme', 'admin-team');
+```
+
+No content is returned.
+
+### List all users with role assigned in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$users = $client->organization()->organizationRoles()->listUsersWithRole('acme', 1);
+```
+
+Returns a list of users with the role assigned to them.
+
+### Assign a single role to a user in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$client->organization()->organizationRoles()->assignRoleToUser('acme', 1, 'admin-user');
+```
+
+No content is returned.
+
+### Remove a single role from a user in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$client->organization()->organizationRoles()->removeRoleFromUser('acme', 1, 'admin-user');
+```
+
+No content is returned.
+
+### Remove all roles from a user in an organization
+
+> Requires [authentication](../security.md).
+
+```php
+$client->organization()->organizationRoles()->removeAllRolesFromUser('acme', 'admin-user');
+```
+
+No content is returned.

lib/Github/Api/Organization.php

@@ -7,6 +7,7 @@
 use Github\Api\Organization\Actions\Variables;
 use Github\Api\Organization\Hooks;
 use Github\Api\Organization\Members;
+use Github\Api\Organization\OrganizationRoles;
 use Github\Api\Organization\OutsideCollaborators;
 use Github\Api\Organization\SecretScanning;
 use Github\Api\Organization\Teams;
@@ -158,4 +159,9 @@ public function secretScanning(): SecretScanning
  {
  return new SecretScanning($this->getClient());
  }
+
+ public function organizationRoles(): OrganizationRoles
+ {
+ return new OrganizationRoles($this->getClient());
+ }
 }

lib/Github/Api/Organization/OrganizationRoles.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace Github\Api\Organization;
+
+use Github\Api\AbstractApi;
+
+/**
+ * @link https://docs.github.com/en/rest/orgs/organization-roles
+ */
+class OrganizationRoles extends AbstractApi
+{
+ public function all(string $organization)
+ {
+ return $this->get('/orgs/'.rawurlencode($organization).'/organization-roles');
+ }
+
+ public function show(string $organization, int $roleId)
+ {
+ return $this->get('/orgs/'.rawurlencode($organization).'/organization-roles/'.$roleId);
+ }
+
+ public function listTeamsWithRole(string $organization, int $roleId)
+ {
+ return $this->get('/orgs/'.rawurlencode($organization).'/organization-roles/'.$roleId.'/teams');
+ }
+
+ public function assignRoleToTeam(string $organization, int $roleId, string $teamSlug): void
+ {
+ $this->put('/orgs/'.rawurlencode($organization).'/organization-roles/teams/'.rawurlencode($teamSlug).'/'.$roleId);
+ }
+
+ public function removeRoleFromTeam(string $organization, int $roleId, string $teamSlug): void
+ {
+ $this->delete('/orgs/'.rawurlencode($organization).'/organization-roles/teams/'.rawurlencode($teamSlug).'/'.$roleId);
+ }
+
+ public function removeAllRolesFromTeam(string $organization, string $teamSlug): void
+ {
+ $this->delete('/orgs/'.rawurlencode($organization).'/organization-roles/teams/'.rawurlencode($teamSlug));
+ }
+
+ public function listUsersWithRole(string $organization, int $roleId): array
+ {
+ return $this->get('/orgs/'.rawurlencode($organization).'/organization-roles/'.$roleId.'/users');
+ }
+
+ public function assignRoleToUser(string $organization, int $roleId, string $username): void
+ {
+ $this->put('/orgs/'.rawurlencode($organization).'/organization-roles/users/'.rawurlencode($username).'/'.$roleId);
+ }
+
+ public function removeRoleFromUser(string $organization, int $roleId, string $username): void
+ {
+ $this->delete('/orgs/'.rawurlencode($organization).'/organization-roles/users/'.rawurlencode($username).'/'.$roleId);
+ }
+
+ public function removeAllRolesFromUser(string $organization, string $username): void
+ {
+ $this->delete('/orgs/'.rawurlencode($organization).'/organization-roles/users/'.rawurlencode($username));
+ }
+}

test/Github/Tests/Api/Organization/OrganizationRolesTest.php

@@ -0,0 +1,187 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Github\Tests\Api\Organization;
+
+use Github\Api\Organization\OrganizationRoles;
+use Github\Tests\Api\TestCase;
+
+class OrganizationRolesTest extends TestCase
+{
+ /**
+ * @test
+ */
+ public function shouldGetAllOrganizationRoles()
+ {
+ $expectedValue = [
+ 'total_count' => 1,
+ 'roles' => [[
+ 'id' => 1,
+ 'name' => 'all_repo_admin',
+ 'description' => 'Grants admin access to all repositories in the organization.',
+ 'permissions' => [],
+ 'organization' => null,
+ 'created_at' => '2023-01-01T00:00:00Z',
+ 'updated_at' => '2023-01-01T00:00:00Z',
+ 'source' => 'Predefined',
+ 'base_role' => 'admin',
+ ]],
+ ];
+
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('get')
+ ->with('/orgs/acme/organization-roles')
+ ->will($this->returnValue($expectedValue));
+
+ $this->assertEquals($expectedValue, $api->all('acme'));
+ }
+
+ /**
+ * @test
+ */
+ public function shouldShowSingleOrganizationRole()
+ {
+ $expectedValue = [
+ 'id' => 1,
+ 'name' => 'all_repo_admin',
+ 'description' => 'Grants admin access to all repositories in the organization.',
+ 'permissions' => [],
+ 'organization' => null,
+ 'created_at' => '2023-01-01T00:00:00Z',
+ 'updated_at' => '2023-01-01T00:00:00Z',
+ 'source' => 'Predefined',
+ 'base_role' => 'admin',
+ ];
+
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('get')
+ ->with('/orgs/acme/organization-roles/1')
+ ->will($this->returnValue($expectedValue));
+
+ $this->assertEquals($expectedValue, $api->show('acme', 1));
+ }
+
+ /**
+ * @test
+ */
+ public function shouldGetAllTeamsWithRole()
+ {
+ $expectedValue = [['name' => 'Acme Admins']];
+
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('get')
+ ->with('/orgs/acme/organization-roles/1/teams')
+ ->will($this->returnValue($expectedValue));
+
+ $this->assertEquals($expectedValue, $api->listTeamsWithRole('acme', 1));
+ }
+
+ /**
+ * @test
+ */
+ public function shouldAssignRoleToTeam()
+ {
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('put')
+ ->with('/orgs/acme/organization-roles/teams/acme-admins/1')
+ ->will($this->returnValue(''));
+
+ $api->assignRoleToTeam('acme', 1, 'acme-admins');
+ }
+
+ /**
+ * @test
+ */
+ public function shouldRemoveRoleFromTeam()
+ {
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('delete')
+ ->with('/orgs/acme/organization-roles/teams/acme-admins/1')
+ ->will($this->returnValue(''));
+
+ $api->removeRoleFromTeam('acme', 1, 'acme-admins');
+ }
+
+ /**
+ * @test
+ */
+ public function shouldRemoveAllRolesFromTeam()
+ {
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('delete')
+ ->with('/orgs/acme/organization-roles/teams/acme-admins')
+ ->will($this->returnValue(''));
+
+ $api->removeAllRolesFromTeam('acme', 'acme-admins');
+ }
+
+ /**
+ * @test
+ */
+ public function shouldGetAllUsersWithRole()
+ {
+ $expectedValue = [['username' => 'Admin']];
+
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('get')
+ ->with('/orgs/acme/organization-roles/1/users')
+ ->will($this->returnValue($expectedValue));
+
+ $this->assertEquals($expectedValue, $api->listUsersWithRole('acme', 1));
+ }
+
+ /**
+ * @test
+ */
+ public function shouldAssignRoleToUser()
+ {
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('put')
+ ->with('/orgs/acme/organization-roles/users/admin/1')
+ ->will($this->returnValue(''));
+
+ $api->assignRoleToUser('acme', 1, 'admin');
+ }
+
+ /**
+ * @test
+ */
+ public function shouldRemoveRoleFromUser()
+ {
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('delete')
+ ->with('/orgs/acme/organization-roles/users/admin/1')
+ ->will($this->returnValue(''));
+
+ $api->removeRoleFromUser('acme', 1, 'admin');
+ }
+
+ /**
+ * @test
+ */
+ public function shouldRemoveAllRolesFromUser()
+ {
+ $api = $this->getApiMock();
+ $api->expects($this->once())
+ ->method('delete')
+ ->with('/orgs/acme/organization-roles/users/admin')
+ ->will($this->returnValue(''));
+
+ $api->removeAllRolesFromUser('acme', 'admin');
+ }
+
+ protected function getApiClass(): string
+ {
+ return OrganizationRoles::class;
+ }
+}