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"
| 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 withneedswait 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.timeouttakes seconds or30s,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. - artifacts are paths in the repository, kept as a
.tar.gzeach (up to 50 MiB) after the job ends:GET /v1/pipelines/runs/{id}/artifactslists 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, 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-tokenis$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 togitfor 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 typeapplication/json; secret: the hook'ssecret(shown once); events: pushes and pull requests. Deliveries are checked withX-Hub-Signature-256and run once each, even when GitHub retries. - GitLab: Settings → Webhooks, with the hook's
secretas the secret token, for push events. - A pull request (opened, synchronized, reopened) runs
refs/pull/N/headat the head commit withevent: pull_request, checked againston.pull_request.branchesby the base branch. Branch deletes and tags are ignored. cron(UTC) also starts a run ofcron_ref(defaultmain) withevent: schedule.
.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.
uses:actions are fetched by act from github.com over git, as GitHub does.actions/checkout,actions/setup-goandactions/setup-nodework.- macOS and Windows jobs are skipped, and shown as skipped.
- Docker is not available to act yet: jobs with
container:orservices:, anddocker://or Dockerfile actions, fail; the run's log warns about them first. Use.kosa8/pipeline.ymlfor those, where a job can setdocker: trueonce hosts run Docker inside sandboxes. - Workflow features act does not implement (some
githubcontext fields, caches throughactions/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 itstimeout. - 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.