# Migration Assistant compatibility

## Overview

The local Migration Assistant converts **GitHub Actions, Azure DevOps, or a supported Jenkins Declarative pipeline → a Zetken `PipelineSpec` → native Zetken YAML**. Analysis reads the uploaded or pasted text in memory; it does not connect to a vendor, clone a repository, execute commands, or import secret values. Users import the original vendor definition—the assistant performs the supported semantic conversion.

## What is converted

### GitHub Actions

| Source | Zetken result |
| --- | --- |
| `jobs` | Jobs in a generated `Pipeline` stage |
| `needs` | Native `needs` |
| `steps[].run` (inline or YAML block scalar) | Native `run` |
| `shell` | Native shell when supported; source `pwsh` remains native `pwsh` |
| `working-directory` | Native `workingDir` |
| Literal `env` | Native environment value where supported |

### Azure DevOps

| Source | Zetken result |
| --- | --- |
| `stages` and `jobs` | Native stages and jobs |
| `dependsOn` | Native `needs` |
| `script`, `bash`, `powershell`, `pwsh` | Native run steps; `powershell` and `pwsh` remain distinct |
| Inline `PowerShell@2`, `Bash@3`, `AzureCLI@2` scripts | Native run and matching supported shell when determinable |
| Literal variables | Native environment value where supported |

File-path task inputs are never read or executed.

### Jenkins

The supported Declarative subset includes literal `stage` blocks and literal `sh`, `bat`, and `powershell` steps. Jenkinsfiles are parsed as text and never evaluated. Scripted Pipeline, dynamic Groovy, shared libraries, credentials, matrices, and advanced Declarative directives are not converted.

## Requires manual review

Review diagnostics keep the source line and explain the next action. Typical cases are GitHub expressions and contexts, `$GITHUB_ENV`/`$GITHUB_OUTPUT`, setup or login actions, Azure service connections and variable groups, tool-setup tasks, platform authentication, and OS-specific shell commands. The assistant may preserve a script so it remains editable, but does not claim vendor runtime behavior is portable and never invents credentials or secret values.

## Unsupported in the current version

Triggers, matrices, templates/reusable workflows, approvals and environments, service connections, arbitrary third-party actions/tasks, Jenkins Scripted Pipeline, and dynamic Groovy are omitted with diagnostics rather than emitted as invalid native structures.

## Before and after examples

GitHub Actions:

```yaml
jobs:
  build:
    steps:
      - run: |
          go test ./...
          go build ./...
```

```yaml
schema: zetken/v1
stages:
  - name: "Pipeline"
    jobs:
      - name: "build"
        steps:
          - name: Migrated step
            run: |
              go test ./...
              go build ./...
```

Azure DevOps PowerShell and Bash steps map to native run steps while preserving their shell:

```yaml
steps:
  - pwsh: |
      Write-Output "PowerShell 7"
  - powershell: |
      Write-Output "Windows PowerShell"
  - bash: |
      go test ./...
```

These become native `run` steps with `shell: "pwsh"`, `shell: "powershell"`, or `shell: "bash"`. GitHub Actions `shell: pwsh` is also preserved as native `pwsh`.

For an inline Azure DevOps `PowerShell@2` task, Zetken maps to native `pwsh` only when the source explicitly requests PowerShell Core with a literal `pwsh: true` input. Otherwise the existing `powershell` mapping is preserved.

PowerShell 7 is not bundled with Zetken. A migrated `shell: "pwsh"` step requires the `pwsh` executable to be installed and available on `PATH`.

A Jenkins Declarative `stage('Build')` containing `sh 'go build ./...'` becomes a native Build stage with a shell run step.

A GitHub command such as `echo "NAME=${{ vars.NAME }}" >> $GITHUB_ENV` is preserved for editing and produces review diagnostics for both the GitHub expression and runtime environment file. Move the literal value to Zetken environment configuration and revise the command for the target shell.

## Analysis and validation states

1. **Source parsed** — syntax and non-empty commands are checked.
2. **Converted** — a construct has a direct native representation.
3. **Requires review** — content is preserved when safe, but vendor behavior is not portable.
4. **Unsupported** — content is omitted with an explanation.
5. **Generated YAML validation** — generated text is parsed by the native Zetken parser and validated before creation is enabled.

Source errors, compatibility diagnostics, and generated native validation errors are presented separately. Selecting a diagnostic returns to its source line; users can review and edit the generated native YAML in place.