---
title: "Repositories"
description: "Repositories, files, commits, releases, accounts, teams and search."
canonical_url: "https://forgeslink-3mwmle35v-poetry.vercel.app/reference/repositories"
---
# Repositories

> Repositories, files, commits, releases, accounts, teams and search.

For an operation that the forge lacks, see [Unsupported operations](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider#unsupported-operations).

## `provider.repos`

Repositories, and the labels, milestones and collaborators that belong to them.

### `repos.get()`

Reads a repository by its ref. Rejects with `NotFoundError` when it does not exist or the credential cannot see
it.

**Capability:** `repos.get`.

```ts
repos.get(ref: RepoRef, options?: RepoGetOptions): Promise<Repo>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#repogetoptions">
        <code>
          RepoGetOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Repo>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#repo)

<api-explorer verb="repos.get">



</api-explorer>

### `repos.list()`

The authenticated account's repositories, or the installation's under app auth.

**Capability:** `repos.list`. Anonymous providers reject it.

```ts
repos.list(options?: RepoQuery): ForgeListing<Repo>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#repoquery">
        <code>
          RepoQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Repo>`

<api-explorer verb="repos.list">



</api-explorer>

### `repos.byOwner()`

The repositories of a user, organisation, group, workspace or project that the credential can see.

**Capability:** `repos.byOwner`.

```ts
repos.byOwner(owner: RepoRef, query?: OwnerRepoQuery): ForgeListing<Repo>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        owner
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      A namespace ref, such as <code>
        namespaceRef(provider, 'acme')
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        query?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#ownerrepoquery">
        <code>
          OwnerRepoQuery
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Repo>`

<api-explorer verb="repos.byOwner">



</api-explorer>

### `repos.labels()`

Every label defined on the repository, whether or not a thread carries it.

**Capability:** `repos.labels`.

```ts
repos.labels(repo: RepoRef, options?: PageOptions): ForgeListing<Label>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Label>`

<api-explorer verb="repos.labels">



</api-explorer>

### `repos.createLabel()`

Creates a label in a repository. A repeat rejects on most forges, because the name is taken.

**Capability:** `repos.createLabel`. Read-only and anonymous providers reject it.

```ts
repos.createLabel(repo: RepoRef, label: LabelInput, options?: BaseOptions): Promise<Label>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        label
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#labelinput">
        <code>
          LabelInput
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Label>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#label)

<api-explorer verb="repos.createLabel">



</api-explorer>

### `repos.milestones()`

Lists the milestones of a repository.

**Capability:** `repos.milestones`.

```ts
repos.milestones(repo: RepoRef, options?: MilestoneListOptions): ForgeListing<Milestone>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#milestonelistoptions">
        <code>
          MilestoneListOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Milestone>`

<api-explorer verb="repos.milestones">



</api-explorer>

### `repos.issueTypes()`

The issue types that issues in the repository can have. On GitHub, the enabled types of the account that owns it.

**Capability:** `repos.issueTypes`.

```ts
repos.issueTypes(repo: RepoRef, options?: BaseOptions): Promise<IssueType[]>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<IssueType[]>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#issuetype)

<api-explorer verb="repos.issueTypes">



</api-explorer>

### `repos.collaborators()`

Lists the collaborators of a repository, with their roles.

**Capability:** `repos.collaborators`.

```ts
repos.collaborators(repo: RepoRef, options?: PageOptions): ForgeListing<Collaborator>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Collaborator>`

<api-explorer verb="repos.collaborators">



</api-explorer>

### `repos.contributors()`

Lists the commit authors of a repository with their commit counts, most commits first. Pass
`includeUnlinked: true` to include the contributors the forge has not linked to an account.

**Capability:** `repos.contributors`.

```ts
repos.contributors(repo: RepoRef, options?: ContributorQuery): ForgeListing<Contributor>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#contributorquery">
        <code>
          ContributorQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Contributor>`

<api-explorer verb="repos.contributors">



</api-explorer>

### `repos.contributorStats()`

Weekly commit activity of each contributor to a repository. Where the forge computes the statistics in the
background, the provider waits for them, and throws a `ForgeApiError` with status `202` if they are still not ready.

**Capability:** `repos.contributorStats`.

```ts
repos.contributorStats(repo: RepoRef, options?: BaseOptions): Promise<ContributorStats[]>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<ContributorStats[]>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#contributorstats)

<api-explorer verb="repos.contributorStats">



</api-explorer>

### `repos.templates()`

The issue and pull request templates a repository offers, ready to fill in before `threads.create()`. On GitHub,
a repository without its own falls back to the owner's `.github` repository, same as the web UI.

**Example**

```ts
const [template] = await provider.repos.templates(repo, { kind: 'pull_request' })
const body = template?.body ?? ''
```

**Capability:** `repos.templates`.

```ts
repos.templates(repo: RepoRef, options?: RepoTemplateOptions): Promise<RepoTemplate[]>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#repotemplateoptions">
        <code>
          RepoTemplateOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<RepoTemplate[]>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#repotemplate)

<api-explorer verb="repos.templates">



</api-explorer>

### `repos.permissionFor()`

One account's role on the repository; `'none'` when it has no access.

**Capability:** `repos.permissionFor`.

```ts
repos.permissionFor(repo: RepoRef, actor: string | Actor, options?: BaseOptions): Promise<RepoRole>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        actor
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#actor">
        <code>
          string | Actor
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<RepoRole>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporole)

