infrastructure/gitlab-ci
2
0
Fork 0
Code Issues 17 Pull Requests 1 Actions Projects Releases 21 Wiki Activity

refactor: move docs as part of restructure

Browse Source 
!21
This commit is contained in:
Jon Lockwood
2023-05-13 15:35:28 +09:30
parent 9670fc4740
commit 408e4eab9e
7 changed files with 90 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
pages/projects/gitlab-ci/ansible_roles.md Normal file
View File

@ -0,0 +1,57 @@
---
title: Ansible
description: How to use No Fuss Computings gitlab-ci job for ansible
date: 2021-08-03
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
This job does ansible role/playbook linting when any commit is pushed to any branch.
This job provides the following badge:
- None
## Dependencies
- None
## your .gitlab-ci.yml changes
To use this job add the following to your `.gitlab-ci.yml` file
``` yaml
stages:
- validation
include:
- remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/development/ansible/.gitlab-ci.yml
Ansible Lint (python 3.6):
variables:
ANSIBLE_LINT_PATH: "roles/"
extends:
- .ansible_linter_defaults
image: python:3.6-slim
```
> You can use any python version you wish.
## CI/CD Variables required
| var name | Description |
|:----:|:----|
| ANSIBLE_LINT_PATH | *The path you wish the linter to search for ansible roles/playbooks* |
## Job Workflow
- This job will lint any yml file in the specified directory using ansible rules.
## Artifacts
- `$CI_PROJECT_DIR/artifacts` - Root artifact directory
- `$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/$PYTHON_VERSION-ansible-lint.junit.xml` - JUnit Test report
- `$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/$PYTHON_VERSION-ansible-lint.log` - Linter log
## License
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)

102
pages/projects/gitlab-ci/conventional_commits.md Normal file
View File

