# Pipelines

A pipeline on [Skmtc Hub](https://skmtc.dev) makes code for one API when
the API gets a new latest revision. Then the pipeline does its other
actions. It can open a pull request with the code, publish the code as an
npm package, or send a signed webhook with the result. This page tells you how
to make a pipeline, check it, and run it.

One run of a pipeline for one revision is a delivery. The page of a
pipeline (`https://skmtc.dev/{owner}/pipelines/{name}`) shows each delivery
and the result of each action.

## Before you start [#before-you-start]

- Sign in to Hub. A user or an organization owns a pipeline. To make a
  pipeline for an organization, you must be a member of it.
- Find the API on Hub. The pipeline follows the latest revision of that API.
- Find the stack that makes the code. A stack is a set of generators that
  its owner publishes on Hub.
- For a pull request, get access to a GitHub repository. See
  [Add a GitHub credential](#add-a-github-credential).
- For a publish, get a classic GitHub token with the `write:packages` scope.
- For a webhook, have an HTTPS endpoint that can receive the request. See
  [API change webhooks](/docs/api-change-webhooks).

## Create a pipeline [#create-a-pipeline]

1. Open the page of the API on Hub.
2. Open the **Pipelines** menu and select **New pipeline for this API**.
   You can also select **New pipeline** on the **Pipelines** page of your
   account (`https://skmtc.dev/{account}/pipelines`).
3. Under **Subscription**, enter a **Name** for the pipeline. The name must
   be unique in the account.
4. Optional: enter a **Minimum interval** in minutes. Hub skips a revision
   that comes sooner than this after the last delivery. `0` is no limit.
5. Under **Actions**, set up the **Generate** action. In **Select stack**,
   select the stack. Hub makes a private project from the API and the
   stack, and shows its name.
6. Select **Add action** to add a **Pull request**, a **Publish** or a
   **Webhook** action. The fields of each action are in
   [The actions](#the-actions).
7. Select **Create and run now**. Hub saves the pipeline and starts a
   delivery for the current latest revision of the API.

If the pipeline has a webhook action, Hub shows the secret of the webhook
signature. Copy it. Hub shows it one time only.

Hub tells you when no server runs the version of the stack. **Run now**
deploys the server before the delivery, in about 15 seconds. Until then, a
delivery for a new revision fails.

## The actions [#the-actions]

A pipeline has one action of each type or none. The actions run in this
order: **Generate**, **Pull request**, **Publish**, **Webhook**.

| Action | What it does | Fields |
| --- | --- | --- |
| **Generate** | Makes code from the API with the stack, and formats the TypeScript and JavaScript files. Each pipeline must have it. | **Select stack** |
| **Pull request** | Pushes the code to the branch `skmtc/{project}` of the repository, and keeps one pull request open against the base branch. | **Git credential**, **Repository** (`owner/name`), **Base branch**. Without a base branch, Hub uses the default branch of the repository. |
| **Publish** | Compiles the code to JavaScript and type files, and publishes it as a package on the GitHub npm registry (`npm.pkg.github.com`). | **Package name**, scoped and lower case, for example `@acme/stripe-sdk`. **First version**, for example `0.1.0`. **Packages token**. |
| **Webhook** | Sends one signed request with the result of each action to your endpoint. It runs last, also after a failure. | **HTTPS destination** |

- **Pull request** and **Publish** need the code of **Generate**. If you
  skip **Generate**, Hub skips them too.
- The first publish uses the **First version**. Each later delivery
  publishes the next patch version, also when the code did not change.
- Each action has a **Skip** switch. A skipped action keeps its settings
  and does not run.

## Add a GitHub credential [#add-a-github-credential]

A credential belongs to the account that owns the pipeline. A pipeline can
use only the credentials of its own account.

- For a pull request, install the GitHub App. Or add a fine-grained token
  with read and write access to **Contents** and **Pull requests** on the
  repository.
- For a publish, add a classic token with the `write:packages` scope. The
  GitHub npm registry does not accept a fine-grained token.

To add a credential, open the settings of the account. For your own
account, open `https://skmtc.dev/settings/git-credentials`. For an
organization, open `https://skmtc.dev/{organization}/settings`. Then select
**Install the GitHub App**, or select **Add token** and paste the token.

Use a token from a GitHub account that your team shares, not a personal
one. Then the pipeline continues to work when a person leaves the team.

Hub does not let you delete a credential that a pipeline uses. To change a
token, select **Replace**.

## Check a pipeline with a dry run [#check-a-pipeline-with-a-dry-run]

On the page of the pipeline, select **Dry run**. The dry run shows what a
delivery for the latest revision does:

- the files that **Generate** makes;
- the files that the pull request adds or changes, read from the base
  branch;
- the version that **Publish** takes next.

A dry run pushes nothing, publishes nothing and sends nothing. Save your
changes before you do a dry run of them.

## Run, pause, edit or delete a pipeline [#run-pause-edit-or-delete-a-pipeline]

On the page of the pipeline:

- **Run now** starts a delivery for the current latest revision. It does
  not wait for the minimum interval. You cannot use it while you pause the
  pipeline or while a delivery runs.
- **Pause** stops new deliveries. **Resume** starts them again.
- Edit the pipeline to change its subscription or its actions. A change
  applies to the next delivery. A delivery keeps the settings that it
  started with.
- **Delete pipeline** removes the pipeline and its deliveries.

## How deliveries run [#how-deliveries-run]

- A pipeline runs one delivery at a time.
- A delivery for a newer revision stops an older delivery before its push
  and its publish. The status of the older delivery becomes
  **Superseded**, and it sends no webhook.
- The first action that fails stops the delivery. Each action after it
  records **Not run**, but the webhook still runs.
- Five failed deliveries in a row pause the pipeline. A temporary failure,
  for example a GitHub rate limit, does not count. Select **Resume** after
  you fix the cause.

## Use a pipeline from an agent [#use-a-pipeline-from-an-agent]

The [pipeline tools](/docs/mcp#pipeline-tools) of the Skmtc Hub MCP server
list, create, update, run and dry run pipelines, and read deliveries.

## See also [#see-also]

- [API change webhooks](/docs/api-change-webhooks): receive the webhook of
  a pipeline and check its signature.
- [MCP server](/docs/mcp): connect an agent to Hub.