<api-explorer verb="repos.permissionFor">



</api-explorer>

### `repos.branchRules()`

The checks and approvals a pull request needs before it can merge into a branch. On GitHub it reads both
rulesets and classic branch protection, and only an admin can read the approvals that classic protection asks for.

**Example**

```ts
const rules = await provider.repos.branchRules(repo, 'main')
const names = rules.requiredChecks.map(check => check.name)
```

**Capability:** `repos.branchRules`.

```ts
repos.branchRules(repo: RepoRef, branch: string, options?: BaseOptions): Promise<BranchRules>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      The repository that holds the branch.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        branch
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The name of the branch, which has to exist.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<BranchRules>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#branchrules)

<api-explorer verb="repos.branchRules">



</api-explorer>

### `repos.addCollaborator()`

Gives an account a role on a repository, or invites it where the forge asks the account to accept first. A repeat
can reject where the forge refuses to add an existing member (GitLab).

**Capability:** `repos.addCollaborator`. Read-only and anonymous providers reject it.

```ts
repos.addCollaborator(repo: RepoRef, actor: string | Actor, role: RepoRole, options?: BaseOptions): Promise<AddCollaboratorResult>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        actor
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#actor">
        <code>
          string | Actor
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        role
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporole">
        <code>
          RepoRole
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<AddCollaboratorResult>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#addcollaboratorresult)

<api-explorer verb="repos.addCollaborator">



</api-explorer>

### `repos.assignableUsers()`

Accounts that can be assigned to a thread in the repository.

**Capability:** `repos.assignableUsers`.

```ts
repos.assignableUsers(repo: RepoRef, options?: PageOptions): ForgeListing<Actor>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Actor>`

<api-explorer verb="repos.assignableUsers">



</api-explorer>

### `repos.reviewerCandidates()`

Accounts that can be asked to review a given pull request.

**Capability:** `repos.reviewerCandidates`.

```ts
repos.reviewerCandidates(ref: ThreadRef, options?: PageOptions): ForgeListing<Actor>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#threadref">
        <code>
          ThreadRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Actor>`

<api-explorer verb="repos.reviewerCandidates">



</api-explorer>

### `repos.events()`

Lists the activity feed of a repository: pushes, new branches and tags, and changes to its threads and releases.
Events come in the order the forge added them to the feed, latest first, which can differ from `occurredAt`
where the forge adds events late. Each event has `source: 'poll'`.

Where the forge supports conditional requests, the first page has an `etag`; pass it back as
`cursor: { etag }` to read the first page again, which has `notModified: true` and no items when the feed is
unchanged. Where the forge sets a minimum wait between reads, reading the first page again sooner sends no
request and returns a `throttled` page with a `feed_throttled` warning, unless you pass `force: true`.
Iterating then yields nothing, and the warning lands in `warnings`.

**Example**

```ts
const page = await provider.repos.events(repo, { cursor: etag ? { etag } : undefined }).page()
if (!page.notModified) {
  etag = page.etag
}
```

**Capability:** `repos.events`.

```ts
repos.events(repo: RepoRef, options?: EventFeedOptions): ForgeListing<ForgeEvent>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#eventfeedoptions">
        <code>
          EventFeedOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<ForgeEvent>`

<api-explorer verb="repos.events">



</api-explorer>

## `provider.contents`

Files, trees, branches and tags of a repository, comparisons between refs, and commits that write files.

### `contents.getFile()`

One file's contents. Binary-safe: `content` is a `Uint8Array` unless the
forge reports text and `as: 'text'` was asked for. Files past the forge's
inline limit (1 MB on GitHub) are read from the raw or blob endpoint
instead of failing.

**Example**

```ts
const file = await provider.contents.getFile(repo, 'package.json', { as: 'text' })
const manifest = JSON.parse(file.content as string)
```

**Capability:** `contents.getFile`.

```ts
contents.getFile(repo: RepoRef, path: string, options?: FileOptions): Promise<FileContent>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      The repository to read from.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        path
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The path of the file from the repository root.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#fileoptions">
        <code>
          FileOptions
        </code>
      </a>
    </td>
    
    <td>
      The revision to read, and whether to decode the content as text.
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<FileContent>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#filecontent)

<api-explorer verb="contents.getFile">



</api-explorer>

### `contents.tree()`

One level, or every descendant with `recursive`. Truncated listings carry a `tree_truncated` warning.

**Capability:** `contents.tree`.

```ts
contents.tree(repo: RepoRef, options?: TreeOptions): ForgeListing<TreeEntry>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#treeoptions">
        <code>
          TreeOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<TreeEntry>`

<api-explorer verb="contents.tree">



</api-explorer>

### `contents.branches()`

Lists the branches of a repository.

**Capability:** `contents.branches`.

```ts
contents.branches(repo: RepoRef, options?: PageOptions): ForgeListing<Branch>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Branch>`

<api-explorer verb="contents.branches">



</api-explorer>

### `contents.tags()`

Lists the tags of a repository.

**Capability:** `contents.tags`.

```ts
contents.tags(repo: RepoRef, options?: PageOptions): ForgeListing<Tag>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Tag>`

<api-explorer verb="contents.tags">



</api-explorer>

### `contents.resolveRef()`

Resolves a branch, tag or sha to a full commit sha; a full sha is returned as is.

**Capability:** `contents.resolveRef`.

```ts
contents.resolveRef(repo: RepoRef, ref: string, options?: BaseOptions): Promise<string>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<string>`

<api-explorer verb="contents.resolveRef">



</api-explorer>

### `contents.compare()`

Commits and files between two refs.

**Capability:** `contents.compare`.

```ts
contents.compare(repo: RepoRef, base: string, head: string, options?: CompareOptions): Promise<Comparison>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        base
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        head
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#compareoptions">
        <code>
          CompareOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Comparison>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#comparison)

<api-explorer verb="contents.compare">



</api-explorer>

### `contents.commitFiles()`

Writes and deletes files in one commit on a branch, and moves the branch to it. A repeat with `expectedHead` or
`createFrom` rejects once the first attempt has moved or created the branch; without them, it adds a second commit.

**Example**

```ts
const commit = await provider.contents.commitFiles(repo, {
  branch: 'docs/readme',
  createFrom: 'main',
  message: 'docs: update readme',
  changes: [
    { path: 'README.md', content: '# widgets\n' },
    { path: 'OLD.md', content: null },
  ],
})
```

**Capability:** `contents.commitFiles`. Read-only and anonymous providers reject it.