@ -0,0 +1,102 @@
---
title: Conventional Commits
description: How to use No Fuss Computings gitlab-ci job for Conventional Commits
date: 2021-08-03
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
## User Manual
Commitizen is used to validate the format of commit messages. we use [Conventional Commit Messages](https://www.conventionalcommits.org/en/v1.0.0/) format for our validation jobs.
This repository may have two CI jobs to do with commitizen:
- **MR Title** *Checks the Merge Request Title*
- **Commit Messages** *Checks all commit messages*
These CI Jobs output a test report that can be viewed inside of the merge request and contain the error(s), if any.
To fix an error please refer to the titled sections below.
### MR Title
Ensure that the merge request title is in the [conventional message](https://www.conventionalcommits.org/en/v1.0.0/) format. NOTE: the title is case sensitive.
### Commit Messages
All commit messages that form part of your merge request must be in [conventional message](https://www.conventionalcommits.org/en/v1.0.0/) format.
To fix them go back and edit your commit messages.
#### fixing commit messages (suggestion)
If only the last commit is the commit with an error just use `git commit --amend` and edit your commit message to be in the correct format and save. now push your changes.
You will require the following information if the commit message with the error is further down the commit tree:
- Commit message SHA1 of your first commit message to the branch `{original_commit}`
- Commit message SHA1 prior to your first commit `{source_commit}`
Run these commands once you have the information above.
``` bash
git format-patch {original_commit}..HEAD -o diff-patches
git reset {source_commit} --hard
```
Now, navigate to the `diff-patches` folder, open up the offending patch (commit) and edit the `subject` or message body as appropriate and save. Once all the edits have been done, re-apply the patches to your tree with:
``` bash
git am diff-patches/*.patch
```
Now push your changes upstream.
| :notebook_with_decorative_cover: Note |
|:-----:|
| *As you have changed the commit SHA1(s), when you next push your changes upstream, you must force push. `git push --force`* |
| :octagonal_sign: **WARNING** |
|:-----:|
| *Ensure that all of your commits were exported prior to reseting the branch and when re-applying, that all of your commits were applied correctly* |
## Conventional Commits Admin Manual Manual
This job checks commit messages on a branch and the merge request title for validity against the [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/)
This job provides the following badge:
- None
### Dependencies
- None
### your .gitlab-ci.yml changes
To use this job add the following to your `.gitlab-ci.yml` file
``` yaml
variables:
GIT_SUBMODULE_STRATEGY: recursive
MY_PROJECT_ID: "{yourproject id number}"
stages:
- validation
include:
- remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/development/conventional_commits/.gitlab-ci.yml
```
## CI/CD Variables required
| var name | Description |
|:----:|:----|
| MR_ACCESS_TOKEN | *only required if you are accessing a private repository.* <br>This token is a user access token that as a minimum requires read-only access to the api to fetch the projects merg requests. |
### Job Workflow
### Artifacts
### License
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)

29
pages/projects/gitlab-ci/docker_container.md Normal file
View File

@ -0,0 +1,29 @@
---
title: Docker Container CI Template
description: How to use No Fuss Computings gitlab-ci template for docker containers
date: 2023-05-13
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
- available tags `dev` for latest dev build
- latest matches latest git tag
- notate available platforms can be viewed in the job
``` yaml
# Available platforms: linux/amd64, linux/amd64/v2, linux/amd64/v3, linux/arm64, linux/riscv64, linux/ppc64, linux/ppc64le, linux/s390x, linux/386, linux/mips64le, linux/mips64, linux/arm/v7, linux/arm/v6
# DOCKER_IMAGE_BUILD_TARGET_PLATFORMS: "linux/amd64,linux/arm64,linux/arm/v7"
DOCKER_IMAGE_BUILD_NAME: $CI_PROJECT_NAME
DOCKER_IMAGE_BUILD_REGISTRY: $CI_REGISTRY_IMAGE
DOCKER_IMAGE_BUILD_TAG: $CI_COMMIT_SHA
# DOCKER_IMAGE_PUBLISH_NAME: $CI_PROJECT_NAME
# DOCKER_IMAGE_PUBLISH_REGISTRY: docker.io/nofusscomputing
# DOCKER_IMAGE_PUBLISH_URL: https://hub.docker.com/r/nofusscomputing/$DOCKER_IMAGE_PUBLISH_NAME
# JOB_STOP_CONVENTIONAL_COMMITS: 'any_value'
# JOB_STOP_GIT_PUSH_MIRROR: 'any_value'
# GIT_SYNC_URL: "https://$GITHUB_USERNAME_ROBOT:$GITHUB_TOKEN_ROBOT@github.com/NoFussComputing/config.git" # Must be defined for job to run
# JOB_STOP_GITLAB_RELEASE: 'any value'
```

68
pages/projects/gitlab-ci/git_mirror.md Normal file
View File

@ -0,0 +1,68 @@
---
title: Git push mirror
description: How to use No Fuss Computings gitlab-ci job for repository mirrororing
date: 2021-08-03
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
This job does a git push to a remote git repo.
This job provides the following badge:
- None
## Dependencies
- None
## your .gitlab-ci.yml changes
To use this job add the following to your `.gitlab-ci.yml` file
``` yaml
stages:
- sync
include:
- remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/development/git_push_mirror/.gitlab-ci.yml
Github (Push --mirror):
variables:
GIT_SYNC_URL: "https://${username variable}:${pasword variable}@github.com/NoFussComputing/gitlab-ci.git"
extends:
- .git_push_mirror
```
## CI/CD Variables required
| var name | Description |
|:----:|:----|
| GIT_SYNC_URL | this is the remote git repositories https clone address. <br>***Note:** if the remote repository requires authentication, you will need to build the url. like above.* |
## Job Workflow
- This job is designed to run on successful completion of the validation tasks and only on the `development` and `master` branches. You can safely override the `rules` when creating the job with your own. i.e.
``` yaml
Github (Push --mirror):
variables:
GIT_SYNC_URL: "https://${username variable}:${pasword variable}@github.com/NoFussComputing/gitlab-ci.git"
extends:
- .git_push_mirror
rules:
- if: '$CI_COMMIT_BRANCH == "master"'
when: never
- if: '$CI_COMMIT_BRANCH == "development"'
when: always
```
This will cause the job to only run on the `development` branch.
## Artifacts
- None
## License
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)

130
pages/projects/gitlab-ci/gitlab_release.md Normal file
View File

@ -0,0 +1,130 @@
---
title: Gitlab Release / Commit Footer References
description: How to use No Fuss Computings gitlab-ci job for Gitlab Releases and commit footer messages
date: 2021-08-03
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
# User Manual
All commit messages must be in [conventional commit format](https://www.conventionalcommits.org/en/v1.0.0/) and have a footer with a gitlab reference. The reference **must** be either a merge request or a gitlab issue. (format i.e. `!1` or `#2` *using the correct reference number*).
## fixing commit messages (suggestion)
If only the last commit is the commit with an error just use `git commit --amend` and edit your commit message to be in the correct format and save. now push your changes.
You will require the following information if the commit message with the error is further down the commit tree:
- Commit message SHA1 of your first commit message to the branch `{original_commit}`
- Commit message SHA1 prior to your first commit `{source_commit}`
Run these commands once you have the information above.
``` bash
git format-patch {original_commit}..HEAD -o diff-patches
git reset {source_commit} --hard
```
Now, navigate to the `diff-patches` folder, open up the offending patch (commit) and edit the `subject` or message body as appropriate and save. Once all the edits have been done, re-apply the patches to your tree with:
``` bash
git am diff-patches/*.patch
```
Now push your changes upstream.
| :notebook_with_decorative_cover: Note |
|:-----:|
| *As you have changed the commit SHA1(s), when you next push your changes upstream, you must force push. `git push --force`* |
| :octagonal_sign: **WARNING** |
|:-----:|
| *Ensure that all of your commits were exported prior to reseting the branch and when re-applying, that all of your commits were applied correctly* |
# Gitlab Release - Developer Manual
This job bumps the version, updates the changelog, creates a git tag and creates a gitlab release. The git tag and release title use [semantic versioning](https://semver.org/). for this job to function correctly a `.cz.yaml` is required in the root of the repository. this file contains the [commitizen](https://github.com/commitizen-tools/commitizen) config and the version details.
This job has the following workflow:
- `master` Branch
> Automatically increment the version
- `development` Branch
> Manual CI job made available to increment the version. (release-candidate increment only)
| :octagonal_sign: Danger |
|:----|
| *If prior to merging to the master branch you do a version increment, and there are no commits prior to merging. the job will not increment the version and the job will fail. it is recommended that you only do a version increment on the `development` branch if you are going to commit further changes to the `development` branch* |
This job provides the following badge:
- None
## Dependencies
- None
## your .gitlab-ci.yml changes
To use this job add the following to your `.gitlab-ci.yml` file
CI Job `ci commit footer` is automatically set to run on all branches except `development` and `master`. This job checks the commits on the users branch that they contain a footer with gitlab references. i.e. `#1` for issue one or `!1` for merge request one.
``` yaml
stages:
- validate
- release
include:
- remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/development/gitlab_release/.gitlab-ci.yml
Gitlab Release:
variables:
MY_COMMAND: "{your command here}"
extends:
- .gitlab_release
```
> if you wish to run any commands you can add them to variable `MY_COMMAND`. The custom command will run under shell `/bin/sh`. This command is set to run before the version bump commit is conducted so any changes you wish to add as part of the version bump, you can do here as long as you `git add {changed file name}`.
## CI/CD Variables required
| var name | Description |
|:----:|:----|
| GIT_COMMIT_TOKEN | *this must be a personal token that has write access to the repository* |
| CHANGELOG_FOOTER_REFERENCES | ***Optional** If set to `False` the changelog will not output gitlab references for each entry of the changelog. If this variable is set globally, it will also prevent the creation of the CI job to validate a users commits as having gitlab references.* |
## Job Workflow
This CI job's workflow is:
1. updates the changelog from the commits
1. commit the changelog to git
1. adds a `git tag` to the changelog commit.
1. pushes the change back to the repo
1. creates a git release from the `git tag`
| :octagonal_sign: **NOTE** |
|:----|
| *If the user has forked the branch, they must keep the development brnach synced with the main repo. If they **don't** the CI job 'commit footer refs' will fail as it will not be able to fetch the parent (`development`) hash of the branch.* |
## Artifacts
- `ci commit footer`
> $CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/$CI_JOB_NAME.junit.xml
- `Gitlab Release`
> None
## License
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)

98
pages/projects/gitlab-ci/python.md Normal file
View File

@ -0,0 +1,98 @@
---
title: Python
description: How to use No Fuss Computings gitlab-ci job for Python
date: 2021-08-11
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
This folder (`python`) covers jobs for python development
These jobs provides the following badge:
- `PyLint` - code quality [![PyLint Score](https://img.shields.io/badge/dynamic/json?&style=plastic&logo=python&label=PyLint%20Score&query=%24.PyLintScore&url=https%3A%2F%2Fgitlab.com%2Fnofusscomputing%2Fprojects%2Fgitlab-ci%2F-%2Fjobs%2Fartifacts%2Fdevelopment%2Fraw%2Fartifacts%2Fvalidation%2FPyLint%2Fbadge_pylint.json%3Fjob%3DPyLint)](https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/jobs/artifacts/development/file/artifacts/validation/tests/gl-code-quality-report.html?job=PyLint)
Use the following MD to add a badge adjusting the variables and ensuring everything is on one line.
``` md
[![PyLint Score](https://img.shields.io/badge/dynamic/json?&style=plastic&logo=python&label=PyLint%20Score&query=%24.PyLintScore&url=https%3A%2F%2Fgitlab.com%2F
{project path}
%2F-%2Fjobs%2Fartifacts%2F
{branch}
%2Fraw%2Fartifacts%2Fvalidation%2FPyLint%2Fbadge_pylint.json%3Fjob%3D
{Job Name}
)](https://gitlab.com/
{project path}
/-/jobs/artifacts/
{branch}
/file/
artifacts/validation/tests/gl-code-quality-report.html
?job=
{Job Name}
)
```
| Variable | Description |
|:----|:----|
| `{project path}` | *project path, what's after gitlab.com/* |
| `{branch}` | *git branch to fetch the score from* |
| `{Job Name}` | *name of the gitlab-ci job for the linting* |
## Dependencies
- None
## your .gitlab-ci.yml changes
To add the `PyLint` job, add the following to your `.gitlab-ci.yml` file
``` yaml
stages:
- validation
include:
- remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/master/python/.gitlab-ci.yml
PyLint:
variables:
PYLINT_PATH: "/*/*.py"
PYLINT_RC_PATH: "."
extends:
- .PyLint
image: python:3.6-slim
```
## CI/CD Variables required
| var name | Description |
|:----:|:----|
| PYLINT_PATH | *The path you wish the linter to search for python files* |
| PYLINT_RC_PATH | *The path to your `.pylintrc` file.* |
## Job Workflow
- This job will lint any yaml file in the specified directory using the specified rules.
## Artifacts
- `$CI_PROJECT_DIR/artifacts` - Root artifact directory
- `$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/gl-code-quality-report.json` - Gitlab code quality report (displays in merge request)
- `$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/gl-code-quality-report.html` - html code quality report
## License
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)

59
pages/projects/gitlab-ci/yaml_lint.md Normal file
View File

@ -0,0 +1,59 @@
---
title: YAML Linting
description: How to use No Fuss Computings gitlab-ci job for YAML Linting
date: 2021-08-11
template: manual.html
about: https://gitlab.com/nofusscomputing/projects/gitlab-ci
---
This job does yaml linting when any commit is pushed to any branch.
This job provides the following badge:
- None
## Dependencies
- None
## your .gitlab-ci.yml changes
To use this job add the following to your `.gitlab-ci.yml` file
``` yaml
stages:
- validation
include:
- remote: https://gitlab.com/nofusscomputing/projects/gitlab-ci/-/raw/master/yaml_lint/.gitlab-ci.yml
Yaml Lint (python 3.6):
variables:
YAML_LINT_PATH: "roles/"
YAML_LINT_CONFIG: ".yamllint.yaml"
extends:
- .yaml_linter_defaults
image: python:3.6-slim
```
> You can use any python version you wish.
## CI/CD Variables required
| var name | Description |
|:----:|:----|
| YAML_LINT_PATH | *The path you wish the linter to search for yaml files* |
| YAML_LINT_CONFOG | *The path you have stored the yaml config file in* |
## Job Workflow
- This job will lint any yaml file in the specified directory using the specified rules.
## Artifacts
- `$CI_PROJECT_DIR/artifacts` - Root artifact directory
- `$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/tests/$PYTHON_VERSION-yaml-lint.junit.xml` - JUnit Test report
- `$CI_PROJECT_DIR/artifacts/$CI_JOB_STAGE/$CI_JOB_NAME/$PYTHON_VERSION-yaml-lint.log` - Linter log
## License
To view the license for this folder and any sub-folders, refer [here](https://gitlab.com/nofusscomputing/projects/gitlab-ci)