Blip

Blip turns an authenticated Git-host webhook delivery into one local executable run. It verifies the provider-specific signature, rejects duplicate delivery IDs, places new deliveries in a single queue, and runs the configured script file.

Status: Phase 1 development, version 0.3.0. The current release provides GitLab, GitHub, Gitea, and Codeberg templates, management CLI, systemd installation, a durable serial queue, graceful shutdown, in-place upgrades, logs, and basic history. Phase 1 remains on 0.x releases; Phase 2 begins at 1.0.0.

Why Blip

Blip replaces the repeated SSH → pull → deploy routine without requiring hosted runner minutes or a full CI/CD platform. It does not define build steps. The executable you register remains the complete deployment procedure for that application.

Configuration

One project needs only an endpoint key, an executable file, and exactly one provider template:

[projects.example-app]
script = "/srv/example-app/deploy"
gitlab.signing_token = "whsec_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="

• example-app becomes /webhook/example-app; there is no duplicate name field.
• The nested gitlab, github, gitea, or codeberg table selects the webhook template; there is no generic provider field in TOML.
• script is an absolute path to an executable file, not a directory and not a shell command.
• Event controls remain at the Git host instead of being repeated in Blip.
• Queue locking is internal and global; it is not project configuration.
• For an existing webhook, secret_token may replace or temporarily accompany signing_token.

See the configuration reference for global defaults and multiple projects.

Install and set up

Prepare the deployment executable first, then choose an installation method.

Method 1: Compile Source installation

curl -fsSL "https://gitlab.com/almateraincubator/utilities/blip/-/raw/dev/docs/install.sh" | sudo bash

The installer obtains the non-root build account from SUDO_USER. No user, repository, branch, or source-directory argument is required for a standard installation.

Method 2: Pre-built binary installation

curl -fsSL "https://gitlab.com/almateraincubator/utilities/blip/-/raw/dev/docs/install.sh" | sudo env BLIP_INSTALL_METHOD="binary" bash

The binary installer detects your host architecture, downloads the matching pre-compiled release archive and checksums, installs the standalone executable, and configures the systemd service without requiring a local Rust toolchain or build tools.

Method 3: Cargo (crates.io)

cargo install bliper
sudo blip service install --user "$USER"

Initial setup

The first run asks for:

1. The project key used in the webhook URL.
2. The absolute path to the executable script file.
3. A provider and its webhook credential. GitLab prefers a Signing token; the other templates use their webhook secret.

If the installer finds the obsolete [[projects]] schema, the same command backs it up and starts the current configuration prompt automatically. After the first installation, use blip --upgrade instead of downloading the installer again. Full options are documented in Installation.

Upgrade

blip --upgrade
# or
blip -U

The upgrade command fast-forwards the installer-managed dev checkout, builds as the non-root build user, installs the new binary, validates the existing configuration, updates the systemd unit, and restarts the service. Configuration and runtime data are preserved. A dirty checkout or non-fast-forward update fails without rewriting local work.

GitLab webhook

For a deployment after a merge into dev, configure GitLab:

The merge updates dev, GitLab emits the selected push webhook, and Blip queues the script. No event or branch field is needed in Blip.

Other Git hosts

[projects.github-app]
script = "/srv/github-app/deploy"
github.secret = "replace-with-a-random-secret"

[projects.gitea-app]
script = "/srv/gitea-app/deploy"
gitea.secret = "replace-with-a-random-secret"

[projects.codeberg-app]
script = "/srv/codeberg-app/deploy"
codeberg.secret = "replace-with-a-random-secret"

All providers use POST /webhook/. See the GitHub, Gitea, and Codeberg setup guides for their native signature and delivery headers.

Queue and lock

Accepted deliveries are appended to blip-deliveries.jsonl beside the history file before Blip returns 202 queued. The journal stores FIFO sequence and queued, running, or completed state. Waiting entries survive a service restart. An entry interrupted while running returns to the queue at startup after Blip obtains the global execution lock.

A retry with the same provider delivery ID receives 202 duplicate and does not create another queue entry. One worker consumes the queue, and blip.queue.lock prevents scripts from overlapping even if two Blip processes use the same runtime directory. A script interrupted by process or host failure may run again, so deployment scripts must remain idempotent.

SIGTERM or SIGINT closes webhook admission and lets the active script finish. Waiting entries remain durable and resume after the next start. Blip does not begin another queued script while shutting down.

CLI

blip config path
blip config show
blip config validate
blip config set --bind 127.0.0.1:8080

blip project list
blip project add --key example-app --script /srv/example-app/deploy --provider gitlab
blip project add --key mirror --script /srv/mirror/deploy --provider github
blip project remove example-app

blip history --project example-app --status failure --limit 20
blip logs --lines 100
blip logs --follow
blip queue
blip --upgrade

blip service status
blip service restart
blip service enable
blip service disable
blip service uninstall

blip --config /etc/blip/blip.toml serve

The installed config is detected automatically. Use global --config FILE for another file. Read commands run as the current user when permissions allow. Config mutations and system service operations invoke sudo when needed, so both blip ... and sudo blip ... are supported.

Versioning

Phase 1 uses 0.x versions while the provider set and operational contracts are still being completed. Minor releases may change pre-1.0 interfaces and must document migrations. Phase 2 starts with 1.0.0 and a stable public configuration and CLI contract.

HTTP responses

202 does not mean deployment succeeded. Check blip history or blip logs.

Build

cargo fmt --check
cargo test --locked
cargo build --locked --release

The binary is written to target/release/blip.

Documentation

• Repository instructions
• Detailed change log
• Wiki index
• Installation
• Configuration
• GitLab setup
• GitHub setup
• Gitea setup
• Codeberg setup
• Runtime and queue
• Security
• Roadmap
• Configuration example

License

Blip is distributed under the Almatera Incubator License.