From b5237f51dc2edda608d99e35028232405128b82f Mon Sep 17 00:00:00 2001
From: Stefan Gruna <stefan@21st.digital>
Date: Fri, 30 Aug 2024 15:29:11 +0200
Subject: [PATCH] chore: set up git automation and document necessary steps

---
 README.md               | 55 +++++++++++++++++++++++++++++++++++++++++
 config/statamic/git.php |  2 +-
 routes/console.php      |  8 +++---
 3 files changed, 59 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 04b7b4ad..f800ef64 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,7 @@ Welcome to the GitHub repository for the 21st digital website! Our aim is to tra
 ## Table of Contents
 
 - [Git LFS](#git-lfs)
+- [Git Automation](#git-automation)
 
 ## Git LFS
 
@@ -27,3 +28,57 @@ git lfs install
 ```
 
 This setup only needs to be done once per user account.
+
+## Git Automation
+
+It might be necessary to push content changes from a staging or production server back to the Git repository. This mechanism is enabled by Laravel's scheduling system via cron jobs. An appropriate task has already been defined in `routes/console.php`:
+
+```php
+Schedule::command('statamic:git:commit')
+    ->everyTenMinutes();
+```
+
+Additionally some [environment variables](#local-environment) have to be set and a [cron job](#cron-job-setup) to execute the scheduler has to be installed.
+
+### Local Environment
+
+It is important to disable the automatic git commit functionality. The best way for the local environment is to disable the git functionality completely:
+
+| Variable                     | Description                                              |
+| ---------------------------- | -------------------------------------------------------- |
+| `STATAMIC_GIT_ENABLED=false` | Disable Statamic's git system for the local environment. |
+
+This is also the default value so it might not be necessary to explicitely set this variable locally.
+
+### Server Environment
+
+The following environment variables have to be set on production or staging servers:
+
+| Variable                       | Description                                                                                                           |
+| ------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
+| `STATAMIC_GIT_ENABLED=true`    | Enable Statamic's git system.                                                                                         |
+| `STATAMIC_GIT_AUTOMATIC=false` | Disable the automatic commit functionality. This allows us to consolidate multiple commit messages into a single one. |
+| `STATAMIC_GIT_PUSH=true`       | Automatically push changes to the repository after a commit has been made.                                            |
+
+### Cron job setup
+
+A cron job has to be set up on the production/staging server to automatically run the scheduled tasks:
+
+```
+* * * * * cd /path-to-your-project && php artisan schedule:run >> /dev/null 2>&1
+```
+
+Further information can be found in [Laravel's Scheduling documentation](https://laravel.com/docs/11.x/scheduling#running-the-scheduler).
+
+### Handle commits from server
+
+The Git setup for production/environment servers collects multiple commits and combines them into a single one. Therefore a generic Git user and email is used (see `config/git.php`). The consolidated commit message from the server starts with the string `chore(cms):`. This can be used in different workflows to enable/disable steps. A common example is the auto deployment feature on services like Laravel Forge:
+
+```
+if [[ $FORGE_DEPLOY_MESSAGE =~ ^chore\(cms\): ]]; then
+    echo "AUTO-COMMITTED ON PRODUCTION. NOTHING TO DEPLOY."
+    exit 0
+fi
+```
+
+This can also be used in github workflows to skip actions or do specific operations.
diff --git a/config/statamic/git.php b/config/statamic/git.php
index c1aa795d..81e63211 100644
--- a/config/statamic/git.php
+++ b/config/statamic/git.php
@@ -133,7 +133,7 @@
 
     'commands' => [
         'git add {{ paths }}',
-        'git -c "user.name={{ name }}" -c "user.email={{ email }}" commit -m "chore(cms): update content ({{ message }})"',
+        'git -c "user.name={{ name }}" -c "user.email={{ email }}" commit -m "chore(cms): update content"',
     ],
 
     /*
diff --git a/routes/console.php b/routes/console.php
index eff2ed24..708e2667 100644
--- a/routes/console.php
+++ b/routes/console.php
@@ -1,8 +1,6 @@
 <?php
 
-use Illuminate\Foundation\Inspiring;
-use Illuminate\Support\Facades\Artisan;
+use Illuminate\Support\Facades\Schedule;
 
-Artisan::command('inspire', function () {
-    $this->comment(Inspiring::quote());
-})->purpose('Display an inspiring quote')->hourly();
+Schedule::command('statamic:git:commit')
+    ->everyTenMinutes();