FAQ

Why use iapetus over X? 🤔

  • YAML and Go support: Define workflows as code or config.

  • Plugin system: Add any backend (Docker, Kubernetes, SSH, etc).

  • Easy assertions and dependencies: Built-in checks and DAG execution.

  • Open source, no vendor lock-in.

Can I use this in CI/CD? 🚦

Yes! iapetus is designed for automation and CI/CD. It runs anywhere Go runs, and integrates easily with GitHub Actions, GitLab CI, Jenkins, and more.

How do I contribute? 🤝

  • See Contributing Guide for setup, code style, and PR guidelines.

  • All contributions—code, docs, tests, issues—are welcome!

Where to get help? 🆘

  • GitHub Issues (for bugs and feature requests)

  • Discussions (for questions, ideas, and community support)

  • This documentation (for usage, API, and troubleshooting)

Common errors and solutions 🛠️

Troubleshooting

  • “command not found”: Check your command or Docker image. Make sure the binary exists in the container or shell.

  • “permission denied”: Check file permissions and Docker access. Try running with elevated privileges if needed.

  • “Go not installed”: Install Go from https://golang.org/dl/ and ensure it’s in your PATH.

  • Docker errors: Make sure Docker is installed, running, and your user has permission to run containers. See iapetus.GetStatus() for backend availability.

  • YAML parse errors: Check indentation, use spaces not tabs, and quote strings with special characters.

  • Assertion failed: Review the step’s output and assertion logic. Use output_contains or custom assertions for flexible checks.

  • Timeouts: Increase the timeout field if your step needs more time.

  • Retries not working: Ensure retries is set at the step/task level.

How do I debug a failing workflow? 🐞

  • Check the output and error logs for each step.

  • Use hooks for custom logging or metrics.

  • Run with increased logging or in a local shell for easier troubleshooting.

  • See How-To Recipes for debugging tips.

How do I run steps in Docker? 🐳

  • Set backend: docker and specify an image for your step or workflow.

  • Make sure Docker is installed and running on your system.

  • See the YAML Reference for examples.

How do I add a custom backend or assertion? 🔌

  • Implement the Backend interface in Go and register it with iapetus.RegisterBackend().

  • Add custom assertion functions in Go and attach them to your tasks.

  • See the API Reference for plugin and assertion examples.

Where can I find more examples? 📚