Artifacts allow jobs to share files explicitly and safely.
Key principles:
- Explicit transfer -
inputs/outputsAPI for reliable file sharing - HOST-based storage -
$NIXACTIONS_ARTIFACTS_DIRexists ONLY on control node - Executor transfers files -
saveArtifact/restoreArtifactcopy between execution env and HOST - Survives cleanup - Artifacts stored outside workspace
- Custom restore paths - Control where artifacts are restored in job directory
+---------------------------------------------------+
| CONTROL NODE (HOST) |
| |
| $NIXACTIONS_ARTIFACTS_DIR/ |
| +-- dist/ |
| | +-- bundle.js |
| +-- coverage/ |
| +-- report.html |
| |
| ^ | |
| | saveArtifact | |
| | restoreArtifact v |
+---+-------------------------------------------+---+
| |
+---v-------------------------------------------v---+
| EXECUTION ENVIRONMENT (Container/Remote/Local) |
| |
| /workspace/jobs/build/ |
| +-- dist/ <- Created by job |
| | +-- bundle.js |
| +-- coverage/ <- Restored input |
| +-- report.html |
| |
+---------------------------------------------------+
jobs = {
build = {
executor = nixactions.executors.local;
# Declare outputs (what to save)
outputs = {
dist = "dist/";
binary = "myapp";
};
steps = [{
bash = ''
npm run build
# dist/ created in job directory
'';
}];
};
test = {
needs = ["build"];
executor = nixactions.executors.local;
# Declare inputs (what to restore)
inputs = [ "dist" "binary" ];
steps = [{
bash = ''
# Artifacts restored before actions run
ls dist/
./binary --version
'';
}];
};
};Control where artifacts are restored:
inputs = [
"dist" # Simple: restore to $JOB_DIR/
{ name = "libs"; path = "lib/"; } # Custom: restore to $JOB_DIR/lib/
{ name = "config"; path = "etc/"; } # Custom: restore to $JOB_DIR/etc/
]Path semantics:
.or./- Root of job directory (default)subdir/- Subdirectory within job directory../other/- Relative to job directory (can go up)
jobs = {
build = {
outputs = {
frontend = "dist/frontend/";
backend = "dist/backend/";
shared = "dist/shared/";
};
steps = [{ bash = "npm run build:all"; }];
};
deploy = {
needs = ["build"];
inputs = [
{ name = "frontend"; path = "public/"; }
{ name = "backend"; path = "server/"; }
{ name = "shared"; path = "lib/"; }
];
steps = [{
bash = ''
ls public/ # Frontend files
ls server/ # Backend files
ls lib/ # Shared files
'';
}];
};
};jobs = {
build-api = {
outputs = { api = "services/api/dist/"; };
steps = [{ bash = "cd services/api && npm run build"; }];
};
build-worker = {
outputs = { worker = "services/worker/dist/"; };
steps = [{ bash = "cd services/worker && npm run build"; }];
};
deploy = {
needs = ["build-api" "build-worker"];
inputs = [
{ name = "api"; path = "services/api/dist/"; }
{ name = "worker"; path = "services/worker/dist/"; }
];
steps = [{
bash = "deploy-monorepo.sh";
}];
};
};jobs = {
test = {
outputs = {
coverage = "coverage/";
};
steps = [{
bash = "npm test -- --coverage";
}];
};
upload-coverage = {
needs = ["test"];
inputs = ["coverage"];
steps = [{
bash = "codecov upload coverage/lcov.info";
}];
};
};Old and new syntax can be mixed:
inputs = [
"dist" # Old syntax (restore to root)
{ name = "config"; path = "etc/"; } # New syntax (custom path)
]Equivalent to:
inputs = [
{ name = "dist"; path = "."; }
{ name = "config"; path = "etc/"; }
]# Setup artifacts dir on HOST
NIXACTIONS_ARTIFACTS_DIR="$HOME/.cache/nixactions/$WORKFLOW_ID/artifacts"
mkdir -p "$NIXACTIONS_ARTIFACTS_DIR"
job_build() {
# Execute actions
cd $JOB_DIR
npm run build
# Save outputs (on HOST)
cp -r "$JOB_DIR/dist" "$NIXACTIONS_ARTIFACTS_DIR/dist/"
}
job_test() {
# Restore inputs (on HOST)
cp -r "$NIXACTIONS_ARTIFACTS_DIR/dist"/* "$JOB_DIR/"
# Execute actions
cd $JOB_DIR
npm test
}job_build() {
docker exec $CONTAINER bash -c 'npm run build'
# Save: docker cp from container to HOST
docker cp "$CONTAINER:/workspace/jobs/build/dist" "$NIXACTIONS_ARTIFACTS_DIR/dist/"
}
job_test() {
# Restore: docker cp from HOST to container
docker cp "$NIXACTIONS_ARTIFACTS_DIR/dist" "$CONTAINER:/workspace/jobs/test/"
docker exec $CONTAINER bash -c 'npm test'
}Each executor must implement saveArtifact and restoreArtifact:
# Local executor
saveArtifact = { name, path, jobName }: ''
if [ -e "$JOB_DIR/${path}" ]; then
mkdir -p "$NIXACTIONS_ARTIFACTS_DIR/${name}"
cp -r "$JOB_DIR/${path}" "$NIXACTIONS_ARTIFACTS_DIR/${name}/"
fi
'';
restoreArtifact = { name, path, jobName }: ''
if [ -e "$NIXACTIONS_ARTIFACTS_DIR/${name}" ]; then
if [ "${path}" = "." ]; then
cp -r "$NIXACTIONS_ARTIFACTS_DIR/${name}"/* "$JOB_DIR/"
else
mkdir -p "$JOB_DIR/${path}"
cp -r "$NIXACTIONS_ARTIFACTS_DIR/${name}"/* "$JOB_DIR/${path}/"
fi
fi
'';# Good: descriptive names
outputs = {
frontend-dist = "dist/frontend/";
backend-dist = "dist/backend/";
test-coverage = "coverage/";
};
# Avoid: generic names
outputs = {
files = "dist/";
data = "output/";
};# Good: organized structure
inputs = [
{ name = "frontend-dist"; path = "public/"; }
{ name = "backend-dist"; path = "server/"; }
];
# Result:
# $JOB_DIR/
# public/ <- frontend files
# server/ <- backend files# Good: share only what's needed
outputs = {
dist = "dist/"; # Built files only
};
# Avoid: sharing everything
outputs = {
all = "."; # Entire directory
};- Artifacts are workflow-scoped - Cleaned up when workflow ends
- No cross-workflow sharing - Use external storage for that
- Size limits - Large artifacts slow down transfers
- No streaming - Entire artifact copied at once
- Executors - Artifact transfer implementation
- Core Contracts - Job inputs/outputs API
- API Reference - Full artifacts API