diff options
author | Tristan Honscheid <honscheid@google.com> | 2022-08-18 15:19:48 -0600 |
---|---|---|
committer | Chromeos LUCI <chromeos-scoped@luci-project-accounts.iam.gserviceaccount.com> | 2022-08-22 22:36:01 +0000 |
commit | 2b60e1b1a8afe84d9b5a46e3e59efcfbb4269a5a (patch) | |
tree | bcae3f52eff11d17febcae09840f91f05e551ac2 /docs | |
parent | e65bbccc49d01fded1bc79d9f58f97b80c02a2aa (diff) | |
download | chrome-ec-2b60e1b1a8afe84d9b5a46e3e59efcfbb4269a5a.tar.gz |
docs: Add guide for running Gitlab CI locally
It's possible to use `gitlab-runner exec` to locally run the CI builds
as specified in `.gitlab-ci.yml`, without needing to copy over the
commands it runs. The run takes place inside the same Docker container
as the real Gitlab CI jobs.
BRANCH=None
BUG=None
TEST=(Ran commands in doc)
Signed-off-by: Tristan Honscheid <honscheid@google.com>
Change-Id: Ief6d9f3add885eba0d6814c02602bc0f58d56797
Reviewed-on: https://chromium-review.googlesource.com/c/chromiumos/platform/ec/+/3840657
Reviewed-by: Jeremy Bettis <jbettis@chromium.org>
Diffstat (limited to 'docs')
-rw-r--r-- | docs/gitlab.md | 84 |
1 files changed, 84 insertions, 0 deletions
diff --git a/docs/gitlab.md b/docs/gitlab.md new file mode 100644 index 0000000000..9f8d07ceec --- /dev/null +++ b/docs/gitlab.md @@ -0,0 +1,84 @@ +# Gitlab CI + +The Zephyr EC Test Team uses external Gitlab CI jobs to generate code coverage +reports. These CI jobs are defined in the `.gitlab-ci.yml` file in +`platform/ec`. + +[TOC] + +## Running CI jobs locally + +For development purposes, it is possible to run the CI jobs on a local machine +using Docker and `gitlab-runner`. + +Note: not all features of Gitlab CI are available when running builds locally. +For example, the local runner cannot build dependencies specified in the +`needs:` sections. (But you can run jobs individually). More details can be +found in the [`gitlab-runner` docs] +(https://docs.gitlab.com/runner/commands/#limitations-of-gitlab-runner-exec). + +### Installation + +First, you must [install Docker](https://docs.docker.com/get-docker/) on your +system. This is out of the scope of this guide, but there are many resources +on the Internet describing how to do this. Docker allows the CI jobs to run in a +controlled environment using containers, ensuring that the jobs run consistently +and without needing to pollute your own system with the many dependencies. + +Next, install the Gitlab Runner. This application is able interpret the +`.gitlab-ci.yml` file, spawn Docker containers to run jobs, and report back +results and artifacts. Usually, runners are deployed in fleets and configured to +register with a Gitlab server, which can push CI jobs to individual runners to +execute. However, it is also possible to use the runner in a purely local mode +using `gitlab-runner exec`. + +Full instructions are available on the +[Gitlab website](https://docs.gitlab.com/runner/install/), but the fastest way +to get it for Debian-based systems is to download and install the package +directly: + +``` +wget https://gitlab-runner-downloads.s3.amazonaws.com/latest/deb/gitlab-runner_amd64.deb +sudo dpkg -i gitlab-runner_amd64.deb +``` + +### Running a Job + +Once Docker and the Gitlab Runner are installed, invoke it as follows. This +takes place outside of the + +``` +(outside) +mkdir ~/gitlab-runner-output # Do once + +cd ~/chromiumos/src/platform/ec +sudo gitlab-runner exec docker \ + --docker-volumes "$HOME/chromiumos/:$HOME/chromiumos/" \ + --docker-volumes "$HOME/gitlab-runner-output:/builds" \ + <name of job> +``` + +Please note: + * `$HOME/chromiumos` should be adjusted to wherever your tree is checked out + to. The reason it is necessary to mount the entire source tree to the + Docker container (as opposed to just `platform/ec`, which is done + automatically) is because the runner needs access to the Git database in + order to clone the source code. Because the `platform/ec` repository is + governed by the `repo` tool, the Git database is actually located at + `$HOME/chromiumos/.repo/projects/src/platform/ec.git`. (The `.git` directory + in `platform/ec` is merely a symlink) + * The second mount causes the runner's work directory to be backed by a + directory on your own system so that you can examine the artifacts after the + job finishes and the container is stopped. + * `<name of job>` is one of the jobs defined in `.gitlab-ci.yml`, such as + `twister_coverage`. + * You may see error messages like `ERROR: Could not create cache adapter`. + These appear to be benign, although getting the cache to work might improve + subsequent build times. This may be investigated at a later date. + +### Accessing Artifacts + +If you used the command as shown above, all of the build artifacts and source, +as checked out by the Gitlab runner, should be under `~/gitlab-runner-output`. +This will persist after the container exits but also get overwritten again on +the next run. |