Use a job from the Hub¶
See Concept page to get more details about R2Devops Hub
⏳ Quick setup¶
Follows these steps to setup your CI/CD pipeline in less than 5 minutes!
If you haven't yet a
.gitlab-ci.ymlfile in the root on your repository: create it with the following list of stages:
stages: - build - tests - provision - review - release - deploy - others
You can check the stages section to get more information about this list or if you already have a configuration with different stages.
Select the Jobs you want in the jobs section and append their URL in the
includelist of your
include: - remote: 'https://api.r2devops.io/job/r/<owner_name>/<job_name>/<version_number>.yaml' - remote: 'https://api.r2devops.io/job/r/<owner_name>/<job_name>/<version_number>.yaml' - ...
By default, the
latestversion is used. You can choose to use a specific version thanks to a
tag. Available tags are listed in each job documentation page.
The description of the
tagformat is available in the versioning page.
Once your pipeline is functional, we recommend using a specific version for the jobs in order to ensure that your pipeline will not be broken by a job update.
The jobs can be customized 👉 check the jobs customization section.
Everything is ready! You can now benefit the full power of a CI/CD pipeline 🎉🚀
You can also combine job's templates and your own jobs in your
🤓 Pipeline examples¶
Several examples of projects using R2Devops hub:
An example of a full
.gitlab-ci.ymlconfiguration using jobs from the hub 👇
Jobs used in the example
- Plug-and-play set of jobs from the hub to automatically build, test and deploy static documentation website:
- Plug-and-play set of jobs from the hub to automatically build, push and test docker images:
- A custom manual job
stages: - build - tests - provision - review - release - deploy - others # Jobs from r2devops.io (they don't need any configuration in standard cases) include: - remote: 'https://api.r2devops.io/job/r/r2devops-bot/mkdocs.yaml' - remote: 'https://api.r2devops.io/job/r/r2devops-bot/lighthouse.yaml' - remote: 'https://api.r2devops.io/job/r/r2devops-bot/pages.yaml' - remote: 'https://api.r2devops.io/job/r/r2devops-bot/docker_build/0.2.0.yaml' - remote: 'https://api.r2devops.io/job/r/r2devops-bot/trivy_image/0.2.0.yaml' # Locally configured job unit_tests: image: python:3.9-alpine stage: tests before_script: - pip install pipenv && pipenv --bare install --dev script: - make test
By default, each job from the hub is a part of on these stages:
- 🧱 Build: building and packaging of the software
- 🔎 Tests: testing your repository files with dynamic and static tests
- 🛠 Provision: preparation of the software infrastructure
- 👌 Review: deployment of the software in an isolated review environment
- 🏷 Release: releasing and tagging of the software
- 🚀 Deploy: deployment of the software on environments
- 🦄 Others: all other magic jobs not included in previous stages
This is an efficient and simple workflow. Nevertheless, if you want to use your own custom stage list: you can re-declare yourself the stage of any job from the hub. Follow the customization section to do it.
🔧 Jobs customization¶
All the jobs from the
r2devops/hub specify a docker image to be run in a docker container.
Each jobs of the hub can be customized. To do it, you have to include the job URL as usual and, in addition, override the options you want to customize.
This way, you can override all Gitlab jobs parameters. All parameters are described in Gitlab documentation.
For example, if you want to use the trivy_image job and customize it by:
- Redefining the
securityto fit in your personal stages workflow,
- Set the variable
0.9.1to use this version instead of the default,
- Set the variable
CRITICALto display only CRITICAL issues.
include: - remote: 'https://api.r2devops.io/job/r/r2devops-bot/trivy_image.yaml' trivy_image: stage: security variables: TRIVY_VERSION: "0.9.1" TRIVY_SEVERITY: "CRITICAL"
✏️ Use custom stage¶
If you want to use your own stage name, it's possible to do so when including your job. Example:
stages: - security include: - remote: 'https://api.r2devops.io/job/r/r2devops-bot/trivy_image.yaml' trivy_image: stage: security
You may want one of your job to interact with a container instance (API, database, web server...) to work. GitLab has an option to run a container next to a job:
To use this option, you must have access to an image of the container you want to run as a service. For example, if you are using our docker_build job to build an image of your application, and you want to test this image using the nmap job, just add the following configuration in your
nameoption must contain your image name and tag, or an image name from Docker Hub.
aliasoption permits to the job to reach your application using a name. This name must be the same that the one specified inside the job target's variable.
- You may also run some other services, like a database depending on your application needs.
nmap: services: - name: $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA alias: app
🎶 Multiple usage of the same job in your pipeline¶
If you want to reuse a job from the hub, for example launching
apiDoc to build 2 API documentations in the same pipeline, you can easily do so with the Hub's jobs using extends GitLab keyword.
stages: - build include: - remote: 'https://api.r2devops.io/job/r/r2devops-bot/apidoc/0.2.0.yaml' apidoc: variables: APIDOC_CONFIG_PATH: src/doc/project1/apidoc.json APIDOC_OUTPUT_PATH: website_build/apidoc/project1/ apidoc_project2: extends: apidoc variables: APIDOC_CONFIG_PATH: src/doc/project2/apidoc.json APIDOC_OUTPUT_PATH: website_build/apidoc/project2/
Be aware to have different artifacts path to not overwrite your first artifact by the second one.