---
title: "Notifications, webhooks and CI"
description: "Notifications, webhooks, checks, CI runs and security alerts."
canonical_url: "https://forgeslink-jzihiqmen-poetry.vercel.app/reference/notifications"
---
# Notifications, webhooks and CI

> Notifications, webhooks, checks, CI runs and security alerts.

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

## `provider.notifications`

Reading and clearing the notifications of the authenticated account.

### `notifications.list()`

Lists the account's notifications.

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

```ts
notifications.list(options?: NotificationListOptions): ForgeListing<Notification>
```

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

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#notificationlistoptions">
        <code>
          NotificationListOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** `ForgeListing<Notification>`

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



</api-explorer>

### `notifications.markRead()`

Marks a notification as read.

**Capability:** `notifications.markRead`. Read-only and anonymous providers reject it.

```ts
notifications.markRead(ref: NotificationRef, 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-jzihiqmen-poetry.vercel.app/reference/data-model#notificationref">
        <code>
          NotificationRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="notifications.markRead">



</api-explorer>

### `notifications.markDone()`

Marks a notification as done, which clears it from the inbox where the forge has that state.

**Capability:** `notifications.markDone`. Read-only and anonymous providers reject it.

```ts
notifications.markDone(ref: NotificationRef, options?: NotificationWriteOptions): 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-jzihiqmen-poetry.vercel.app/reference/data-model#notificationref">
        <code>
          NotificationRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#notificationwriteoptions">
        <code>
          NotificationWriteOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="notifications.markDone">



</api-explorer>

### `notifications.unsubscribe()`

Stops notifications for the notification's thread, and on some forges also clears the notification.

**Capability:** `notifications.unsubscribe`. Read-only and anonymous providers reject it.

```ts
notifications.unsubscribe(ref: NotificationRef, options?: NotificationWriteOptions): 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-jzihiqmen-poetry.vercel.app/reference/data-model#notificationref">
        <code>
          NotificationRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#notificationwriteoptions">
        <code>
          NotificationWriteOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="notifications.unsubscribe">



</api-explorer>

### `notifications.markAllRead()`

Marks every notification as read, or those of one repository.

**Capability:** `notifications.markAllRead`. Read-only and anonymous providers reject it.

```ts
notifications.markAllRead(options?: BulkNotificationOptions): Promise<void>
```

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

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#bulknotificationoptions">
        <code>
          BulkNotificationOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="notifications.markAllRead">



</api-explorer>

### `notifications.markAllDone()`

Marks every notification as done, or those of one repository.

**Capability:** `notifications.markAllDone`. Read-only and anonymous providers reject it.

```ts
notifications.markAllDone(options?: BulkNotificationOptions): Promise<void>
```

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

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#bulknotificationoptions">
        <code>
          BulkNotificationOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="notifications.markAllDone">



</api-explorer>

### `notifications.unreadCount()`

The number of unread notifications.

**Capability:** `notifications.unreadCount`. Anonymous providers reject it.

```ts
notifications.unreadCount(options?: BaseOptions): Promise<number>
```

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

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

**Returns:** `Promise<number>`

<api-explorer verb="notifications.unreadCount">



</api-explorer>

## `provider.sources`

Long-lived push streams of events.

### `sources.stream()`

Push delivery over a long-lived connection. Iteration ends when the signal
aborts or the consumer stops iterating; a dropped connection throws
`StreamClosedError` carrying the last cursor. There is no automatic
reconnection.

**Capability:** `sources.stream`.

```ts
sources.stream(options?: StreamOptions): AsyncIterable<StreamItem>
```

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

<tbody>
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#streamoptions">
        <code>
          StreamOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`AsyncIterable<StreamItem>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#streamitem)

## `provider.webhooks`

Receiving webhook deliveries, and managing the hooks registered on the forge.

### `webhooks.verify()`

Checks a delivery's signature or token against the secret.

**Capability:** `webhooks.ingest`.

```ts
webhooks.verify(delivery: WebhookDelivery): Promise<boolean>
```

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

<tbody>
  <tr>
    <td>
      <code>
        delivery
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookdelivery">
        <code>
          WebhookDelivery
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

### `webhooks.ingest()`

Verifies the delivery, then translates it into normalised events.

**Example**

