Shipit
Shipit is a CLI that automatically detects the type of project you are trying to run, builds it and runs it using Starlark definition files (called Shipit).
It can run builds locally, inside Docker, or through Wasmer, and bundles a one-command experience for common frameworks.
Quick Start
To use shipit, you'll need to have uv installed.
Install nothing globally; use uvx shipit-cli to run Shipit from anywhere.
uvx shipit-cli .
Running in auto mode will generate the Shipit file when needed, build the
project, and can also run it. Shipit picks the safest builder automatically
and falls back to Docker or Wasmer when requested:
uvx shipit-cli . --wasmerbuilds locally and runs inside Wasmer.uvx shipit-cli . --dockerbuilds it with Docker (you can customize the docker client as well, eg:--docker-client depot).uvx shipit-cli . --startlaunches the app after building.
You can combine them as needed:
uvx shipit-cli . --start --wasmer --skip-prepare
Commands
Default auto mode
Full pipeline in one command. Combine flags such as --regenerate to rewrite
the Shipit file. Use --wasmer to run with Wasmer.
generate
uvx shipit-cli generate .
Create or refresh the Shipit file. Override build and run commands with
--install-command, --build-command, or --start-command. Pick an explicit
provider with --use-provider.
plan
uvx shipit-cli plan --out plan.json
Evaluate the project and emit config, derived commands, and required services without building. Helpful for CI checks or debugging configuration.
build
uvx shipit-cli build
Run the build steps defined in Shipit. Append --wasmer to execute inside
Wasmer, --docker to use Docker builds.
run
uvx shipit-cli run
Run explicit commands for the project. Use --start to run the start
command, or pass one or more --command values. Combine with --wasmer
for WebAssembly execution.
deploy
uvx shipit-cli deploy
Deploy a Wasmer package generated by shipit build --wasmer. Use
--wasmer-deploy-config to write deployment metadata instead of publishing.
The Shipit file
shipit generate writes a small, editable Starlark file that pairs a
provider build with a serve:
load("//shipit/tools:python.shipit", "python_build", "python_serve")
build = python_build(config)
python_serve(config, build, name = "my-app")
The file is yours: add steps around the build (build_pre / build_post),
extend the runtime (extra_deps, extra_env), attach services, or compose
builds and serves from different providers (a Hugo build served by the
shared static serve, a PHP build with a Node asset build folded in). Any
config field can also be overridden without editing anything, via SHIPIT_*
environment variables (e.g. SHIPIT_PHPIX=true) or --config JSON.
See docs/shipit-files.md for the full format
reference: builtins, file_exists(), load labels, the serve override
surface, and composition examples.
Supported Technologies
Shipit works with three execution environments:
- Local builder for fast, host-native builds.
- Docker builder when container isolation is required.
- Wasmer runner for portable WebAssembly packaging and deployment.
Development
Clone the repository and use the uv project environment.
uv run shipit . --start
Use any other subcommand during development by prefixing with uv run shipit,
for example uv run shipit build . --wasmer. This keeps changes local while
matching the published CLI behaviour.
Tests
Run the test suite with:
uv run pytest
You can run the e2e tests in parallel (-n 8) with:
uv run pytest -m e2e -v "tests/test_e2e.py" -s -n 8
You can also run one technology slice at a time with e2e_static,
e2e_staticpython, e2e_staticnode1, e2e_staticnode2, e2e_python,
e2e_node, or e2e_php, for example:
uv run pytest -m "e2e and e2e_staticnode1" -v "tests/test_e2e.py" -s -n 4
The e2e tests will:
- Build the project (locally, or with docker)
- Run the project (locally or with Wasmer)
- Test that the project output (via http requests) is the correct one
Release Automation
Releases are automated with Release Please and PyPI Trusted Publishing.
Requirements:
- Enable GitHub Actions workflow permissions for creating pull requests in the
repository settings. Release Please uses the built-in
GITHUB_TOKEN. - Configure PyPI Trusted Publishing for the
shipit-cliproject:- owner:
wasmerio - repository:
shipit - workflow:
pypi-publish.yml - environment:
pypi
- owner:
- Create a GitHub environment named
pypi. Add reviewers there if releases should require manual approval before publishing.
On each push to main, Release Please opens or updates a release PR based on
Conventional Commits. When that PR is merged, it creates a GitHub release with
a vX.Y.Z tag and dispatches the PyPI workflow for that tag with the built-in
GITHUB_TOKEN. The PyPI workflow also supports manual dispatch for reruns. It:
- Runs regular tests, excluding e2e tests.
- Validates that the tag version without the leading
vmatches:project.versioninpyproject.tomlversioninsrc/shipit/version.py
- Builds the package and publishes to PyPI only if all checks pass.
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file shipit_cli-0.22.0.tar.gz.
File metadata
- Download URL: shipit_cli-0.22.0.tar.gz
- Upload date:
- Size: 111.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
97755bb1fd793cf64e4995ab491c2e7e20c74f2a20396167b143c8e5a49b0739
|
|
| MD5 |
ca9bf2d92f0ac4dac8eb7e385127a8f9
|
|
| BLAKE2b-256 |
deea8d02177bb9bc37ca16951f564309faaa0bf6005082fd470cf4cdd1166762
|
Provenance
The following attestation bundles were made for shipit_cli-0.22.0.tar.gz:
Publisher:
pypi-publish.yml on wasmerio/shipit
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
shipit_cli-0.22.0.tar.gz -
Subject digest:
97755bb1fd793cf64e4995ab491c2e7e20c74f2a20396167b143c8e5a49b0739 - Sigstore transparency entry: 2187913399
- Sigstore integration time:
-
Permalink:
wasmerio/shipit@a51d7d11e839a3b40eaaae7d83dfbefd3f09c047 -
Branch / Tag:
refs/tags/v0.22.0 - Owner: https://github.com/wasmerio
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-publish.yml@a51d7d11e839a3b40eaaae7d83dfbefd3f09c047 -
Trigger Event:
workflow_dispatch
-
Statement type:
File details
Details for the file shipit_cli-0.22.0-py3-none-any.whl.
File metadata
- Download URL: shipit_cli-0.22.0-py3-none-any.whl
- Upload date:
- Size: 93.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.12
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
03a00258854ae0296d62b948d113b99a7f1274cd1d114d7bbebc66344d0116c2
|
|
| MD5 |
dca9a6cd31599c546d83b3fcd83cfdd8
|
|
| BLAKE2b-256 |
53222ad973fc9aa36c22096008843176578be281a726c0adbaf8a7a7748e6f36
|
Provenance
The following attestation bundles were made for shipit_cli-0.22.0-py3-none-any.whl:
Publisher:
pypi-publish.yml on wasmerio/shipit
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
shipit_cli-0.22.0-py3-none-any.whl -
Subject digest:
03a00258854ae0296d62b948d113b99a7f1274cd1d114d7bbebc66344d0116c2 - Sigstore transparency entry: 2187913405
- Sigstore integration time:
-
Permalink:
wasmerio/shipit@a51d7d11e839a3b40eaaae7d83dfbefd3f09c047 -
Branch / Tag:
refs/tags/v0.22.0 - Owner: https://github.com/wasmerio
-
Access:
private
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
pypi-publish.yml@a51d7d11e839a3b40eaaae7d83dfbefd3f09c047 -
Trigger Event:
workflow_dispatch
-
Statement type:
