Repository Discovery

Relevant source files

The following files were used as context for generating this wiki page:

• src/github/mod.rs
• src/sync.rs
• src/config.rs
• src/main.rs
• README.md
• AGENTS.md

Repository Discovery identifies the GitHub repositories that Orcastrate manages. This system allows the tool to find target repositories through explicit configuration or by searching a GitHub organization for specific topics. It serves as the initial phase of the synchronization process, ensuring all relevant repositories are scanned for managed workflows.

The discovery logic combines static entries from orchestrator.toml with dynamic results from the GitHub Search API. This hybrid approach enables administrators to manage a fixed list of repositories while automatically including new projects that match organizational criteria.

Architecture and Data Flow

The discovery process begins during the execution of the sync or list-repos commands. The system resolves a final list of repository names by merging configured entries with discovered ones.

The diagram shows how the system prioritizes and merges different repository sources to create a unified list for processing.
Sources: src/sync.rs:215-251, src/main.rs:88-106

Key Components

Component	Responsibility
DiscoveryConfig	Holds the organization name and optional topic filter for the search.
resolve_repos	Merges static repositories from config with dynamic results from the GitHub API.
discover_repos	Executes the GitHub search query and handles API pagination.
GitHubClient	Provides the interface to the octocrab search and repository modules.

Sources: src/config.rs:34-38, src/sync.rs:215-220, src/github/mod.rs:346-350

Dynamic Discovery via GitHub API

When the [discovery] section is present in orchestrator.toml, Orcastrate uses the GitHub Search API to find repositories. The discover_repos function constructs a query using the org:{org} qualifier and optionally appends topic:{topic} if provided.

Search Implementation

The search implementation performs the following actions:

1. It initializes a search request for repositories within a specific organization.
2. It applies a topic filter if configured to narrow the scope.
3. It requests results with a limit of 100 items per page.
4. It iterates through all available pages using the next link in the API response headers to ensure complete coverage.

Sources: src/github/mod.rs:350-388

This sequence illustrates the pagination logic used to retrieve all matching repositories from the GitHub organization.
Sources: src/github/mod.rs:364-388

Configuration

Discovery behavior is controlled through the orchestrator.toml file. Users define either a static list of repositories or dynamic discovery parameters.

Discovery Settings

Field	Type	Description
org	String	The GitHub organization to search within.
topic	Option	An optional repository topic (e.g., "managed-workflows") to filter results.

Sources: src/config.rs:34-38, README.md:144-147

Static Repository Filtering

Static repositories are defined in the [[repos]] array. Each entry includes a name in owner/repo format and an enabled flag. The active_repos method filters out any entries where enabled is set to false. During the resolution phase, any repositories found via dynamic discovery that are already in the static list are deduplicated.

Sources: src/config.rs:25-32, src/sync.rs:228-235

CLI Interaction

The discovery system integrates with the CLI to provide visibility and control over the repository list.

• orcastrate list-repos: This command displays the final resolved list. It shows "Configured repos" followed by "Discovered repos" if discovery is enabled.
• --repo <NAME>: This flag allows users to filter the discovery results to a single specific repository. If the requested repository is not found in either the static config or the discovery results, the system returns a configuration error.

Sources: src/main.rs:88-106, src/sync.rs:240-250

// src/sync.rs:221-236
async fn resolve_repos(
    config: &Config,
    client: &GitHubClient,
    filter_repo: Option<&str>,
) -> crate::error::Result<Vec<String>> {
    let mut repos: Vec<String> = config
        .active_repos()
        .iter()
        .map(|r| r.name.clone())
        .collect();

    if let Some(ref discovery) = config.discovery {
        let discovered = client
            .discover_repos(&discovery.org, discovery.topic.as_deref())
            .await?;
        // ... deduplication and merge logic
    }
}

Sources: src/sync.rs:221-236

Summary

Repository Discovery provides a flexible mechanism for identifying target repositories. By supporting both static configuration and dynamic organization-wide searches, it allows Orcastrate to scale across large GitHub organizations without requiring manual updates for every new repository. The system ensures comprehensive coverage by handling API pagination and provides administrative control through status flags and CLI filters.