Repositories & namespaces

The repo string format per provider, namespaces, and the normalized Repository type.

Every git provider organizes repositories differently — owners, groups, workspaces, projects. repo-sdk reconciles this with two ideas: a repo string that addresses a single repository, and a normalized Namespace that describes the containers repositories live in.

The `repo` string

Every call that targets a repository takes a repo string in the provider’s native path form. It is passed through verbatim, so it always matches what you see in the provider’s own URLs.

Provider	`repo` format	Provider config
GitHub	`owner/name`	—
GitLab	`group/subgroup/project` or numeric id	—
Bitbucket	`workspace/repo_slug`	—
Azure DevOps	`project/repository`	`organization` (req.)
Gitea	`owner/name`	—

await client.repos.get({ repo: 'capawesome-team/repo-sdk' }); // GitHub
await client.repos.get({ repo: 'acme/backend/api' }); // GitLab subgroup
await client.repos.get({ repo: 'acme-workspace/api' }); // Bitbucket
await client.repos.get({ repo: 'Payments/checkout' }); // Azure DevOps (org set on the provider)

Namespaces

A Namespace is the normalized container a repository belongs to. Because providers use different words for the same idea, the kind field tells you which one you’re looking at:

PropType

id?string

Provider id of the namespace.

Typestring

slug?string

URL/path segment used in the repo string.

Typestring

name?string

Human-readable display name.

Typestring

kind?'user' | 'organization' | 'group' | 'workspace' | 'project'

The provider-native container type.

Type'user' | 'organization' | 'group' | 'workspace' | 'project'

parent?string

Parent namespace slug, for nested groups.

Typestring

avatarUrl?string

Avatar/logo URL, when the provider exposes one (not on Azure DevOps projects).

Typestring

raw?unknown

The untouched provider payload.

Typeunknown

List them with namespaces.list / namespaces.listAll:

for await (const namespace of client.namespaces.listAll()) {
  console.log(namespace.kind, namespace.slug);
}

The Repository type

repos.get and the repos.list family return the normalized Repository:

PropType

id?string

Provider id.

Typestring

name?string

Repository name.

Typestring

path?string

Full path — the same string you pass as repo.

Typestring

namespace?string

Slug of the owning namespace.

Typestring

defaultBranch?string

Default branch, when available.

Typestring

private?boolean

Whether the repository is private.

Typeboolean

archived?boolean

Whether the repository is archived.

Typeboolean

urls?{ web, cloneHttp?, cloneSsh? }

Web and clone URLs. web is always present — constructed from the provider base URL when the API omits it; clone URLs when available.

Type{ web, cloneHttp?, cloneSsh? }

raw?unknown

The untouched provider response.

Typeunknown

const repo = await client.repos.get({ repo: 'capawesome-team/repo-sdk' });
repo.defaultBranch; // normalized
repo.urls.cloneHttp; // normalized
repo.raw; // original provider response — reach for provider-specific fields here

The raw escape hatch is present on every normalized object, so you never lose access to a provider-specific field the normalized shape doesn’t cover.

Next: Pagination

Cursor pages and the listAll iterator.