```ts
const events = await provider.webhooks.ingest({
  headers: request.headers,
  body: await request.text(),
})
```

**Capability:** `webhooks.ingest`.

```ts
webhooks.ingest(delivery: WebhookDelivery): Promise<ForgeEvent[]>
```

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

<tbody>
  <tr>
    <td>
      <code>
        delivery
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookdelivery">
        <code>
          WebhookDelivery
        </code>
      </a>
    </td>
    
    <td>
      The headers and the raw body of the request, exactly as received.
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<ForgeEvent[]>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#forgeevent)

### `webhooks.events`

Normalised kinds and actions this provider can deliver, whatever a hook is subscribed to.

**type:** [`WebhookEventType[]`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookeventtype)

### `webhooks.list()`

Hooks on a repository, or on an organisation or workspace when `target` is a namespace ref.

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

```ts
webhooks.list(target: RepoRef, options?: PageOptions): ForgeListing<Webhook>
```

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

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

**Returns:** `ForgeListing<Webhook>`

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



</api-explorer>

### `webhooks.create()`

Registers a webhook. A repeat registers a second one, or rejects where the forge refuses a second hook for the same URL.

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

```ts
webhooks.create(target: RepoRef, input: WebhookInput, options?: BaseOptions): Promise<Webhook>
```

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

<tbody>
  <tr>
    <td>
      <code>
        target
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        input
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookinput">
        <code>
          WebhookInput
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Webhook>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhook)

<api-explorer verb="webhooks.create">



</api-explorer>

### `webhooks.update()`

Changes a webhook.

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

```ts
webhooks.update(ref: WebhookRef, update: WebhookUpdate, options?: BaseOptions): Promise<Webhook>
```

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

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookref">
        <code>
          WebhookRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        update
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookupdate">
        <code>
          WebhookUpdate
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Webhook>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhook)

<api-explorer verb="webhooks.update">



</api-explorer>

### `webhooks.delete()`

Deletes a webhook. A repeat can reject with `NotFoundError` once the webhook is gone.

**Capability:** `webhooks.delete`. Read-only and anonymous providers reject it.

