Implement getInstallationRepository method

[hmacr]

Towards SER-1129

Summary by CodeRabbit

• New Features

  • Added capability to retrieve a specific repository from VCS installations by name.
  • GitHub: implemented installation-level repository lookup with validation and clear error when not found.
  • Gitea: adapter scaffold present; repository lookup not implemented yet.

• Tests

  • Added tests covering repository retrieval and lookup behavior for GitHub.

[coderabbitai]

Walkthrough

Adds a new abstract method getInstallationRepository(string $repositoryName): array to Utopia\VCS\Adapter. Implements getInstallationRepository in the GitHub adapter: it requests installation repositories, validates responses, performs a case-insensitive name match, returns the matching repository array, and throws RepositoryNotFound (or a generic Exception if repositories are missing). Adds a stubbed getInstallationRepository in the Gitea adapter that throws a not-implemented error. Adds PHPUnit tests for getInstallationRepository and getRepository in the GitHub tests.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 36.36% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Implement getInstallationRepository method' directly and accurately describes the main change—adding a new abstract method to the Adapter class and implementing it in GitHub and Gitea adapters.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ser-1129

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/VCS/Adapter/Git/GitHub.php`:
- Around line 192-211: getInstallationRepository currently requests only page 1
(per_page=100) and can miss repositories beyond the first page; update
getInstallationRepository to paginate through installation repositories (like
searchRepositories does) by looping pages (incrementing page until no more
repositories or found), merging/iterating over each
response['body']['repositories'] batch, comparing strtolower($repo['name']) to
strtolower($repositoryName) and returning immediately if matched, and only throw
RepositoryNotFound after exhausting all pages; reuse the same call(...)
signature, headers and per_page handling used in the existing method.

In `@tests/VCS/Adapter/GitHubTest.php`:
- Around line 176-182: getInstallationRepository in class GitHub only checks the
first page of installation repositories and must be updated to paginate until
the target repo is found or no more pages remain; modify
GitHub::getInstallationRepository to loop through pages (using the client call
you already use to list installation repositories with per_page=100 and page
increments, or use the client's built-in pagination helper) and check each page
for $repositoryName, returning the repo when found and only throwing
RepositoryNotFound after all pages are exhausted. Also add a failing-unit
negative test that calls getInstallationRepository with a non-existent name and
asserts RepositoryNotFound is thrown to guard against regressions.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between c92d09d and ec25d52.

📒 Files selected for processing (4)

• src/VCS/Adapter.php
• src/VCS/Adapter/Git/GitHub.php
• src/VCS/Adapter/Git/Gitea.php
• tests/VCS/Adapter/GitHubTest.php

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/VCS/Adapter/Git/GitHub.php`:
- Around line 197-224: Remove the artificial $maxRepositories cap and the
$totalRepositories increment logic in the pagination loop so we paginate until
the API indicates the last page; specifically, delete the $maxRepositories
variable and any checks against it and stop updating $totalRepositories, change
the loop condition to an infinite loop (e.g. while (true)) around the call(...)
+ foreach that searches repositories, and rely on the existing break when
count($response['body']['repositories']) < $perPage; keep throwing
RepositoryNotFound if the loop completes without a match.

---

ℹ️ Review info

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between cb0f8eb and b33588a.

📒 Files selected for processing (1)

• src/VCS/Adapter/Git/GitHub.php

[Copilot]

Pull request overview

This pull request implements the getInstallationRepository method to retrieve a specific repository from a VCS installation by name, contributing to ticket SER-1129. The method searches through installation-accessible repositories and returns the matching repository data, with proper error handling when a repository is not found.

Changes:

• Added abstract method getInstallationRepository to the VCS Adapter base class
• Implemented the method in GitHub adapter with pagination support and case-insensitive repository name matching
• Added stub implementation in Gitea adapter (not yet implemented)
• Added tests for both getInstallationRepository and the existing getRepository methods

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
src/VCS/Adapter.php	Added abstract method definition for getInstallationRepository
src/VCS/Adapter/Git/GitHub.php	Implemented repository lookup with pagination through installation repositories
src/VCS/Adapter/Git/Gitea.php	Added stub method that throws "Not implemented yet" exception
tests/VCS/Adapter/GitHubTest.php	Added tests for repository retrieval functionality

Comments suppressed due to low confidence (5)

src/VCS/Adapter/Git/GitHub.php:192

• The getInstallationRepository method is missing a PHPDoc comment. Based on the codebase conventions, all public methods should have PHPDoc comments that include a description, parameter documentation with @param, return type documentation with @return, and any exceptions thrown with @throws. For example, see the documentation for searchRepositories (lines 97-107) or getRepository (lines 227-233).

    public function getInstallationRepository(string $repositoryName): array

src/VCS/Adapter/Git/GitHub.php:221

• The loop condition uses $totalRepositories < $maxRepositories but increments $totalRepositories by $perPage even when fewer repositories might be returned. This could lead to incorrect pagination behavior. For instance, if 50 repositories are returned in a page, $totalRepositories is still incremented by 100. Consider using $totalRepositories += count($response['body']['repositories']) instead to accurately track the number of repositories fetched.

            $totalRepositories += $perPage;

src/VCS/Adapter.php:106

• The abstract method definition in the Adapter class is missing the @throws annotation. The implementation in GitHub.php throws both Exception and RepositoryNotFound, so the abstract method should document this. Following the pattern of other abstract methods in this file (see line 96 for searchRepositories), add @throws Exception to the PHPDoc.

    /**
     * Get repository for the installation
     *
     * @param string $repositoryName
     * @return array<mixed>
     */
    abstract public function getInstallationRepository(string $repositoryName): array;

tests/VCS/Adapter/GitHubTest.php:182

• The test does not cover the error case where a repository is not found. Consider adding a test case that verifies the RepositoryNotFound exception is thrown when searching for a non-existent repository, following the pattern used in other test methods for error handling.

    public function testGetInstallationRepository(): void
    {
        $repositoryName = 'astro-starter';
        $repo = $this->vcsAdapter->getInstallationRepository($repositoryName);
        $this->assertIsArray($repo);
        $this->assertSame($repositoryName, $repo['name']);
    }

src/VCS/Adapter/Git/GitHub.php:197

• The method uses a hardcoded limit of 1000 repositories ($maxRepositories). If an installation has more than 1000 repositories and the target repository is beyond this limit, it won't be found even if it exists. Consider either removing this limit, documenting this limitation clearly in the PHPDoc, or using GitHub's total_count from the API response to determine when all repositories have been fetched.

        $maxRepositories = 1000;

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.