From ac253bc75bedda9304b77f9dc2df2d1f6c855bb6 Mon Sep 17 00:00:00 2001 From: Philippe Antoine Date: Mon, 19 Sep 2022 22:41:09 +0200 Subject: [PATCH 1/3] gitlab: improve documentation between Gitlab.com with shared runner and self-managed instances. --- docs/running-clusterfuzzlite/gitlab.md | 61 ++++++++++++++++++-------- 1 file changed, 43 insertions(+), 18 deletions(-) diff --git a/docs/running-clusterfuzzlite/gitlab.md b/docs/running-clusterfuzzlite/gitlab.md index 4cda1a3..b817477 100644 --- a/docs/running-clusterfuzzlite/gitlab.md +++ b/docs/running-clusterfuzzlite/gitlab.md @@ -18,10 +18,8 @@ To get the most of this page, you should have already set up your [build integration] and read the more [high-level document on running ClusterFuzzLite]. -## Gitlab runner -The following examples use a `docker` gitlab runner running sibling containers: -See this [doc](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-socket-binding) -for more information. +The following documentation is primarily meant for Gitlab.com with the use of shared runners. +It works also for self-managed Gitlab instances. ## .gitlab-ci.yml For basic ClusterFuzzLite functionality, all you need is a single job @@ -38,7 +36,7 @@ To enable more features, we recommend having different jobs for: To add a fuzzing job that fuzzes all merge requests to your repo, add the following default configurations to `.gitlab-ci.yml`: -This configuration requires at least GitLab 13.3 to be run. +For self-managed Gitlab instances, this configuration requires at least GitLab 13.3 to be run. With older versions, the `parallel` keywords does not exist, but you can define `SANITIZER` as a Gitlab CI variable. {% raw %} @@ -46,8 +44,8 @@ With older versions, the `parallel` keywords does not exist, but you can define variables: SANITIZER: address CFL_PLATFORM: gitlab - DOCKER_HOST: "tcp://docker:2375" - DOCKER_IN_DOCKER: "true" + DOCKER_HOST: "tcp://docker:2375" # may be removed in self-managed Gitlab instances + DOCKER_IN_DOCKER: "true" # may be removed in self-managed Gitlab instances clusterfuzzlite: @@ -55,7 +53,7 @@ clusterfuzzlite: name: gcr.io/oss-fuzz-base/clusterfuzzlite-run-fuzzers:v1 entrypoint: [""] services: - - docker:dind + - docker:dind # may be removed in self-managed Gitlab instances stage: test parallel: @@ -80,7 +78,8 @@ clusterfuzzlite: ``` {% endraw %} -You may also wish to set [tags](https://docs.gitlab.com/runner/#tags) to select a relevant runner. +For self-managed Gitlab instances, you may also wish to set [tags](https://docs.gitlab.com/runner/#tags) +to select a relevant runner. Optionally, edit the following variables to customize your settings: - `SANITIZER` Select sanitizer(s) @@ -106,7 +105,7 @@ clusterfuzzlite-corpus: name: gcr.io/oss-fuzz-base/clusterfuzzlite-run-fuzzers:v1 entrypoint: [""] services: - - docker:dind + - docker:dind # may be removed in self-managed Gitlab instances stage: test rules: - if: $MODE == "prune" @@ -127,6 +126,9 @@ In one, you should set the variable `MODE` to `batch` to run the actual batch fu In the other, you should set the variable `MODE` to `prune` for corpus pruning once a day. These schedules should target the main/default/`CFL_BRANCH` branch. +Note that you can also use gitlab-ci.yml [extends](https://docs.gitlab.com/ee/ci/yaml/#extends) +keyword to avoid duplicating most of the common parameters between the different type of jobs. + ![gitlab-schedule-mode] ### Continuous builds @@ -148,7 +150,7 @@ clusterfuzzlite-build: name: gcr.io/oss-fuzz-base/clusterfuzzlite-run-fuzzers:v1 entrypoint: [""] services: - - docker:dind + - docker:dind # may be removed in self-managed Gitlab instances stage: test rules: # Use $CI_DEFAULT_BRANCH or $CFL_BRANCH. @@ -179,7 +181,7 @@ clusterfuzzlite-coverage: name: gcr.io/oss-fuzz-base/clusterfuzzlite-run-fuzzers:v1 entrypoint: [""] services: - - docker:dind + - docker:dind # may be removed in self-managed Gitlab instances stage: test variables: SANITIZER: "coverage" @@ -202,6 +204,30 @@ This schedule should target the main/default/`CFL_BRANCH` branch. ## Extra configuration +### Gitlab runners on self-managed Gitlab instances + +The previous examples used [Docker in docker](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-in-docker) + +From a performance point of view, it is recommended to use a `docker` gitlab runner running sibling containers: +See this [doc](https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#use-docker-socket-binding) +for more information. + +To do so, if you have such a runner ready, you simply need to remove the following lines from the configuration : +{% raw %} +```yaml +variables: + DOCKER_HOST: "tcp://docker:2375" # may be removed in self-managed Gitlab instances + DOCKER_IN_DOCKER: "true" # may be removed in self-managed Gitlab instances + + services: + - docker:dind # may be removed in self-managed Gitlab instances +``` + +Note that it should be possible to achieve the same functionality using a shell +executor, though this is unsupported. +In that case, the `.gitlab-ci.yml` will different. For one you must explicitly +call the `docker` commands on ClusterFuzzLite images. + ### Gitlab filestore You can use the variable `FILESTORE: gitlab` to use Gitlab artifacts for storing @@ -226,12 +252,17 @@ For continuous builds, you need to use a [cache](https://docs.gitlab.com/ee/ci/c The cache directory needs to defined as `CFL_CACHE_DIR` to be used by ClusterFuzzLite. If it is not defined, the default value is `cache`. You should ensure that the runners share the access to the cache. +As such, this filestore is not available with shared runners on Gitlab.com and you +should resort to another filestore provided by ClusterFuzzLite. For coverage reports and corpus, it is recommended to set up another git repository for storage. You need to create a project access token for this repository, with `read_repository` and `write_repository` rights. +You can also use a personal access token if you do not have access to +project access token, due to your Gitlab license. + ![gitlab-project-token] And this token should be used from the fuzzed repository as a CI/CD variable. @@ -267,12 +298,6 @@ This job will build a static web site with everything which is in the `public` d You may then access the site at `https://baseurl/coverage/latest/report/linux/report.html` where `baseurl` is the domain you configured for your GitLab pages. -## Shell executor -Note that it should be possible to achieve the same functionality using a shell -executor, though this is unsupported. -In that case, the `.gitlab-ci.yml` will different. For one you must explicitly -call the `docker` commands on ClusterFuzzLite images. - [GitLab]: https://about.gitlab.com/ [build integration]: {{ site.baseurl }}/build-integration/ [high-level document on running ClusterFuzzLite]: {{ site.baseurl }}/running-clusterfuzzlite/ From 91a874d7f6b1731fc55d584d036a055e2d1940fc Mon Sep 17 00:00:00 2001 From: Philippe Antoine Date: Thu, 22 Sep 2022 17:32:08 +0200 Subject: [PATCH 2/3] add a notive about gitlab CI variable "protected" --- docs/running-clusterfuzzlite/gitlab.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/running-clusterfuzzlite/gitlab.md b/docs/running-clusterfuzzlite/gitlab.md index b817477..c09491c 100644 --- a/docs/running-clusterfuzzlite/gitlab.md +++ b/docs/running-clusterfuzzlite/gitlab.md @@ -268,6 +268,7 @@ project access token, due to your Gitlab license. And this token should be used from the fuzzed repository as a CI/CD variable. You can name this variable as you like, in the following example it is named `CFL_TOKEN`. This variable should be defined as masked to avoid leaks. +It should not be protected if you need it on unprotected branches. ![gitlab-variable-token] From c1585af70e5d08474290471703ce115032ccab65 Mon Sep 17 00:00:00 2001 From: Philippe Antoine Date: Fri, 23 Sep 2022 13:43:57 +0200 Subject: [PATCH 3/3] remove irrelevant assumption about gitlab shared runners abilities --- docs/running-clusterfuzzlite/gitlab.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/running-clusterfuzzlite/gitlab.md b/docs/running-clusterfuzzlite/gitlab.md index c09491c..e93a9d9 100644 --- a/docs/running-clusterfuzzlite/gitlab.md +++ b/docs/running-clusterfuzzlite/gitlab.md @@ -252,8 +252,6 @@ For continuous builds, you need to use a [cache](https://docs.gitlab.com/ee/ci/c The cache directory needs to defined as `CFL_CACHE_DIR` to be used by ClusterFuzzLite. If it is not defined, the default value is `cache`. You should ensure that the runners share the access to the cache. -As such, this filestore is not available with shared runners on Gitlab.com and you -should resort to another filestore provided by ClusterFuzzLite. For coverage reports and corpus, it is recommended to set up another git repository for storage.