Statamic Git experimental deployment workflow

This is an advanced, opinionated and VERY experimental (not well tested) workflow for experienced developers to deploy Statamic, where all content is stored as files and managed with Git using the Statamic Git Automation. See the Git Automation Statamic docs article (Pro feature) to get the idea and as reference.

# Concepts

It's kinda like a two way git binding. Usually git works as a one way street at fortrabbit.

Create a repo on the environment, which has the same upstream as your local repo. We create a new branch because we do not want to push changes to the main branch to avoid a deployment loop and to keep code and content separated. Then, any changes we make to content on the environment can be pulled into your local repo, where it can be merged back into main.

┌───────────────────────┐
│  fortrabbit app env   │
└──────▲─────────┬──────┘
       │         │
     main     content
       │         │
┌──────┴─────────▼──────┐
│        GitHub         │
└──────▲─────────┬──────┘
       │         │
     main     content
       │         │
┌──────┴─────────▼──────┐
│   local development   │
└───────────────────────┘
raw

# Get ready

• Statamic running on your local machine
• a good understanding of Git and rsync
• an app with environment on fortrabbit, see Statamic topic too

# 1 - Local preparation

1. Install Statamic on your local computer as described above.
2. Follow our GitHub guides to connect to GitHub and enable automatic deployment

Once finished you git push to deploy, so that Statamic will be installed with the environment on fortrabbit.

# 2 - Get Statamic Pro

The Git Automation is part of the commercial Statamic version. You need to enable the Pro version and obtain a Statamic license to use that feature on fortrabbit. See the official guide on how to do that. As usual, do this with your local installation first and then push the latest state to fortrabbit. After this, you should be able to find Git with the utilities under the Statamic control panel.

# 3 - Set ENV vars in the fortrabbit dashboard

Add the environment variables listed below to the environment with the fortrabbit dashboard.

STATAMIC_LICENSE_KEY=your-site-license-key
STATAMIC_GIT_ENABLED=true
STATAMIC_GIT_AUTOMATIC=true
shell

# 4 - Prepare Git on the environment

Login to your fortrabbit environment by SSH and:

1. Set up an SSH key with SSH keygen (no passphrase), see our SSH keys setup guide
2. Copy the content of the public key (likely .ssh/id_ed25519_fortrabbit.pub) to a buffer
3. Add the public key to GitHub so you can push from the environment

# 5 - Init Git on the environment

We create a separate branch to deployment loops when pushing and to separate code from content. SStill logged in by SSH on the fortrabbit environment.

First add a .gitignore file. Its contents should be the same as the .gitignore file on your local project. Then:

1. Initialise a new Git repo: git init.
2. Create a Git user (see example below)
3. git add . & git commit -m 'initial commit'
4. Create an editorial branch and check it out (git checkout -b 'editorial')
5. Add the GitHub repo as remote

git config --global user.name "John Doe"
git config --global user.email johndoe@example.com
shell

See the Statamic Git guide and the fortrabbit git guide as reference.

# 6 - Try it out

Still logged in by SSH you should be now able to add and commit files with Git to the App and push changes to the deploy service remote from the editorial branch.

When pushing for the first time, set the remote as an upstream. To get this new branch locally fetch new branches from the GitHub remote.

With the Git repo on your local computer you can fetch and checkout the editorial remote branch. Pull changes from there and merge them back into your main branch that you are using for development.

# 7 - Git in the Statamic Control Panel

Now you can also use the Statamic Git Automation, depending on the setup, pending editorial changes are visible with the online Git editor in the Statamic control panel or get committed and pushed automatically (we advise using the recommended delay).