README-jekyll.md 9.58 KB
Newer Older
1 2
# Jekyll pipelines

3 4
[[_TOC_]]

5 6 7

## Jekyll multi-environment on GitLab Pages

8 9 10
* **production**: automatically deployed when `production` branch changes
  * proposed domain name: *subdomain.example.com*
* **pre-production**: automatically deployed when `master` branch changes
11
  * proposed domain name: *pre-subdomain.example.com*
12
  * Restricted access to gitlab project members
13 14 15
* **pre-production** can be manualy deployed for any feature branch (any branch that is not `master` or `production`).
  * Inform the rest of the team because it will destroy and replace the **pre-production** linked to the `master` branch.
  * In the GitLab project click on *CI/CD* (the rocket icon)
16
  * Search a pipeline with status *blocked* (with a gear icon) that match the desired branch and commit
17 18 19 20 21
  * Click in the *deploy_preprod* play button (the triangle icon)
  * Once done the *pre-production* environment will host the build for the feature branch.
  * Warning: It will be automatically replaced by any new commit on the `master` branch.

Validate wich commit is deployed in any environment via `/commit.html` by example https://www.linagora.com/commit.html
22 23


24 25 26
## Workflow

The workflow is based in the gitlab branching strategy and this is the overview:
27 28 29
* feature branch -MR-> `master` branch -MR-> `production` branch
  * Any branch other that `master` or `production` is considered a feature branch.
  * MR means Merge Requuest at Gitlab
30 31 32 33 34 35 36 37

Jekyll projects usually have two types of contributors:
* **Content developer**: write articles and upload images for the website, usually from GitLab Web interface.
* **Theme developer**: write or improve the Jekyll theme code

In any case is very important to know:
* If you push directly to `production` is almost sure you will mess up the repository.
  * Setup proposed below avoid this to happen.
38
* **Only merge to `production` from `master`**. Otherwise you will mess up the repository.
39 40 41
  * `Warning` Be extremely carrefull while merging to `production`.
  * There is no way to avoid this via configurtion. Again, be atentive while merging to `production`.
