Documentation

Guidance

Getting started, local execution, projects, pipelines, logs, snapshots, artifacts, parameters, cache, Docker builds, and beta testing guidance.

Audience: Beta users
Platforms: Windows, Linux, macOS
Product: Zetken CI/CD Studio (zci)
Status: Beta guidance based on the current implementation

1. What Zetken CI/CD Studio is

Zetken CI/CD Studio is a local-first CI/CD runner. It lets you create, validate, run, inspect, and troubleshoot CI/CD pipelines directly on your computer.

The main idea is simple:

Write or import pipeline
        ↓
Validate locally
        ↓
Run locally
        ↓
Inspect stages / jobs / steps / logs
        ↓
Fix problems before using a remote CI/CD platform

Zetken currently provides:

Zetken currently executes pipeline commands on the same machine where zci is running. There are no remote Zetken runner pools yet.

2. What you receive

Your beta package contains a Zetken executable appropriate for your operating system.

For the examples in this guide, the executable is named:

Windows:       zci.exe
Linux/macOS:   zci

Automatic 60-day beta trial

Zetken starts a 60-day local beta trial automatically on first use. You do not need a license file to begin testing.

The trial works offline and keeps its original start and expiration times across normal restarts and binary updates that use the same Zetken application-data directory. Check the current access state with:

zci license status

After the trial expires, Zetken keeps your existing projects, pipelines, runs, logs, artifacts, and snapshots available in read-only mode. Installing a valid signed Zetken .license file restores or extends full access.

3. Before you start

Zetken itself is a standalone executable.

You do not need Node.js, Java, Docker, Kubernetes, or a database simply to open Zetken.

However, pipeline commands execute locally, so every external tool used by your pipeline must be installed on your machine.

Examples:

go
node / npm
python
java
docker
terraform
kubectl
git
bash
powershell
pwsh

For example:

run: terraform validate

requires Terraform to be installed and available on PATH.

Check local tools with:

zci doctor

4. Start Zetken

Windows

Open PowerShell in the folder containing zci.exe.

.\zci.exe version
.\zci.exe doctor
.\zci.exe serve

Linux

Make the binary executable once:

chmod +x ./zci

Then:

./zci version
./zci doctor
./zci serve

macOS

chmod +x ./zci
./zci version
./zci doctor
./zci serve

5. Open the Web UI

By default, Zetken starts at:

http://127.0.0.1:37687

You can also use:

zci serve --open

or another port:

zci serve --port 37688

The normal beta configuration binds to 127.0.0.1, so the UI is available only on your local machine.

Do not expose the beta UI to an untrusted network.

6. Check Zetken paths

Use:

zci paths

or:

zci paths --json

Default project workspace

Windows:

%USERPROFILE%\ZetkenProjects

Linux/macOS:

~/ZetkenProjects

A managed project normally contains pipelines like:

ZetkenProjects/
└── my-project/
    └── pipelines/
        └── my-pipeline/
            ├── pipeline.yaml
            └── .zetken-ci/

.zetken-ci contains local runtime information such as builds, logs, artifacts, snapshots, and cache.

Application data and server logs

Windows:

%LOCALAPPDATA%\Zetken
%LOCALAPPDATA%\Zetken\logs\ui-server.log

Linux:

~/.local/share/zetken
~/.local/share/zetken/logs/ui-server.log

When XDG_DATA_HOME is set, Linux uses:

$XDG_DATA_HOME/zetken

macOS:

~/Library/Application Support/Zetken
~/Library/Application Support/Zetken/logs/ui-server.log

After starting Zetken:

Projects
→ Create project
→ Open project
→ Create pipeline
→ Use a Zetken template
→ Basic
→ Create
→ Editor
→ Validate
→ Run pipeline
→ Open the new run
→ Inspect logs
→ Open Snapshots

This confirms that the main workflow works before testing a complex real pipeline.

8. Create a project

From Projects, select:

Create project

Enter:

Then select Create.

The new project is stored in the managed Zetken projects workspace.

9. Create a pipeline

Inside a project, select:

Create pipeline

Three creation methods are available:

Start with a blank pipeline

Use this when you want to write native Zetken YAML yourself.

Use a Zetken template

Use one of the available starter templates, such as:

Basic
Go
Node
Docker
Matrix
Cache
Parameters
Artifacts

Templates are starting points and can be edited afterward.

Import an existing pipeline

The Migration Assistant currently supports source definitions from:

GitHub Actions
Azure DevOps
Jenkins

Typical flow:

Select source system
→ Upload or paste source definition
→ Analyze pipeline
→ Review Migration analysis
→ Review Generated Zetken pipeline
→ Resolve review/validation issues
→ Create pipeline

The Migration Assistant analyzes the supplied definition locally. It does not need to connect to GitHub, Azure DevOps, or Jenkins, and it does not import secret values.

