#self-hosted #ci-cd #scm #git

app phantom_ci

Secure Headless Self-Hosted Runner

33 releases

0.1.304 Mar 31, 2025
0.1.303 Mar 31, 2025
0.1.173 Feb 8, 2025
0.1.165 Dec 31, 2024
0.1.156 Nov 29, 2024

#63 in Testing

Download history 10/week @ 2024-12-18 154/week @ 2024-12-25 153/week @ 2025-01-01 8/week @ 2025-01-08 453/week @ 2025-02-05 59/week @ 2025-02-12 25/week @ 2025-02-19 4/week @ 2025-02-26 1245/week @ 2025-03-26 177/week @ 2025-04-02

1,422 downloads per month

MIT license

55KB
1.5K SLoC

🐱 phantom_ci

βš™οΈ Secure, Headless, Self-Hosted CI Runner

βœ… Zero unnecessary outbound connections
πŸ“€ Output to stdout by default (with optional webhooks)
πŸ”’ Built for minimal trust surfaces


🧠 Summary

phantom_ci is a fully self-hosted CI runner that detects changes in Git repositories and executes pipeline steps defined in a workflow.toml file.
All execution happens locally, as the user who runs phantom_ci. No external services are contacted unless explicitly configured.

This project was built with isolation and security in mind β€” specifically to prevent granting inbound or outbound access to unowned servers.


🚫 Common CI Tradeoffs vs phantom_ci

Approach Tradeoff
GitHub Actions / SaaS Runners Inbound access from GitHub into your servers
GitHub’s Self-Hosted Runners Outbound access to GitHub's infra
3rd-party Runners Implicit outbound connections or exposed APIs
βœ… phantom_ci No inbound or outbound access required

πŸ›‘οΈ Security Posture

  • Workflows are only run from a locally configured branch (target_branch)
  • Branch execution config is stored outside the repo, reducing tampering risk
  • CLI-based only β€” no API, no sockets, no network listeners
  • Workflow steps are executed via std::process::Command with optional sandboxing

Default target_branch is "master" β€” configure this explicitly and enforce restrictions via Git to avoid unauthorized command execution.


πŸ“¦ Example: $REPO_ROOT/workflow/master.toml

[0] # step index must be numeric and define execution order
run = "pwd"

[1]
run = "make build"

[2]
run = "make deploy"

πŸ“ Repo Configuration

Monitored repositories are defined in:

~/.config/phantom_ci/Repo.toml
[sys-compare]
path = "https://github.com/helloimalemur/sys-compare"
target_branch = "master"

[elktool]
path = "https://github.com/helloimalemur/ELKTool"
target_branch = "master"

[elktool2] # section headers must be unique
path = "git@github.com:helloimalemur/ELKTool" # SSH recommended
target_branch = "test-branch" # ensure the branch exists

πŸ”” Webhook Notifications (Optional)

To enable Discord webhook notifications, create a .env file at:

~/.config/phantom_ci/.env
DISCORD_WEBHOOK_URL="https://discord.com/api/webhooks/..."

Additional options for verbosity and payload formatting are planned.


πŸš€ Installation

Requires Rust:

cargo install phantom_ci

βš™οΈ Usage

# Run normally
phantom_ci

# Add repo via HTTPS
phantom_ci add https://github.com/your/repo

# Add repo via SSH (recommended)
phantom_ci add git@github.com:your/repo

# Install systemd service
phantom_ci configure service

πŸ’‘ Workflow Configuration

Create a workflow.toml at the root of any monitored repo.
Steps are executed in numeric key order.


πŸ’£ Development & Contribution

Contributions welcome β€” PRs encouraged!

cargo clippy -- -D clippy::all
cargo fmt -- --check

Dependencies

~48MB
~775K SLoC