```ts
contents.commitFiles(repo: RepoRef, input: CommitFilesInput, options?: BaseOptions): Promise<Commit>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      The repository to commit to.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        input
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitfilesinput">
        <code>
          CommitFilesInput
        </code>
      </a>
    </td>
    
    <td>
      The branch, the message and the files, with the head the branch must have and the ref to create it from.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Commit>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commit)

**Throws:**

- `BranchMovedError` when the branch no longer points at `expectedHead`.
- `NotFoundError` when a file to delete does not exist.

<api-explorer verb="contents.commitFiles">



</api-explorer>

## `provider.commits`

Commits of a repository and the comments on them.

### `commits.list()`

Lists the commits that lead to `ref`, or to the default branch.

**Capability:** `commits.list`.

```ts
commits.list(repo: RepoRef, query?: CommitQuery): ForgeListing<Commit>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        query?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitquery">
        <code>
          CommitQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Commit>`

<api-explorer verb="commits.list">



</api-explorer>

### `commits.get()`

One commit, with its files and stats.

**Capability:** `commits.get`.

```ts
commits.get(ref: CommitRef, options?: BaseOptions): Promise<Commit>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitref">
        <code>
          CommitRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Commit>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commit)

<api-explorer verb="commits.get">



</api-explorer>

### `commits.comments()`

Lists the comments on a commit.

**Capability:** `commits.comments`.

```ts
commits.comments(ref: CommitRef, options?: PageOptions): ForgeListing<CommitComment>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitref">
        <code>
          CommitRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<CommitComment>`

### `commits.getComment()`

Reads one comment on a commit. Where the forge has no endpoint for it (`capabilities.commits.getComment` is
`'emulated'`), it lists the comments of the commit page by page until the id matches, which costs a request for
each page read.

**Capability:** `commits.getComment`.

```ts
commits.getComment(ref: CommitCommentRef, options?: BaseOptions): Promise<CommitComment>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcommentref">
        <code>
          CommitCommentRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<CommitComment>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcomment)

### `commits.createComment()`

Comments on a commit.

**Capability:** `commits.createComment`. Read-only and anonymous providers reject it.

```ts
commits.createComment(ref: CommitRef, body: string, options?: BaseOptions): Promise<CommitComment>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitref">
        <code>
          CommitRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        body
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<CommitComment>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcomment)

### `commits.updateComment()`

Replaces the body of a comment on a commit.

**Capability:** `commits.updateComment`. Read-only and anonymous providers reject it.

