From b8a13f0223d62b34ccebcc2c670f47fcaf93e160 Mon Sep 17 00:00:00 2001 From: Hannes Papenberg Date: Thu, 12 Nov 2026 22:04:04 +0100 Subject: [PATCH] Add the Checks API package Adds Joomla\Github\Package\Checks ($github->checks) with the sub-packages Checks\Runs and Checks\Suites, covering all 12 operations of the GitHub REST checks category (check runs, annotations, check suites and their preferences). Co-Authored-By: Claude Opus 5.5 --- Tests/Package/Checks/RunsTest.php | 298 ++++++++++++++++++++++++++++ Tests/Package/Checks/SuitesTest.php | 245 +++++++++++++++++++++++ Tests/Package/ChecksTest.php | 59 ++++++ docs/checks.md | 59 ++++++ src/Package/Checks.php | 26 +++ src/Package/Checks/Runs.php | 199 +++++++++++++++++++ src/Package/Checks/Suites.php | 148 ++++++++++++++ 7 files changed, 1034 insertions(+) create mode 100644 Tests/Package/Checks/RunsTest.php create mode 100644 Tests/Package/Checks/SuitesTest.php create mode 100644 Tests/Package/ChecksTest.php create mode 100644 docs/checks.md create mode 100644 src/Package/Checks.php create mode 100644 src/Package/Checks/Runs.php create mode 100644 src/Package/Checks/Suites.php diff --git a/Tests/Package/Checks/RunsTest.php b/Tests/Package/Checks/RunsTest.php new file mode 100644 index 00000000..d1ea227d --- /dev/null +++ b/Tests/Package/Checks/RunsTest.php @@ -0,0 +1,298 @@ +object = new Runs($this->options, $this->client); + } + + /** + * Tests the create method. + * + * @return void + */ + public function testCreate() + { + $this->response = $this->getResponseObject($this->sampleString, 201); + $body = '{"status":"in_progress","name":"code-coverage","head_sha":"ce587453ced02b1526dfb4cb910479d431683101"}'; + + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-platform/check-runs', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->create('joomla', 'joomla-platform', 'code-coverage', 'ce587453ced02b1526dfb4cb910479d431683101', ['status' => 'in_progress']) + ); + } + + /** + * Tests the create method - failure. + * + * @return void + */ + public function testCreateFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->create('joomla', 'joomla-platform', 'code-coverage', 'ce587453ced02b1526dfb4cb910479d431683101', ['status' => 'in_progress']); + } + + /** + * Tests the get method. + * + * @return void + */ + public function testGet() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/check-runs/4', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->get('joomla', 'joomla-platform', 4) + ); + } + + /** + * Tests the get method - failure. + * + * @return void + */ + public function testGetFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->get('joomla', 'joomla-platform', 4); + } + + /** + * Tests the edit method. + * + * @return void + */ + public function testEdit() + { + $body = '{"status":"completed","conclusion":"success"}'; + + $this->client->expects($this->once()) + ->method('patch') + ->with('/repos/joomla/joomla-platform/check-runs/4', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->edit('joomla', 'joomla-platform', 4, ['status' => 'completed', 'conclusion' => 'success']) + ); + } + + /** + * Tests the edit method - failure. + * + * @return void + */ + public function testEditFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('patch') + ->willReturn($this->response); + + $this->object->edit('joomla', 'joomla-platform', 4, ['status' => 'completed', 'conclusion' => 'success']); + } + + /** + * Tests the getListAnnotations method. + * + * @return void + */ + public function testGetListAnnotations() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/check-runs/4/annotations?page=2&per_page=10', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListAnnotations('joomla', 'joomla-platform', 4, 2, 10) + ); + } + + /** + * Tests the getListAnnotations method - failure. + * + * @return void + */ + public function testGetListAnnotationsFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListAnnotations('joomla', 'joomla-platform', 4, 2, 10); + } + + /** + * Tests the rerequest method. + * + * @return void + */ + public function testRerequest() + { + $this->response = $this->getResponseObject($this->sampleString, 201); + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-platform/check-runs/4/rerequest', '', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->rerequest('joomla', 'joomla-platform', 4) + ); + } + + /** + * Tests the rerequest method - failure. + * + * @return void + */ + public function testRerequestFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->rerequest('joomla', 'joomla-platform', 4); + } + + /** + * Tests the getListForSuite method. + * + * @return void + */ + public function testGetListForSuite() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/check-suites/5/check-runs?page=2&per_page=10&status=completed', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListForSuite('joomla', 'joomla-platform', 5, ['status' => 'completed'], 2, 10) + ); + } + + /** + * Tests the getListForSuite method - failure. + * + * @return void + */ + public function testGetListForSuiteFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListForSuite('joomla', 'joomla-platform', 5, ['status' => 'completed'], 2, 10); + } + + /** + * Tests the getListForRef method. + * + * @return void + */ + public function testGetListForRef() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/commits/feature%2Fnew/check-runs?page=2&per_page=10&check_name=build&filter=latest', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListForRef('joomla', 'joomla-platform', 'feature/new', ['check_name' => 'build', 'filter' => 'latest'], 2, 10) + ); + } + + /** + * Tests the getListForRef method - failure. + * + * @return void + */ + public function testGetListForRefFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListForRef('joomla', 'joomla-platform', 'feature/new', ['check_name' => 'build', 'filter' => 'latest'], 2, 10); + } +} diff --git a/Tests/Package/Checks/SuitesTest.php b/Tests/Package/Checks/SuitesTest.php new file mode 100644 index 00000000..ddea450b --- /dev/null +++ b/Tests/Package/Checks/SuitesTest.php @@ -0,0 +1,245 @@ +object = new Suites($this->options, $this->client); + } + + /** + * Tests the create method. + * + * @return void + */ + public function testCreate() + { + $this->response = $this->getResponseObject($this->sampleString, 201); + $body = '{"head_sha":"ce587453ced02b1526dfb4cb910479d431683101"}'; + + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-platform/check-suites', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->create('joomla', 'joomla-platform', 'ce587453ced02b1526dfb4cb910479d431683101') + ); + } + + /** + * Tests the create method with the alternative 200 response. + * + * @return void + */ + public function testCreateAlternativeCode() + { + $this->response = $this->getResponseObject($this->sampleString, 200); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->create('joomla', 'joomla-platform', 'ce587453ced02b1526dfb4cb910479d431683101') + ); + } + + /** + * Tests the create method - failure. + * + * @return void + */ + public function testCreateFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->create('joomla', 'joomla-platform', 'ce587453ced02b1526dfb4cb910479d431683101'); + } + + /** + * Tests the setPreferences method. + * + * @return void + */ + public function testSetPreferences() + { + $body = '{"auto_trigger_checks":[{"app_id":4,"setting":false}]}'; + + $this->client->expects($this->once()) + ->method('patch') + ->with('/repos/joomla/joomla-platform/check-suites/preferences', $body, [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->setPreferences('joomla', 'joomla-platform', ['auto_trigger_checks' => [['app_id' => 4, 'setting' => false]]]) + ); + } + + /** + * Tests the setPreferences method - failure. + * + * @return void + */ + public function testSetPreferencesFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('patch') + ->willReturn($this->response); + + $this->object->setPreferences('joomla', 'joomla-platform', ['auto_trigger_checks' => [['app_id' => 4, 'setting' => false]]]); + } + + /** + * Tests the get method. + * + * @return void + */ + public function testGet() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/check-suites/5', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->get('joomla', 'joomla-platform', 5) + ); + } + + /** + * Tests the get method - failure. + * + * @return void + */ + public function testGetFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->get('joomla', 'joomla-platform', 5); + } + + /** + * Tests the rerequest method. + * + * @return void + */ + public function testRerequest() + { + $this->response = $this->getResponseObject($this->sampleString, 201); + $this->client->expects($this->once()) + ->method('post') + ->with('/repos/joomla/joomla-platform/check-suites/5/rerequest', '', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->rerequest('joomla', 'joomla-platform', 5) + ); + } + + /** + * Tests the rerequest method - failure. + * + * @return void + */ + public function testRerequestFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('post') + ->willReturn($this->response); + + $this->object->rerequest('joomla', 'joomla-platform', 5); + } + + /** + * Tests the getListForRef method. + * + * @return void + */ + public function testGetListForRef() + { + $this->client->expects($this->once()) + ->method('get') + ->with('/repos/joomla/joomla-platform/commits/feature%2Fnew/check-suites?page=2&per_page=10&app_id=1', [], 0) + ->willReturn($this->response); + + $this->assertEquals( + json_decode($this->sampleString), + $this->object->getListForRef('joomla', 'joomla-platform', 'feature/new', ['app_id' => 1], 2, 10) + ); + } + + /** + * Tests the getListForRef method - failure. + * + * @return void + */ + public function testGetListForRefFailure() + { + $this->expectException(UnexpectedResponseException::class); + + $this->response = $this->getResponseObject($this->errorString, 500); + + $this->client->expects($this->once()) + ->method('get') + ->willReturn($this->response); + + $this->object->getListForRef('joomla', 'joomla-platform', 'feature/new', ['app_id' => 1], 2, 10); + } +} diff --git a/Tests/Package/ChecksTest.php b/Tests/Package/ChecksTest.php new file mode 100644 index 00000000..b7af002b --- /dev/null +++ b/Tests/Package/ChecksTest.php @@ -0,0 +1,59 @@ +object = new Checks($this->options, $this->client); + } + + /** + * Tests that the runs sub-package is resolved. + * + * @return void + */ + public function testGetRuns() + { + $this->assertInstanceOf(Checks\Runs::class, $this->object->runs); + } + + /** + * Tests that the suites sub-package is resolved. + * + * @return void + */ + public function testGetSuites() + { + $this->assertInstanceOf(Checks\Suites::class, $this->object->suites); + } +} diff --git a/docs/checks.md b/docs/checks.md new file mode 100644 index 00000000..b115c799 --- /dev/null +++ b/docs/checks.md @@ -0,0 +1,59 @@ +# Checks + +The Checks package covers the [GitHub Checks API](https://docs.github.com/rest/checks): check runs and check suites +reported against a commit. It is reached as `$github->checks`, which is a container for the sub-packages +`$github->checks->runs` and `$github->checks->suites`, for example +`$github->checks->runs->getListForRef('joomla', 'joomla-cms', '5.3-dev')`. + +Reading check runs and suites works with any token that can read the repository. Creating and updating check runs, +creating check suites, changing the check suite preferences and rerequesting runs or suites are only allowed for +GitHub Apps, so these calls need an installation access token of a GitHub App (passed as `gh.token`). + +```php +use Joomla\Github\Github; +use Joomla\Registry\Registry; + +$options = new Registry(); +$options->set('gh.token', $installationToken); + +$github = new Github($options); + +// Start a check run for a commit and complete it later +$run = $github->checks->runs->create('joomla', 'joomla-cms', 'code-style', $sha, ['status' => 'in_progress']); + +$github->checks->runs->edit( + 'joomla', + 'joomla-cms', + $run->id, + ['status' => 'completed', 'conclusion' => 'success', 'output' => ['title' => 'Code style', 'summary' => 'No issues']] +); + +// List the latest check runs for a branch +$runs = $github->checks->runs->getListForRef('joomla', 'joomla-cms', '5.3-dev', ['filter' => 'latest']); +``` + +Optional request body fields are passed in `$options` and optional query parameters in `$filters`; the +docblock of each method lists the accepted keys. Git references are URL-encoded, so branch names containing +`/` can be passed as they are. + +## Runs (`$github->checks->runs`) + +| Method | Endpoint | +| --- | --- | +| create($owner, $repo, $name, $headSha, $options) | POST /repos/{owner}/{repo}/check-runs | +| get($owner, $repo, $checkRunId) | GET /repos/{owner}/{repo}/check-runs/{check_run_id} | +| edit($owner, $repo, $checkRunId, $options) | PATCH /repos/{owner}/{repo}/check-runs/{check_run_id} | +| getListAnnotations($owner, $repo, $checkRunId, $page, $limit) | GET /repos/{owner}/{repo}/check-runs/{check_run_id}/annotations | +| rerequest($owner, $repo, $checkRunId) | POST /repos/{owner}/{repo}/check-runs/{check_run_id}/rerequest | +| getListForSuite($owner, $repo, $checkSuiteId, $filters, $page, $limit) | GET /repos/{owner}/{repo}/check-suites/{check_suite_id}/check-runs | +| getListForRef($owner, $repo, $ref, $filters, $page, $limit) | GET /repos/{owner}/{repo}/commits/{ref}/check-runs | + +## Suites (`$github->checks->suites`) + +| Method | Endpoint | +| --- | --- | +| create($owner, $repo, $headSha) | POST /repos/{owner}/{repo}/check-suites | +| setPreferences($owner, $repo, $options) | PATCH /repos/{owner}/{repo}/check-suites/preferences | +| get($owner, $repo, $checkSuiteId) | GET /repos/{owner}/{repo}/check-suites/{check_suite_id} | +| rerequest($owner, $repo, $checkSuiteId) | POST /repos/{owner}/{repo}/check-suites/{check_suite_id}/rerequest | +| getListForRef($owner, $repo, $ref, $filters, $page, $limit) | GET /repos/{owner}/{repo}/commits/{ref}/check-suites | diff --git a/src/Package/Checks.php b/src/Package/Checks.php new file mode 100644 index 00000000..16c9d50c --- /dev/null +++ b/src/Package/Checks.php @@ -0,0 +1,26 @@ + $name, 'head_sha' => $headSha])); + + return $this->processResponse($this->client->post($this->fetchUrl($path), $data), 201); + } + + /** + * Get a check run. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkRunId Check run identifier. + * + * @return object + * + * @link https://docs.github.com/rest/checks/runs#get-a-check-run + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function get(string $owner, string $repo, int $checkRunId) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-runs/' . $checkRunId; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Update a check run. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkRunId Check run identifier. + * @param array $options Optional request body fields: name, details_url, external_id, started_at, status, conclusion, completed_at, output, actions. + * + * @return object + * + * @link https://docs.github.com/rest/checks/runs#update-a-check-run + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function edit(string $owner, string $repo, int $checkRunId, array $options = []) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-runs/' . $checkRunId; + + $data = json_encode((object) $options); + + return $this->processResponse($this->client->patch($this->fetchUrl($path), $data)); + } + + /** + * List check run annotations. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkRunId Check run identifier. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return array + * + * @link https://docs.github.com/rest/checks/runs#list-check-run-annotations + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListAnnotations(string $owner, string $repo, int $checkRunId, int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-runs/' . $checkRunId . '/annotations'; + + return $this->processResponse($this->client->get($this->fetchUrl($path, $page, $limit))); + } + + /** + * Rerequest a check run. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkRunId Check run identifier. + * + * @return object + * + * @link https://docs.github.com/rest/checks/runs#rerequest-a-check-run + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function rerequest(string $owner, string $repo, int $checkRunId) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-runs/' . $checkRunId . '/rerequest'; + + return $this->processResponse($this->client->post($this->fetchUrl($path), ''), 201); + } + + /** + * List check runs in a check suite. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkSuiteId Check suite identifier. + * @param array $filters Optional query parameters: check_name, status, filter. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object + * + * @link https://docs.github.com/rest/checks/runs#list-check-runs-in-a-check-suite + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListForSuite(string $owner, string $repo, int $checkSuiteId, array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-suites/' . $checkSuiteId . '/check-runs'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } + + /** + * List check runs for a Git reference. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $ref Git reference (SHA, branch name or tag name). + * @param array $filters Optional query parameters: check_name, status, filter, app_id. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object + * + * @link https://docs.github.com/rest/checks/runs#list-check-runs-for-a-git-reference + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListForRef(string $owner, string $repo, string $ref, array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/commits/' . rawurlencode($ref) . '/check-runs'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } +} diff --git a/src/Package/Checks/Suites.php b/src/Package/Checks/Suites.php new file mode 100644 index 00000000..031561e8 --- /dev/null +++ b/src/Package/Checks/Suites.php @@ -0,0 +1,148 @@ + $headSha]); + + $response = $this->client->post($this->fetchUrl($path), $data); + + return $this->processResponse( + $response, + \in_array($response->getStatusCode(), [200, 201], true) ? $response->getStatusCode() : 201 + ); + } + + /** + * Update repository preferences for check suites. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param array $options Optional request body fields: auto_trigger_checks. + * + * @return object + * + * @link https://docs.github.com/rest/checks/suites#update-repository-preferences-for-check-suites + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function setPreferences(string $owner, string $repo, array $options = []) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-suites/preferences'; + + $data = json_encode((object) $options); + + return $this->processResponse($this->client->patch($this->fetchUrl($path), $data)); + } + + /** + * Get a check suite. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkSuiteId Check suite identifier. + * + * @return object + * + * @link https://docs.github.com/rest/checks/suites#get-a-check-suite + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function get(string $owner, string $repo, int $checkSuiteId) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-suites/' . $checkSuiteId; + + return $this->processResponse($this->client->get($this->fetchUrl($path))); + } + + /** + * Rerequest a check suite. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param integer $checkSuiteId Check suite identifier. + * + * @return object + * + * @link https://docs.github.com/rest/checks/suites#rerequest-a-check-suite + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function rerequest(string $owner, string $repo, int $checkSuiteId) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/check-suites/' . $checkSuiteId . '/rerequest'; + + return $this->processResponse($this->client->post($this->fetchUrl($path), ''), 201); + } + + /** + * List check suites for a Git reference. + * + * @param string $owner Repository owner. + * @param string $repo Repository name. + * @param string $ref Git reference (SHA, branch name or tag name). + * @param array $filters Optional query parameters: app_id, check_name. + * @param integer $page The page number from which to get items. + * @param integer $limit The number of items on a page. + * + * @return object + * + * @link https://docs.github.com/rest/checks/suites#list-check-suites-for-a-git-reference + * @since __DEPLOY_VERSION__ + * @throws UnexpectedResponseException + */ + public function getListForRef(string $owner, string $repo, string $ref, array $filters = [], int $page = 0, int $limit = 0) + { + // Build the request path. + $path = '/repos/' . $owner . '/' . $repo . '/commits/' . rawurlencode($ref) . '/check-suites'; + + $uri = $this->fetchUrl($path, $page, $limit); + + foreach ($filters as $key => $value) { + $uri->setVar($key, $value); + } + + return $this->processResponse($this->client->get($uri)); + } +}