diff --git a/README.md b/README.md index 314f6075f2030c884ff06ebb807d83ae12aaa642..7c3720cdb1eaa65915362139af7471bb6d1fc37c 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # HowToGitLabRunner -The goal of this project is to demonstrate how to use -[GitLab-Runner](https://docs.gitlab.com/runner) with a very simple use case: -transform this README.md into README.pdf with [pandoc](https://pandoc.org/). +A simple use case to demonstrate how to use a +[shell](https://docs.gitlab.com/runner/executors/shell.html) +[GitLab-Runner](https://docs.gitlab.com/runner) to transform this README.md into +README.pdf with [pandoc](https://pandoc.org/) and create a +GitLab's [release](https://gitlab.epfl.ch/idevelop/howtogitlabrunner/-/tags). ## Preamble @@ -12,16 +14,16 @@ PDF and push it into this repo. While it seems feasible, it not a good idea. First of all, you want to keep your commits atomic, meaning that you don't want a commit creates a new commit automatically. Secondly, the CI/CD mechanisms is here to build and/or deploy a specific commit to other systems/environment, not -modifying the current one. Finally, we choose to do it the following way: +modifying the current one. We ended to do it the following way: 1. One modify the README.md file; 1. It trigger the build to create the README.pdf file; - 1. Then, a release is created, association the README.pdf file to it. + 1. Then, a release is created, associating the README.pdf file to it. That way, the things are kept as close as possible to a standard dev/stage/prod -environment. +environment but still in the same repo, keeping it simple to understand. -Before diving into it, you may want to check the +> 💡 Before diving into it, you may want to check the [documentation](https://docs.gitlab.com/ce/ci/README.html) and some [real world examples](https://docs.gitlab.com/ce/ci/examples/README.html). @@ -31,15 +33,18 @@ examples](https://docs.gitlab.com/ce/ci/examples/README.html). First of all, you need a runner on a machine. The installation process is described here: https://docs.gitlab.com/runner/install/ -It creates the gitlab-runner user on your system. On some Linux, you may want to +It creates the gitlab-runner user on your system. + +> 💡 On some Linux, you may want to remove the `~/.bash_logout` file to avoid the issue [4092](https://gitlab.com/gitlab-org/gitlab-runner/issues/4092) — thanks me later. The last step explains how to register the runner with `sudo gitlab-runner register`. Answer the questions (the runner key is found on your Project > -Settings > CI/CD > Runner). You may want to check the runner options (for -example "Run untagged jobs"). It will create the +Settings > CI/CD > Runner), choosing +[shell](https://docs.gitlab.com/runner/executors/shell.html) as +[executor](https://docs.gitlab.com/runner/executors/). It will create the `/etc/gitlab-runner/config.toml` file which looks like that: ``` @@ -60,16 +65,24 @@ check_interval = 0 [runners.cache.gcs] ``` +On the runner configuration page of the project, the runner tags are defined to +be used by default. In the `.gitlab-ci.yaml` files, all the jobs are set to be +run with the tags "test" — please double check that this tag is defined in the +runner configuration, or allow your runner to be ran without any tags. + +> 💡 Read more about tags here: https://docs.gitlab.com/ee/ci/runners/#using-tags + ## Check and edit the `.gitlab-ci.yaml` The whole pipeline/stage/job configuration stands in the `.gitlab-ci.yaml` file. A lot of documentation is provided by GitLab: https://docs.gitlab.com/ce/ci/. In short, this file defines the pipeline process, which contain stages. A stage -can contains jobs, which describes what to do. Jobs can be parallel and manual. +can contains jobs, which describes what to do. Jobs can be parallel and manual, +as of the "deploy_to_production" job. -Note that if you want to keep "produced" files between jobs, you have to use the -artifacts system. +> 💡 Note that if you want to keep "produced" files between jobs, you have to use the +[artifacts](https://docs.gitlab.com/ce/user/project/pipelines/job_artifacts.html) system. The file of this project define 4 stages: - test → just prints out some env variables. @@ -108,6 +121,7 @@ the repo, or go into your project CI/CD pipelines and use the "Run pipeline" button. Once the deploy stage is finished, you should be able to see the release: +  Also, you can manually continue the pipeline by clicking "Deploy to production"