Git Push Deployments

MicroFly supports native Git-push deployments. You can push commits directly from your local development workstation or CI/CD runner to your MicroFly server to trigger immediate, automated builds and deployments.

---

1. Initializing the Git Repository

On the server hosting MicroFly, initialize a bare Git repository for your application:

sudo microfly init-git my-app

Output:

git remote ready: /var/lib/microfly/repos/my-app.git
push with: git remote add production /var/lib/microfly/repos/my-app.git && git push production main

This creates a secured, bare Git repository under /var/lib/microfly/repos/my-app.git owned by root:root with permissions 0700 and configures a pre-built post-receive hook.

---

2. Configuring Remote on Your Development Workstation

From your local project repository, add the remote pointing to your MicroFly server:

# Via SSH (replace user and server-ip with your server's credentials)
git remote add production ssh://[email protected]/var/lib/microfly/repos/my-app.git

Ensure your SSH key has access to push to the server.

---

3. Deploying to Production

When your code is ready to deploy, commit and push your changes to the main or master branch:

git push production main

Terminal output:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Writing objects: 100% (3/3), 2.45 KiB | 2.45 MiB/s, done.
Total 3 (delta 1), reused 0 (delta 0)
remote: {"app":"my-app","release":"20260903T101530.123456789Z-000001"}
To ssh://192.168.1.75/var/lib/microfly/repos/my-app.git
   1a2b3c4..5d6e7f8  main -> main

---

4. Branch Deployments (Ephemeral Previews)

If you push any branch other than main or master, MicroFly automatically provisions an ephemeral preview environment:

git push production feature/user-authentication

Output:

remote: deployed my-app-feature-user-authentication-98af12cd release 20260903T101600.987654321Z-000002
remote: preview URL: http://feature-user-authentication-98af12cd-mysite.local/
To ssh://192.168.1.75/var/lib/microfly/repos/my-app.git
 * [new branch]      feature/user-authentication -> feature/user-authentication

See the Preview Environments Guide for details on managing and promoting preview branches.

---

5. How the post-receive Hook Works

The automated hook inside /var/lib/microfly/repos/<app>.git/hooks/post-receive:

1. Reads the incoming Git revisions (oldrev, newrev, refname).
2. Calls the MicroFly admin API (POST http://microfly/api/apps/<app>/deploy) over the local Unix domain socket.
3. MicroFly runs git archive on the bare repository for that commit, extracts the code (safely handling PAX global extended headers), validates app.toml, runs release_command, validates health checks, and shifts traffic atomically.