# Zetken CI/CD Studio — 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:

```text
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:

- Local pipeline execution
- Browser-based project and pipeline management
- Native Zetken YAML
- Pipeline validation
- Run history and detailed logs
- Run cancellation
- Artifacts
- Build-linked source snapshots and comparison
- Runtime parameters
- Environment variables and environment files
- Secret masking
- Job dependencies with `needs`
- Parallel jobs
- Matrix jobs
- Cache restore/save
- `hashFiles()`
- Job outputs
- Artifact downloads between dependent jobs
- Docker image build steps
- Migration Assistant for supported GitHub Actions, Azure DevOps, and Jenkins Declarative pipelines

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:

```text
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:

```text
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:

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

For example:

```yaml
run: terraform validate
```

requires Terraform to be installed and available on `PATH`.

Check local tools with:

```text
zci doctor
```

---

## 4. Start Zetken

### Windows

Open PowerShell in the folder containing `zci.exe`.

```powershell
.\zci.exe version
.\zci.exe doctor
.\zci.exe serve
```

### Linux

Make the binary executable once:

```bash
chmod +x ./zci
```

Then:

```bash
./zci version
./zci doctor
./zci serve
```

### macOS

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

---

## 5. Open the Web UI

By default, Zetken starts at:

```text
http://127.0.0.1:37687
```

You can also use:

```bash
zci serve --open
```

or another port:

```bash
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:

```text
zci paths
```

or:

```text
zci paths --json
```

### Default project workspace

Windows:

```text
%USERPROFILE%\ZetkenProjects
```

Linux/macOS:

```text
~/ZetkenProjects
```

A managed project normally contains pipelines like:

```text
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:

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

Linux:

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

When `XDG_DATA_HOME` is set, Linux uses:

```text
$XDG_DATA_HOME/zetken
```

macOS:

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

---

## 7. Recommended first test

After starting Zetken:

```text
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:

```text
Create project
```

Enter:

- Name
- Description (optional)

Then select **Create**.

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

---

## 9. Create a pipeline

Inside a project, select:

```text
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:

```text
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:

```text
GitHub Actions
Azure DevOps
Jenkins
```

Typical flow:

```text
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:

```text
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:

```text
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:

```text
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:

```text
Editor
```

The editor provides:

```text
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:

```text
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:

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

Use:

```yaml
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:

```text
Run pipeline
```

or from the Editor:

```text
Validate
→ Save
→ Run pipeline
```

The execution hierarchy is:

```text
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:

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

Windows-specific example:

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

Linux/macOS example:

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

---

## 14. Native shell values

Current native Zetken YAML supports:

```text
default
cmd
powershell
pwsh
bash
sh
```

`default` resolves approximately as:

```text
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:

```text
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:

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

---

## 16. Snapshots

Open:

```text
Pipeline
→ Snapshots
```

Pipeline runs create build-linked source snapshots.

The snapshot view shows information such as:

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

After at least two eligible builds, use:

```text
Compare latest two builds
```

to review source differences.

---

## 17. Environment variables

Environment variables can be defined at:

```text
pipeline
stage
job
step
```

Example:

```yaml
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:

```text
${VARIABLE_NAME}
```

Environment files are also supported:

```yaml
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:

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

  - name: packageName
    type: string
    required: true
```

Reference:

```text
${params.target}
${params.packageName}
```

Standalone CLI example:

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

Secret parameter:

```yaml
- 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:

```yaml
maxParallel: 2
```

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

Use:

```yaml
needs:
  - build
```

to express dependencies.

Example:

```yaml
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:

```yaml
strategy:
  matrix:
    dev:
      target: dev
    prod:
      target: prod
```

Use:

```text
${matrix.target}
```

Example:

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

---

## 21. Cache and `hashFiles()`

Restore:

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

Save:

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

Multiple files can be hashed:

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

---

## 22. Artifacts and job outputs

Store artifacts:

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

A `run` step receives a temporary output file path through:

```text
ZCI_OUTPUT
```

Bash/sh:

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

PowerShell:

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

A dependent job can reference:

```text
${needs.producer.outputs.package}
```

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

---

## 23. Download dependency artifacts

Example:

```yaml
needs:
  - producer

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

---

## 24. Conditions, retries, and timeout

Supported step conditions:

```text
success()
failure()
always()
```

Example:

```yaml
if: always()
```

Timeout:

```yaml
timeout: 2m
```

Retry:

```yaml
retries: 2
retryDelay: 5s
```

Duration syntax includes examples such as:

```text
500ms
10s
2m
1h
```

Continue after a failed step:

```yaml
continueOnError: true
```

Use this intentionally rather than hiding real failures.

---

## 25. Docker build

Example:

```yaml
- 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:

```text
zci version
zci doctor
zci paths
zci serve
```

Other current CLI commands include:

```text
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:

```text
zci --help
```

for the command list included in your specific beta build.

---

## 27. Current beta limitations

Keep these expectations in mind:

- Pipeline execution is local.
- There are no remote Zetken runners/agents yet.
- The browser UI is local-only.
- Native Kubernetes deployment support is not yet available.
- External CLIs must be installed and authenticated separately.
- Docker support is limited; there are no Docker container jobs yet.
- Migration is a supported subset, not guaranteed 1:1 semantic conversion.
- OS-specific pipeline commands may require changes between Windows, Linux, and macOS.
- This is beta software; unexpected behavior should be reported.

---

## 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:

```text
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:

```text
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

```yaml
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`.