* If you are content developer working on small changes try to work (add commits) directly in the `master` branch
42
* If you are theme developer then you must to create a feature branch, to deliver your work please [create a Merge Request](https://docs.gitlab.com/ee/user/project/merge_requests/creating_merge_requests.html) from your feature branch to `master` (**never** to `production`).
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60


### Workflow Content Developer

* Go to main project in gitlab web interface
* Modify the website content
* Commit (Save) your changes in the default branch (`master`)
* Wait 2 to 5 minutes (check Gitlab CI/CD pipeline for details)
* Check your changes in the preproduction environment domain (ex: pre-subdomain.example.com)
* If you think is good then:
  * If you have a reviewer (ex: the project manager) create a Merge Request and made him the owner for the MR and ask him to check ASAP
    * If good he supposed to merge your content to `production` and by doing that your changes will be deployed in production.
    * If changes are required your reviewer supposed to write comments in the MR sugesting changes or pointing problems.


### Workflow Theme Developer

* Go to main project in gitlab and copy the link to clone it
61
* Clone main project (`master` default branch).
62 63 64 65 66 67 68 69 70 71
* Checkout a new branch (other that `master` or `production`) by example `git checkout -b TRI-feature-name`
* Push your feature branch to our GitLab
* While ready do a MR from your feature branch (ex: `TRI-feature-name`) to `master` and assign it to the project manager.


### Workflow Project Manager

* You must to review the Merge Request, your main mission is to ensure:
  * Theme Developers propose MR from their own feature branch to `master` branch
    * Almost inmediatly merge (do a MR and then merge it yourself) this changes to `production`
72
  * Content Developers propose MR from `master` to `production`
73 74 75 76 77
* You also suposed to take a look to the code (both real code and content) to ensure things are OK and you also supposed to check the preproduction website (validate *pre-subdomain.example.com/commit.hml* to know wich commit you are reviewing) to validate that it works as expected.



## GitLab projects
78

79
GitLab offer one GitLab Page per project and we require one Gitlab Page per environment, then we require two Gitlab projets per website:
80

81
* **Primary project (Production environment)**
82 83 84
  * Contains Jekyll code used by the main pipeline to generate and deploy the website.
  * The GitLab Page of this project is used to automatically deploy *production* (`production` branch).
  * Example: https://ci.linagora.com/linagora/communication/corporate-website/next-website-project/corporate-website
85 86
  * Sugestion: Follow [this guide](https://ci.linagora.com/linagora/organization/procedure-de-deployement-des-sites-internes-avec-gitlab-et-jekyll#3-cr%C3%A9ation-dun-nouveau-projet-sur-gitlab) (in French) to create your new Jekyll project from a template.
* **Secondary project (Pre-Production environment)**
87 88
  * Almost empty (no code or project management) but configured to run the secondary pipeline
  * The GitLab Page of this projet is used to deploy *pre-production*
89 90
    * `master` is automatically deployed (from primary project)
    * Feature branches could be manually deployed (from primary project)
91
  * Example: https://ci.linagora.com/linagora/communication/corporate-website/next-website-project/corporate-website-preprod
92

93 94 95
Notes:
* Neither of this repositories supposed to have a `.gitlab-ci.yml` file. If your project already have one please remove it to avoid misunderstandings.
* Next sections proposes configuration values intended to be modified in a brand new Gitlab project. If your Gitlab project does not have the defaults this setup could not work properly.
96 97 98 99


### Primary project configuration

100
All this options are in the left menu:
Fredy PULIDO's avatar
Fredy PULIDO committed
101 102
* Repository / Branches:
  * Create (from `master`) a new branch named `production`
103 104 105 106 107
* Members:
  * Sugestion: While convinient do it at the Gitlab parent group level to avoid doing this setup for each project.
  * *Max role*: `Developer` for content or code developers
  * *Max role*: `Maintainer(or owner) for the project manager
  * Warning: giving maintainer or owner to content or theme developers give to them the power to destroy the repository by accident. Please do not do it.
108
* Settings / General / Visibility, project features, permissions / Pages
109
  * Enabled: `Everyone`
110 111
* Settings / General / Merge requests / Merge method:
  * `Fast-forward merge` (clean git log, avoid braking repo)
112
* Settings / General / Merge requests / Merge checks:
113
  * `Pipelines must succeed`
114
* Settings / Repository / Protected Branches:
115
  * `master` (default)
116 117
    * Allowed to merge: `Developers + Maintainers`
    * Allowed to push: `Developers + Maintainers`
118 119 120
  * `production`
    * Allowed to merge: `Maintainers`
    * Allowed to push: `No one`
121 122
* Settings / CI-CD / General pipelines
  * Custom CI configuration path: `ci-jekyll-gl_pages-primary.yml@publicgroup/templates/gitlab-ci-yml`
Fredy PULIDO's avatar
Fredy PULIDO committed
123
* Settings / CI-CD / Variables:
124 125 126
  * Type: `Variable`
  * Key: `CI_SECONDARY_PROJECT_ID`
  * Value: Get it from the **secondary project** [General Settings](https://docs.gitlab.com/ee/user/project/settings/index.html#general-settings)
Fredy PULIDO's avatar
Fredy PULIDO committed
127
* Settings / Pages / New Domain
Fredy PULIDO's avatar
Fredy PULIDO committed
128
    * Warning: If this website is already in production (ex: actually a Wordpress and you are migrating it to Jekyll) leave this configuration for the very end. Otherwise you will shutdown the production (the Wordpress in our example).
Fredy PULIDO's avatar
Fredy PULIDO committed
129 130 131 132 133 134
    * Domain: www.example.com  (replace with your domain name)
    * Automatic certificate management using Let's Encrypt: Enabled
    * Note: After you clik "Create New Domain" button the **DNS** fiels will appear.
      * Copy it and ask the domain name administrator (usally IT) to create that record.
      * `Warning`: Do not forget to click the "Save Changes" green button.
    * Note: If your domain provider offer http redirections (gandi.net does) create on for example.com. If it does not offer it then do this same process for example.com.
135

136

137 138
### Secondary project configuration

Fredy PULIDO's avatar
Fredy PULIDO committed
139 140 141 142 143
* Repository / Branches:
  * Ensure that `master` is the only branch in this project.
* Repository / Files:
  * Ensure that `master` only contains a `README.md` file with this content:
    * `WARNING: Read [README-jekyll.md](https://ci.linagora.com/publicgroup/templates/gitlab-ci-yml/blob/master/README-jekyll.md) before to do anything.`
144 145
* Settings / General / Naming, topics avatar:
  * Project description (optional): `The GitLab Page of this projet is used to deploy pre-production`
146
* Settings / General / Visibility, project features, permissions / Pages
Fredy PULIDO's avatar
Fredy PULIDO committed
147
  * Enabled: `Only Project Members`
148 149 150 151
* Settings / General / Merge requests / Merge method:
  * `Fast-forward merge` (clean git log, avoid braking repo)
* Settings / Repository / Protected Branches:
  * `master`
Fredy PULIDO's avatar
Fredy PULIDO committed
152
    * Allowed to merge: `Developers + Maintainers`
153
    * Allowed to push: `No one`
154 155
* Settings / CI-CD / General pipelines / Custom CI configuration path:
  * `ci-jekyll-gl_pages-secondary.yml@publicgroup/templates/gitlab-ci-yml`
Fredy PULIDO's avatar
Fredy PULIDO committed
156 157 158 159 160 161
* Settings / Pages / New Domain
    * Domain: pre-www.example.com  (replace with your domain name, keep the "pre-")
    * Automatic certificate management using Let's Encrypt: Enabled
    * Note: After you clik "Create New Domain" button the **DNS** fiels will appear.
      * Copy it and ask the domain name administrator (usally IT) to create that record.
      * `Warning`: Do not forget to click the "Save Changes" green button.
162

163

Fredy PULIDO's avatar
Fredy PULIDO committed
164 165
## Jekyll tips
* [Matomo configuration reference](https://ci.linagora.com/linagora/organization/expertise-libre.fr/commit/b90a9faf0828b1db551e30d771dc9938b2e0104d)