kosa8 docs

Guides / kosa8 Cloud / Pipelines

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 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"
FieldWhat it is
repo_urlAn https:// clone URL, with no credentials in it.
refBranch, tag, commit SHA or refs/… (default main).
eventworkflow_dispatch (default), push, pull_request or schedule: what the file's on: is checked against, and the event act is given.
secretskosa8 secret names to give the jobs (see Secrets).
token_secretA secret holding a token that can read the repository, for private repositories.
status_secretA secret holding a GitHub token with commit status write: the run sets kosa8/pipelines on the commit (pending, then success or failure).
timeout_sThe whole run's limit: default 3600, at most 21600 (6 hours).
workflow, job, inputs, sizeact 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]

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, 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}'

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/workflows through act

Without .kosa8/pipeline.yml, a run installs act (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.

Limits and billing