From 4aa3028ae9602e5a347d20df89a86c36f88bd250 Mon Sep 17 00:00:00 2001
From: Mario Ramundo <ramundomario@gmail.com>
Date: Thu, 25 Nov 2021 22:33:20 +0100
Subject: [PATCH] [Docs] GitLab CI/CD (#2777)

* [Docs] GitLab CI/CD

* [Docs] GitLab CI/CD - Prevent deployment concurrency

* [Docs] GitLab CI/CD - Deploy secrets

* [Docs] GitLab CI/CD - Deploy code with `rsync`

* [Docs] GitLab CI/CD - Fix typo
---
 docs/ci-cd.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/docs/ci-cd.md b/docs/ci-cd.md
index d5334a8ac..c0f8e5ce4 100755
--- a/docs/ci-cd.md
+++ b/docs/ci-cd.md
@@ -1,3 +1,58 @@
 # CI/CD
 
-TODO
+## GitLab CI/CD
+
+Set the following variables in GitLab project:
+
+- `SSH_KNOW_HOSTS`: Content of `~/.ssh/known_hosts` file. 
+The public SSH keys for a host may be obtained using the utility `ssh-keyscan`. 
+For example: `ssh-keyscan deployer.org`.
+- `SSH_PRIVATE_KEY`: Private key for connecting to remote hosts. 
+To generate private key: `ssh-keygen -t ed25519 -C 'gitlab@deployer.org'`.
+
+Create .gitlab-ci.yml file with following content:
+
+```yml
+stages:
+  - deploy
+
+deploy:
+  stage: deploy
+  image:
+    name: debreczeniandras/deployerphp:7-beta
+    entrypoint: [""]
+  before_script:
+    - mkdir -p ~/.ssh
+    - eval $(ssh-agent -s)
+    - echo "$SSH_KNOWN_HOSTS" > ~/.ssh/known_hosts
+    - chmod 644 ~/.ssh/known_hosts
+    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add - > /dev/null
+  script:
+    - dep deploy -vvv
+  resource_group: production
+  only:
+    - master
+```
+
+###Deployment concurrency
+Only one deployment job runs at a time with the [`resource_group` keyword](https://docs.gitlab.com/ee/ci/yaml/index.html#resource_group) in .gitlab-ci.yml.
+
+In addition, you can ensure that older deployment jobs are cancelled automatically when a newer deployment runs by enabling the [Skip outdated deployment jobs](https://docs.gitlab.com/ee/ci/pipelines/settings.html#skip-outdated-deployment-jobs) feature.
+
+###Deploy code
+Since by default every GitLab CI job already clone the repo, you could use [`rsync`](contrib/rsync.md#usage) task instead of `deploy:update_code` to upload the code from the job to the host.
+
+###Deploy secrets
+Since it is not recommended pushing secrets in the repository, you could use a GitLab variable to store them.
+
+Many frameworks use dotenv to store secrets, let's create a GitLab file variable named `DOTENV`, so it can be deployed along with the code.
+
+Set up a deployer task to copy secrets to the server:
+
+```php
+task('deploy:secrets', function () {
+    upload(getenv('DOTENV'), get('deploy_path') . '/shared/.env');
+});
+```
+
+Run the task immediately after updating the code.