```ts
webhooks.delete(ref: WebhookRef, 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-jzihiqmen-poetry.vercel.app/reference/data-model#webhookref">
        <code>
          WebhookRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="webhooks.delete">



</api-explorer>

### `webhooks.rotateSecret()`

Replaces the signing secret in place. `false` where the forge can only do it by recreating the hook.

**Capability:** `webhooks.rotateSecret`. Read-only and anonymous providers reject it.

```ts
webhooks.rotateSecret(ref: WebhookRef, secret: string, options?: BaseOptions): Promise<Webhook>
```

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

<tbody>
  <tr>
    <td>
      <code>
        ref
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhookref">
        <code>
          WebhookRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        secret
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<Webhook>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#webhook)

<api-explorer verb="webhooks.rotateSecret">



</api-explorer>

### `webhooks.deliveries()`

Lists the recent deliveries of a webhook.

**Capability:** `webhooks.deliveries`. Anonymous providers reject it.

```ts
webhooks.deliveries(ref: WebhookRef, options?: PageOptions): ForgeListing<WebhookDeliveryRecord>
```

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

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

**Returns:** `ForgeListing<WebhookDeliveryRecord>`

<api-explorer verb="webhooks.deliveries">



</api-explorer>

### `webhooks.redeliver()`

Sends a past delivery again. A repeat sends it once more.

**Capability:** `webhooks.redeliver`. Read-only and anonymous providers reject it.

```ts
webhooks.redeliver(ref: WebhookDeliveryRef, 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-jzihiqmen-poetry.vercel.app/reference/data-model#webhookdeliveryref">
        <code>
          WebhookDeliveryRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="webhooks.redeliver">



</api-explorer>

## `provider.checks`

Reading and reporting the checks on a commit.

### `checks.list()`

Every check on a commit: check runs, commit statuses, jobs or policy evaluations.

**Capability:** `checks.list`.

```ts
checks.list(repo: RepoRef, sha: string, options?: BaseOptions): Promise<Page<Check>>
```

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

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

**Returns:** [`Promise<Page<Check>>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#check)

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



</api-explorer>

### `checks.get()`

Reads one check. Rejects for a `CheckRef.type` the forge cannot read on its own.

**Capability:** `checks.get`.

```ts
checks.get(ref: CheckRef, options?: BaseOptions): Promise<Check>
```

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

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

**Returns:** [`Promise<Check>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#check)

### `checks.report()`

Writes a commit status, or a check run where the credential can (GitHub app auth). A repeat writes a second check
run; a second commit status with the same name takes the place of the first, except on GitLab, which rejects a
repeat of a status that is still pending.

**Capability:** `checks.report`. Read-only and anonymous providers reject it.

```ts
checks.report(repo: RepoRef, sha: string, input: CheckReportInput, options?: BaseOptions): Promise<Check>
```

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

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

**Returns:** [`Promise<Check>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#check)

<api-explorer verb="checks.report">



</api-explorer>

### `checks.rerun()`

Re-runs a check. Rejects for a `CheckRef.type` the forge cannot re-run. A repeat can start another run.

**Capability:** `checks.rerun`. Read-only and anonymous providers reject it.

```ts
checks.rerun(ref: CheckRef, 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-jzihiqmen-poetry.vercel.app/reference/data-model#checkref">
        <code>
          CheckRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="checks.rerun">



</api-explorer>

## `provider.ci`

Reading CI runs and their jobs, and re-running the jobs that failed.

### `ci.runs()`

Lists the CI runs of a repository.

**Capability:** `ci.runs`.

```ts
ci.runs(repo: RepoRef, query?: CiRunQuery): ForgeListing<CiRun>
```

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

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

**Returns:** `ForgeListing<CiRun>`

<api-explorer verb="ci.runs">



</api-explorer>

### `ci.getRun()`

Reads one CI run.

**Capability:** `ci.getRun`.

```ts
ci.getRun(ref: CiRunRef, options?: BaseOptions): Promise<CiRun>
```

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

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

**Returns:** [`Promise<CiRun>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#cirun)

<api-explorer verb="ci.getRun">



</api-explorer>

### `ci.jobs()`

Lists the jobs of a CI run.

**Capability:** `ci.jobs`.

```ts
ci.jobs(ref: CiRunRef, options?: PageOptions): ForgeListing<CiJob>
```

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

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

**Returns:** `ForgeListing<CiJob>`

<api-explorer verb="ci.jobs">



</api-explorer>

### `ci.getJob()`

Reads one CI job. Where the forge has no endpoint for it (`capabilities.ci.getJob` is `'emulated'`), it lists the jobs
of the ref's `run` page by page until the id matches, which costs a request for each page read, so the ref must
name its run.

**Capability:** `ci.getJob`.

```ts
ci.getJob(ref: CiJobRef, options?: BaseOptions): Promise<CiJob>
```

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

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

**Returns:** [`Promise<CiJob>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#cijob)

### `ci.log()`

The job's log as it arrives.

**Capability:** `ci.log`.

```ts
ci.log(ref: CiJobRef, options?: BaseOptions): 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-jzihiqmen-poetry.vercel.app/reference/data-model#cijobref">
        <code>
          CiJobRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="ci.log">



</api-explorer>

### `ci.rerunFailed()`

Re-runs the jobs of a CI run that failed, and the jobs that depend on them. A repeat can start another attempt.

**Capability:** `ci.rerunFailed`. Read-only and anonymous providers reject it.

```ts
ci.rerunFailed(ref: CiRunRef, 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-jzihiqmen-poetry.vercel.app/reference/data-model#cirunref">
        <code>
          CiRunRef
        </code>
      </a>
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
    </td>
  </tr>
</tbody>
</table>

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

<api-explorer verb="ci.rerunFailed">



</api-explorer>

## `provider.securityAlerts`

Reading the security alerts of a repository.

### `securityAlerts.list()`

Lists the security alerts of a repository.

**Capability:** `securityAlerts.list`.

```ts
securityAlerts.list(repo: RepoRef, options?: SecurityAlertListOptions): ForgeListing<SecurityAlert>
```

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

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

**Returns:** `ForgeListing<SecurityAlert>`

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



</api-explorer>

## Checks helpers

Import from `forges/helpers`. It only needs `checks.list()`, so it works on any forge that has it.

### `WaitForChecksOptions`

Options for [`waitForChecks`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/notifications#waitforchecks).

**extends:** [`BaseOptions`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions)

<table>
<thead>
  <tr>
    <th>
      Member
    </th>
    
    <th>
      Type
    </th>
    
    <th>
      Default
    </th>
    
    <th>
      Description
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        timeout?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        600000
      </code>
    </td>
    
    <td>
      Milliseconds before it gives up. <code>
        Infinity
      </code>
      
       waits for good.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        interval?
      </code>
    </td>
    
    <td>
      <code>
        number
      </code>
    </td>
    
    <td>
      <code>
        15000
      </code>
    </td>
    
    <td>
      Milliseconds between reads. Each read is a <code>
        checks.list()
      </code>
      
      , so mind the rate limit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        signal?
      </code>
    </td>
    
    <td>
      <code>
        AbortSignal
      </code>
    </td>
    
    <td>
      
    </td>
    
    <td>
      Aborts the operation's requests, and the operation rejects with the signal's reason. Writes the forge has already received are not undone. Inherited from <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#baseoptions">
        <code>
          BaseOptions
        </code>
      </a>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `WaitForChecksResult`

What [`waitForChecks`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/notifications#waitforchecks) found on its last read.

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

<tbody>
  <tr>
    <td>
      <code>
        timedOut
      </code>
    </td>
    
    <td>
      <code>
        boolean
      </code>
    </td>
    
    <td>
      Time ran out with checks still running, or with none at all.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        state
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#checkssummary">
        <code>
          ChecksSummary['state']
        </code>
      </a>
    </td>
    
    <td>
      Summed up like <code>
        Thread.checks
      </code>
      
      : <code>
        failure
      </code>
      
       when any check failed, even if others are still pending at the timeout, and <code>
        unknown
      </code>
      
       when the commit has no checks.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        checks
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#check">
        <code>
          Check[]
        </code>
      </a>
    </td>
    
    <td>
      Every check from the last read.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        pending
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#check">
        <code>
          Check[]
        </code>
      </a>
    </td>
    
    <td>
      The checks from the last read that were still running.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        warnings?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/requests#forgewarning">
        <code>
          ForgeWarning[]
        </code>
      </a>
    </td>
    
    <td>
      Sources the last read could not reach, whose checks are missing from <code>
        checks
      </code>
      
       and <code>
        state
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

### `waitForChecks()`

Polls `checks.list()` until every check on the commit has finished, or `timeout` runs out. No checks yet counts as
pending, and `neutral` or `unknown` as finished; a failure does not end the wait. It sees only the checks a read
returns, so a check that registers late, or one that a read with `warnings` leaves out, can still be running.

**Example**

```ts
import { waitForChecks } from 'forges/helpers'

const { state, timedOut, warnings } = await waitForChecks(provider, repo, sha)
```

```ts
function waitForChecks(provider: ForgeProvider, repo: RepoRef, sha: string, options: WaitForChecksOptions = {}): Promise<WaitForChecksResult>
```

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

<tbody>
  <tr>
    <td>
      <code>
        provider
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/provider">
        <code>
          ForgeProvider
        </code>
      </a>
    </td>
    
    <td>
      The provider to read the checks with.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        repo
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/data-model#reporef">
        <code>
          RepoRef
        </code>
      </a>
    </td>
    
    <td>
      The repository of the commit.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        sha
      </code>
    </td>
    
    <td>
      <code>
        string
      </code>
    </td>
    
    <td>
      The commit to wait for.
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        options?
      </code>
    </td>
    
    <td>
      <a href="https://forgeslink-jzihiqmen-poetry.vercel.app/reference/notifications#waitforchecksoptions">
        <code>
          WaitForChecksOptions
        </code>
      </a>
    </td>
    
    <td>
      The <code>
        timeout
      </code>
      
      , the <code>
        interval
      </code>
      
       between reads, and a <code>
        signal
      </code>
      
       to stop waiting. Defaults to <code>
        {}
      </code>
      
      .
    </td>
  </tr>
</tbody>
</table>

**Returns:** [`Promise<WaitForChecksResult>`](https://forgeslink-jzihiqmen-poetry.vercel.app/reference/notifications#waitforchecksresult)


## Sitemap

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