```ts
commits.updateComment(ref: CommitCommentRef, body: string, options?: BaseOptions): Promise<CommitComment>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcommentref">
        <code>
          CommitCommentRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        body
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<CommitComment>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcomment)

### `commits.deleteComment()`

Deletes a comment on a commit. A repeat can reject with `NotFoundError` once the comment is gone.

**Capability:** `commits.deleteComment`. Read-only and anonymous providers reject it.

```ts
commits.deleteComment(ref: CommitCommentRef, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcommentref">
        <code>
          CommitCommentRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

### `commits.hideComment()`

Hides a comment on a commit behind a note of the reason, as `threads.hideComment()` does for a thread comment. A repeat leaves it hidden.

**Capability:** `commits.hideComment`. Read-only and anonymous providers reject it.

```ts
commits.hideComment(ref: CommitCommentRef, reason: HideCommentReason, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcommentref">
        <code>
          CommitCommentRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        reason
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#hidecommentreason">
        <code>
          HideCommentReason
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

### `commits.unhideComment()`

Shows a hidden comment on a commit again. A repeat leaves it shown.

**Capability:** `commits.hideComment`. Read-only and anonymous providers reject it.

```ts
commits.unhideComment(ref: CommitCommentRef, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitcommentref">
        <code>
          CommitCommentRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

## `provider.releases`

Reading, creating and updating the releases of a repository, and downloading their assets.

### `releases.list()`

Lists the releases of a repository, including drafts and pre-releases where the credential can see them.

**Capability:** `releases.list`.

```ts
releases.list(repo: RepoRef, options?: PageOptions): ForgeListing<Release>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Release>`

<api-explorer verb="releases.list">



</api-explorer>

### `releases.get()`

Reads a release by its ref.

**Capability:** `releases.get`.

```ts
releases.get(ref: ReleaseRef, options?: BaseOptions): Promise<Release>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseref">
        <code>
          ReleaseRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Release>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#release)

<api-explorer verb="releases.get">



</api-explorer>

### `releases.getByTag()`

The release for a tag name.

**Capability:** `releases.getByTag`.

```ts
releases.getByTag(repo: RepoRef, tag: string, options?: BaseOptions): Promise<Release>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        tag
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Release>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#release)

<api-explorer verb="releases.getByTag">



</api-explorer>

### `releases.downloadAsset()`

Downloads a release asset, as a stream of its bytes, a `Uint8Array` with `as: 'binary'` or a string with
`as: 'text'`. A redirect to a CDN host is followed without the `Authorization` header, which those hosts reject.

**Example**

```ts
const release = await provider.releases.getByTag(repo, 'v1.0.0')
const asset = release.assets?.find(asset => asset.name.endsWith('.pdf'))
if (asset?.ref) {
  const bytes = await provider.releases.downloadAsset(asset.ref, { as: 'binary' })
}
```

**Capability:** `releases.downloadAsset`.

**Overload 1 of 3**

```ts
releases.downloadAsset(ref: ReleaseAssetRef, options?: DownloadAssetOptions & { as?: 'stream' }): Promise<ReadableStream<Uint8Array>>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseassetref">
        <code>
          ReleaseAssetRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#downloadassetoptions">
        <code>
          DownloadAssetOptions & { as?: 'stream' }
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<ReadableStream<Uint8Array>>`

**Overload 2 of 3**

```ts
releases.downloadAsset(ref: ReleaseAssetRef, options: DownloadAssetOptions & { as: 'binary' }): Promise<Uint8Array>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseassetref">
        <code>
          ReleaseAssetRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#downloadassetoptions">
        <code>
          DownloadAssetOptions & { as: 'binary' }
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<Uint8Array>`

**Overload 3 of 3**

```ts
releases.downloadAsset(ref: ReleaseAssetRef, options: DownloadAssetOptions & { as: 'text' }): Promise<string>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseassetref">
        <code>
          ReleaseAssetRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#downloadassetoptions">
        <code>
          DownloadAssetOptions & { as: 'text' }
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<string>`

<api-explorer verb="releases.downloadAsset">



</api-explorer>

### `releases.latest()`

The most recent published release that is not a draft or prerelease, if any.

**Capability:** `releases.latest`.

```ts
releases.latest(repo: RepoRef, options?: BaseOptions): Promise<Release | undefined>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Release | undefined>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#release)

<api-explorer verb="releases.latest">



</api-explorer>

### `releases.create()`

Creates a release, and its tag from `target` when the tag does not exist yet. A repeat for the same tag rejects on
forges that hold one release per tag; read it back with `getByTag()`.

**Example**

```ts
const release = await provider.releases.create(repo, { tag: 'v1.2.0', body: notes, draft: true })
```

**Capability:** `releases.create`. Read-only and anonymous providers reject it.

```ts
releases.create(repo: RepoRef, input: ReleaseInput, options?: BaseOptions): Promise<Release>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      The repository to release.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        input
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseinput">
        <code>
          ReleaseInput
        </code>
      </a>
    </td>
    
    <td>
      The tag, the name, the notes and whether the release is a draft or a prerelease.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Release>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#release)

**Throws:**

- `UnsupportedOperationError` for `draft: true` or `prerelease: true` on a forge without drafts or prereleases.

### `releases.update()`

Changes a release. Fields left out stay as they are, so `{ draft: false }` publishes a draft.

**Capability:** `releases.update`. Read-only and anonymous providers reject it.

```ts
releases.update(ref: ReleaseRef, update: ReleaseUpdate, options?: BaseOptions): Promise<Release>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseref">
        <code>
          ReleaseRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#releaseupdate">
        <code>
          ReleaseUpdate
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Release>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#release)

**Throws:**

- `UnsupportedOperationError` for a change the forge cannot make, such as a new tag on GitLab.
- `ForbiddenError` with reason `immutable_release` when the forge refuses the write because the
release is immutable (GitHub); its name, notes, prerelease and `latest` flags stay editable.

## `provider.users`

Reading accounts.

### `users.get()`

Reads an account by login, without needing a credential where the forge allows it.

**Capability:** `users.get`.

```ts
users.get(login: string, options?: BaseOptions): Promise<User>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<User>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#user)

<api-explorer verb="users.get">



</api-explorer>

### `users.me()`

The account the provider's credential belongs to.

**Example**

```ts
const me = await provider.users.me()
console.log(me.login)
```

**Capability:** `users.me`. Anonymous providers reject it.

```ts
users.me(options?: BaseOptions): Promise<User>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<User>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#user)

<api-explorer verb="users.me">



</api-explorer>

### `users.sponsorable()`

Whether an account accepts sponsorship on the forge, such as through a GitHub Sponsors listing. Rejects with
`NotFoundError` when no account has the login.

**Example**

```ts
if (await provider.users.sponsorable('danielroe')) {
  console.log('https://github.com/sponsors/danielroe')
}
```

**Capability:** `users.sponsorable`. Anonymous providers reject it.

```ts
users.sponsorable(login: string, options?: BaseOptions): Promise<boolean>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The account to check.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<boolean>`

<api-explorer verb="users.sponsorable">



</api-explorer>

### `users.events()`

Lists what an account did across the repositories the credential can see, in the feed's order as for
`ReposApi.events`, with the same conditional requests and throttling. Each event has `source: 'poll'`.

**Capability:** `users.events`.

```ts
users.events(login: string, options?: EventFeedOptions): ForgeListing<ForgeEvent>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#eventfeedoptions">
        <code>
          EventFeedOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<ForgeEvent>`

<api-explorer verb="users.events">



</api-explorer>

### `users.block()`

Blocks an account on behalf of the account the credential belongs to. A repeat can reject with a
`ForgeApiError` with `status` 422.

**Capability:** `users.block`. Read-only and anonymous providers reject it.

```ts
users.block(login: string, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The account to block.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

<api-explorer verb="users.block">



</api-explorer>

### `users.unblock()`

Unblocks an account that `block()` blocked. A repeat can reject with a `ForgeApiError` with `status` 422.

**Capability:** `users.block`. Read-only and anonymous providers reject it.

```ts
users.unblock(login: string, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

<api-explorer verb="users.unblock">



</api-explorer>

## `provider.installations`

The installations of the app that the provider authenticates as.

### `installations.list()`

Lists the installations of the app.

**Capability:** `installations.list`. Anonymous providers reject it.

```ts
installations.list(options?: PageOptions): ForgeListing<Installation>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Installation>`

### `installations.get()`

Reads one installation.

**Capability:** `installations.list`. Anonymous providers reject it.

```ts
installations.get(installation: Installation | string, options?: BaseOptions): Promise<Installation>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        installation
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#installation">
        <code>
          Installation | string
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Installation>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#installation)

### `installations.token()`

Mints (or reuses a cached) installation token.

**Capability:** `installations.list`. Anonymous providers reject it.

```ts
installations.token(installation: Installation | string, options?: BaseOptions): Promise<InstallationToken>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        installation
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#installation">
        <code>
          Installation | string
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<InstallationToken>`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#installationtoken)

### `installations.repos()`

Lists the repositories that an installation can access.

**Capability:** `installations.list`. Anonymous providers reject it.

```ts
installations.repos(installation: Installation | string, options?: PageOptions): ForgeListing<Repo>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        installation
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#installation">
        <code>
          Installation | string
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Repo>`

### `installations.provider()`

Provider authenticated as one installation, sharing this instance's app credentials.

**Capability:** `installations.list`. Anonymous providers reject it.

```ts
installations.provider(installation: Installation | string): ForgeProvider
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        installation
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#installation">
        <code>
          Installation | string
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`ForgeProvider`](https://forgeslink-3mwmle35v-poetry.vercel.app/reference/provider)

### `installations.providers()`

One provider per installation.

**Capability:** `installations.list`. Anonymous providers reject it.

```ts
installations.providers(): AsyncIterable<{ installation: Installation, provider: ForgeProvider }>
```

**Returns:** `AsyncIterable<{ installation: Installation, provider: ForgeProvider }>`

## `provider.orgs`

The teams of an organisation and their members. An organisation is a
namespace ref, as `repos.byOwner()` takes one. GitLab has no teams of its
own, so its subgroups play the role of teams and their members are the
subgroup's members.

### `orgs.teams()`

Lists the teams of an organisation.

**Capability:** `orgs.teams`.

```ts
orgs.teams(org: RepoRef, options?: PageOptions): ForgeListing<Team>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        org
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      A namespace ref, such as <code>
        namespaceRef(provider, 'acme')
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Team>`

<api-explorer verb="orgs.teams">



</api-explorer>

### `orgs.teamMembers()`

Lists the members of a team, as actors.

**Capability:** `orgs.teamMembers`. Anonymous providers reject it.

```ts
orgs.teamMembers(team: TeamRef, options?: PageOptions): ForgeListing<Actor>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        team
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#teamref">
        <code>
          TeamRef
        </code>
      </a>
    </td>
    
    <td>
      A team's <code>
        ref
      </code>
      
       from <code>
        teams()
      </code>
      
      , or a ref with only <code>
        org
      </code>
      
       and <code>
        slug
      </code>
      
      , such as <code>
        { forge, instance, org, slug: 'stewards' }
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#pageoptions">
        <code>
          PageOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Actor>`

<api-explorer verb="orgs.teamMembers">



</api-explorer>

### `orgs.block()`

Blocks an account from the repositories of an organisation. A repeat can reject with a `ForgeApiError` with
`status` 422.

**Example**

```ts
await provider.orgs.block(namespaceRef(provider, 'acme'), 'spammer')
```

**Capability:** `orgs.block`. Read-only and anonymous providers reject it.

```ts
orgs.block(org: RepoRef, login: string, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        org
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      A namespace ref, as for <code>
        teams()
      </code>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The account to block.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
    
    <td>
      
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

<api-explorer verb="orgs.block">



</api-explorer>

### `orgs.unblock()`

Unblocks an account that `block()` blocked. A repeat can reject with a `ForgeApiError` with `status` 422.

**Capability:** `orgs.block`. Read-only and anonymous providers reject it.

```ts
orgs.unblock(org: RepoRef, login: string, options?: BaseOptions): Promise<void>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        org
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        login
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `Promise<void>`

<api-explorer verb="orgs.unblock">



</api-explorer>

## `provider.search`

Searching issues and pull requests, repositories, commits and code across the forge.

### `search.threads()`

Issues and pull requests across repositories. Fields the forge cannot
filter on come back as a `filter_unsupported` warning on the page.

**Capability:** `search.threads`.

```ts
search.threads(query: ThreadSearchQuery): ForgeListing<Thread>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#threadsearchquery">
        <code>
          ThreadSearchQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Thread>`

<api-explorer verb="search.threads">



</api-explorer>

### `search.repos()`

Searches repositories.

**Capability:** `search.repos`.

```ts
search.repos(query: RepoSearchQuery): ForgeListing<Repo>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#reposearchquery">
        <code>
          RepoSearchQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Repo>`

<api-explorer verb="search.repos">



</api-explorer>

### `search.commits()`

Commits across repositories, where the forge indexes them.

**Capability:** `search.commits`.

```ts
search.commits(query: CommitSearchQuery): ForgeListing<Commit>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#commitsearchquery">
        <code>
          CommitSearchQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Commit>`

<api-explorer verb="search.commits">



</api-explorer>

### `search.code()`

Searches the contents of files, where the forge indexes them.

**Capability:** `search.code`.

```ts
search.code(query: CodeSearchQuery): ForgeListing<CodeMatch>
```

<table>
<thead>
  <tr>
    <th>
      Parameter
    </th>
    
    <th>
      Type
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        query
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-3mwmle35v-poetry.vercel.app/reference/data-model#codesearchquery">
        <code>
          CodeSearchQuery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<CodeMatch>`


## Sitemap

See the full [sitemap](https://forgeslink-3mwmle35v-poetry.vercel.app/sitemap.md) for all pages.