BuildKit pipelines.

Documentation website.

Pix is a portable pipeline executor - a CI framework that enables you to define and execute pipelines that can run on any host with Docker support. Pipelines are defined as code and executed efficiently via Docker BuildKit.

The building blocks of a pipeline are:

• stage: The core execution unit where work is performed (e.g., running tests, building applications, deploying services). Each stage can be customized via arguments.
• output: Stages can produce tangible outputs (e.g., test coverage reports, documentation, build artifacts).
• dependency: Stages are interconnected via dependencies to create a structured execution graph.

Under the hood, a pipeline is an intelligent Docker multistage build, programmatically defined using Elixir code through the Pix.Pipeline.SDK.

Pix generates optimized multistage Docker build definitions and executes them via docker buildx build. The execution follows Docker build semantics for parallelism, caching, and resource management.

Your project's root directory can contain a .pix.exs file that declares available pipelines. This configuration file specifies pipelines with their default arguments and targets. Pipeline definitions can be imported either from a local path or a remote git repository.

More details in the Pix.Project module documentation.

A pipeline is a programmatic definition of a Docker multistage build. It consists of targets (named Docker build stages) defined in pipeline.exs using the Pix.Pipeline.SDK.

More details in the Pix.Pipeline.SDK module documentation.

Pix requires a docker engine installed and running on your host system.

$ mix escript.install github athonet-open/pix ref vX.Y.Z

$ docker run --rm -it \
  --volume $PWD:/$PWD --workdir /$PWD \
  --volume /var/run/docker.sock:/var/run/docker.sock \
  --volume $SSH_AUTH_SOCK:$SSH_AUTH_SOCK \
  --env SSH_AUTH_SOCK=$SSH_AUTH_SOCK \
  ghcr.io/athonet-open/pix:X.Y.Z "$@"

Important considerations:

• Docker engine access is required via either Docker Socket Mounting (DooD) or Docker-in-Docker (dind)
• For SSH access, forward the SSH agent socket to the Pix container
• For macOS users with Docker Desktop:

--volume /run/host-services/ssh-auth.sock:/run/host-services/ssh-auth.sock \
--env SSH_AUTH_SOCK=/run/host-services/ssh-auth.sock

Shell completion scripts are available for the following shells:

• fish shell

  # install completion with
  pix completion_script fish > ~/.config/fish/completions/pix.fish

Let's explore Pix using its own project as an example:

1. The project configuration is in .pix.exs, defining the pix pipeline with default settings.
2. The pipeline.exs contains the actual pipeline definition.

Key commands:

$ pix run pix                   # Run the complete pipeline
$ pix ls --verbose pix          # List pipeline configuration
$ pix graph pix                 # Generate pipeline visualization
$ pix run --output pix          # Run pipeline and output artifacts

Access documentation at .pipeline/output/doc/index.html after running with output.

For detailed command information, use pix help.

Customize Pix behavior through ~/.config/pix/settings.exs. See Pix.UserSettings documentation for configuration options.

• Only import remote pipelines from verified, trusted sources

• Service containers are not currently supported (e.g., sidecar containers for integration testing)

Workaround: Use Docker Compose to define and manage test environments.