Skip to main content

ADR-0006: Repository listing scope

  • Status: Accepted
  • Date: 2026-10-25

Context​

Each provider defines repository visibility differently. Listing "all repositories" is not a single portable operation: the result depends on the token's permissions, the organization or namespace, and whether archived repositories are included.

Decision​

ListRepositoriesAsync returns repositories visible to the supplied token within the configured owner, namespace, or project scope.

RepositoryQuery inputGitHubGitLabAzure DevOps
Owner setUser or organization repositories for that ownerProjects in that group or user namespaceOrganization repositories
Owner and Project setValidation error (Project is not used)Projects in the subgroup pathRepositories in the team project
Owner not setRepositories visible to the authenticated userProjects visible to the authenticated userOrganization from configuration, or a configuration error if no organization is set

Rules:

  • Results are always limited by token permissions. VcsManager never widens the query or requests additional scopes.
  • IncludeArchived defaults to false. GitHub filters on the archived field, GitLab uses the project archived query parameter, and Azure DevOps has no repository archive concept, so the flag has no effect there.
  • Visibility and NameContains filters are applied provider-side when the provider supports them. Otherwise the provider filters the current page after retrieval and documents the difference. Pagination metadata still describes the provider response, not the filtered subset.
  • Group and organization listings include nested GitLab subgroups only when the caller sets Project; Azure DevOps does not cross team projects unless the organization scope is requested.
  • A listing never crosses organizations or provider hosts.
  • Results are paginated according to ADR-0009. The provider does not fetch all pages to satisfy a single request.

Consequences​

  • Callers get predictable, permission-bounded results on every provider.
  • "List everything" is not portable; callers must supply the scope they need.
  • Archived handling differs by provider and is documented in the capability matrix.
  • Unit tests cover each scope branch and the archived filter.

References​