Resolve "Create a sandbox to test usage of the hub"

You can use them for any kind of software and deployment type. Each job can be

customized through configuration.

Check the [Documentation](https://r2devops.io) 📚 and [Jobs

index](https://r2devops.io/jobs/) 🚀

* **🚀 Find jobs to use in your pipeline in [Jobs index](https://r2devops.io/jobs/)**

* **📚 Understand how to use the hub in [Documentation](https://r2devops.io)**

* **🙋 Add your own job using the [Contributing guide](https://r2devops.io/how-to-contribute/)**

## Repository

This mono-repo contains several parts:

* Documentation sources

* Jobs

* Tools

    * Builder: build the jobs' documentation

    * Notify: send notification about jobs' updates to our [discord server](https://discord.gg/5QKpGqR)

    * Template: job template

* Jobs' sources and a job template (jobs structure is described in [documentation](https://r2devops.io/job-structure/))

* Documentation of the hub

* Tools used in hub pipeline to check jobs

```

.

├── docs            # Documentation sources

├── jobs            # Folder containing jobs sources

│   ├── docker_build

│   │   ├── docker_build.yml        # Job content

│   │   ├── job.yml                 # Job metadata

│   │   ├── README.md               # Job documentation

│   │   └── versions                # Jobs changelogs

│   │       ├── 0.1.0.md

│   │       └── ...

│   └── ...

├── mkdocs.yml      # Documentation configuration

├── Pipfile         # Pipenv dependency file to build doc

├── Pipfile.lock

├── requirements.txt                # Python dependency file to build doc

└── tools           # Folder containing tools

    ├── builder

    │   ├── builder.py

    │   ├── Pipfile

    │   ├── Pipfile.lock

    │   └── templates

    ├── job_template

    └── notify

        ├── discord_release_notify.py

        ├── Pipfile

        └── Pipfile.lock

    └── ...

```

## How to update the documentation

### How to add or update a job

### Clone the repository

* Follow the [Contributing guide](https://r2devops.io/how-to-contribute/)

Clone the repository locally

### How to update the hub documentation

As prerequisites, you need to install following dependencies on your system:

* `python3`

* `pipenv`

1. Clone the repository locally

```shell

git clone git@gitlab.com:r2devops/hub.git

cd hub

```

### Requirements

2. Install requirements

Documentation is built using [Mkdocs](https://www.mkdocs.org) and [Material for

Mkdocs](https://squidfunk.github.io/mkdocs-material/){:target="_blank"}.

You can use `pipenv` or `pip` to install python requirements:

* Using `pipenv`

```shell

pipenv install

    pipenv shell

```

* OR using `pip`

    ```shell

    pip install -r requirements

    ```

🚨 Take care to update both `Pipfile` and `requirements.txt` when you modify

dependencies.

### Launch Mkdocs

3. Launch Mkdocs

You can launch mkdocs in order to create a local web server with hot reload to

see your updates in live:

```shell

mkdocs serve

pipenv run mkdocs serve

```

## How to update tools

4. See your update in live at [https://localhost:8000](https://localhost:8000)

### How to update hub tools

### Guidelines

#### Guidelines

For `pyhton` tools:

* [`Format`](https://docs.python.org/3/library/functions.html?highlight=format#format) must be used instead of `%s` or string concatenation with `+`

* Docstring format compliant with [Google styleguide](https://google.github.io/styleguide/pyguide.html#244-decision)

### Requirements

#### Requirements

Each tools have their own `Pipfile` in their folder to manage their

dependencies. You must install `pipenv` to work on them:

```shell

pip install pipenv

```

### Work on `builder`

```shell

cd tools/builder

pipenv install

pipenv shell

```

### Work on `notify`

```shell

cd tools/notify

pipenv install

pipenv shell

```

    cursor: pointer;

}

.md-typeset code {

    font-size: .75em;

}

.codehilitetable .linenos, .highlighttable .linenos {

    font-size: .75em;

}

## 📝 Prerequisites

- 🦊  Manage your project in Gitlab and understand what is [CI/CD with Gitlab](https://docs.gitlab.com/ee/ci/){:target="_blank"}

- ✏️   Have the write access to the `.gitlab-ci.yml` file in your project

- 🔫  Be aware each file modification in your project will trigger the [Pipeline](/r2bulary/#pipeline)

- 🗝  Have access to the pipelines page in your Gitlab project to see the pipeline execution

* 🦊  Manage your project in Gitlab and understand what is [CI/CD with Gitlab](https://docs.gitlab.com/ee/ci/){:target="_blank"}

* 🔫  Be aware each file modification in your project can trigger a [Pipeline](/r2bulary/#pipeline)

* 🗝  Have access to the pipelines page in your Gitlab project and write access to your project `.gitlab-ci.yml` file

## ⏳ Quick setup

        each job in [jobs section](/jobs/). Description of `tag` format is

        available in [Versioning page](/versioning/).

        Once your pipeline is functional, we recommend to use a specific version

        Once your pipeline is functional, we recommend using a specific version

        for jobs in order to ensure that your pipeline will not be broken by a

        job update.

        You can also combine jobs templates and your own jobs in

        `.gitlab-ci.yml` configuration file.

### 🏳󠁵󠁳󠁴󠁸󠁿 Example

An example of a full `.gitlab-ci.yml` file with:

<a alt="See all jobs" href="/jobs">

    <button class="md-button border-radius-10 md-button-center" >

        See all jobs available <img alt="" class="heart" src="../images/rocket.png">

    </button>

</a>

* One job template with latest version. Note that `latest/` is optional in the

  job URL

* One job template with specific version using tag `0.1.0`

* Your own local `unit_tests` job

## 🤓 Pipeline examples

* Several examples of projects using the r2devops hub:

    * Python flask based REST API permitting to play TicTacToe 👉 [tictactoe/grid-api](https://gitlab.com/tictac-toe/grid-api)

    * Vue.js project providing a client to the TicTacToe API 👉 [tictactoe/grid-frontend](https://gitlab.com/tictac-toe/grid-frontend)

    * React.js project providing our landing page 👉 [r2devops/landing-page](https://gitlab.com/r2devops/landing-page)

* An example of a full `.gitlab-ci.yml` configuration using jobs from the hub 👇

    !!! info "Jobs used in the example"

        * Plug-and-play set of jobs from the hub to automatically build, test

          and deploy static documentation website:

            * [`mkdocs`](https://r2devops.io/jobs/build/mkdocs/) (`latest`

              version)

            * [`lighthouse`](https://r2devops.io/jobs/dynamic_tests/lighthouse/)

              (`latest` version)

            * [`pages`](https://r2devops.io/jobs/deploy/pages/) (`latest`

              version)

        * Plug-and-play set of jobs from the hub to automatically build, push

          and test docker images:

            * [`docker_build`](https://r2devops.io/jobs/build/docker_build/)

              (version `0.3.0`)

            * [`trivy_image`](https://r2devops.io/jobs/dynamic_tests/trivy_image/)

              (version `0.2.0`)

        * A custom manual job `unit_tests`

    ``` yaml

    stages:

    - deploy

    - others

# Jobs from g2s hub

    # Jobs from r2devops.io (they don't need any configuration in standard cases)

    include:

  - remote: 'https://jobs.r2devops.io/latest/docker_build.yml'

  - remote: 'https://jobs.r2devops.io/0.1.0/mkdocs.yml'

    - remote: 'https://jobs.r2devops.io/latest/mkdocs.yml'

    - remote: 'https://jobs.r2devops.io/latest/lighthouse.yml'

    - remote: 'https://jobs.r2devops.io/latest/pages.yml'

    - remote: 'https://jobs.r2devops.io/0.3.0/docker_build.yml'

    - remote: 'https://jobs.r2devops.io/0.2.0/trivy_image.yml'

# You can also include your own local jobs

    # Locally configured job

    unit_tests:

  image: python:3.7-alpine3.10

      image: python:3.9-alpine

      stage: static_tests

      before_script:

        - pip install pipenv && pipenv --bare install --dev

        - make test

    ```

<a alt="See all jobs" href="/jobs">

    <button class="md-button border-radius-10 md-button-center" >

        See all jobs available <img alt="" class="heart" src="../images/rocket.png">

    </button>

</a>

## ▶ Stages

By default, each job from the hub is a part of on these stages:

    TRIVY_SEVERITY: "CRITICAL"

```

### ✏ Change the default stage of job

### ✏️  Use custom stage

If you want to use your own stage name it's possible to do so when including

your job.

your job. Example:

```yaml

stages:

  - security

include:

  - remote: 'https://jobs.r2devops.io/trivy_image.yml'

### Example of `.gitlab-ci.yml` file

If you want to [change the default stage](/use-the-hub/#change-the-default-stage-of-job), or [customize your job](/use-the-hub/#global) have a look on the example below 👇🏽

If you want to [change the default stage](/use-the-hub/#use-custom-stage), or [customize your job](/use-the-hub/#global) have a look on the example below 👇🏽

```yaml

stages:

pymdown-extensions==8.0.1

mkdocs-awesome-pages-plugin==2.4.0

mkdocs-git-revision-date-localized-plugin==0.7.2

mkdocs-material==6.1.5

mkdocs-material-extensions==1.0.1

mkdocs-minify-plugin==0.3.0