GitHub Actions execution model + Nix reproducibility + Agentless deployment
NixActions compiles workflows into self-contained executables that run anywhere without agents or central infrastructure. Actions are Nix derivations, provisioned at build-time.
| Document | Description |
|---|---|
| User Guide | Quick start, installation, first workflow |
| Philosophy | Why NixActions, core principles |
| Document | Description |
|---|---|
| Architecture | Layered design, system overview |
| Core Contracts | Action, Executor, Job, Workflow contracts |
| Execution Model | Level-based parallel execution, DAG |
| Document | Description |
|---|---|
| Actions | Actions as Derivations, mkAction, build-time compilation |
| Executors | Local, OCI, SSH, K8s executors, deduplication |
| Conditions | success(), failure(), always(), bash conditions |
| Retry | Retry mechanism, backoff strategies |
| Environment | Env providers, secrets, multi-level config |
| Artifacts | inputs/outputs, custom restore paths |
| Document | Description |
|---|---|
| API Reference | mkWorkflow, mkExecutor, mkAction, full API |
| Comparison | vs GitHub Actions, GitLab CI |
| Roadmap | Current status, planned features |
Nix Code Compiled Workflow Execution
========== ================= =========
nixactions.mkWorkflow { #!/usr/bin/env bash $ nix run .#ci
jobs = {
test = { setup_workspace() -> Setting up workspace
steps = [ job_test() -> Running job: test
{ bash = "..." } /nix/store/xxx/bin/test -> Action: test
]; job_build() -> Running job: build
}; /nix/store/yyy/bin/build -> Action: build
build = { ... }; cleanup() -> Cleanup
};
} All jobs succeeded!
Actions are Derivations - Every action compiles to a /nix/store path. Build-time validation, caching, and reproducibility come for free.
Executors define where - Local machine, Docker containers, SSH remotes, or Kubernetes pods. Same workflow, different execution environments.
Jobs are parallel by default - Like GitHub Actions, jobs without dependencies run in parallel. Use needs for explicit ordering.
Conditions control flow - Built-in conditions (success(), failure(), always()) and bash scripts for custom logic.
# ci.nix
{ pkgs, nixactions }:
nixactions.mkWorkflow {
name = "ci";
jobs = {
test = {
executor = nixactions.executors.local;
steps = [
{ bash = "npm test"; }
];
};
build = {
needs = [ "test" ];
executor = nixactions.executors.local;
steps = [
{ bash = "npm run build"; }
];
};
};
}# Run locally
$ nix run .#ci
# Or on remote
$ nix build .#ci && ssh server < result+-----------------------------------------+
| Level 5: User Abstractions |
| Custom helpers, presets, wrappers |
+-----------------------------------------+
|
+-----------------------------------------+
| Level 4: Workflow (DAG of jobs) |
| mkWorkflow { name, jobs } |
+-----------------------------------------+
|
+-----------------------------------------+
| Level 3: Job (actions + executor) |
| { executor, actions, needs } |
+-----------------------------------------+
|
+-----------------------------------------+
| Level 2: Executor (where to run) |
| local, oci, ssh, k8s |
+-----------------------------------------+
|
+-----------------------------------------+
| Level 1: Action = Derivation |
| /nix/store/xxx-action-name |
+-----------------------------------------+
|
+-----------------------------------------+
| Level 0: Nix Store |
| Content-addressed, cached, hermetic |
+-----------------------------------------+
jobs = {
lint = { ... }; # Level 0 - runs immediately
test = { ... }; # Level 0 - runs in parallel with lint
build = {
needs = [ "lint" "test" ]; # Level 1 - waits for both
...
};
};# Built-in conditions
condition = "success()"; # Run if deps succeeded (default)
condition = "failure()"; # Run if any dep failed
condition = "always()"; # Always run
# Bash conditions
condition = ''[ "$BRANCH" = "main" ]'';
condition = ''[ -f package.json ]'';jobs = {
test = {
executor = nixactions.executors.local;
...
};
build = {
executor = nixactions.executors.oci {
extraPackages = [ pkgs.nodejs ];
};
...
};
};jobs = {
build = {
outputs = { dist = "dist/"; };
...
};
deploy = {
needs = [ "build" ];
inputs = [ "dist" ];
...
};
};{
retry = {
max_attempts = 3;
backoff = "exponential";
min_time = 1;
max_time = 60;
};
}nixactions/
+-- lib/
| +-- mk-workflow.nix # Workflow compiler
| +-- mk-executor.nix # Executor contract
| +-- executors/ # local, oci, ssh, k8s
| +-- actions/ # Standard actions library
| +-- env-providers/ # file, sops, vault, etc.
+-- examples/
| +-- 01-basic/ # Simple workflows
| +-- 02-features/ # Advanced features
| +-- 03-real-world/ # Production pipelines
+-- docs/ # This documentation
- User Guide - Get started with your first workflow
- Actions - Understand how actions work
- Executors - Learn about execution environments
- API Reference - Full API documentation