GitHub: Search repositories

← Search operations · Get started

Operation github.search_repos

Provider route: GET /search/repositories. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/github with npm, or alter-sdk-github with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { GitHubIntegration } from "@alter-ai/github";

async function execute(input: Parameters<GitHubIntegration["search"]["searchRepos"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new GitHubIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.search.searchRepos(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_github import GitHubIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = GitHubIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.search.search_repos(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
query	object	Required within parent	Additional keys: not allowed
query.q	string	Required within parent
query.sort	string	Optional	One of: stars, forks, help-wanted-issues, updated
query.order	string	Optional	Default: desc One of: desc, asc
query.per_page	integer	Optional	Default: 30
query.page	integer	Optional	Default: 1

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root
incomplete_results	boolean	Required within parent
items	array	Required within parent
items[]	Model	Each item	Expand Search repositories — response body — items item
total_count	JSON	Required within parent
total_count (anyOf 1)	integer	Alternative
total_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Referenced models: Search repositories — response body — items item

Schemas

3 more schemas are linked from the tables above, on the schema pages.

Search repositories — response body — items item

Field	Type	Presence	Description and constraints
$	object	Root	Repo Search Result Item
allow_auto_merge	boolean	Optional
allow_forking	boolean	Optional
allow_merge_commit	boolean	Optional
allow_rebase_merge	boolean	Optional
allow_squash_merge	boolean	Optional
archive_url	string	Required within parent
archived	boolean	Required within parent
assignees_url	string	Required within parent
blobs_url	string	Required within parent
branches_url	string	Required within parent
clone_url	string	Required within parent
collaborators_url	string	Required within parent
comments_url	string	Required within parent
commits_url	string	Required within parent
compare_url	string	Required within parent
contents_url	string	Required within parent
contributors_url	string	Required within parent	Format: uri
created_at	string	Required within parent	Format: date-time
default_branch	string	Required within parent
delete_branch_on_merge	boolean	Optional
deployments_url	string	Required within parent	Format: uri
description	JSON	Required within parent
description (anyOf 1)	string	Alternative
description (anyOf 2)	null	Alternative
disabled	boolean	Required within parent	Returns whether or not this repository disabled.
downloads_url	string	Required within parent	Format: uri
events_url	string	Required within parent	Format: uri
fork	boolean	Required within parent
forks	JSON	Required within parent
forks (anyOf 1)	integer	Alternative
forks (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
forks_count	JSON	Required within parent
forks_count (anyOf 1)	integer	Alternative
forks_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
forks_url	string	Required within parent	Format: uri
full_name	string	Required within parent
git_commits_url	string	Required within parent
git_refs_url	string	Required within parent
git_tags_url	string	Required within parent
git_url	string	Required within parent
has_discussions	boolean	Optional
has_downloads	boolean	Required within parent
has_issues	boolean	Required within parent
has_pages	boolean	Required within parent
has_projects	boolean	Required within parent
has_pull_requests	boolean	Optional
has_wiki	boolean	Required within parent
homepage	JSON	Required within parent
homepage (anyOf 1)	string	Alternative	Format: uri
homepage (anyOf 2)	null	Alternative
hooks_url	string	Required within parent	Format: uri
html_url	string	Required within parent	Format: uri
id	JSON	Required within parent
id (anyOf 1)	integer	Alternative
id (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
is_template	boolean	Optional
issue_comment_url	string	Required within parent
issue_events_url	string	Required within parent
issues_url	string	Required within parent
keys_url	string	Required within parent
labels_url	string	Required within parent
language	JSON	Required within parent
language (anyOf 1)	string	Alternative
language (anyOf 2)	null	Alternative
languages_url	string	Required within parent	Format: uri
license	Model	Required within parent	Expand Create a fork — response body — license
master_branch	string	Optional
merges_url	string	Required within parent	Format: uri
milestones_url	string	Required within parent
mirror_url	JSON	Required within parent
mirror_url (anyOf 1)	string	Alternative	Format: uri
mirror_url (anyOf 2)	null	Alternative
name	string	Required within parent
node_id	string	Required within parent
notifications_url	string	Required within parent
open_issues	JSON	Required within parent
open_issues (anyOf 1)	integer	Alternative
open_issues (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
open_issues_count	JSON	Required within parent
open_issues_count (anyOf 1)	integer	Alternative
open_issues_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
owner	Model	Required within parent	Expand Get an issue — response body — user
permissions	object	Optional
permissions.admin	boolean	Required within parent
permissions.maintain	boolean	Optional
permissions.pull	boolean	Required within parent
permissions.push	boolean	Required within parent
permissions.triage	boolean	Optional
private	boolean	Required within parent
pull_request_creation_policy	string	Optional	The policy controlling who can create pull requests: all or collaborators_only. Known values: all, collaborators_only
pulls_url	string	Required within parent
pushed_at	string	Required within parent	Format: date-time
releases_url	string	Required within parent
score	JSON	Required within parent
score (anyOf 1)	number	Alternative
score (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
size	JSON	Required within parent
size (anyOf 1)	integer	Alternative
size (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
ssh_url	string	Required within parent
stargazers_count	JSON	Required within parent
stargazers_count (anyOf 1)	integer	Alternative
stargazers_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
stargazers_url	string	Required within parent	Format: uri
statuses_url	string	Required within parent
subscribers_url	string	Required within parent	Format: uri
subscription_url	string	Required within parent	Format: uri
svn_url	string	Required within parent	Format: uri
tags_url	string	Required within parent	Format: uri
teams_url	string	Required within parent	Format: uri
temp_clone_token	string	Optional	When present and non-empty, a temporary credential for read-only Git access to this repository. It expires five minutes after generation and cannot be used to push changes. Treat this value as sensitive and avoid recording it in logs.
text_matches	Model	Optional	Expand Search code — response body — items item text matches
topics	array	Optional
topics[]	string	Each item
trees_url	string	Required within parent
updated_at	string	Required within parent	Format: date-time
url	string	Required within parent	Format: uri
visibility	string	Optional	The repository visibility: public, private, or internal.
watchers	JSON	Required within parent
watchers (anyOf 1)	integer	Alternative
watchers (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
watchers_count	JSON	Required within parent
watchers_count (anyOf 1)	integer	Alternative
watchers_count (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
web_commit_signoff_required	boolean	Optional

Referenced models: Create a fork — response body — license, Get an issue — response body — user, Search code — response body — items item text matches

Get an issue — response body — user

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	Model	Alternative	Expand Get an issue — response body — user A Git Hub user
$ (anyOf 2)	null	Alternative

Referenced models: Get an issue — response body — user A Git Hub user

Policy, approvals and errors

SDK function policy ID: github.search_repos. Catalog operation: search/repos. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"X-GitHub-Api-Version": "2026-03-10", "User-Agent": "Alter", "Accept": "application/vnd.github+json"}

Official provider source