Downloading code

Download a repository archive as a stream or get an authenticated clone URL.

There are two ways to get repository contents: repos.downloadArchive streams a zip or tar.gz archive at a ref, and repos.getCloneUrl returns an authenticated clone URL. The clone URL embeds credentials — treat it as a secret and never log it.

Downloading an archive

repos.downloadArchive resolves a ref to a snapshot and returns an Archive whose stream is a Web-standard ReadableStream<Uint8Array>:

PropType

repo?string

The repository, in the provider path form.

Typestring

ref?string

Branch, tag, or SHA to snapshot.

Typestring

format?'zip' | 'tar.gz'

Archive format. Defaults to 'zip'. Must be in capabilities.archiveFormats.

Type'zip' | 'tar.gz'

const archive = await client.repos.downloadArchive({
  repo: 'capawesome-team/repo-sdk',
  ref: 'v1.0.0',
  format: 'zip',
});
// archive: { stream: ReadableStream<Uint8Array>, contentType?: string, filename?: string }

Because it’s a stream, you can pipe it straight to disk without buffering the whole archive in memory:

import { createWriteStream } from 'node:fs';
import { Writable } from 'node:stream';

const archive = await client.repos.downloadArchive({
  repo: 'capawesome-team/repo-sdk',
  ref: 'v1.0.0',
  format: 'tar.gz',
});

const file = createWriteStream(archive.filename ?? 'archive.tar.gz');
await archive.stream.pipeTo(Writable.toWeb(file));

Getting a clone URL

repos.getCloneUrl returns a CloneUrl you can hand to git clone:

PropType

url?string

The clone URL. For most providers it embeds the credential.

Typestring

headers?Record<string, string>

Auth headers to pass instead of embedding — used by Azure DevOps Entra auth.

TypeRecord<string, string>

expiresAt?Date

When the embedded credential expires (e.g. GitHub App tokens, ~1h).

TypeDate

const clone = await client.repos.getCloneUrl({ repo: 'capawesome-team/repo-sdk' });
// clone: { url, headers?, expiresAt? }

Expiring credentials

expiresAt is set when the embedded token has a lifetime — most notably GitHub App installation tokens (~1 hour). Re-fetch the clone URL once it’s past expiresAt rather than caching it indefinitely.

Azure DevOps with Entra auth

With an OAuth accessToken, the token is embedded in the URL with the oauth2 username (https://oauth2:<token>@dev.azure.com/...). With an Entra ID tokenProvider, the credential is returned in headers instead of being embedded in the URL. Pass it to git via http.extraheader:

const clone = await client.repos.getCloneUrl({ repo: 'Payments/checkout' });
// clone.url has no credential; clone.headers = { Authorization: 'Bearer …' }

// git -c http.extraheader="Authorization: Bearer …" clone <clone.url>

Next: Managing webhooks