depush

Deploy a versioned codebase directory to S3/MinIO, SSH, or a local directory.

depush reads a version file from your codebase directory and deploys all files to {prefix}/{version}/ at the destination. Stale files at the destination that no longer exist in the source are automatically deleted, keeping deployments in sync. You can also override the version string at deploy time without touching the version file.

Configuration is flexible: use CLI flags, environment variables, or a YAML config file. Precedence (highest to lowest): CLI flag > environment variable > YAML config > default.

Installation

pip install depush

Or with uv:

uv add depush

To install as a standalone CLI tool:

uv tool install depush

Quick start

Your codebase directory must contain a version file:

my-project/
├── version        # contains e.g. "1.2.3"
├── main.py
└── ...

If you supply --version-override (or DEPUSH_DEPLOY_VERSION_OVERRIDE), the version file is optional and its value is ignored.

Deploy to S3 / MinIO

depush --target s3 --prefix mylib \
  --s3-bucket deployments \
  --s3-endpoint http://localhost:9000 \
  --s3-access-key admin \
  --s3-secret-key secret

Files are uploaded to s3://deployments/mylib/1.2.3/.

Deploy over SSH

depush --target ssh --prefix mylib \
  --ssh-host myserver.example.com \
  --ssh-user deploy \
  --ssh-key-file ~/.ssh/id_rsa

Files are copied to /deployments/mylib/1.2.3/ on the remote host.

Deploy to a local directory

depush --target local --prefix mylib --local-dest /srv/releases

Files are copied to /srv/releases/mylib/1.2.3/.

Dry run

Add --dry-run to any command to preview what would be deployed without making any changes:

depush --target s3 --prefix mylib --s3-bucket deployments --dry-run

Override the version

Pass --version-override to use a custom version string instead of reading the version file. The file does not need to exist when this flag is set:

depush --target local --prefix mylib --local-dest /srv/releases \
  --version-override "$(git rev-parse --short HEAD)"

Files are deployed to /srv/releases/mylib/<git-sha>/.

Configuration file

Place a depush.yaml in the current directory (or pass --config path/to/file.yaml) to avoid repeating flags:

target: s3
prefix: mylib
codebase_dir: ./codebase
# dry_run: false
# version_override: "v1-hello"    # optional; overrides the version file when set
                        # empty string (or omitting the key) falls back to reading the version file

s3:
  bucket: deployments
  endpoint: http://localhost:9000   # omit for AWS
  region: us-east-1
  access_key: admin
  secret_key: secret

# local:
#   dest: ./dist

# ssh:
#   host: myserver.example.com
#   port: 22
#   user: deploy
#   key_file: ~/.ssh/id_rsa
#   deploy_root: /deployments

Environment variables

All options can also be set via environment variables:

Ignoring files

Create a .depushignore file in the directory you run depush from (the same place depush.yaml is looked up) using the same syntax as .gitignore to exclude files from deployment. Patterns are matched relative to the codebase directory:

*.log
__pycache__/
.env

Programmatic use

from depush import depush

# Parse args and deploy
depush.main()

# Or use individual functions
files = depush.collect_files(Path("./my-codebase"))