10. Migration Assistant result types

You may see:

Converted
Requires review
Unsupported
Validation error

Converted means Zetken found a direct supported representation.

Requires review means content was preserved or translated where safe, but some vendor-specific behavior is not fully portable.

Unsupported means the source construct is not represented as executable native Zetken functionality.

Always review the generated Zetken YAML before creation.

GitHub Actions

Common supported areas include:

jobs
needs
run
shell
working-directory
literal env

Vendor-specific constructs such as GitHub contexts, $GITHUB_ENV, $GITHUB_OUTPUT, setup/login actions, environments, and third-party actions may require review.

Azure DevOps

Common mappings include:

stages
jobs
dependsOn
script
bash
powershell
pwsh
supported inline task scripts
literal variables

Service connections, variable groups, approvals/checks, deployment-environment semantics, and unsupported tasks may require manual review.

Jenkins

The supported scope focuses on Jenkins Declarative Pipeline.

Common supported areas include literal stages and supported shell steps. Scripted Pipeline, dynamic Groovy, shared libraries, credentials, approvals, and plugin-specific behavior may require review or be unsupported.

11. Edit and validate YAML

Open a pipeline and choose:

Editor

The editor provides:

Validate
Save
Run pipeline

Use Validate before running after meaningful YAML changes.

Validation checks more than YAML syntax. It also checks Zetken pipeline semantics, including:

Required stages/jobs/steps
Unknown needs dependencies
Dependency cycles
Supported shells
Working directories
Step actions
Variables and expressions
Parameters
Matrix references
Artifact paths
Cache paths
Timeout/retry values

12. Managed pipeline YAML

Pipeline created in the Zetken Studio UI

File:

<project>/pipelines/<pipeline>/pipeline.yaml

Use:

schema: zetken/v1

stages:
  - name: build
    jobs:
      - name: test
        steps:
          - name: Hello
            run: echo hello

The pipeline name is managed by Zetken Studio metadata. Do not add a top-level name: merely to duplicate the UI pipeline name.

13. Run a pipeline

From the pipeline page select:

Run pipeline

or from the Editor:

Validate
→ Save
→ Run pipeline

The execution hierarchy is:

Pipeline
→ Stage
  → Job
    → Step

All commands execute on the local machine.

That means a Windows-specific command may not work on Linux/macOS and vice versa.

Portable example:

- name: Test
  run: go test ./...

Windows-specific example:

shell: powershell
run: |
  New-Item -ItemType Directory -Force output
  Set-Content output\result.txt "done"

Linux/macOS example:

shell: bash
run: |
  mkdir -p output
  echo "done" > output/result.txt

14. Native shell values

Current native Zetken YAML supports:

default
cmd
powershell
pwsh
bash
sh

default resolves approximately as:

Windows       → COMSPEC / cmd.exe
Linux/macOS   → $SHELL, otherwise /bin/sh

The selected shell executable must exist on the machine. Zetken does not install or bundle external shells.

PowerShell versions

powershell selects Windows PowerShell. pwsh selects PowerShell 7+ and is supported on Windows, Linux, and macOS when pwsh is installed and available on PATH.

Zetken keeps the two shell values distinct. Selecting pwsh never silently falls back to powershell.

15. Runs and logs

Open the Runs tab and select a run.

Inspect the exact:

Stage
Job
Step

where the problem occurred.

Active runs can be cancelled. Completed runs can be deleted.

Artifacts for a run are available from the run actions.

When reporting a log problem, include:

Run ID
Stage name
Job name
Step name
Expected log
Actual log/message

16. Snapshots

Open:

Pipeline
→ Snapshots

Pipeline runs create build-linked source snapshots.

The snapshot view shows information such as:

Run/build
Run status
Snapshot status
Created time
Files tracked
Tracked size
Stored content size

After at least two eligible builds, use:

Compare latest two builds

to review source differences.

17. Environment variables

Environment variables can be defined at:

pipeline
stage
job
step

Example:

env:
  APP_ENV: test

stages:
  - name: build
    env:
      COMPONENT: backend
    jobs:
      - name: compile
        steps:
          - name: Show values
            run: echo ${APP_ENV} ${COMPONENT}

Reference environment variables with:

${VARIABLE_NAME}

Environment files are also supported:

envFiles:
  - .env.local

Do not intentionally put .env files, tokens, passwords, private keys, or other secrets into artifacts or cache paths.

18. Runtime parameters

Example:

parameters:
  - name: target
    type: string
    default: dev
    allowed:
      - dev
      - staging
      - prod

  - name: packageName
    type: string
    required: true

Reference:

${params.target}
${params.packageName}

Standalone CLI example:

zci run --param target=prod --param packageName=my-app

Secret parameter:

- name: apiToken
  type: string
  secret: true

Do not persist secret parameter values in artifact paths, cache keys, or cache paths.

19. Dependencies and parallel jobs

Use:

maxParallel: 2

at stage level to allow multiple ready jobs to execute concurrently.

Use:

needs:
  - build

to express dependencies.

Example:

stages:
  - name: ci
    maxParallel: 2
    jobs:
      - name: build
        steps:
          - name: Build
            run: go build ./...

      - name: test
        needs:
          - build
        steps:
          - name: Test
            run: go test ./...

needs references jobs in the same stage.

20. Matrix jobs

Example:

strategy:
  matrix:
    dev:
      target: dev
    prod:
      target: prod

Use:

${matrix.target}

Example:

- name: Build target
  run: echo Building ${matrix.target}

21. Cache and hashFiles()

Restore:

- name: Restore cache
  cache:
    action: restore
    key: go-${hashFiles("go.sum")}
    restoreKeys:
      - go-
    paths:
      - .cache/go

Save:

- name: Save cache
  cache:
    action: save
    key: go-${hashFiles("go.sum")}
    paths:
      - .cache/go

Multiple files can be hashed:

${hashFiles("package-lock.json", "package.json")}

22. Artifacts and job outputs

Store artifacts:

- name: Package
  run: echo result > result.txt
  artifacts:
    - result.txt

A run step receives a temporary output file path through:

ZCI_OUTPUT

Bash/sh:

run: |
  echo "package=backend.txt" >> "$ZCI_OUTPUT"

PowerShell:

run: |
  Add-Content $env:ZCI_OUTPUT "package=backend.txt"

A dependent job can reference:

${needs.producer.outputs.package}

The producing job must be listed in the consumer's needs.

23. Download dependency artifacts

Example:

needs:
  - producer

steps:
  - name: Download artifact
    downloadArtifacts:
      from: producer
      to: downloaded
      files:
        - backend.txt
      overwrite: true

24. Conditions, retries, and timeout

Supported step conditions:

success()
failure()
always()

Example:

if: always()

Timeout:

timeout: 2m

Retry:

retries: 2
retryDelay: 5s

Duration syntax includes examples such as:

500ms
10s
2m
1h

Continue after a failed step:

continueOnError: true

Use this intentionally rather than hiding real failures.

25. Docker build

Example:

- name: Build image
  dockerBuild:
    context: .
    dockerfile: Dockerfile
    tag: my-app:local

Docker must be installed and available locally.

Zetken does not currently mean that the whole pipeline runs inside a Docker container simply because dockerBuild is used.

26. Useful CLI commands

For normal Studio beta testing, these are especially useful:

zci version
zci doctor
zci paths
zci serve

Other current CLI commands include:

zci init
zci scan
zci validate
zci plan
zci run
zci status
zci history
zci logs <build>
zci artifacts <build>
zci report <build>
zci diagnose <build>
zci build show <build>
zci build diff <old> <new>
zci snapshot
zci snapshot show <id>
zci snapshot diff <old> <new>
zci retention
zci cleanup

Use:

zci --help

for the command list included in your specific beta build.

27. Current beta limitations

Keep these expectations in mind:

28. Suggested first-day test checklist

Please try:

  1. Start Zetken.
  2. Create a project.
  3. Create and run a Basic template.
  4. Inspect run logs.
  5. Edit YAML and validate it.
  6. Introduce one intentional validation error.
  7. Run a pipeline that creates an artifact.
  8. Run it twice and inspect/compare snapshots.
  9. Test two independent jobs with maxParallel.
  10. Test a needs dependency.
  11. Test a matrix pipeline.
  12. Test environment variables.
  13. Test a runtime parameter.
  14. Import one existing GitHub Actions, Azure DevOps, or Jenkins pipeline if applicable.
  15. Restart Zetken and confirm projects and runs remain available.
  16. Test a pipeline similar to your real workload.

Feedback about confusing wording or workflow is valuable even when nothing crashes.

29. How to report a bug

Please include:

Operating system
CPU architecture
Zetken version
What you were trying to do
Exact reproduction steps
Expected result
Actual result
Screenshot/video where useful
Relevant pipeline YAML
Run ID
Stage/job/step
Relevant logs
Server log when UI/server-related

Collect:

zci version
zci doctor
zci paths

Never send real passwords, tokens, private keys, or production secrets in a bug report. Replace them with safe placeholders.

30. Minimal managed pipeline example

schema: zetken/v1

env:
  APP_ENV: test

stages:
  - name: validate
    jobs:
      - name: test
        steps:
          - name: Show environment
            run: echo Environment is ${APP_ENV}

          - name: Run tests
            run: go test ./...

For a Studio-managed pipeline, the pipeline name comes from Zetken Studio rather than a top-level name: field in pipeline.yaml.

View Markdown source Pipeline YAML Reference Migration Assistant