diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2022-02-18 09:45:46 +0000 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2022-02-18 09:45:46 +0000 |
commit | a7b3560714b4d9cc4ab32dffcd1f74a284b93580 (patch) | |
tree | 7452bd5c3545c2fa67a28aa013835fb4fa071baf /doc/development/cicd | |
parent | ee9173579ae56a3dbfe5afe9f9410c65bb327ca7 (diff) | |
download | gitlab-ce-a7b3560714b4d9cc4ab32dffcd1f74a284b93580.tar.gz |
Add latest changes from gitlab-org/gitlab@14-8-stable-eev14.8.0-rc42
Diffstat (limited to 'doc/development/cicd')
-rw-r--r-- | doc/development/cicd/index.md | 2 | ||||
-rw-r--r-- | doc/development/cicd/templates.md | 74 |
2 files changed, 74 insertions, 2 deletions
diff --git a/doc/development/cicd/index.md b/doc/development/cicd/index.md index 17a70393c96..2779b457fb9 100644 --- a/doc/development/cicd/index.md +++ b/doc/development/cicd/index.md @@ -27,7 +27,7 @@ On the left side we have the events that can trigger a pipeline based on various - A `git push` is the most common event that triggers a pipeline. - The [Web API](../../api/pipelines.md#create-a-new-pipeline). - A user clicking the "Run pipeline" button in the UI. -- When a [merge request is created or updated](../../ci/pipelines/merge_request_pipelines.md#pipelines-for-merge-requests). +- When a [merge request is created or updated](../../ci/pipelines/merge_request_pipelines.md). - When an MR is added to a [Merge Train](../../ci/pipelines/merge_trains.md#merge-trains). - A [scheduled pipeline](../../ci/pipelines/schedules.md#pipeline-schedules). - When project is [subscribed to an upstream project](../../ci/pipelines/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt). diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index b1252b86cc0..d7edad842b8 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -5,7 +5,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w type: index, concepts, howto --- -# Development guide for GitLab CI/CD templates +# Development guide for GitLab CI/CD templates **(FREE)** This document explains how to develop [GitLab CI/CD templates](../../ci/examples/index.md). @@ -18,6 +18,7 @@ Before submitting a merge request with a new or updated CI/CD template, you must - Name the template following the `*.gitlab-ci.yml` format. - Use valid [`.gitlab-ci.yml` syntax](../../ci/yaml/index.md). Verify it's valid with the [CI/CD lint tool](../../ci/lint.md). +- [Add template metrics](#add-metrics). - Include [a changelog](../changelog.md) if the merge request introduces a user-facing change. - Follow the [template review process](#contribute-cicd-template-merge-requests). - (Optional but highly recommended) Test the template in an example GitLab project @@ -382,6 +383,77 @@ you must: This information is important for users when [a stable template](#stable-version) is updated in a major version GitLab release. +### Add metrics + +Every CI/CD template must also have metrics defined to track their use. + +To add a metric definition for a new template: + +1. Install and start the [GitLab GDK](https://gitlab.com/gitlab-org/gitlab-development-kit#installation). +1. In the `gitlab` directory in your GDK, check out the branch that contains the new template. +1. [Add the template inclusion event](../service_ping/implement.md#add-new-events) + with this Rake task: + + ```shell + bin/rake gitlab:usage_data:generate_ci_template_events + ``` + + The task adds a section like the following to [`lib/gitlab/usage_data_counters/known_events/ci_templates.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/usage_data_counters/known_events/ci_templates.yml): + + ```yaml + - name: p_ci_templates_my_template_name + category: ci_templates + redis_slot: ci_templates + aggregation: weekly + ``` + +1. Copy the value of `name` from the new YAML section, and add it to the weekly + and monthly CI/CD template total count metrics: + - [`config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml) + - [`config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml) + +1. Use the same `name` as above as the last argument in the following command to + [add new metric definitions](../service_ping/metrics_dictionary.md#metrics-added-dynamic-to-service-ping-payload): + + ```shell + bundle exec rails generate gitlab:usage_metric_definition:redis_hll ci_templates <template_metric_event_name> + ``` + + The output should look like: + + ```shell + $ bundle exec rails generate gitlab:usage_metric_definition:redis_hll ci_templates p_ci_templates_my_template_name + create config/metrics/counts_7d/20220120073740_p_ci_templates_my_template_name_weekly.yml + create config/metrics/counts_28d/20220120073746_p_ci_templates_my_template_name_monthly.yml + ``` + +1. Edit both newly generated files as follows: + + - `name:` and `performance_indicator_type:`: Delete (not needed). + - `introduced_by_url:`: The URL of the MR adding the template. + - `data_source:`: Set to `redis_hll`. + - All other fields that have no values: Set to empty strings (`''`). + - Add the following to the end of each file: + + ```yaml + options: + events: + - p_ci_templates_my_template_name + ``` + +1. Commit and push the changes. + +For example, these are the metrics configuration files for the +[5 Minute Production App template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/5-Minute-Production-App.gitlab-ci.yml): + +- The template inclusion event: [`lib/gitlab/usage_data_counters/known_events/ci_templates.yml#L438-L441`](https://gitlab.com/gitlab-org/gitlab/-/blob/dcddbf83c29d1ad0839d55362c1b43888304f453/lib/gitlab/usage_data_counters/known_events/ci_templates.yml#L438-L441) +- The weekly and monthly metrics definitions: + - [`config/metrics/counts_7d/20210901223501_p_ci_templates_5_minute_production_app_weekly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/1a6eceff3914f240864b2ca15ae2dc076ea67bf6/config/metrics/counts_7d/20210216184515_p_ci_templates_5_min_production_app_weekly.yml) + - [`config/metrics/counts_28d/20210901223505_p_ci_templates_5_minute_production_app_monthly.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/config/metrics/counts_28d/20210216184517_p_ci_templates_5_min_production_app_monthly.yml) +- The metrics count totals: + - [`config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml#L19`](https://gitlab.com/gitlab-org/gitlab/-/blob/4e01ef2b094763943348655ef77008aba7a052ae/config/metrics/counts_7d/20210216184557_ci_templates_total_unique_counts_weekly.yml#L19) + - [`config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml#L19`](https://gitlab.com/gitlab-org/gitlab/-/blob/4e01ef2b094763943348655ef77008aba7a052ae/config/metrics/counts_28d/20210216184559_ci_templates_total_unique_counts_monthly.yml#L19) + ## Security A template could contain malicious code. For example, a template that contains the `export` shell command in a job |