PDK (Pipeline Development Kit)

A CLI tool that runs GitHub Actions workflows and Azure Pipelines locally, in Docker containers or directly on your machine, so you can test pipeline changes before pushing them.

• Runs the same YAML you commit: .github/workflows/*.yml, azure-pipelines.yml (multi-stage pipelines included) and .gitlab-ci.yml (see docs/providers/gitlab.md).
• Expressions and conditions as on the CI service: GitHub ${{ }} / if: with the github, env, vars, secrets, matrix, needs, steps, runner contexts; Azure $(macro), ${{ }}, $[ ] and function-style condition:. See docs/expressions.md.
• Job graph: jobs run in dependency order, job outputs flow to dependents (needs.X.outputs, dependencies.X.outputs), matrix jobs are expanded, --job runs a job with its dependencies.
• Step semantics: continue-on-error, always() / failure() steps, timeouts, $GITHUB_OUTPUT / $GITHUB_ENV / $GITHUB_PATH and ##vso[...] logging commands.
• Docker isolation (one container per job, container: images honoured) or --host execution.
• Artifacts between jobs, stored under .pdk/artifacts.
• Variables, encrypted local secrets with output masking, configuration files.
• Watch mode, dry run with an execution plan, step filtering, structured logging.

• .NET 8.0 SDK
• Docker (optional: without it, use --host)

dotnet tool install --global pdk

Or from source:

dotnet pack src/PDK.CLI -c Release -o ./artifacts
dotnet tool install --global --add-source ./artifacts pdk

Upgrading from 1.x? See docs/upgrading-to-2.0.md - exit codes, step filtering, host environment variables and the secret store all changed.

# Check whether Docker is usable
pdk doctor

# Validate a pipeline file
pdk validate --file .github/workflows/ci.yml

# List jobs and steps
pdk list --file .github/workflows/ci.yml --details

# Run the whole pipeline (auto-detects the file when --file is omitted)
pdk run --file .github/workflows/ci.yml

# Run one job (its dependencies run first; add --no-deps to skip them)
pdk run --file azure-pipelines.yml --job Build

# Run on the host instead of Docker
pdk run --file .github/workflows/ci.yml --host

# Show the execution plan without running anything
pdk run --dry-run

# Run one step, present a different event, fail on unsupported actions
pdk run --job build --step Test
pdk run --event pull_request
pdk run --strict

pdk run exits with 0 on success, 1 when a job failed, 2 for invalid arguments (unknown job, several candidate pipeline files), 3 when the pipeline file is missing, 4 when Docker was required but unavailable, and 130 when cancelled with Ctrl+C. The full option list is in docs/commands/run.md; error codes are explained in docs/errors.md.

PDK maps each step to a local executor. Steps it cannot run are skipped with a warning (--strict turns that into a failure); tool setup steps are no-ops because the runner image or the host is expected to provide the tool.

GitHub Actions

Azure Pipelines

Known gaps: parallel jobs (jobs run one after another), templates from other repositories (@otherRepo), runtime ($[ ]) matrices, workflow_dispatch inputs, service containers, composite/local actions, persistent counter() values.

PDK/
├── src/
│   ├── PDK.CLI/           # Command-line interface
│   ├── PDK.Core/          # Models, expressions, variables, secrets, artifacts, logging
│   ├── PDK.Providers/     # GitHub Actions and Azure DevOps parsers
│   └── PDK.Runners/       # Docker and host job runners, step executors
├── tests/
│   ├── PDK.Tests.Unit/
│   ├── PDK.Tests.Integration/
│   └── PDK.Tests.Performance/
├── examples/              # Example projects with runnable workflows
├── samples/               # Sample pipeline files (no project needed)
├── scripts/               # Release, coverage and dogfooding scripts
└── docs/                  # Documentation

# Build (warnings are errors)
dotnet build -c Release

# Unit tests
dotnet test tests/PDK.Tests.Unit --no-build -c Release

# Integration tests (tests that need a Docker daemon skip themselves when none is reachable;
# PDK_DOCKER_TESTS=require makes them fail instead, PDK_DOCKER_TESTS=skip always skips them)
dotnet test tests/PDK.Tests.Integration --no-build -c Release

# Coverage report (CI enforces 70% line coverage across both suites)
./scripts/coverage.sh

# Run the CLI from source
dotnet run --project src/PDK.CLI -- run --file samples/github/ci.yml --host

See CONTRIBUTING.md and docs/developers for the full developer guide.

PDK includes complete, working example projects:

Each example includes a complete CI workflow that you can run with PDK. The samples/ directory contains stand-alone pipeline files, including samples/github/expressions.yml and samples/azure/expressions-pipeline.yml, which demonstrate expressions, conditions, outputs and failure handling without needing a project.

• Getting started
• Command reference
• Expressions, contexts and execution semantics
• Configuration, variables, secrets, logging
• Error codes
• Troubleshooting

• GitHub Actions workflow parsing, including matrix expansion

• Azure DevOps pipeline parsing, including stages and deployment jobs

• Expressions, conditions, job outputs and dependency ordering

• Docker container execution

• Host-based execution

• Tool executors (.NET, npm, Docker, Maven, Gradle)

• Configuration file support

• Secret management

• Artifact handling

• Watch mode

• Dry-run mode

• Structured logging

• GitLab CI support

• Service containers
• Reusable workflows and composite actions
• Parallel job execution

Contributions welcome! See CONTRIBUTING.md.

MIT