diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-12-20 16:37:47 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-12-20 16:37:47 +0300 |
commit | aee0a117a889461ce8ced6fcf73207fe017f1d99 (patch) | |
tree | 891d9ef189227a8445d83f35c1b0fc99573f4380 /doc/development/cicd | |
parent | 8d46af3258650d305f53b819eabf7ab18d22f59e (diff) |
Add latest changes from gitlab-org/gitlab@14-6-stable-eev14.6.0-rc42
Diffstat (limited to 'doc/development/cicd')
-rw-r--r-- | doc/development/cicd/cicd_reference_documentation_guide.md | 183 | ||||
-rw-r--r-- | doc/development/cicd/templates.md | 2 |
2 files changed, 92 insertions, 93 deletions
diff --git a/doc/development/cicd/cicd_reference_documentation_guide.md b/doc/development/cicd/cicd_reference_documentation_guide.md index aa3888cd866..e937220d208 100644 --- a/doc/development/cicd/cicd_reference_documentation_guide.md +++ b/doc/development/cicd/cicd_reference_documentation_guide.md @@ -6,17 +6,17 @@ info: To determine the technical writer assigned to the Stage/Group associated w # CI/CD YAML reference style guide **(FREE)** -The CI/CD YAML reference uses a standard style to make it easier to use and update. +The [CI/CD YAML reference](../../ci/yaml/index.md) uses a standard style to make it easier to use and update. The reference information should be kept as simple as possible, and expanded details -and examples documented in a separate page. +and examples should be documented on other pages. ## YAML reference structure Every YAML keyword must have its own section in the reference. The sections should be nested so that the keywords follow a logical tree structure. For example: -```plaintext +```markdown ### `artifacts` #### `artifacts:name` #### `artifacts:paths` @@ -27,128 +27,127 @@ be nested so that the keywords follow a logical tree structure. For example: ## YAML reference style -Each keyword entry in the reference should use the following style: +Each keyword entry in the reference: -````markdown -### `keyword-name` - -> Version information - -Keyword description and main details. - -**Keyword type**: - -**Possible inputs**: +- Must have a simple introductory section. The introduction should give the fundamental + information needed to use the keyword. Advanced details and tasks should be in + feature pages, not the reference page. -**Example of `keyword-name`**: +- Must use the keyword name as the title, for example: -(optional) In this example... + ```markdown + ### `artifacts` + ``` -(optional) **Additional details**: +- Should include the following sections: + - [Keyword type](#keyword-type) + - [Possible inputs](#possible-inputs) + - [Example of `keyword-name`](#example-of-keyword-name) +- (Optional) Can also include the following sections when needed: + - [Additional details](#additional-details) + - [Related topics](#related-topics) -- List of extra details. +The keyword name must always be in backticks without a final `:`, like `artifacts`, not `artifacts:`. +If it is a subkey of another keyword, write out all the subkeys to the "parent" key the first time it +is used, like `artifacts:reports:dast`. Afterwards, you can use just the subkey alone, like `dast`. -(optional) **Related topics**: +## Keyword type -- List of links to topics related to the keyword. -```` - -- ``### `keyword-name` ``: The keyword name must always be in backticks. - If it is a subkey of another keyword, write out all the keywords, with each separated - by `:`, for example: `artifacts:reports:dast`. - -- ``> Version information``: The [version history details](../documentation/styleguide/index.md#version-text-in-the-version-history). - If the keyword is feature flagged, see the [feature flag documentation guide](../documentation/feature_flags.md) - as well. +The keyword can be either a job or global keyword. If it can be used in a `default` +section, make not of that as well, for example: -- `Keyword description and main details.`: A simple description of the keyword, and - how to use it. Additional use cases and benefits should be added to a page outside - the reference document. Link to that document in this section. +- `**Keyword type**: Global keyword.` +- `**Keyword type**: Job keyword. You can use it only as part of a job.` +- ``**Keyword type**: Job keyword. You can use it only as part of a job or in the [`default:` section](#default).`` -- `**Keyword type**:`: Most keywords are defined at the job level, like `script`, - or at the pipeline level, like `stages`. Add the appropriate line: +### Possible inputs - - `**Keyword type**: Job keyword. You can use it only as part of a job.` - - `**Keyword type**: Pipeline keyword. You cannot use it as part of a job.` +List all the possible inputs, and any extra details about the inputs, such as defaults +or changes due to different GitLab versions, for example: - If a keyword can be used at both the job and pipeline level, like `variables`, - explain it in detail instead of using the pre-written lines above. +```markdown +**Possible inputs**: -- `**Possible inputs**:`: Explain in detail which inputs the keyword can accept. - You can add the details in a sentence, paragraph, or list. +- `true` (default if not defined) or `false`. +``` -- ``**Example of `keyword-name`**:``: An example configuration that uses the keyword. - Do not add extra keywords that are not required to understand the behavior. +```markdown +**Possible inputs**: -- (optional) `In this example...`: If the example needs extra details, - add the clarification text below the example. +- A single exit code. +- An array of exit codes. +``` -- (optional) `**Additional details**:` If there are any caveats or extra details you - want to document along with the keyword, add each one as a list item here. +```markdown +**Possible inputs**: -- (optional) `**Related topics**:` If there are any other keywords or pages that - relate to this keyword, add these links as list items here. +- A string with the long description. +- The path to a file that contains the description. Introduced in [GitLab 13.7](https://gitlab.com/gitlab-org/release-cli/-/merge_requests/67). + - The file location must be relative to the project directory (`$CI_PROJECT_DIR`). + - If the file is a symbolic link, it must be in the `$CI_PROJECT_DIR`. + - The `./path/to/file` and filename can't contain spaces. +``` -### YAML reference style example +### Example of `keyword-name` -See the [`only:changes` / `except:changes`](../../ci/yaml/index.md#onlychanges--exceptchanges) -documentation for an example of the YAML reference style. The following example is a -shortened version of that documentation's Markdown: +An example of the keyword. Use the minimum number of other keywords necessary +to make the example valid. If the example needs explanation, add it after the example, +for example: ````markdown -#### `only:changes` / `except:changes` +**Example of `dast`**: -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/19232) in GitLab 11.4. - -Use the `changes` keyword with `only` to run a job, or with `except` to skip a job, -when a Git push event modifies a file. +```yaml +stages: + - build + - dast -Use `changes` in pipelines with the following refs: +include: + - template: DAST.gitlab-ci.yml -- `branches` -- `external_pull_requests` -- `merge_requests` (see additional details about [using `only:changes` with pipelines for merge requests](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests)) +dast: + dast_configuration: + site_profile: "Example Co" + scanner_profile: "Quick Passive Test" +``` -**Keyword type**: Job keyword. You can use it only as part of a job. +In this example, the `dast` job extends the `dast` configuration added with the `include:` keyword +to select a specific site profile and scanner profile. +```` -**Possible inputs**: An array including any number of: +### Additional details -- Paths to files. -- Wildcard paths for single directories, for example `path/to/directory/*`, or a directory - and all its subdirectories, for example `path/to/directory/**/*`. +The additional details should be an unordered list of extra information that is +useful to know, but not important enough to put in the introduction. This information +can include changes introduced in different GitLab versions. For example: -**Example of `only:changes`**: +```markdown +**Additional details**: -```yaml -docker build: - script: docker build -t my-image:$CI_COMMIT_REF_SLUG . - only: - refs: - - branches - changes: - - Dockerfile - - docker/scripts/* - - dockerfiles/**/* +- The expiration time period begins when the artifact is uploaded and stored on GitLab. + If the expiry time is not defined, it defaults to the [instance wide setting](../../user/admin_area/settings/continuous_integration.md#default-artifacts-expiration). +- To override the expiration date and protect artifacts from being automatically deleted: + - Select **Keep** on the job page. + - [In GitLab 13.3 and later](https://gitlab.com/gitlab-org/gitlab/-/issues/22761), set the value of + `expire_in` to `never`. ``` -In this example, `docker build` only runs in branch pipelines, and only if at least one of -these files changed: +### Related topics -- `Dockerfile`. -- Any file in `docker/scripts` -- Any file in `dockerfiles/` or any of its subdirectories. +The related topics should be an unordered list of crosslinks to related pages, including: -**Additional details**: +- Specific tasks that you can accomplish with the keyword. +- Advanced examples of the keyword. +- Other related keywords that can be used together with this keyword. -- If you use refs other than `branches`, `external_pull_requests`, or `merge_requests`, - `changes` can't determine if a given file is new or old and always returns `true`. -- If you use `only: changes` with other refs, jobs ignore the changes and always run. -- If you use `except: changes` with other refs, jobs ignore the changes and never run. +For example: +```markdown **Related topics**: -- [`only: changes` and `except: changes` examples](../jobs/job_control.md#onlychanges--exceptchanges-examples). -- If you use `changes` with [only allow merge requests to be merged if the pipeline succeeds](../../user/project/merge_requests/merge_when_pipeline_succeeds.md#only-allow-merge-requests-to-be-merged-if-the-pipeline-succeeds), - you should [also use `only:merge_requests`](../jobs/job_control.md#use-onlychanges-with-pipelines-for-merge-requests). -- Use `changes` with [scheduled pipelines](../jobs/job_control.md#use-onlychanges-with-scheduled-pipelines). -```` +- You can specify a [fallback cache key](../caching/index.md#use-a-fallback-cache-key) + to use if the specified `cache:key` is not found. +- You can [use multiple cache keys](../caching/index.md#use-multiple-caches) in a single job. +- See the [common `cache` use cases](../caching/index.md#common-use-cases-for-caches) for more + `cache:key` examples. +``` diff --git a/doc/development/cicd/templates.md b/doc/development/cicd/templates.md index 46442aa6106..b1252b86cc0 100644 --- a/doc/development/cicd/templates.md +++ b/doc/development/cicd/templates.md @@ -392,6 +392,6 @@ If you're unsure if it's secure or not, you must ask security experts for cross- After your CI/CD template MR is created and labeled with `ci::templates`, DangerBot suggests one reviewer and one maintainer that can review your code. When your merge -request is ready for review, please [mention](../../user/project/issues/issue_data_and_actions.md#mentions) +request is ready for review, please [mention](../../user/discussions/index.md#mentions) the reviewer and ask them to review your CI/CD template changes. See details in the merge request that added [a DangerBot task for CI/CD template MRs](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/44688). |