Repository Discovery

repository-discovery is a TypeScript library for git repository discovery across different hosting providers. Currently supports GitHub, GitLab, Azure DevOps and Bitbucket.

Installation

npm install repository-discovery

Quickstart

import { discoverRepositories } from 'repository-discovery';

const repos = await discoverRepositories({
  platform: 'github',
  token: process.env.GITHUB_TOKEN,
  sources: { orgs: ['my-organization'] },
});

Platform Examples

// GitHub: orgs, users, repos
await discoverRepositories({
  platform: 'github',
  token: '...',
  sources: { orgs: ['facebook'], users: ['torvalds'], repos: ['torvalds/linux'] },
});

// GitLab: groups, users, projects
await discoverRepositories({
  platform: 'gitlab',
  token: '...',
  sources: { groups: ['gitlab-org'], users: ['username'], projects: ['group/project'] },
});

// Bitbucket: workspaces, projects, repos
await discoverRepositories({
  platform: 'bitbucket',
  token: '...',
  sources: {
    workspaces: ['atlassian'],
    projects: ['workspace/project'],
    repos: ['workspace/repo'],
  },
});

// Azure DevOps: organizations (required), projects, repos
await discoverRepositories({
  platform: 'azuredevops',
  token: '...',
  sources: {
    organizations: ['https://dev.azure.com/my-org'],
    projects: ['https://dev.azure.com/my-org/my-project'],
    repos: ['https://dev.azure.com/my-org/my-project/my-repo'],
  },
});

Options

await discoverRepositories({
  platform: 'github',
  token: '...', // or async function: () => fetchToken()
  hostUrl: 'https://github.mycompany.com', // Self-hosted instances
  sources: { orgs: ['internal'] },
  filter: {
    excludeArchived: true,
    excludeForks: true,
    skipRepos: ['owner/repo-to-skip'],
  },
  continueOnError: true, // Returns { repositories, errors } instead of throwing
  signal: abortController.signal,
});

Error Handling

import {
  discoverRepositories,
  DiscoveryError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  PermissionError,
} from 'repository-discovery';

try {
  const repos = await discoverRepositories({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    // Invalid or expired token
  } else if (error instanceof RateLimitError) {
    // Rate limit exceeded
  } else if (error instanceof NotFoundError) {
    // Source not found
  } else if (error instanceof PermissionError) {
    // Insufficient permissions
  }
}

// Or use continueOnError to collect errors without throwing
const { repositories, errors } = await discoverRepositories({
  ...options,
  continueOnError: true,
});

License

MIT