diff options
Diffstat (limited to 'doc/development/cicd/templates.md')
| -rw-r--r-- | doc/development/cicd/templates.md | 74 |
1 files changed, 73 insertions, 1 deletions
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 |