# kosa8 Pipelines

CI that runs on kosa8 Cloud and nowhere else. Your git host (GitHub, GitLab or any HTTPS git server) is only where the code is: a run clones it, and a push can start one through a webhook. Each job runs in a sized sandbox of your organization, deleted when the job ends, and billed by the second like any sandbox. No GitHub Actions minutes, no GitHub-hosted runners.

**Two kinds of file.** A repository with `.kosa8/pipeline.yml` runs that file: the kosa8 format below, each job in its own sandbox. A repository without one runs its `.github/workflows` through [act](https://github.com/nektos/act) in one sandbox, so workflows you already have work with no changes, within the limits listed at the end.

## Start a run

```
# from a checkout: this repository's origin, this branch; prints the logs, exits non-zero on failure
kosa8 ci run
kosa8 ci run --ref v1.4.0 --secret npm-token
kosa8 ci ls
kosa8 ci logs prun_… --follow
kosa8 ci cancel prun_…
```

Or through the API (the `sandboxes:write` scope):

```
curl -s -X POST https://api.kosa8.com/v1/pipelines/runs \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"repo_url":"https://github.com/acme/app.git","ref":"main","secrets":["npm-token"]}'
curl -s https://api.kosa8.com/v1/pipelines/runs/prun_… -H "Authorization: Bearer $KOSA8_API_KEY"
curl -s "https://api.kosa8.com/v1/pipelines/runs/prun_…/logs?job=test" -H "Authorization: Bearer $KOSA8_API_KEY"
```

| Field | What it is |
|---|---|
| `repo_url` | An `https://` clone URL, with no credentials in it. |
| `ref` | Branch, tag, commit SHA or `refs/…` (default `main`). |
| `event` | `workflow_dispatch` (default), `push`, `pull_request` or `schedule`: what the file's `on:` is checked against, and the event act is given. |
| `secrets` | kosa8 secret names to give the jobs (see Secrets). |
| `token_secret` | A secret holding a token that can read the repository, for private repositories. |
| `status_secret` | A secret holding a GitHub token with commit status write: the run sets `kosa8/pipelines` on the commit (pending, then success or failure). |
| `timeout_s` | The whole run's limit: default 3600, at most 21600 (6 hours). |
| `workflow`, `job`, `inputs`, `size` | act runs only: one workflow file, one job id, `workflow_dispatch` inputs, and the sandbox size (default `4x8`). |

A run is `queued` until its file is read, then `running`, then `success`, `failure`, `cancelled`, `error` (it could not run: a bad file, a missing secret) or `skipped` (the file's `on:` does not take this event or branch). Each job reports its state, exit code, duration and, for native jobs, each step's.

## .kosa8/pipeline.yml

```
name: app CI
on:
  push:
    branches: [main, "release/*"]
  pull_request:
    branches: [main]
  schedule:
    - cron: "0 3 * * *"       # also needs a hook with a cron (below)
  manual: true                # runs asked for through the API or kosa8 ci
size: 2x4                     # default for every job
image: kosa8-template/universal-24.04-20261114.1
env:
  CI: "1"
secrets: [npm-token]          # every job gets $NPM_TOKEN
timeout: 40m

jobs:
  lint:
    steps:
      - run: npm ci && npm run lint
  test:
    size: 8x16
    secrets: [database-url]   # only this job gets $DATABASE_URL
    steps:
      - name: Install
        run: npm ci
      - name: Test
        run: npm test
        timeout: 15m
        env: {NODE_ENV: test}
    artifacts: [coverage]
  build:
    needs: [lint, test]
    steps:
      - run: npm run build
    artifacts: [dist]
```

- **Jobs** run in sandboxes of their own, from a fresh clone of the commit in `/workspace/src`. Jobs with `needs` wait for those jobs to succeed, and are skipped if one does not; the rest run side by side, up to your organization's limit (4 at once unless we raise it for you).

- **Steps** run one after another with `bash -eo pipefail`, in `/workspace/src`. A step that fails stops the job. `timeout` takes seconds or `30s`, `10m`, `2h`. A step is a map, or just the command as a string.

- **size** is one of `2x4`, `4x8`, `8x16`, `16x32` (vCPU x GiB). **image** defaults to the [universal image](https://docs.kosa8.com/guides/cloud-images/).

- **artifacts** are paths in the repository, kept as a `.tar.gz` each (up to 50 MiB) after the job ends: `GET /v1/pipelines/runs/{id}/artifacts` lists them.

- **cache** is accepted and ignored for now (the run says so in its warnings).

- `uses:` is refused in this file: it is GitHub Actions syntax. Keep such steps in `.github/workflows`, without a `.kosa8/pipeline.yml`, and they run through act.

A mistake in the file ends the run as `error` with a message that names the line's key, such as `jobs.test.steps[1]: unknown key with`.

## Secrets

A pipeline uses the organization's [secrets](https://docs.kosa8.com/guides/cloud-secrets/), but differently from a sandbox: a CI job needs the value itself (to publish a package, to reach a test database), not a placeholder. So a secret is given to pipelines only if an admin says so when storing it:

```
curl -s -X PUT https://api.kosa8.com/v1/secrets/npm-token \
  -H "Authorization: Bearer $KOSA8_ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"value":"npm_…","upstream":"https://registry.npmjs.org","pipelines":true}'
```

- A job gets it as an environment variable, upper-cased with `-` as `_`: `npm-token` is `$NPM_TOKEN`, and `${{ secrets.NPM_TOKEN }}` in a workflow run through act.

- Values are never stored with the run, in the audit log or in the job's script. Every log line is stored with each value, and its base64 and URL-encoded forms, replaced by `***` (act also masks them itself). A step that prints a value transformed some other way is not caught, as in any CI.

- `token_secret`'s token is handed to `git` for the clone only, by a credential helper, and removed from the environment before any of your code runs.

## Start runs from pushes, pull requests and a schedule

An admin makes a hook: a URL your git host calls on each push.

```
curl -s -X POST https://api.kosa8.com/v1/pipelines/hooks \
  -H "Authorization: Bearer $KOSA8_ADMIN_KEY" -H 'Content-Type: application/json' \
  -d '{"repo_url":"https://github.com/acme/app.git","secrets":["npm-token"],
       "token_secret":"github-read","status_secret":"github-status","cron":"0 3 * * *"}'
# → {"hook": {"id": "phk_…", "url": "https://api.kosa8.com/v1/pipelines/hooks/phk_…", "secret": "…"}}
```

- **GitHub**: Settings → Webhooks → Add webhook. Payload URL: the hook's `url`; content type `application/json`; secret: the hook's `secret` (shown once); events: pushes and pull requests. Deliveries are checked with `X-Hub-Signature-256` and run once each, even when GitHub retries.

- **GitLab**: Settings → Webhooks, with the hook's `secret` as the secret token, for push events.

- A pull request (opened, synchronized, reopened) runs `refs/pull/N/head` at the head commit with `event: pull_request`, checked against `on.pull_request.branches` by the base branch. Branch deletes and tags are ignored.

- `cron` (UTC) also starts a run of `cron_ref` (default `main`) with `event: schedule`.

## .github/workflows through act

Without `.kosa8/pipeline.yml`, a run installs act ([nektos/act](https://github.com/nektos/act) 0.2.89, its SHA-256 checked) in one sandbox and runs the repository's workflows for the run's event. Linux jobs (`ubuntu-latest`, `ubuntu-24.04`, `ubuntu-22.04`, `self-hosted`, …) run directly in the sandbox, as on a GitHub-hosted runner, with the universal image's tools. Each workflow job is reported as a job of the run, with its own log.

- `uses:` actions are fetched by act from github.com over git, as GitHub does. `actions/checkout`, `actions/setup-go` and `actions/setup-node` work.

- **macOS and Windows jobs are skipped**, and shown as skipped.

- **Docker is not available to act yet**: jobs with `container:` or `services:`, and `docker://` or Dockerfile actions, fail; the run's log warns about them first. Use `.kosa8/pipeline.yml` for those, where a job can set `docker: true` once hosts run Docker inside sandboxes.

- Workflow features act does not implement (some `github` context fields, caches through `actions/cache`'s service, OIDC tokens) behave as they do under act.

## Limits and billing

- Every job's sandbox is made through the same create as any other, as your organization: it needs a payment method, counts toward your running sandboxes and your spending cap, and is refused while the organization is frozen. A refused create ends the job with the reason.

- 4 jobs at once per organization (more on request); jobs over that wait their turn. 50 runs queued or running at most.

- A run lasts at most its `timeout_s` (default 1 hour, at most 6 hours); a job, at most its `timeout`.

- 5 MiB of log per job; the rest is cut, with a note at the end.

- Every run started and cancelled, and every hook made and deleted, is in the audit log.

---
Source: https://docs.kosa8.com/guides/cloud-pipelines/
