Thank you for your interest in contributing to NixActions! This document provides guidelines and information for contributors.
Please be respectful and constructive in all interactions with the community.
- Fork the repository on GitHub
- Clone your fork locally:
git clone https://github.com/yourusername/nixactions.git cd nixactions - Set up the development environment:
nix develop
- Nix with flakes enabled
- Basic understanding of Nix language
- Familiarity with CI/CD concepts
Test your changes by running the examples:
# Run all examples
nix run .#example-simple
nix run .#example-parallel
nix run .#example-complete
nix run .#example-secrets
nix run .#example-python-ci
nix run .#example-nix-shell
nix run .#example-artifactsBuild specific examples or the entire project:
# Build an example
nix build .#example-simple
# Build all packages
nix flake checknixactions/
├── lib/ # Core library
│ ├── default.nix # Main API export
│ ├── mk-executor.nix # Executor constructor
│ ├── mk-workflow.nix # Workflow compiler
│ ├── executors/ # Built-in executors
│ └── actions/ # Standard actions
├── examples/ # Working examples
├── DESIGN.md # Architecture documentation
└── README.md # User documentation
- Check existing issues or create a new one
- Include a failing test case if possible
- Fix the bug and verify all examples still work
To add a new executor (e.g., podman):
-
Create
lib/executors/podman.nix:{ pkgs, mkExecutor }: mkExecutor { name = "podman"; setupWorkspace = '' # Setup code ''; cleanupWorkspace = '' # Cleanup code ''; executeJob = { jobName, script }: '' # Execute job in podman container ${script} ''; }
-
Export it in
lib/executors/default.nix:{ # ... podman = import ./podman.nix args; }
-
Add an example in
examples/podman-ci.nix -
Update documentation in README.md
To add a new action (e.g., dockerBuild):
-
Create
lib/actions/docker.nix:{ pkgs }: { build = { dockerfile ? "Dockerfile", tag }: { name = "docker-build"; deps = [ pkgs.docker ]; bash = '' docker build -f ${dockerfile} -t ${tag} . ''; }; }
-
Export it in
lib/actions/default.nix -
Add examples and documentation
- Keep README.md up to date with examples
- Update DESIGN.md for architectural changes
- Add inline comments for complex logic
- Update TODO.md roadmap if adding planned features
- Nix: Follow standard Nix formatting (use
nixpkgs-fmt) - Bash: Use proper quoting and error handling
- Comments: Write clear, concise comments
- Naming: Use descriptive names following existing conventions
Before submitting:
-
Run all examples:
for example in simple parallel complete secrets python-ci; do echo "Testing example-$example..." nix run .#example-$example done
-
Check formatting:
nixpkgs-fmt --check . -
Verify builds:
nix flake check
-
Create a feature branch:
git checkout -b feature/my-new-feature
-
Make your changes following the guidelines above
-
Commit with clear messages:
git commit -m "Add podman executor with example" -
Push to your fork:
git push origin feature/my-new-feature
-
Open a Pull Request with:
- Clear description of changes
- Link to related issues
- Examples of usage
- Test results
- Title: Clear, descriptive summary
- Description:
- What changes were made
- Why they were made
- How to test them
- Scope: Keep PRs focused on a single feature/fix
- Tests: Include or update examples demonstrating the feature
- Documentation: Update relevant docs
- Maintainers will review your PR
- Address any feedback or requested changes
- Once approved, your PR will be merged
- Your contribution will be acknowledged in the release notes
Please read DESIGN.md for detailed architecture documentation covering:
- Core concepts (Actions, Executors, Jobs, Workflows)
- Execution model (GitHub Actions-style parallelism)
- Secrets management
- Artifacts management
- Built-in executors and actions
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Contributors will be:
- Listed in release notes
- Acknowledged in the README
- Forever grateful for helping make CI/CD better!
Thank you for contributing to NixActions! 🎉