From 4fb85408b8f4e8b87eb97a43db50c86399d8e350 Mon Sep 17 00:00:00 2001 From: Jon Date: Mon, 22 May 2023 14:59:31 +0930 Subject: [PATCH] docs: move readme to project pages index !25 --- README.md | 98 ++----------------------------- pages/projects/gitlab-ci/index.md | 96 +++++++++++++++++++++++++++++- 2 files changed, 99 insertions(+), 95 deletions(-) diff --git a/README.md b/README.md index db97cd7..5cbadf3 100644 --- a/README.md +++ b/README.md @@ -43,12 +43,15 @@ links: ## Using this repository for your Gitlab CI/CD Jobs. + This repository has been designed as a central point for your repositories CI/CD jobs. By simply linking this repository to your repository and configuring, your CI/CD jobs will run as part of the build process, whilst keeping any CI/CD commits limited within your git history. Each CI/CD job is contained within its own sub-folder. Each sub-folder has a readme specific to the job, which includes the details on how to implement, use etc. +For further details on using these templates with your Gitlab CI/CD jobs, pleaase view the [documentation](https://nofusscomputing.com/projects/gitlab-ci). -### gitlab-ci layout + +### gitlab-ci repository layout We use the following branches *(these jobs assume you do as well)*: - `master` - Considered as the stable branch @@ -57,99 +60,8 @@ We use the following branches *(these jobs assume you do as well)*: We also tag each branch to denote the version of release. We use our own repo to do the version increment automagically in line with [semantic versioning](https://semver.org/). - -### CI Stages -The CI stages for these jobs are as follows, and in the order expected by the jobs: - -- validation - > validation of files, commits, Merge Request titles, code quality, license checks. - -- build - > build any binaries or files that would be used in the later stages . - -- prepare - > any jobs that must run after build but before testing. for example a docker image build that includes artifacts from the build job - -- test - > unit, functional, integration and any other tests. - -- release - > git tagging and creating a gitlab release. Also includes adding build artifacts to gitlab registry. - -- sync - > repository synchronization, i.e. push mirror to github. - -- publish - > placement of build objects to external sources - -### .gitlab-ci.yml example - -example: -``` yaml -stages: - - validation - - build - - prepare - - test - - release - - sync - - publish - -variables: - GIT_SUBMODULE_STRATEGY: recursive - MY_PROJECT_ID: "{your_project_id}" - -include: - - project: nofusscomputing/projects/gitlab-ci - ref: 68b6bc3bfacf0770e10d2e10a5c57952070d44fe - file: - - conventional_commits/.gitlab-ci.yml - - gitlab_release/.gitlab-ci.yml - - git_push_mirror/.gitlab-ci.yml - - ansible/.gitlab-ci.yml - -``` -| :bulb: Tip | -|:----| -| *Use a project import in your `.gitlab-ci.yml` file that is tied to a specific `ref`. for example a commit or tag. Also ensure that the `gitlab-ci` `git sub-module` and the `ref` as part of the includes matches.* | - - -### Artifacts -Any artifacts by jobs will be created in folders named after the stage. - -preference is placed on jobs to output JUnit.xml test reports. This is because they are visible in merge requests. - - -## Git Sub-Module setup - -It is recommended that you set-up this repo as a git sub-module to your repo and that you configure it to a set commit/tag. This ensures that any change to `gitlab-ci` repo, does not effect your CI/CD jobs. - -run the following commands: -``` bash -git submodule add -b {ref} https://gitlab.com/nofusscomputing/projects/gitlab-ci.git gitlab-ci -git submodule update --remote - -``` - -| :bulb: Tip | -|:-----| -| NOTE: `{ref}` should be replaced with the branch name, `master` is the stable branch and recommended. by default the sub-module will be created in folder `gitlab-ci`, it is recommended that you **don't** change this folder name. -You can also substitute the gitlab url with the github url `https://github.com/NoFussComputing/gitlab-ci.git` for the submodule if you desire. this repo is auto-synced with github on each change to the repo. | - -After each `git submodule update --remote` you will have to commit the sub-module update to your repo. Suggested commands as follows: -``` bash -git add .gitmodules - -git add gitlab-ci - -git commit -m "ci(gitlab-ci): updated to use version x - -{your reason here or explain what is provided/changed}" -``` -Then push the changes to your source. - - ## Contributing + All contributions for this project must conducted from [Gitlab](https://gitlab.com/nofusscomputing/projects/gitlab-ci). For further details on contributing please refer to the [contribution guide](CONTRIBUTING.md). diff --git a/pages/projects/gitlab-ci/index.md b/pages/projects/gitlab-ci/index.md index 588f169..2462bad 100644 --- a/pages/projects/gitlab-ci/index.md +++ b/pages/projects/gitlab-ci/index.md @@ -1,7 +1,7 @@ --- title: No Fuss Computings Gitlab-CI Project description: How to use No Fuss Computings gitlab-ci project within your CI/CD pipelines -date: 2021-08-11 +date: 2023-05-22 template: project.html about: https://gitlab.com/nofusscomputing/projects/gitlab-ci --- @@ -9,7 +9,99 @@ about: https://gitlab.com/nofusscomputing/projects/gitlab-ci !!! Note Docs Still under development + ## Docs ToDo - Templates folder is for `gitlab-ci.yaml` that automagically create the jobs if included -- other sub folders are for `` which **DO NOT** automagically create jobs, but are pure definitions only. \ No newline at end of file + +- other sub folders are for `` which **DO NOT** automagically create jobs, but are pure definitions only. + + +## CI Stages + +The CI stages for these jobs are as follows, and in the order expected by the jobs: + +- validation + > validation of files, commits, Merge Request titles, code quality, license checks. + +- build + > build any binaries or files that would be used in the later stages . + +- prepare + > any jobs that must run after build but before testing. for example a docker image build that includes artifacts from the build job + +- test + > unit, functional, integration and any other tests. + +- release + > git tagging and creating a gitlab release. Also includes adding build artifacts to gitlab registry. + +- sync + > repository synchronization, i.e. push mirror to github. + +- publish + > placement of build objects to external sources + + +## Git Sub-Module setup + +It is recommended that you set-up this repo as a git sub-module to your repo and that you configure it to a set commit/tag. This ensures that any change to `gitlab-ci` repo, does not effect your CI/CD jobs. + +run the following commands: + +``` bash + +git submodule add -b {ref} https://gitlab.com/nofusscomputing/projects/gitlab-ci.git gitlab-ci +git submodule update --remote + +``` + +!!! Tip + NOTE: `{ref}` should be replaced with the branch name, `master` is the stable branch and recommended. by default the sub-module will be created in folder `gitlab-ci`, it is recommended that you **don't** change this folder name. + + You can also substitute the gitlab url with the github url `https://github.com/NoFussComputing/gitlab-ci.git` for the submodule if you desire. this repo is auto-synced with github on each change to the repo. + +After each `git submodule update --remote` you will have to commit the sub-module update to your repo. Suggested commands as follows: + +``` bash + +git add .gitmodules + +git add gitlab-ci + +git commit -m "ci(gitlab-ci): updated to use version x + +{your reason here or explain what is provided/changed}" + +``` + +Then push the changes to your source. + + +## .gitlab-ci.yaml example + +example: + +``` yaml + +include: + - project: nofusscomputing/projects/gitlab-ci + ref: master + file: + - .gitlab-ci_common.yaml + - $JOB_ROOT_DIR/{filepath to include here and is relative to the gitlab-ci repo root} + +variables: + MY_PROJECT_ID: "{your_project_id}" + +``` + +!!! Tip + Use a project import in your `.gitlab-ci.yml` file that is tied to a specific `ref`. for example a branch, commit or tag. Also ensure that the `gitlab-ci` `git sub-module` and the `ref` as part of the includes matches.* + + +## Artifacts + +Any artifacts by jobs will be created in folders named after the stage. + +preference is placed on jobs to output JUnit.xml test reports. This is because they are visible in merge requests.