Observe How the Monorepo By Includes Pattern Works.
1. Guided Exploration Monorepo Design Review
Important: These instructions depend on the initial setup being completed first: .gitlab/issue_templates/01-Setup-Repository.md
1.1. Create an Exploration Checklist for Personal Progress Tracking
Since this document is implemented as a GitLab issue template, it can be used to create a new issue for your personal progress tracking. The checklist steps below will become clickable (without changing to markdown edit mode) and you can have your own copy for progress.
-
-
On the left navigation of this repository click Issues
-
-
-
Click New issue
-
-
-
On the New Issue page, next to Title, click Choose a template and select 02-Guided-Exploration-Monorepo-Design-Review
-
-
-
The new issue created allows you to check items off as you complete them.
-
Note: Remove the above section if creating an issue from this template.
1.2. GitLab Flow is Used for This Design Pattern
GitLab Flow follows GitOps disciplines - conseqently all changes - including configuration and deployments - must be made by using a merge request as the change and review gating mechanism for environments.
In this case there is a repository branch per environment and merges between these branches are how changes are promoted to the various environments.
- Merge feature branches to "Master" to collect a changeset / feature set. No builds happen.
- Merge master to sandbox to test release changes. (Branch is protected to only allow merges) Alternatively, feature branches could go straight to sandbox (or even make "sandbox" the default repo branch)
Possible MR Title: "Promote changeset x.y from development to sandbox environment"
- When merge to "sandbox" builds satisfactory, merge "sandbox" to "stage" (Branch is protected to only allow merges and only upon successful build)
Possible MR Title: "Promote changeset x.y from sandbox to stage environment"
- When merge to "stage" builds satisfactorily, at the designated maintenance window, merge it to "production" (Branch is protected to only allow merges and only upon successful build)
Possible MR Title: "Promote changeset x.y from stage to production environment"
1.3. Guided Explorations
- Observe the Variable Setup for Per-Deployment Environment (Branch) Configuration
- Observe the GitLab CI Configuration for Monorepo Design
- Observe a Single Sub-Directory Build
- Observe a Multi-Sub-Directory Build
- Observe a Group Level CI/CD Variables Layering and Overrides
1.3.1. Observe the Variable Setup for Per-Deployment Environment (Branch) Configuration
The CI/CD variable in this repo meet the following unique requirements:
- Repo level CI/CD Variables Can be different per any of the three deployment environments
- Repo level CI/CD Variables Can target multiple environments with a wildcard ("s*" environment scope on variable MULTI_ENV_VAR)
- Branch names map to environment names exactly (in .gitlab-ci.yml)
- Can hold secrets that cannot be seen in logs (masked) for anyone who does not have a maintainer or higher role
-
-
In this repository, from the left hand navigation click Settings => CI/CD => Variables
-
-
-
For GLOBAL_VISIBLE_VAR note that the Scope is set to All environments - this means it will be the same value in all environments.
-
-
- [ ] For PWD1 note that there are three entries - one for each scope ("produciton", "sandbox" and "stage"). This is how the variables are different for each environment. Note that these entires are also:
- Protected - which means they cannot be changed inside of CI/CD
- Masked - which means they will never show in clear text in logs. This is GitLabs way of providing very lightweight security for secrets. (These can be viewed by anyone who has Maintainer or above to the repository.)
-
- [ ] For VISIBLE_ENV_DATA note that there are three entries. These are emited in the build logs to clearly demonstrate that they actually vary by environment (branch) build.
-
-
From the left navigation, click Repository => Files => .build-template.yml
-
-
-
Search for "environment:" and observe that the line below it is name: $CI_COMMIT_REFNAME. Since this variable will be the branch name (in the cases we care about) it will map the build of a specific branch to the environment scopes you observed for variables earlier.
-
-
-
From the left navigation, click Operations => Environments and observe that these environments were auto-populated by the .gitlab-ci.yml mapping that you just observed. Environments do not need to be explicitly created before use (but they can be)
-
1.3.2. Observe the GitLab CI Configuration for Monorepo Design
UNDER CONSTRUCTION
-
-
How .gitlab-ci.yml includes work
-
-
-
gitlab includes (for enhanced control over entire repo level workflow and elimination of repeating code)
-
-
-
limiting builds to changes in a sub-directory
-
-
-
GitLab CI code "templates"
-
1.3.3. Observe a Single Sub-Directory Build
UNDER CONSTRUCTION
For when changes are only made to one sub-project.
-
-
Lorem ipsum dolor sit amet
-
1.3.4. Observe a Multi-Sub-Directory Build
UNDER CONSTRUCTION For when changes in one sub-project require simultaneous, dependent changes in another sub-project.
-
-
Lorem ipsum dolor sit amet
-
1.3.5. Observe a Group Level CI/CD Variables Layering and Overrides
UNDER CONSTRUCTION
For when changes are only made to one sub-project.
-
-
Lorem ipsum dolor sit amet
-