summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
Diffstat (limited to 'doc')
-rw-r--r--doc/.vale/gitlab/Acronyms.yml4
-rw-r--r--doc/.vale/gitlab/Contractions.yml12
-rw-r--r--doc/.vale/gitlab/FutureTense.yml19
-rw-r--r--doc/api/import.md1
-rw-r--r--doc/ci/yaml/README.md141
-rw-r--r--doc/topics/autodevops/index.md10
-rw-r--r--doc/topics/autodevops/requirements.md14
-rw-r--r--doc/user/packages/container_registry/index.md2
-rw-r--r--doc/user/project/integrations/prometheus.md2
-rw-r--r--doc/user/project/pages/getting_started/pages_from_scratch.md2
10 files changed, 113 insertions, 94 deletions
diff --git a/doc/.vale/gitlab/Acronyms.yml b/doc/.vale/gitlab/Acronyms.yml
index c432b0a734a..90ec3d9a830 100644
--- a/doc/.vale/gitlab/Acronyms.yml
+++ b/doc/.vale/gitlab/Acronyms.yml
@@ -18,6 +18,7 @@ exceptions:
- ARN
- ASCII
- AWS
+ - CLI
- CNAME
- CPU
- CSS
@@ -34,9 +35,10 @@ exceptions:
- HTTP
- HTTPS
- IAM
+ - IBM
- IDE
- IRC
- - IBM
+ - ISO
- JSON
- LDAP
- LDAPS
diff --git a/doc/.vale/gitlab/Contractions.yml b/doc/.vale/gitlab/Contractions.yml
index d5ef52fb242..dc48b876f40 100644
--- a/doc/.vale/gitlab/Contractions.yml
+++ b/doc/.vale/gitlab/Contractions.yml
@@ -20,7 +20,6 @@ swap:
have not: haven't
that is: that's
we are: we're
- will not: won't
would not: wouldn't
you are: you're
you have: you've
@@ -31,25 +30,16 @@ swap:
didn't: did not
doesn't: does not
hasn't: has not
- how'll: how will
how's: how is
isn't: is not
- it'll: it will
shouldn't: should not
- that'll: that will
- they'll: they will
they're: they are
wasn't: was not
weren't: were not
- we'll: we will
we've: we have
what's: what is
- what'll: what will
when's: when is
- when'll: when will
where's: where is
- where'll: where will
who's: who is
- who'll: who will
why's: why is
- why'll: why will
+
diff --git a/doc/.vale/gitlab/FutureTense.yml b/doc/.vale/gitlab/FutureTense.yml
index edb7e1afff1..a53a7dd29cc 100644
--- a/doc/.vale/gitlab/FutureTense.yml
+++ b/doc/.vale/gitlab/FutureTense.yml
@@ -8,17 +8,10 @@
extends: existence
message: 'Avoid using future tense: "%s"'
ignorecase: true
-level: suggestion
+level: warning
link: https://docs.gitlab.com/ee/development/documentation/styleguide.html#language-to-avoid
-tokens:
- - going to be
- - going to
- - he'll
- - she'll
- - they'll
- - we'll
- - will be
- - will have
- - will # Leave this word after the two-word 'will' variants as a catchall
- - won't
- - you'll
+raw:
+ - "(going to( |\n|[[:punct:]])[a-zA-Z]*|"
+ - "will( |\n|[[:punct:]])[a-zA-Z]*|"
+ - "won't( |\n|[[:punct:]])[a-zA-Z]*|"
+ - "[a-zA-Z]*'ll( |\n|[[:punct:]])[a-zA-Z]*)"
diff --git a/doc/api/import.md b/doc/api/import.md
index a64d8783da4..3daf5e7be53 100644
--- a/doc/api/import.md
+++ b/doc/api/import.md
@@ -45,7 +45,6 @@ POST /import/bitbucket_server
| Attribute | Type | Required | Description |
|------------|---------|----------|---------------------|
-
| `bitbucket_server_url` | string | yes | Bitbucket Server URL |
| `bitbucket_server_username` | string | yes | Bitbucket Server Username |
| `personal_access_token` | string | yes | Bitbucket Server personal access token/password |
diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md
index 5bb0c7af49f..5b06afc0ab1 100644
--- a/doc/ci/yaml/README.md
+++ b/doc/ci/yaml/README.md
@@ -1088,7 +1088,7 @@ The job attributes allowed by `rules` are:
- If used as `when: delayed`, `start_in` is also required.
- [`allow_failure`](#allow_failure): If not defined, defaults to `allow_failure: false`.
-If `when` is evaluated to any value except `never`, the job is included in the pipeline.
+If a rule evaluates to true, and `when` has any value except `never`, the job is included in the pipeline.
For example:
@@ -1189,10 +1189,11 @@ for more details.
#### Differences between `rules` and `only`/`except`
-A very important difference between `rules` and `only/except`, is that jobs defined
-with `only/except` do not trigger merge request pipelines without explicit configuration.
-`rules` *can* trigger all types of pipelines, without explicitly configuring each
-type.
+Jobs defined with `only/except` do not trigger merge request pipelines by default.
+You must explicitly add `only: merge_requests`.
+
+Jobs defined with `rules` can trigger all types of pipelines.
+You do not have to explicitly configure each type.
For example:
@@ -1259,6 +1260,8 @@ Some details regarding the logic that determines the `when` for the job:
rule without `if` or `changes`, always matches, and is always used if reached.
- If a rule matches and has no `when` defined, the rule uses the `when`
defined for the job, which defaults to `on_success` if not defined.
+- You can define `when` once per rule, or once at the job-level, which applies to
+ all rules. You can't mix `when` at the job-level with `when` in rules.
For behavior similar to the [`only`/`except` keywords](#onlyexcept-basic), you can
check the value of the `$CI_PIPELINE_SOURCE` variable.
@@ -3626,30 +3629,21 @@ For more information, see [Deployments Safety](../environments/deployment_safety
> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/19298) in GitLab 13.2.
-`release` indicates that the job will create a [Release](../../user/project/releases/index.md),
-and optionally include URLs for Release assets.
+`release` indicates that the job creates a [Release](../../user/project/releases/index.md),
+and optionally includes URLs for Release assets.
These methods are supported:
-- [`name`](#releasename)
-- [`description`](#releasedescription)
- [`tag_name`](#releasetag_name)
-- [`ref`](#releaseref)
-- [`milestones`](#releasemilestones)
-- [`released_at`](#releasereleased_at)
+- [`name`](#releasename) (optional)
+- [`description`](#releasedescription) (optional)
+- [`ref`](#releaseref) (optional)
+- [`milestones`](#releasemilestones) (optional)
+- [`released_at`](#releasereleased_at) (optional)
The Release is created only if the job processes without error. If the Rails API
returns an error during Release creation, the `release` job fails.
-#### Tags
-
-A `release` job should not be run against a tag commit, or it will continually re-trigger itself. This can be specified by including:
-
-```yaml
-only:
- - tags
-```
-
#### `release-cli` Docker image
The Docker image to use for the `release-cli` must be specified, using the following directive:
@@ -3674,23 +3668,25 @@ A pipeline can have multiple `release` jobs, for example:
```yaml
ios-release:
- script: release > changelog.md
+ script:
+ - echo 'iOS release job'
release:
tag_name: v1.0.0-ios
- description: changelog.md
+ description: 'iOS release v1.0.0'
android-release:
- script: release > changelog.md
+ script:
+ - echo 'Android release job'
release:
tag_name: v1.0.0-android
- description: changelog.md
+ description: 'Android release v1.0.0'
```
#### `release:tag_name`
The `tag_name` must be specified. It can refer to an existing Git tag or can be specified by the user.
-When the specified tag doesn't exist in repository, a new tag is created from the associated SHA of the pipeline.
+When the specified tag doesn't exist in the repository, a new tag is created from the associated SHA of the pipeline.
For example, when creating a Release from a Git tag:
@@ -3699,8 +3695,6 @@ job:
release:
tag_name: $CI_COMMIT_TAG
description: changelog.txt
- only:
- - tags
```
It is also possible to create any unique tag, in which case `only: tags` is not mandatory.
@@ -3719,17 +3713,16 @@ job:
#### `release:name`
-The Release name. This is an optional field. If omitted, it is populated with
-`release:tag_name`.
+The Release name. If omitted, it is populated with the value of `release: tag_name`.
#### `release:description`
-Specifies a file containing the longer description of the Release. This is a mandatory
-field and can point to a changelog.
+Specifies the longer description of the Release.
#### `release:ref`
-When the `tag_name` does not exist, `release:ref` specifies the commit to be used instead of the pipeline `ref`. If `tag_name` doesn’t exist, the release will be created from `ref`. `ref` can be a commit SHA, another tag name, or a branch name.
+If the `release: tag_name` doesn’t exist yet, the release is created from `ref`.
+`ref` can be a commit SHA, another tag name, or a branch name.
#### `release:milestones`
@@ -3737,36 +3730,64 @@ The title of each milestone the release is associated with.
#### `release:released_at`
-The date when the release will be or was ready. Defaults to the current time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
+The date and time when the release is ready. Defaults to the current date and time if not
+defined. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
#### Complete example for `release`
-Combining the individual examples given above for `release`, we'd have the following code snippet:
+Combining the individual examples given above for `release` results in the following
+code snippets. There are two options, depending on how you generate the
+tags. These options cannot be used together, so choose one:
-```yaml
-stages:
- - build
- - test
- - release-stg
+- To create a release when you push a Git tag, or when you add a Git tag
+ in the UI by going to **Repository > Tags**:
-release_job:
- stage: release
- image: registry.gitlab.com/gitlab-org/release-cli:latest
- only:
- - tags
- script:
- - echo 'running release_job'
- release:
- name: 'Release $CI_COMMIT_SHA'
- description: 'Created using the release-cli $EXTRA_DESCRIPTION'
- tag_name: 'release-$CI_COMMIT_SHA'
- ref: '$CI_COMMIT_SHA'
- milestones:
- - 'm1'
- - 'm2'
- - 'm3'
- released_at: '2020-07-15T08:00:00Z'
-```
+ ```yaml
+ release_job:
+ stage: release
+ image: registry.gitlab.com/gitlab-org/release-cli:latest
+ rules:
+ - if: $CI_COMMIT_TAG # Run this job when a tag is created manually
+ script:
+ - echo 'running release_job'
+ release:
+ name: 'Release $CI_COMMIT_TAG'
+ description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION must be defined
+ tag_name: '$CI_COMMIT_TAG' # elsewhere in the pipeline.
+ ref: '$CI_COMMIT_TAG'
+ milestones:
+ - 'm1'
+ - 'm2'
+ - 'm3'
+ released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined,
+ # or can use a variable.
+ ```
+
+- To create a release automatically when changes are pushed to the default branch,
+ using a new Git tag that is defined with variables:
+
+ ```yaml
+ release_job:
+ stage: release
+ image: registry.gitlab.com/gitlab-org/release-cli:latest
+ rules:
+ - if: $CI_COMMIT_TAG
+ when: never # Do not run this job when a tag is created manually
+ - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH # Run this job when the default branch changes
+ script:
+ - echo 'running release_job'
+ release:
+ name: 'Release $CI_COMMIT_SHA'
+ description: 'Created using the release-cli $EXTRA_DESCRIPTION' # $EXTRA_DESCRIPTION and the tag_name
+ tag_name: 'v${MAJOR}.${MINOR}.${REVISION}' # variables must be defined elsewhere
+ ref: '$CI_COMMIT_SHA' # in the pipeline.
+ milestones:
+ - 'm1'
+ - 'm2'
+ - 'm3'
+ released_at: '2020-07-15T08:00:00Z' # Optional, will auto generate if not defined,
+ # or can use a variable.
+ ```
#### `releaser-cli` command line
@@ -3774,10 +3795,10 @@ The entries under the `:release` node are transformed into a `bash` command line
to the Docker container, which contains the [release-cli](https://gitlab.com/gitlab-org/release-cli).
You can also call the `release-cli` directly from a `script` entry.
-The YAML described above would be transferred into a command line like this:
+The YAML described above would be translated into a CLI command like this:
```shell
-release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "release-$CI_COMMIT_SHA" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3"
+release-cli create --name "Release $CI_COMMIT_SHA" --description "Created using the release-cli $EXTRA_DESCRIPTION" --tag-name "v${MAJOR}.${MINOR}.${REVISION}" --ref "$CI_COMMIT_SHA" --released-at "2020-07-15T08:00:00Z" --milestone "m1" --milestone "m2" --milestone "m3"
```
### `pages`
diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md
index e9b59b8c222..04de415b859 100644
--- a/doc/topics/autodevops/index.md
+++ b/doc/topics/autodevops/index.md
@@ -104,7 +104,7 @@ knowledge of the following:
- [GitLab Runner](https://docs.gitlab.com/runner/)
- [Prometheus](https://prometheus.io/docs/introduction/overview/)
-Auto DevOps provides great defaults for all the stages; you can, however,
+Auto DevOps provides great defaults for all the stages and makes use of [CI templates](https://gitlab.com/gitlab-org/gitlab/-/tree/master/lib/gitlab/ci/templates); you can, however,
[customize](customize.md) almost everything to your needs.
For an overview on the creation of Auto DevOps, read more
@@ -114,6 +114,10 @@ NOTE: **Note**
Kubernetes clusters can [be used without](../../user/project/clusters/index.md)
Auto DevOps.
+## Kubernetes requirements
+
+See [Auto DevOps requirements for Kubernetes](requirements.md#auto-devops-requirements-for-kubernetes).
+
## Auto DevOps base domain
The Auto DevOps base domain is required to use
@@ -163,6 +167,10 @@ set the Auto DevOps base domain to `1.2.3.4.nip.io`.
After completing setup, all requests hit the load balancer, which routes requests
to the Kubernetes pods running your application.
+### AWS ECS
+
+See [Auto DevOps requirements for Amazon ECS](requirements.md#auto-devops-requirements-for-amazon-ecs).
+
## Enabling/Disabling Auto DevOps
When first using Auto DevOps, review the [requirements](#requirements) to ensure
diff --git a/doc/topics/autodevops/requirements.md b/doc/topics/autodevops/requirements.md
index c0b43caaf78..33db94be97e 100644
--- a/doc/topics/autodevops/requirements.md
+++ b/doc/topics/autodevops/requirements.md
@@ -103,9 +103,9 @@ After all requirements are met, you can [enable Auto DevOps](index.md#enablingdi
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/208132) in GitLab 13.0.
-You can choose to target [Amazon Elastic Container Service (ECS)](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes.
+You can choose to target [AWS ECS](../../ci/cloud_deployment/index.md) as a deployment platform instead of using Kubernetes.
-To get started on Auto DevOps to Amazon ECS, you'll have to add a specific Environment
+To get started on Auto DevOps to AWS ECS, you'll have to add a specific Environment
Variable. To do so, follow these steps:
1. In your project, go to **Settings > CI / CD** and expand the **Variables**
@@ -116,9 +116,13 @@ Variable. To do so, follow these steps:
- `FARGATE` if the service you're targeting must be of launch type FARGATE.
- `ECS` if you're not enforcing any launch type check when deploying to ECS.
-When you trigger a pipeline, if Auto DevOps is enabled and if you've correctly
+When you trigger a pipeline, if you have Auto DevOps enabled and if you have correctly
[entered AWS credentials as environment variables](../../ci/cloud_deployment/index.md#deploy-your-application-to-the-aws-elastic-container-service-ecs),
-your application will be deployed to Amazon ECS.
+your application will be deployed to AWS ECS.
+
+NOTE: **Note:**
+[GitLab Managed Apps](../../user/clusters/applications.md) are not available when deploying to AWS ECS.
+You must manually configure your application (such as Ingress or Help) on AWS ECS.
NOTE: **Note:**
If you have both a valid `AUTO_DEVOPS_PLATFORM_TARGET` variable and a Kubernetes cluster tied to your project,
@@ -130,5 +134,5 @@ defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/git
However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate)
it on its own. This template is designed to be used with Auto DevOps only. It may change
unexpectedly causing your pipeline to fail if included on its own. Also, the job
-names within this template may also change. Don't override these jobs' names in your
+names within this template may also change. Do not override these jobs' names in your
own pipeline, as the override will stop working when the name changes.
diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md
index bf35db8ea2c..9dd6eec7744 100644
--- a/doc/user/packages/container_registry/index.md
+++ b/doc/user/packages/container_registry/index.md
@@ -509,7 +509,7 @@ before this feature was deployed to production (February 2020).
Support for pre-existing projects on GitLab.com
[is planned](https://gitlab.com/gitlab-org/gitlab/-/issues/196124).
For self-managed instances, cleanup policies may be enabled by an admin in the
-[CI/CD Package Registry settings](./../../admin_area/settings/index.md#cicd).
+[GitLab application settings](../../../api/settings.md#change-application-settings) by setting `container_expiration_policies_enable_historic_entries` to true.
Note the inherent [risks involved](./index.md#use-with-external-container-registries).
The cleanup policy algorithm starts by collecting all the tags for a given repository in a list,
diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md
index 1ebba7b2871..9f07c1c7607 100644
--- a/doc/user/project/integrations/prometheus.md
+++ b/doc/user/project/integrations/prometheus.md
@@ -754,6 +754,8 @@ When a query returns too many data points, the heatmap data bucket dimensions te
### Templating variables for metrics dashboards
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/214539) in GitLab 13.0.
+
Templating variables can be used to make your metrics dashboard more versatile.
#### Templating variable types
diff --git a/doc/user/project/pages/getting_started/pages_from_scratch.md b/doc/user/project/pages/getting_started/pages_from_scratch.md
index 86523ab9d10..7278c734b07 100644
--- a/doc/user/project/pages/getting_started/pages_from_scratch.md
+++ b/doc/user/project/pages/getting_started/pages_from_scratch.md
@@ -161,7 +161,7 @@ is now available.
If you want to do more advanced tasks, you can update your `.gitlab-ci.yml` file
with [any of the available settings](../../../../ci/yaml/README.md). You can check
-your CI syntax with the [GitLab CI/CD Lint Tool](https://gitlab.com/ci/lint).
+your CI syntax with the [GitLab CI/CD Lint Tool](../../../../ci/yaml/README.md#validate-the-gitlab-ciyml).
The following topics show other examples of other options you can add to your CI/CD file.
View Lorry Controller Status