Skip to content

G
gitlab-ce
Commit 8c7fae1f authored by Achilleas Pipinellis's avatar Achilleas Pipinellis
Browse files
Options

Merge branch 'docs-rename-readmes-ci-3' into 'master' 

Rename ci yaml readme to index

See merge request gitlab-org/gitlab!64887
parents 22f0a2c7 0d978174
Hide whitespace changes
Inline Side-by-side
Showing with 5230 additions and 5222 deletions
app/views/projects/pipelines/_with_tabs.html.haml
View file @ 8c7fae1f
......@@ -78,7 +78,7 @@
= build_summary(build)
#js-tab-dag.tab-pane
#js-pipeline-dag-vue{ data: { pipeline_project_path: @project.full_path, pipeline_iid: @pipeline.iid, empty_svg_path: image_path('illustrations/empty-state/empty-dag-md.svg'), about_dag_doc_path: help_page_path('ci/directed_acyclic_graph/index.md'), dag_doc_path: help_page_path('ci/yaml/README.md', anchor: 'needs')} }
#js-pipeline-dag-vue{ data: { pipeline_project_path: @project.full_path, pipeline_iid: @pipeline.iid, empty_svg_path: image_path('illustrations/empty-state/empty-dag-md.svg'), about_dag_doc_path: help_page_path('ci/directed_acyclic_graph/index.md'), dag_doc_path: help_page_path('ci/yaml/index.md', anchor: 'needs')} }
#js-tab-tests.tab-pane
#js-pipeline-tests-detail{ data: { summary_endpoint: summary_project_pipeline_tests_path(@project, @pipeline, format: :json),
......
doc/administration/instance_limits.md
View file @ 8c7fae1f
......@@ -192,7 +192,7 @@ The number of pipelines that can be created in a single push is 4.
This is to prevent the accidental creation of pipelines when `git push --all`
or `git push --mirror` is used.
Read more in the [CI documentation](../ci/yaml/README.md#processing-git-pushes).
Read more in the [CI documentation](../ci/yaml/index.md#processing-git-pushes).
## Retention of activity history
......@@ -407,7 +407,7 @@ Plan.default.actual_limits.update!(ci_instance_level_variables: 30)
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/37226) in GitLab 13.3.
Job artifacts defined with [`artifacts:reports`](../ci/yaml/README.md#artifactsreports)
Job artifacts defined with [`artifacts:reports`](../ci/yaml/index.md#artifactsreports)
that are uploaded by the runner are rejected if the file size exceeds the maximum
file size limit. The limit is determined by comparing the project's
[maximum artifact size setting](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size)
......@@ -576,7 +576,7 @@ prevent any more changes from rendering. For more information about these limits
Reports that go over the 20 MB limit won't be loaded. Affected reports:
- [Merge request security reports](../user/project/merge_requests/testing_and_reports_in_merge_requests.md#security-reports)
- [CI/CD parameter `artifacts:expose_as`](../ci/yaml/README.md#artifactsexpose_as)
- [CI/CD parameter `artifacts:expose_as`](../ci/yaml/index.md#artifactsexpose_as)
- [Unit test reports](../ci/unit_test_reports.md)
## Advanced Search limits
......
doc/administration/job_artifacts.md
View file @ 8c7fae1f
......@@ -42,10 +42,10 @@ To disable artifacts site-wide, follow the steps below.
GitLab Runner can upload an archive containing the job artifacts to GitLab. By default,
this is done when the job succeeds, but can also be done on failure, or always, via the
[`artifacts:when`](../ci/yaml/README.md#artifactswhen) parameter.
[`artifacts:when`](../ci/yaml/index.md#artifactswhen) parameter.
Most artifacts are compressed by GitLab Runner before being sent to the coordinator. The exception to this is
[reports artifacts](../ci/yaml/README.md#artifactsreports), which are compressed after uploading.
[reports artifacts](../ci/yaml/index.md#artifactsreports), which are compressed after uploading.
### Using local storage
......@@ -326,7 +326,7 @@ To migrate back to local storage:
## Expiring artifacts
If [`artifacts:expire_in`](../ci/yaml/README.md#artifactsexpire_in) is used to set
If [`artifacts:expire_in`](../ci/yaml/index.md#artifactsexpire_in) is used to set
an expiry for the artifacts, they are marked for deletion right after that date passes.
Otherwise, they expire per the [default artifacts expiration setting](../user/admin_area/settings/continuous_integration.md).
......
doc/api/commits.md
View file @ 8c7fae1f
......@@ -638,8 +638,8 @@ GET /projects/:id/repository/commits/:sha/statuses
| `id` | integer/string | yes | The ID or [URL-encoded path of the project](index.md#namespaced-path-encoding) owned by the authenticated user
| `sha` | string | yes | The commit SHA
| `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch
| `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test`
| `name` | string | no | Filter by [job name](../ci/yaml/README.md#job-keywords), e.g., `bundler:audit`
| `stage` | string | no | Filter by [build stage](../ci/yaml/index.md#stages), e.g., `test`
| `name` | string | no | Filter by [job name](../ci/yaml/index.md#job-keywords), e.g., `bundler:audit`
| `all` | boolean | no | Return all statuses, not only the latest ones
```shell
......
doc/api/job_artifacts.md
View file @ 8c7fae1f
......@@ -28,7 +28,7 @@ Example request using the `PRIVATE-TOKEN` header:
curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"
```
To use this in a [`script` definition](../ci/yaml/README.md#script) inside
To use this in a [`script` definition](../ci/yaml/index.md#script) inside
`.gitlab-ci.yml` **(PREMIUM)**, you can use either:
- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
......@@ -93,7 +93,7 @@ Example request using the `PRIVATE-TOKEN` header:
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/main/download?job=test"
```
To use this in a [`script` definition](../ci/yaml/README.md#script) inside
To use this in a [`script` definition](../ci/yaml/index.md#script) inside
`.gitlab-ci.yml` **(PREMIUM)**, you can use either:
- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable.
......
doc/api/lint.md
View file @ 8c7fae1f
......@@ -87,8 +87,8 @@ Example responses:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/29568) in GitLab 13.5.
The CI lint returns an expanded version of the configuration. The expansion does not
work for CI configuration added with [`include: local`](../ci/yaml/README.md#includelocal),
or with [`extends:`](../ci/yaml/README.md#extends).
work for CI configuration added with [`include: local`](../ci/yaml/index.md#includelocal),
or with [`extends:`](../ci/yaml/index.md#extends).
Example contents of a `.gitlab-ci.yml` passed to the CI Lint API with
`include_merged_yaml` set as true:
......
doc/api/templates/gitlab_ci_ymls.md
View file @ 8c7fae1f
......@@ -9,7 +9,7 @@ type: reference
In GitLab, there is an API endpoint available to work with GitLab CI/CD YMLs. For more
information on CI/CD pipeline configuration in GitLab, see the
[configuration reference documentation](../../ci/yaml/README.md).
[configuration reference documentation](../../ci/yaml/index.md).
## List GitLab CI YAML templates
......
doc/ci/caching/index.md
View file @ 8c7fae1f
......@@ -11,7 +11,7 @@ A cache is one or more files that a job downloads and saves. Subsequent jobs tha
the same cache don't have to download the files again, so they execute more quickly.
To learn how to define the cache in your `.gitlab-ci.yml` file,
see the [`cache` reference](../yaml/README.md#cache).
see the [`cache` reference](../yaml/index.md#cache).
## How cache is different from artifacts
......@@ -38,8 +38,8 @@ can't link to files outside it.
- Subsequent jobs in later stages of the same pipeline can use artifacts.
- Different projects cannot share artifacts.
Artifacts expire after 30 days unless you define an [expiration time](../yaml/README.md#artifactsexpire_in).
Use [dependencies](../yaml/README.md#dependencies) to control which jobs fetch the artifacts.
Artifacts expire after 30 days unless you define an [expiration time](../yaml/index.md#artifactsexpire_in).
Use [dependencies](../yaml/index.md#dependencies) to control which jobs fetch the artifacts.
## Good caching practices
......@@ -48,7 +48,7 @@ To ensure maximum availability of the cache, do one or more of the following:
- [Tag your runners](../runners/configure_runners.md#use-tags-to-limit-the-number-of-jobs-using-the-runner) and use the tag on jobs
that share the cache.
- [Use runners that are only available to a particular project](../runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects).
- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow. For example,
- [Use a `key`](../yaml/index.md#cachekey) that fits your workflow. For example,
you can configure a different cache for each branch.
For runners to work with caches efficiently, you must do one of the following:
......@@ -97,7 +97,7 @@ the fallback cache is fetched every time a cache is not found.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/merge_requests/1534) in GitLab Runner 13.4.
You can use the `$CI_COMMIT_REF_SLUG` [predefined variable](../variables/predefined_variables.md)
to specify your [`cache:key`](../yaml/README.md#cachekey). For example, if your
to specify your [`cache:key`](../yaml/index.md#cachekey). For example, if your
`$CI_COMMIT_REF_SLUG` is `test`, you can set a job to download cache that's tagged with `test`.
If a cache with this tag is not found, you can use `CACHE_FALLBACK_KEY` to
......@@ -134,7 +134,7 @@ job:
## Inherit global configuration, but override specific settings per job
You can override cache settings without overwriting the global cache by using
[anchors](../yaml/README.md#anchors). For example, if you want to override the
[anchors](../yaml/index.md#anchors). For example, if you want to override the
`policy` for one job:
```yaml
......@@ -154,7 +154,7 @@ job:
policy: pull
```
For more information, see [`cache: policy`](../yaml/README.md#cachepolicy).
For more information, see [`cache: policy`](../yaml/index.md#cachepolicy).
## Common use cases for caches
......@@ -212,7 +212,7 @@ cache:
If your project uses [npm](https://www.npmjs.com/) to install Node.js
dependencies, the following example defines `cache` globally so that all jobs inherit it.
By default, npm stores cache data in the home folder (`~/.npm`). However, you
[can't cache things outside of the project directory](../yaml/README.md#cachepaths).
[can't cache things outside of the project directory](../yaml/index.md#cachepaths).
Instead, tell npm to use `./.npm`, and cache it per-branch:
```yaml
......@@ -392,7 +392,7 @@ test:
Caching is an optimization, but it isn't guaranteed to always work. You might need
to regenerate cached files in each job that needs them.
After you define a [cache in `.gitlab-ci.yml`](../yaml/README.md#cache),
After you define a [cache in `.gitlab-ci.yml`](../yaml/index.md#cache),
the availability of the cache depends on:
- The runner's executor type.
......@@ -489,7 +489,7 @@ machines, it is a safe default.
## Clearing the cache
Runners use [cache](../yaml/README.md#cache) to speed up the execution
Runners use [cache](../yaml/index.md#cache) to speed up the execution
of your jobs by reusing existing data. This can sometimes lead to
inconsistent behavior.
......
doc/ci/chatops/index.md
View file @ 8c7fae1f
......@@ -32,7 +32,7 @@ to the job:
- `CHAT_CHANNEL` is set to the name of channel the action was triggered in.
When executed, ChatOps looks up the specified job name and attempts to match it
to a corresponding job in [`.gitlab-ci.yml`](../yaml/README.md). If a matching job
to a corresponding job in [`.gitlab-ci.yml`](../yaml/index.md). If a matching job
is found on the default branch, a pipeline containing only that job is scheduled. After the
job completes:
......
doc/ci/cloud_deployment/index.md
View file @ 8c7fae1f
......@@ -91,7 +91,7 @@ path to point to your ECR image.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207962) in GitLab 12.9.
> - The `Deploy-ECS.gitlab-ci.yml` template was [moved](https://gitlab.com/gitlab-org/gitlab/-/issues/220821) to `AWS/Deploy-ECS.gitlab-ci.yml` in GitLab 13.2.
GitLab provides a series of [CI templates that you can include in your project](../yaml/README.md#include).
GitLab provides a series of [CI templates that you can include in your project](../yaml/index.md#include).
To automate deployments of your application to your [Amazon Elastic Container Service](https://aws.amazon.com/ecs/) (AWS ECS)
cluster, you can `include` the `AWS/Deploy-ECS.gitlab-ci.yml` template in your `.gitlab-ci.yml` file.
......@@ -231,7 +231,7 @@ pass three JSON input objects, based on existing templates:
- [Template for the _Create stack_ step on AWS](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-anatomy.html).
- Template for the _Push to S3_ step. Note that `source` is where a preceding `build` job built
your application, exporting the build through [`artifacts:paths`](../yaml/README.md#artifactspaths):
your application, exporting the build through [`artifacts:paths`](../yaml/index.md#artifactspaths):
```json
{
......
doc/ci/directed_acyclic_graph/index.md
View file @ 8c7fae1f
......@@ -66,9 +66,9 @@ as quickly as possible.
## Usage
Relationships are defined between jobs using the [`needs:` keyword](../yaml/README.md#needs).
Relationships are defined between jobs using the [`needs:` keyword](../yaml/index.md#needs).
Note that `needs:` also works with the [parallel](../yaml/README.md#parallel) keyword,
Note that `needs:` also works with the [parallel](../yaml/index.md#parallel) keyword,
giving you powerful options for parallelization within your pipeline.
## Limitations
......@@ -76,7 +76,7 @@ giving you powerful options for parallelization within your pipeline.
A directed acyclic graph is a complicated feature, and as of the initial MVC there
are certain use cases that you may need to work around. For more information:
- [`needs` requirements and limitations](../yaml/README.md#requirements-and-limitations).
- [`needs` requirements and limitations](../yaml/index.md#requirements-and-limitations).
- Related epic [tracking planned improvements](https://gitlab.com/groups/gitlab-org/-/epics/1716).
## Needs Visualization
......
doc/ci/docker/using_docker_build.md
View file @ 8c7fae1f
......@@ -577,7 +577,7 @@ don't work because a fresh Docker daemon is started with the service.
### Option 1: Run `docker login`
In [`before_script`](../yaml/README.md#before_script), run `docker
In [`before_script`](../yaml/index.md#before_script), run `docker
login`:
```yaml
......@@ -682,10 +682,10 @@ There are multiple ways to define this authentication:
- In [`pre_build_script`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section)
in the runner configuration file.
- In [`before_script`](../yaml/README.md#before_script).
- In [`script`](../yaml/README.md#script).
- In [`before_script`](../yaml/index.md#before_script).
- In [`script`](../yaml/index.md#script).
The following example shows [`before_script`](../yaml/README.md#before_script).
The following example shows [`before_script`](../yaml/index.md#before_script).
The same commands apply for any solution you implement.
```yaml
......@@ -798,7 +798,7 @@ which can be avoided if a different driver is used, for example `overlay2`.
### Use the OverlayFS driver per project
You can enable the driver for each project individually by using the `DOCKER_DRIVER`
[CI/CD variable](../yaml/README.md#variables) in `.gitlab-ci.yml`:
[CI/CD variable](../yaml/index.md#variables) in `.gitlab-ci.yml`:
```yaml
variables:
......
doc/ci/docker/using_docker_images.md
View file @ 8c7fae1f
......@@ -153,9 +153,9 @@ CI/CD jobs:
from `Dockerfile` that may be overridden in the `.gitlab-ci.yml` file.
1. The runner attaches itself to a running container.
1. The runner prepares a script (the combination of
[`before_script`](../yaml/README.md#before_script),
[`script`](../yaml/README.md#script),
and [`after_script`](../yaml/README.md#after_script)).
[`before_script`](../yaml/index.md#before_script),
[`script`](../yaml/index.md#script),
and [`after_script`](../yaml/index.md#after_script)).
1. The runner sends the script to the container's shell `stdin` and receives the
output.
......
doc/ci/enable_or_disable_ci.md
View file @ 8c7fae1f
......@@ -9,7 +9,7 @@ type: howto
To effectively use GitLab CI/CD, you need:
- A valid [`.gitlab-ci.yml`](yaml/README.md) file present at the root directory
- A valid [`.gitlab-ci.yml`](yaml/index.md) file present at the root directory
of your project.
- A [runner](runners/index.md) properly set up.
......
doc/ci/environments/deployment_safety.md
View file @ 8c7fae1f
......@@ -35,7 +35,7 @@ Pipeline jobs in GitLab CI/CD run in parallel, so it's possible that two deploym
jobs in two different pipelines attempt to deploy to the same environment at the same
time. This is not desired behavior as deployments should happen sequentially.
You can ensure only one deployment job runs at a time with the [`resource_group` keyword](../yaml/README.md#resource_group) in your `.gitlab-ci.yml`.
You can ensure only one deployment job runs at a time with the [`resource_group` keyword](../yaml/index.md#resource_group) in your `.gitlab-ci.yml`.
For example:
......@@ -59,7 +59,7 @@ The improved pipeline flow **after** using the resource group:
1. `deploy` job in Pipeline-A finishes.
1. `deploy` job in Pipeline-B starts running.
For more information, see [`resource_group` keyword in `.gitlab-ci.yml`](../yaml/README.md#resource_group).
For more information, see [`resource_group` keyword in `.gitlab-ci.yml`](../yaml/index.md#resource_group).
## Skip outdated deployment jobs
......
doc/ci/environments/index.md
View file @ 8c7fae1f
......@@ -10,7 +10,7 @@ disqus_identifier: 'https://docs.gitlab.com/ee/ci/environments.html'
Environments describe where code is deployed.
Each time [GitLab CI/CD](../yaml/README.md) deploys a version of code to an environment,
Each time [GitLab CI/CD](../yaml/index.md) deploys a version of code to an environment,
a deployment is created.
GitLab:
......@@ -84,7 +84,7 @@ When the job runs, the environment and deployment are created.
NOTE:
Some characters cannot be used in environment names.
For more information about the `environment` keywords, see
[the `.gitlab-ci.yml` keyword reference](../yaml/README.md#environment).
[the `.gitlab-ci.yml` keyword reference](../yaml/index.md#environment).
### Create a dynamic environment
......@@ -107,7 +107,7 @@ deploy_review:
In this example:
- The `name` is `review/$CI_COMMIT_REF_NAME`. Because the [environment name](../yaml/README.md#environmentname)
- The `name` is `review/$CI_COMMIT_REF_NAME`. Because the [environment name](../yaml/index.md#environmentname)
can contain slashes (`/`), you can use this pattern to distinguish between dynamic and static environments.
- For the `url`, you could use `$CI_COMMIT_REF_NAME`, but because this value
may contain a `/` or other characters that would not be valid in a domain name or URL,
......@@ -119,7 +119,7 @@ However, when you use this format, you can [group similar environments](#group-s
NOTE:
Some variables cannot be used as environment names or URLs.
For more information about the `environment` keywords, see
[the `.gitlab-ci.yml` keyword reference](../yaml/README.md#environment).
[the `.gitlab-ci.yml` keyword reference](../yaml/index.md#environment).
## Deployment tier of environments
......@@ -141,8 +141,8 @@ you can use tiers:
| `development` | Dev, [Review apps](../review_apps/index.md), Trunk |
| `other` | |
By default, GitLab assumes a tier based on [the environment name](../yaml/README.md#environmentname).
Instead, you can use the [`deployment_tier` keyword](../yaml/README.md#environmentdeployment_tier) to specify a tier.
By default, GitLab assumes a tier based on [the environment name](../yaml/index.md#environmentname).
Instead, you can use the [`deployment_tier` keyword](../yaml/index.md#environmentdeployment_tier) to specify a tier.
## Configure manual deployments
......@@ -250,7 +250,7 @@ GitLab supports the [dotenv (`.env`)](https://github.com/bkeepers/dotenv) file f
and expands the `environment:url` value with variables defined in the `.env` file.
To use this feature, specify the
[`artifacts:reports:dotenv`](../yaml/README.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
[`artifacts:reports:dotenv`](../yaml/index.md#artifactsreportsdotenv) keyword in `.gitlab-ci.yml`.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
For an overview, see [Set dynamic URLs after a job finished](https://youtu.be/70jDXtOf4Ig).
......@@ -334,7 +334,7 @@ To retry or rollback a deployment:
### Environment URL
The [environment URL](../yaml/README.md#environmenturl) is displayed in a few
The [environment URL](../yaml/index.md#environmenturl) is displayed in a few
places in GitLab:
- In a merge request as a link:
......@@ -364,7 +364,7 @@ When you stop an environment:
- On the **Environments** page, it moves from the list of **Available** environments
to the list of **Stopped** environments.
- An [`on_stop` action](../yaml/README.md#environmenton_stop), if defined, is executed.
- An [`on_stop` action](../yaml/index.md#environmenton_stop), if defined, is executed.
Dynamic environments stop automatically when their associated branch is
deleted.
......@@ -400,8 +400,8 @@ stop_review:
when: manual
```
Both jobs must have the same [`rules`](../yaml/README.md#only--except)
or [`only/except`](../yaml/README.md#only--except) configuration. Otherwise,
Both jobs must have the same [`rules`](../yaml/index.md#only--except)
or [`only/except`](../yaml/index.md#only--except) configuration. Otherwise,
the `stop_review` job might not be included in all pipelines that include the
`deploy_review` job, and you cannot trigger `action: stop` to stop the environment automatically.
......@@ -413,7 +413,7 @@ set the [`GIT_STRATEGY`](../runners/configure_runners.md#git-strategy) to `none`
`stop_review` job. Then the [runner](https://docs.gitlab.com/runner/) doesn't
try to check out the code after the branch is deleted.
Read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_stop).
Read more in the [`.gitlab-ci.yml` reference](../yaml/index.md#environmenton_stop).
#### Stop an environment after a certain time period
......@@ -421,7 +421,7 @@ Read more in the [`.gitlab-ci.yml` reference](../yaml/README.md#environmenton_st
You can set environments to stop automatically after a certain time period.
In your `.gitlab-ci.yml` file, specify the [`environment:auto_stop_in`](../yaml/README.md#environmentauto_stop_in)
In your `.gitlab-ci.yml` file, specify the [`environment:auto_stop_in`](../yaml/index.md#environmentauto_stop_in)
keyword. You can specify a human-friendly date as the value, such as `1 hour and 30 minutes` or `1 day`.
After the time period passes, GitLab automatically triggers a job to stop the environment.
......@@ -767,7 +767,7 @@ To ensure the `action: stop` can always run when needed, you can:
when: manual
```
- Add a [`needs`](../yaml/README.md#needs) entry to the `action: stop` job so the
- Add a [`needs`](../yaml/index.md#needs) entry to the `action: stop` job so the
job can start out of stage order:
```yaml
......
doc/ci/examples/end_to_end_testing_webdriverio/index.md
View file @ 8c7fae1f
......@@ -146,10 +146,10 @@ new browser window interacting with your app as you specified.
Which brings us to the exciting part: how do we run this in GitLab CI/CD? There are two things we
need to do for this:
1. Set up [CI/CD jobs](../../yaml/README.md) that actually have a browser available.
1. Set up [CI/CD jobs](../../yaml/index.md) that actually have a browser available.
1. Update our WebdriverIO configuration to use those browsers to visit the review apps.
For the scope of this article, we've defined an additional [CI/CD stage](../../yaml/README.md#stages)
For the scope of this article, we've defined an additional [CI/CD stage](../../yaml/index.md#stages)
`confidence-check` that is executed _after_ the stage that deploys the review app. It uses the `node:latest` [Docker
image](../../docker/using_docker_images.md). However, WebdriverIO fires up actual browsers
to interact with your application, so we need to install and run them.
......@@ -255,5 +255,5 @@ production project, see:
There's plenty more that WebdriverIO can do. For example, you can configure a [`screenshotPath`](http://v4.webdriver.io/guide/getstarted/configuration.html#screenshotPath) to tell WebdriverIO to take
a screenshot when tests are failing. Then tell GitLab CI/CD to store those
[artifacts](../../yaml/README.md#artifacts), and you'll be able to see what went
[artifacts](../../yaml/index.md#artifacts), and you'll be able to see what went
wrong within GitLab.
doc/ci/examples/laravel_with_gitlab_and_envoy/index.md
View file @ 8c7fae1f
......@@ -548,7 +548,7 @@ If you wish to test your app with different PHP versions and [database managemen
#### CI/CD variables
GitLab CI/CD allows us to use [CI/CD variables](../../yaml/README.md#variables) in our jobs.
GitLab CI/CD allows us to use [CI/CD variables](../../yaml/index.md#variables) in our jobs.
We defined MySQL as our database management system, which comes with a superuser root created by default.
So we should adjust the configuration of MySQL instance by defining `MYSQL_DATABASE` variable as our database name and `MYSQL_ROOT_PASSWORD` variable as the password of `root`.
......@@ -567,7 +567,7 @@ variables:
#### Unit Test as the first job
We defined the required shell scripts as an array of the [script](../../yaml/README.md#script) keyword to be executed when running `unit_test` job.
We defined the required shell scripts as an array of the [script](../../yaml/index.md#script) keyword to be executed when running `unit_test` job.
These scripts are some Artisan commands to prepare the Laravel, and, at the end of the script, we'll run the tests by `PHPUnit`.
......@@ -593,7 +593,7 @@ To deploy our app with Envoy, we had to set up the `$SSH_PRIVATE_KEY` variable a
If the SSH keys have added successfully, we can run Envoy.
As mentioned before, GitLab supports [Continuous Delivery](https://about.gitlab.com/blog/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#continuous-delivery) methods as well.
The [environment](../../yaml/README.md#environment) keyword tells GitLab that this job deploys to the `production` environment.
The [environment](../../yaml/index.md#environment) keyword tells GitLab that this job deploys to the `production` environment.
The `url` keyword is used to generate a link to our application on the GitLab Environments page.
The `only` keyword tells GitLab CI/CD that the job should be executed only when the pipeline is building the `main` branch.
Lastly, `when: manual` is used to turn the job from running automatically to a manual action.
......
doc/ci/index.md
View file @ 8c7fae1f
......@@ -77,7 +77,7 @@ GitLab CI/CD supports numerous configuration options:
| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. |
| [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. |
| [Optimize GitLab and GitLab Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repositories. |
| [`.gitlab-ci.yml` full reference](yaml/README.md) | All the attributes you can use with GitLab CI/CD. |
| [`.gitlab-ci.yml` full reference](yaml/index.md) | All the attributes you can use with GitLab CI/CD. |
Note that certain operations can only be performed according to the
[user](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions.
......
doc/ci/jobs/index.md
View file @ 8c7fae1f
......@@ -11,7 +11,7 @@ Pipeline configuration begins with jobs. Jobs are the most fundamental element o
Jobs are:
- Defined with constraints stating under what conditions they should be executed.
- Top-level elements with an arbitrary name and must contain at least the [`script`](../yaml/README.md#script) clause.
- Top-level elements with an arbitrary name and must contain at least the [`script`](../yaml/index.md#script) clause.
- Not limited in how many can be defined.
For example:
......@@ -101,7 +101,7 @@ jobs. Click to expand them.
![Grouped pipelines](img/pipelines_grouped.png)
To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/README.md),
To create a group of jobs, in the [CI/CD pipeline configuration file](../yaml/index.md),
separate each job name with a number and one of the following:
- A slash (`/`), for example, `test 1/3`, `test 2/3`, `test 3/3`.
......@@ -168,7 +168,7 @@ for a single run of the manual job.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/21767) in GitLab 11.4.
When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/README.md#whendelayed) keyword to
When you do not want to run a job immediately, you can use the [`when:delayed`](../yaml/index.md#whendelayed) keyword to
delay a job's execution for a certain period.
This is especially useful for timed incremental rollout where new code is rolled out gradually.
......
doc/ci/jobs/job_control.md
View file @ 8c7fae1f
......@@ -12,22 +12,22 @@ the status of variables, the pipeline type, and so on.
To configure a job to be included or excluded from certain pipelines, you can use:
- [`rules`](../yaml/README.md#rules)
- [`only`](../yaml/README.md#only--except)
- [`except`](../yaml/README.md#only--except)
- [`rules`](../yaml/index.md#rules)
- [`only`](../yaml/index.md#only--except)
- [`except`](../yaml/index.md#only--except)
Use [`needs`](../yaml/README.md#needs) to configure a job to run as soon as the
Use [`needs`](../yaml/index.md#needs) to configure a job to run as soon as the
earlier jobs it depends on finish running.
## Specify when jobs run with `rules`
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3.
Use [`rules`](../yaml/README.md#rules) to include or exclude jobs in pipelines.
Use [`rules`](../yaml/index.md#rules) to include or exclude jobs in pipelines.
Rules are evaluated in order until the first match. When a match is found, the job
is either included or excluded from the pipeline, depending on the configuration.
See the [`rules`](../yaml/README.md#rules) reference for more details.
See the [`rules`](../yaml/index.md#rules) reference for more details.
Future keyword improvements are being discussed in our [epic for improving `rules`](https://gitlab.com/groups/gitlab-org/-/epics/2783),
where anyone can add suggestions or requests.
......@@ -150,7 +150,7 @@ causes duplicated pipelines.
To avoid duplicate pipelines, you can:
- Use [`workflow`](../yaml/README.md#workflow) to specify which types of pipelines
- Use [`workflow`](../yaml/index.md#workflow) to specify which types of pipelines
can run.
- Rewrite the rules to run the job only in very specific cases,
and avoid a final `when:` rule:
......@@ -179,7 +179,7 @@ job:
```
You should not include both push and merge request pipelines in the same job without
[`workflow:rules` that prevent duplicate pipelines](../yaml/README.md#switch-between-branch-pipelines-and-merge-request-pipelines):
[`workflow:rules` that prevent duplicate pipelines](../yaml/index.md#switch-between-branch-pipelines-and-merge-request-pipelines):
```yaml
job:
......@@ -206,12 +206,12 @@ job-with-rules:
For every change pushed to the branch, duplicate pipelines run. One
branch pipeline runs a single job (`job-with-no-rules`), and one merge request pipeline
runs the other job (`job-with-rules`). Jobs with no rules default
to [`except: merge_requests`](../yaml/README.md#only--except), so `job-with-no-rules`
to [`except: merge_requests`](../yaml/index.md#only--except), so `job-with-no-rules`
runs in all cases except merge requests.
### Common `if` clauses for `rules`
For behavior similar to the [`only`/`except` keywords](../yaml/README.md#only--except), you can
For behavior similar to the [`only`/`except` keywords](../yaml/index.md#only--except), you can
check the value of the `$CI_PIPELINE_SOURCE` variable:
| Value | Description |
......@@ -222,7 +222,7 @@ check the value of the `$CI_PIPELINE_SOURCE` variable:
| `external_pull_request_event` | When an external pull request on GitHub is created or updated. See [Pipelines for external pull requests](../ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests). |
| `merge_request_event` | For pipelines created when a merge request is created or updated. Required to enable [merge request pipelines](../merge_request_pipelines/index.md), [merged results pipelines](../merge_request_pipelines/pipelines_for_merged_results/index.md), and [merge trains](../merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md). |
| `parent_pipeline` | For pipelines triggered by a [parent/child pipeline](../parent_child_pipelines.md) with `rules`. Use this pipeline source in the child pipeline configuration so that it can be triggered by the parent pipeline. |
| `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](../yaml/README.md#trigger) keyword. |
| `pipeline` | For [multi-project pipelines](../multi_project_pipelines.md) created by [using the API with `CI_JOB_TOKEN`](../multi_project_pipelines.md#create-multi-project-pipelines-by-using-the-api), or the [`trigger`](../yaml/index.md#trigger) keyword. |
| `push` | For pipelines triggered by a `git push` event, including for branches and tags. |
| `schedule` | For [scheduled pipelines](../pipelines/schedules.md). |
| `trigger` | For pipelines created by using a [trigger token](../triggers/index.md#trigger-token). |
......@@ -292,7 +292,7 @@ You can use the `$` character for both variables and paths. For example, if the
## Specify when jobs run with `only` and `except`
You can use [`only`](../yaml/README.md#only--except) and [`except`](../yaml/README.md#only--except)
You can use [`only`](../yaml/index.md#only--except) and [`except`](../yaml/index.md#only--except)
to control when to add jobs to pipelines.
- Use `only` to define when a job runs.
......@@ -301,7 +301,7 @@ to control when to add jobs to pipelines.
### `only:refs` / `except:refs` examples
`only` or `except` used without `refs` is the same as
[`only:refs` / `except/refs`](../yaml/README.md#onlyrefs--exceptrefs)
[`only:refs` / `except/refs`](../yaml/index.md#onlyrefs--exceptrefs)
In the following example, `job` runs only for:
......@@ -334,7 +334,7 @@ except `main` and branches that start with `release/`.
### `only: variables` / `except: variables` examples
You can use [`except:variables`](../yaml/README.md#onlyvariables--exceptvariables) to exclude jobs based on a commit message:
You can use [`except:variables`](../yaml/index.md#onlyvariables--exceptvariables) to exclude jobs based on a commit message:
```yaml
end-to-end:
......@@ -502,9 +502,9 @@ test:
You can use [predefined CI/CD variables](../variables/predefined_variables.md) to choose
which pipeline types jobs run in, with:
- [`rules`](../yaml/README.md#rules)
- [`only:variables`](../yaml/README.md#onlyvariables--exceptvariables)
- [`except:variables`](../yaml/README.md#onlyvariables--exceptvariables)
- [`rules`](../yaml/index.md#rules)
- [`only:variables`](../yaml/index.md#onlyvariables--exceptvariables)
- [`except:variables`](../yaml/index.md#onlyvariables--exceptvariables)
The following table lists some of the variables that you can use, and the pipeline
types the variables can control for:
......@@ -592,14 +592,14 @@ Feature.enable(:allow_unsafe_ruby_regexp)
## CI/CD variable expressions
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/README.md#onlyvariables--exceptvariables)
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/README.md#rules)
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/37397) in GitLab 10.7 for [the `only` and `except` CI keywords](../yaml/index.md#onlyvariables--exceptvariables)
> - [Expanded](https://gitlab.com/gitlab-org/gitlab/-/issues/27863) in GitLab 12.3 with [the `rules` keyword](../yaml/index.md#rules)
Use variable expressions to control which jobs are created in a pipeline after changes
are pushed to GitLab. You can use variable expressions with:
- [`rules:if`](../yaml/README.md#rules).
- [`only:variables` and `except:variables`](../yaml/README.md#onlyvariables--exceptvariables).
- [`rules:if`](../yaml/index.md#rules).
- [`only:variables` and `except:variables`](../yaml/index.md#onlyvariables--exceptvariables).
For example, with `rules:if`:
......
doc/ci/lint.md
View file @ 8c7fae1f
......@@ -20,7 +20,7 @@ in your project and click **CI lint**.
## Validate basic logic and syntax
By default, the CI lint checks the syntax of your CI YAML configuration and also runs
some basic logical validations. Configuration added with the [`includes` keyword](yaml/README.md#include),
some basic logical validations. Configuration added with the [`includes` keyword](yaml/index.md#include),
is also validated.
To use the CI lint, paste a complete CI configuration (`.gitlab-ci.yml` for example)
......
doc/ci/merge_request_pipelines/index.md
View file @ 8c7fae1f
......@@ -39,13 +39,13 @@ To enable pipelines for merge requests:
## Configure pipelines for merge requests
To configure pipelines for merge requests, you must configure your [CI/CD configuration file](../yaml/README.md).
To configure pipelines for merge requests, you must configure your [CI/CD configuration file](../yaml/index.md).
To do this, you can use [`rules`](#use-rules-to-run-pipelines-for-merge-requests) or [`only/except`](#use-only-or-except-to-run-pipelines-for-merge-requests).
### Use `rules` to run pipelines for merge requests
GitLab recommends that you use the `rules` keyword, which is available in
[`workflow:rules` templates](../yaml/README.md#workflowrules-templates).
[`workflow:rules` templates](../yaml/index.md#workflowrules-templates).
### Use `only` or `except` to run pipelines for merge requests
......@@ -138,7 +138,7 @@ Instead, use the
[`$CI_COMMIT_REF_NAME` predefined environment
variable](../variables/predefined_variables.md) in
combination with
[`only:variables`](../yaml/README.md#onlyvariables--exceptvariables) to
[`only:variables`](../yaml/index.md#onlyvariables--exceptvariables) to
accomplish this behavior:
```yaml
......@@ -199,7 +199,7 @@ If you are seeing two pipelines when using `only/except`, please see the caveats
related to using `only/except` above (or, consider moving to `rules`).
In [GitLab 13.7](https://gitlab.com/gitlab-org/gitlab/-/issues/201845) and later,
you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/README.md#switch-between-branch-pipelines-and-merge-request-pipelines).
you can add `workflow:rules` to [switch from branch pipelines to merge request pipelines](../yaml/index.md#switch-between-branch-pipelines-and-merge-request-pipelines).
After a merge request is open on the branch, the pipeline switches to a merge request pipeline.
### Two pipelines created when pushing an invalid CI configuration file
......
doc/ci/metrics_reports.md
View file @ 8c7fae1f
......@@ -37,7 +37,7 @@ For an MR, the values of these metrics from the feature branch are compared to t
## How to set it up
Add a job that creates a [metrics report](yaml/README.md#artifactsreportsmetrics) (default filename: `metrics.txt`). The file should conform to the [OpenMetrics](https://openmetrics.io/) format.
Add a job that creates a [metrics report](yaml/index.md#artifactsreportsmetrics) (default filename: `metrics.txt`). The file should conform to the [OpenMetrics](https://openmetrics.io/) format.
For example:
......
doc/ci/migration/circleci.md
View file @ 8c7fae1f
......@@ -68,7 +68,7 @@ job1:
### Workflows
CircleCI determines the run order for jobs with `workflows`. This is also used to determine concurrent, sequential, scheduled, or manual runs. The equivalent function in GitLab CI/CD is called [stages](../yaml/README.md#stages). Jobs on the same stage run in parallel, and only run after previous stages complete. Execution of the next stage is skipped when a job fails by default, but this can be allowed to continue even [after a failed job](../yaml/README.md#allow_failure).
CircleCI determines the run order for jobs with `workflows`. This is also used to determine concurrent, sequential, scheduled, or manual runs. The equivalent function in GitLab CI/CD is called [stages](../yaml/index.md#stages). Jobs on the same stage run in parallel, and only run after previous stages complete. Execution of the next stage is skipped when a job fails by default, but this can be allowed to continue even [after a failed job](../yaml/index.md#allow_failure).
See [the Pipeline Architecture Overview](../pipelines/pipeline_architectures.md) for guidance on different types of pipelines that you can use. Pipelines can be tailored to meet your needs, such as for a large complex project or a monorepo with independent defined components.
......@@ -140,7 +140,7 @@ job4:
#### Scheduled run
GitLab CI/CD has an easy to use UI to [schedule pipelines](../pipelines/schedules.md). Also, [rules](../yaml/README.md#rules) can be used to determine if jobs should be included or excluded from a scheduled pipeline.
GitLab CI/CD has an easy to use UI to [schedule pipelines](../pipelines/schedules.md). Also, [rules](../yaml/index.md#rules) can be used to determine if jobs should be included or excluded from a scheduled pipeline.
CircleCI example of a scheduled workflow:
......@@ -159,7 +159,7 @@ scheduled-workflow:
- build
```
Example of the same scheduled pipeline using [`rules`](../yaml/README.md#rules) in GitLab CI/CD:
Example of the same scheduled pipeline using [`rules`](../yaml/index.md#rules) in GitLab CI/CD:
```yaml
job1:
......@@ -188,7 +188,7 @@ release-branch-workflow:
- testing
```
Example of the same workflow using [`when: manual`](../yaml/README.md#whenmanual) in GitLab CI/CD:
Example of the same workflow using [`when: manual`](../yaml/index.md#whenmanual) in GitLab CI/CD:
```yaml
deploy_prod:
......@@ -200,7 +200,7 @@ deploy_prod:
### Filter job by branch
[Rules](../yaml/README.md#rules) are a mechanism to determine if the job runs for a specific branch.
[Rules](../yaml/index.md#rules) are a mechanism to determine if the job runs for a specific branch.
CircleCI example of a job filtered by branch:
......@@ -294,7 +294,7 @@ GitLab.com shared runners:
### Machine and specific build environments
[Tags](../yaml/README.md#tags) can be used to run jobs on different platforms, by telling GitLab which runners should run the jobs.
[Tags](../yaml/index.md#tags) can be used to run jobs on different platforms, by telling GitLab which runners should run the jobs.
CircleCI example of a job running on a specific environment:
......
doc/ci/migration/jenkins.md
View file @ 8c7fae1f
......@@ -19,7 +19,7 @@ that were able to quickly complete this migration:
1. Learn the importance of [managing the organizational transition](#managing-the-organizational-transition).
1. [Add runners](../runners/index.md) to your GitLab instance.
1. Educate and enable your developers to independently perform the following steps in their projects:
1. Review the [Quick Start Guide](../quick_start/index.md) and [Pipeline Configuration Reference](../yaml/README.md).
1. Review the [Quick Start Guide](../quick_start/index.md) and [Pipeline Configuration Reference](../yaml/index.md).
1. Use the [Jenkins Wrapper](#jenkinsfile-wrapper) to temporarily maintain fragile Jenkins jobs.
1. Migrate the build and CI jobs and configure them to show results directly in your merge requests. They can use [Auto DevOps](../../topics/autodevops/index.md) as a starting point, and [customize](../../topics/autodevops/customize.md) or [decompose](../../topics/autodevops/customize.md#using-components-of-auto-devops) the configuration as needed.
1. Add [Review Apps](../review_apps/index.md).
......@@ -71,7 +71,7 @@ If you are interested in helping GitLab test the wrapper, join our [public testi
There are some high level differences between the products worth mentioning:
- With GitLab you don't need a root `pipeline` keyword to wrap everything.
- The way pipelines are triggered and [trigger other pipelines](../yaml/README.md#trigger)
- The way pipelines are triggered and [trigger other pipelines](../yaml/index.md#trigger)
is different than Jenkins. GitLab pipelines can be triggered:
- on push
......@@ -82,34 +82,34 @@ There are some high level differences between the products worth mentioning:
- by [ChatOps](../chatops/index.md)
- You can control which jobs run in which cases, depending on how they are triggered,
with the [`rules` syntax](../yaml/README.md#rules).
with the [`rules` syntax](../yaml/index.md#rules).
- GitLab [pipeline scheduling concepts](../pipelines/schedules.md) are also different from Jenkins.
- You can reuse pipeline configurations using the [`include` keyword](../yaml/README.md#include)
- You can reuse pipeline configurations using the [`include` keyword](../yaml/index.md#include)
and [templates](#templates). Your templates can be kept in a central repository (with different
permissions), and then any project can use them. This central project could also
contain scripts or other reusable code.
- You can also use the [`extends` keyword](../yaml/README.md#extends) to reuse configuration
- You can also use the [`extends` keyword](../yaml/index.md#extends) to reuse configuration
within a single pipeline configuration.
- All jobs within a single stage always run in parallel, and all stages run in sequence. We are planning
to allow certain jobs to break this sequencing as needed with our [directed acyclic graph](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/47063)
feature.
- The [`parallel`](../yaml/README.md#parallel) keyword can automatically parallelize tasks,
- The [`parallel`](../yaml/index.md#parallel) keyword can automatically parallelize tasks,
like tests that support parallelization.
- Normally all jobs within a single stage run in parallel, and all stages run in sequence.
There are different [pipeline architectures](../pipelines/pipeline_architectures.md)
that allow you to change this behavior.
- The new [`rules` syntax](../yaml/README.md#rules) is the recommended method of
- The new [`rules` syntax](../yaml/index.md#rules) is the recommended method of
controlling when different jobs run. It is more powerful than the `only/except` syntax.
- One important difference is that jobs run independently of each other and have a
fresh environment in each job. Passing artifacts between jobs is controlled using the
[`artifacts`](../yaml/README.md#artifacts) and [`dependencies`](../yaml/README.md#dependencies)
[`artifacts`](../yaml/index.md#artifacts) and [`dependencies`](../yaml/index.md#dependencies)
keywords. When finished, use the planned [Workspaces](https://gitlab.com/gitlab-org/gitlab/-/issues/29265)
feature to more easily persist a common workspace between serial jobs.
- The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but
is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most
is in the YAML format (see [complete reference](../yaml/index.md)) instead of a Groovy DSL. It's most
analogous to the declarative Jenkinsfile format.
- Manual approvals or gates can be set up as [`when:manual` jobs](../yaml/README.md#whenmanual). These can
also leverage [`protected environments`](../yaml/README.md#protecting-manual-jobs)
- Manual approvals or gates can be set up as [`when:manual` jobs](../yaml/index.md#whenmanual). These can
also leverage [`protected environments`](../yaml/index.md#protecting-manual-jobs)
to control who is able to approve them.
- GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using
container images to set up your build environment. For example, set up one pipeline that builds your build environment
......@@ -154,8 +154,8 @@ and manage.
That said, we do of course still value DRY (don't repeat yourself) principles and want to ensure that
behaviors of your jobs can be codified once and applied as needed. You can use the `extends:` syntax to
[reuse configuration in your jobs](../yaml/README.md#extends), and `include:` can
be used to [reuse pipeline configurations](../yaml/README.md#include) in pipelines
[reuse configuration in your jobs](../yaml/index.md#extends), and `include:` can
be used to [reuse pipeline configurations](../yaml/index.md#include) in pipelines
in different projects:
```yaml
......@@ -234,7 +234,7 @@ We also support using [tags](../runners/configure_runners.md#use-tags-to-limit-t
to different runners (execution agents).
The `agent` section also allows you to define which Docker images should be used for execution, for which we use
the [`image`](../yaml/README.md#image) keyword. The `image` can be set on a single job or at the top level, in which
the [`image`](../yaml/index.md#image) keyword. The `image` can be set on a single job or at the top level, in which
case it applies to all jobs in the pipeline:
```yaml
......@@ -258,7 +258,7 @@ stages:
```
Setting a step to be performed before and after any job can be done via the
[`before_script`](../yaml/README.md#before_script) and [`after_script`](../yaml/README.md#after_script) keywords:
[`before_script`](../yaml/index.md#before_script) and [`after_script`](../yaml/index.md#after_script) keywords:
```yaml
default:
......@@ -268,10 +268,10 @@ default:
#### `stages`
GitLab CI/CD also lets you define stages, but is a little bit more free-form to configure. The GitLab [`stages` keyword](../yaml/README.md#stages)
GitLab CI/CD also lets you define stages, but is a little bit more free-form to configure. The GitLab [`stages` keyword](../yaml/index.md#stages)
is a top level setting that enumerates the list of stages, but you are not required to nest individual jobs underneath
the `stages` section. Any job defined in the `.gitlab-ci.yml` can be made a part of any stage through use of the
[`stage:` keyword](../yaml/README.md#stage).
[`stage:` keyword](../yaml/index.md#stage).
Note that, unless otherwise specified, every pipeline is instantiated with a `build`, `test`, and `deploy` stage
which are run in that order. Jobs that have no `stage` defined are placed by default in the `test` stage.
......@@ -289,7 +289,7 @@ my_job:
#### `steps`
The `steps` section is equivalent to the [`script` section](../yaml/README.md#script) of an individual job. This is
The `steps` section is equivalent to the [`script` section](../yaml/index.md#script) of an individual job. This is
a simple YAML array with each line representing an individual command to be run:
```yaml
......@@ -303,7 +303,7 @@ my_job:
#### `environment`
In GitLab, we use the [`variables` keyword](../yaml/README.md#variables) to define different variables at runtime.
In GitLab, we use the [`variables` keyword](../yaml/index.md#variables) to define different variables at runtime.
These can also be set up through the GitLab UI, under CI/CD settings. See also our [general documentation on variables](../variables/index.md),
including the section on [protected variables](../variables/index.md#protect-a-cicd-variable) which can be used
to limit access to certain variables to certain environments or runners:
......@@ -318,7 +318,7 @@ variables:
Here, options for different things exist associated with the object in question itself. For example, options related
to jobs are defined in relation to the job itself. If you're looking for a certain option, you should be able to find
where it's located by searching our [complete configuration reference](../yaml/README.md) page.
where it's located by searching our [complete configuration reference](../yaml/index.md) page.
#### `parameters`
......@@ -347,9 +347,9 @@ variable entry.
#### `when`
GitLab does support a [`when` keyword](../yaml/README.md#when) which is used to indicate when a job should be
GitLab does support a [`when` keyword](../yaml/index.md#when) which is used to indicate when a job should be
run in case of (or despite) failure, but most of the logic for controlling pipelines can be found in
our very powerful [`rules` system](../yaml/README.md#rules):
our very powerful [`rules` system](../yaml/index.md#rules):
```yaml
my_job:
......
doc/ci/multi_project_pipelines.md
View file @ 8c7fae1f
......@@ -78,17 +78,17 @@ the `staging` job is marked as _failed_.
#### Trigger job configuration keywords
Trigger jobs can use only a limited set of the GitLab CI/CD [configuration keywords](yaml/README.md).
Trigger jobs can use only a limited set of the GitLab CI/CD [configuration keywords](yaml/index.md).
The keywords available for use in trigger jobs are:
- [`trigger`](yaml/README.md#trigger)
- [`stage`](yaml/README.md#stage)
- [`allow_failure`](yaml/README.md#allow_failure)
- [`rules`](yaml/README.md#rules)
- [`only` and `except`](yaml/README.md#only--except)
- [`when`](yaml/README.md#when) (only with a value of `on_success`, `on_failure`, or `always`)
- [`extends`](yaml/README.md#extends)
- [`needs`](yaml/README.md#needs)
- [`trigger`](yaml/index.md#trigger)
- [`stage`](yaml/index.md#stage)
- [`allow_failure`](yaml/index.md#allow_failure)
- [`rules`](yaml/index.md#rules)
- [`only` and `except`](yaml/index.md#only--except)
- [`when`](yaml/index.md#when) (only with a value of `on_success`, `on_failure`, or `always`)
- [`extends`](yaml/index.md#extends)
- [`needs`](yaml/index.md#needs)
#### Specify a downstream pipeline branch
......@@ -175,7 +175,7 @@ the ones defined in the upstream project take precedence.
#### Pass CI/CD variables to a downstream pipeline by using variable inheritance
You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/index.md#pass-an-environment-variable-to-another-job) and [cross project artifact downloads](yaml/README.md#cross-project-artifact-downloads-with-needs).
You can pass variables to a downstream pipeline with [`dotenv` variable inheritance](variables/index.md#pass-an-environment-variable-to-another-job) and [cross project artifact downloads](yaml/index.md#cross-project-artifact-downloads-with-needs).
In the upstream pipeline:
......@@ -215,14 +215,14 @@ In the upstream pipeline:
#### Use `rules` or `only`/`except` with multi-project pipelines
You can use CI/CD variables or the [`rules`](yaml/README.md#rulesif) keyword to
You can use CI/CD variables or the [`rules`](yaml/index.md#rulesif) keyword to
[control job behavior](jobs/job_control.md) for multi-project pipelines. When a
downstream pipeline is triggered with the [`trigger`](yaml/README.md#trigger) keyword,
downstream pipeline is triggered with the [`trigger`](yaml/index.md#trigger) keyword,
the value of the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md)
is `pipeline` for all its jobs.
If you use [`only/except`](yaml/README.md#only--except) to control job behavior, use the
[`pipelines`](yaml/README.md#onlyrefs--exceptrefs) keyword.
If you use [`only/except`](yaml/index.md#only--except) to control job behavior, use the
[`pipelines`](yaml/index.md#onlyrefs--exceptrefs) keyword.
#### Mirror status of a triggered pipeline in the trigger job
......@@ -267,10 +267,10 @@ outbound connections for upstream and downstream pipeline dependencies.
When using:
- CI/CD variables or [`rules`](yaml/README.md#rulesif) to control job behavior, the value of
- CI/CD variables or [`rules`](yaml/index.md#rulesif) to control job behavior, the value of
the [`$CI_PIPELINE_SOURCE` predefined variable](variables/predefined_variables.md) is
`pipeline` for multi-project pipeline triggered through the API with `CI_JOB_TOKEN`.
- [`only/except`](yaml/README.md#only--except) to control job behavior, use the
- [`only/except`](yaml/index.md#only--except) to control job behavior, use the
`pipelines` keyword.
## Trigger a pipeline when an upstream project is rebuilt **(PREMIUM)**
......
doc/ci/parent_child_pipelines.md
View file @ 8c7fae1f
......@@ -15,7 +15,7 @@ As pipelines grow more complex, a few related problems start to emerge:
job in next stage begins, causes arbitrary waits, slowing things down.
- Configuration for the single global pipeline becomes very long and complicated,
making it hard to manage.
- Imports with [`include`](yaml/README.md#include) increase the complexity of the configuration, and create the potential
- Imports with [`include`](yaml/index.md#include) increase the complexity of the configuration, and create the potential
for namespace collisions where jobs are unintentionally duplicated.
- Pipeline UX can become unwieldy with so many jobs and stages to work with.
......@@ -38,12 +38,12 @@ set of concurrently running child pipelines, but within the same project:
Child pipelines work well with other GitLab CI/CD features:
- Use [`rules: changes`](yaml/README.md#ruleschanges) to trigger pipelines only when
- Use [`rules: changes`](yaml/index.md#ruleschanges) to trigger pipelines only when
certain files change. This is useful for monorepos, for example.
- Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal
pipelines, they can have their own behaviors and sequencing in relation to triggers.
See the [`trigger:`](yaml/README.md#trigger) keyword documentation for full details on how to
See the [`trigger:`](yaml/index.md#trigger) keyword documentation for full details on how to
include the child pipeline configuration.
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
......@@ -51,7 +51,7 @@ For an overview, see [Parent-Child Pipelines feature demo](https://youtu.be/n8Kp
## Examples
The simplest case is [triggering a child pipeline](yaml/README.md#trigger) using a
The simplest case is [triggering a child pipeline](yaml/index.md#trigger) using a
local YAML file to define the pipeline configuration. In this case, the parent pipeline
triggers the child pipeline, and continues without waiting:
......@@ -72,7 +72,7 @@ microservice_a:
```
In [GitLab 13.5](https://gitlab.com/gitlab-org/gitlab/-/issues/205157) and later,
you can use [`include:file`](yaml/README.md#includefile) to trigger child pipelines
you can use [`include:file`](yaml/index.md#includefile) to trigger child pipelines
with a configuration file in a different project:
```yaml
......@@ -148,7 +148,7 @@ microservice_a:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/35632) in GitLab 12.9.
Instead of running a child pipeline from a static YAML file, you can define a job that runs
your own script to generate a YAML file, which is then [used to trigger a child pipeline](yaml/README.md#trigger-child-pipeline-with-generated-configuration-file).
your own script to generate a YAML file, which is then [used to trigger a child pipeline](yaml/index.md#trigger-child-pipeline-with-generated-configuration-file).
This technique can be very powerful in generating pipelines targeting content that changed or to
build a matrix of targets and architectures.
......
doc/ci/pipeline_editor/index.md
View file @ 8c7fae1f
......@@ -18,7 +18,7 @@ From the pipeline editor page you can:
- Select the branch to work from. [Introduced in GitLab 13.12](https://gitlab.com/gitlab-org/gitlab/-/issues/326189), disabled by default.
- [Validate](#validate-ci-configuration) your configuration syntax while editing the file.
- Do a deeper [lint](#lint-ci-configuration) of your configuration, that verifies it with any configuration
added with the [`include`](../yaml/README.md#include) keyword.
added with the [`include`](../yaml/index.md#include) keyword.
- See a [visualization](#visualize-ci-configuration) of the current configuration.
- View an [expanded](#view-expanded-configuration) version of your configuration.
- [Commit](#commit-changes-to-ci-configuration) the changes to a specific branch.
......@@ -58,7 +58,7 @@ reflected in the CI lint. It displays the same results as the existing [CI Lint
To view a visualization of your `gitlab-ci.yml` configuration, in your project,
go to **CI/CD > Editor**, and then select the **Visualize** tab. The
visualization shows all stages and jobs. Any [`needs`](../yaml/README.md#needs)
visualization shows all stages and jobs. Any [`needs`](../yaml/index.md#needs)
relationships are displayed as lines connecting jobs together, showing the
hierarchy of execution:
......@@ -80,10 +80,10 @@ To view the fully expanded CI/CD configuration as one combined file, go to the
pipeline editor's **View merged YAML** tab. This tab displays an expanded configuration
where:
- Configuration imported with [`include`](../yaml/README.md#include) is copied into the view.
- Jobs that use [`extends`](../yaml/README.md#extends) display with the
[extended configuration merged into the job](../yaml/README.md#merge-details).
- YAML anchors are [replaced with the linked configuration](../yaml/README.md#anchors).
- Configuration imported with [`include`](../yaml/index.md#include) is copied into the view.
- Jobs that use [`extends`](../yaml/index.md#extends) display with the
[extended configuration merged into the job](../yaml/index.md#merge-details).
- YAML anchors are [replaced with the linked configuration](../yaml/index.md#anchors).
## Commit changes to CI configuration
......
doc/ci/pipelines/index.md
View file @ 8c7fae1f
......@@ -67,9 +67,9 @@ Pipelines can be configured in many different ways:
Pipelines and their component jobs and stages are defined in the CI/CD pipeline configuration file for each project.
- [Jobs](../jobs/index.md) are the basic configuration component.
- Stages are defined by using the [`stages`](../yaml/README.md#stages) keyword.
- Stages are defined by using the [`stages`](../yaml/index.md#stages) keyword.
For a list of configuration options in the CI pipeline file, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/README.md).
For a list of configuration options in the CI pipeline file, see the [GitLab CI/CD Pipeline Configuration Reference](../yaml/index.md).
You can also configure specific aspects of your pipelines through the GitLab UI. For example:
......@@ -146,7 +146,7 @@ The pipeline now executes the jobs as configured.
> [Introduced in](https://gitlab.com/gitlab-org/gitlab/-/issues/30101) GitLab 13.7.
You can use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines)
You can use the [`value` and `description`](../yaml/index.md#prefill-variables-in-manual-pipelines)
keywords to define
[pipeline-level (global) variables](../variables/index.md#create-a-custom-cicd-variable-in-the-gitlab-ciyml-file)
that are prefilled when running a pipeline manually.
......@@ -200,7 +200,7 @@ For each `var` or `file_var`, a key and value are required.
### Add manual interaction to your pipeline
Manual actions, configured using the [`when:manual`](../yaml/README.md#whenmanual) keyword,
Manual actions, configured using the [`when:manual`](../yaml/index.md#whenmanual) keyword,
allow you to require manual interaction before moving forward in the pipeline.
You can do this straight from the pipeline graph. Just click the play button
......@@ -347,7 +347,7 @@ You can group the jobs by:
![jobs grouped by stage](img/pipelines_graph_stage_view_v13_12.png)
- [Job dependencies](#view-job-dependencies-in-the-pipeline-graph), which arranges
jobs based on their [`needs`](../yaml/README.md#needs) dependencies.
jobs based on their [`needs`](../yaml/index.md#needs) dependencies.
[Multi-project pipeline graphs](../multi_project_pipelines.md#multi-project-pipeline-visualization) help
you visualize the entire pipeline, including all cross-project inter-dependencies. **(PREMIUM)**
......@@ -365,7 +365,7 @@ This in-development feature might not be available for your use. There can be
[risks when enabling features still in development](../../user/feature_flags.md#risks-when-enabling-features-still-in-development).
Refer to this feature's version history for more details.
You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/README.md#needs)
You can arrange jobs in the pipeline graph based on their [`needs`](../yaml/index.md#needs)
dependencies.
Jobs in the leftmost column run first, and jobs that depend on them are grouped in the next columns.
......
doc/ci/pipelines/job_artifacts.md
View file @ 8c7fae1f
......@@ -48,7 +48,7 @@ is used.
If you run two types of pipelines (like branch and scheduled) for the same ref,
the pipeline that finishes later creates the job artifact.
For more examples, view the [keyword reference for the `.gitlab-ci.yml` file](../yaml/README.md#artifacts).
For more examples, view the [keyword reference for the `.gitlab-ci.yml` file](../yaml/index.md#artifacts).
## Download job artifacts
......@@ -173,7 +173,7 @@ https://gitlab.com/gitlab-org/gitlab/-/jobs/artifacts/main/file/htmlcov/index.ht
## When job artifacts are deleted
See the [`expire_in`](../yaml/README.md#artifactsexpire_in) documentation for information on when
See the [`expire_in`](../yaml/index.md#artifactsexpire_in) documentation for information on when
job artifacts are deleted.
### Keep artifacts from most recent successful jobs
......
doc/ci/pipelines/pipeline_architectures.md
View file @ 8c7fae1f
......@@ -18,7 +18,7 @@ own advantages. These methods can be mixed and matched if needed:
- [Child/Parent Pipelines](#child--parent-pipelines): Good for monorepos and projects with lots of independently defined components.
For more details about
any of the keywords used below, check out our [CI YAML reference](../yaml/README.md) for details.
any of the keywords used below, check out our [CI YAML reference](../yaml/index.md) for details.
## Basic Pipelines
......@@ -96,7 +96,7 @@ deploy_b:
If efficiency is important to you and you want everything to run as quickly as possible,
you can use [Directed Acyclic Graphs (DAG)](../directed_acyclic_graph/index.md). Use the
[`needs` keyword](../yaml/README.md#needs) to define dependency relationships between
[`needs` keyword](../yaml/index.md#needs) to define dependency relationships between
your jobs. When GitLab knows the relationships between your jobs, it can run everything
as fast as possible, and even skips into subsequent stages when possible.
......@@ -163,12 +163,12 @@ deploy_b:
In the examples above, it's clear we've got two types of things that could be built independently.
This is an ideal case for using [Child / Parent Pipelines](../parent_child_pipelines.md)) via
the [`trigger` keyword](../yaml/README.md#trigger). It separates out the configuration
the [`trigger` keyword](../yaml/index.md#trigger). It separates out the configuration
into multiple files, keeping things very simple. You can also combine this with:
- The [`rules` keyword](../yaml/README.md#rules): For example, have the child pipelines triggered only
- The [`rules` keyword](../yaml/index.md#rules): For example, have the child pipelines triggered only
when there are changes to that area.
- The [`include` keyword](../yaml/README.md#include): Bring in common behaviors, ensuring
- The [`include` keyword](../yaml/index.md#include): Bring in common behaviors, ensuring
you are not repeating yourself.
- [DAG pipelines](#directed-acyclic-graph-pipelines) inside of child pipelines, achieving the benefits of both.
......
doc/ci/pipelines/pipeline_artifacts.md
View file @ 8c7fae1f
......@@ -9,7 +9,7 @@ type: reference, howto
Pipeline artifacts are files created by GitLab after a pipeline finishes. These are different than [job artifacts](job_artifacts.md) because they are not explicitly managed by the `.gitlab-ci.yml` definitions.
Pipeline artifacts are used by the [test coverage visualization feature](../../user/project/merge_requests/test_coverage_visualization.md) to collect coverage information. It uses the [`artifacts: reports`](../yaml/README.md#artifactsreports) CI/CD keyword.
Pipeline artifacts are used by the [test coverage visualization feature](../../user/project/merge_requests/test_coverage_visualization.md) to collect coverage information. It uses the [`artifacts: reports`](../yaml/index.md#artifactsreports) CI/CD keyword.
## Storage
......
doc/ci/pipelines/pipeline_efficiency.md
View file @ 8c7fae1f
......@@ -146,7 +146,7 @@ with embedded metric charts and all valuable details to analyze the problem.
Review the storage use of the following to help analyze costs and efficiency:
- [Job artifacts](job_artifacts.md) and their [`expire_in`](../yaml/README.md#artifactsexpire_in)
- [Job artifacts](job_artifacts.md) and their [`expire_in`](../yaml/index.md#artifactsexpire_in)
configuration. If kept for too long, storage usage grows and could slow pipelines down.
- [Container registry](../../user/packages/container_registry/index.md) usage.
- [Package registry](../../user/packages/package_registry/index.md) usage.
......@@ -162,9 +162,9 @@ make pipelines run faster and more efficiently.
Try to find which jobs don't need to run in all situations, and use pipeline configuration
to stop them from running:
- Use the [`interruptible`](../yaml/README.md#interruptible) keyword to stop old pipelines
- Use the [`interruptible`](../yaml/index.md#interruptible) keyword to stop old pipelines
when they are superseded by a newer pipeline.
- Use [`rules`](../yaml/README.md#rules) to skip tests that aren't needed. For example,
- Use [`rules`](../yaml/index.md#rules) to skip tests that aren't needed. For example,
skip backend tests when only the frontend code is changed.
- Run non-essential [scheduled pipelines](schedules.md) less frequently.
......@@ -195,7 +195,7 @@ Another optimization method is to [cache](../caching/index.md) dependencies. If
dependencies change rarely, like [NodeJS `/node_modules`](../caching/index.md#cache-nodejs-dependencies),
caching can make pipeline execution much faster.
You can use [`cache:when`](../yaml/README.md#cachewhen) to cache downloaded dependencies
You can use [`cache:when`](../yaml/index.md#cachewhen) to cache downloaded dependencies
even when a job fails.
### Docker Images
......
doc/ci/pipelines/schedules.md
View file @ 8c7fae1f
......@@ -52,14 +52,14 @@ is installed on.
### Using variables
You can pass any number of arbitrary variables. They are available in
GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/README.md).
GitLab CI/CD so that they can be used in your [`.gitlab-ci.yml` file](../../ci/yaml/index.md).
![Scheduled pipeline variables](img/pipeline_schedule_variables.png)
### Using `rules`
To configure a job to be executed only when the pipeline has been
scheduled, use the [`rules`](../yaml/README.md#rules) keyword.
scheduled, use the [`rules`](../yaml/index.md#rules) keyword.
In this example, `make world` runs in scheduled pipelines, and `make build`
runs in branch and tag pipelines:
......
doc/ci/pipelines/settings.md
View file @ 8c7fae1f
......@@ -228,7 +228,7 @@ You can set pending or running pipelines to cancel automatically when a new pipe
1. Check the **Auto-cancel redundant pipelines** checkbox.
1. Click **Save changes**.
Use the [`interruptible`](../yaml/README.md#interruptible) keyword to indicate if a
Use the [`interruptible`](../yaml/index.md#interruptible) keyword to indicate if a
running job can be cancelled before it completes.
## Skip outdated deployment jobs
......
doc/ci/quick_start/index.md
View file @ 8c7fae1f
......@@ -142,7 +142,7 @@ The pipeline starts when the commit is committed.
- You can also use [CI/CD configuration visualization](../pipeline_editor/index.md#visualize-ci-configuration) to
view a graphical representation of your `.gitlab-ci.yml` file.
- For the complete `.gitlab-ci.yml` syntax, see
[the `.gitlab-ci.yml` reference topic](../yaml/README.md).
[the `.gitlab-ci.yml` reference topic](../yaml/index.md).
### View the status of your pipeline and jobs
......
doc/ci/runners/configure_runners.md
View file @ 8c7fae1f
......@@ -169,13 +169,13 @@ GitLab CI tags are not the same as Git tags. GitLab CI tags are associated with
Git tags are associated with commits.
By tagging a runner for the types of jobs it can handle, you can make sure
shared runners will [only run the jobs they are equipped to run](../yaml/README.md#tags).
shared runners will [only run the jobs they are equipped to run](../yaml/index.md#tags).
For instance, at GitLab we have runners tagged with `rails` if they contain
the appropriate dependencies to run Rails test suites.
When you [register a runner](https://docs.gitlab.com/runner/register/), its default behavior is to **only pick**
[tagged jobs](../yaml/README.md#tags).
[tagged jobs](../yaml/index.md#tags).
To change this, you must have the [Owner role](../../user/permissions.md#project-members-permissions) for the project.
To make a runner pick untagged jobs:
......@@ -250,7 +250,7 @@ You can also use variables to configure how many times a runner
> - `GIT_STRATEGY=none` requires GitLab Runner v1.7+.
You can set the `GIT_STRATEGY` used to fetch the repository content, either
globally or per-job in the [`variables`](../yaml/README.md#variables) section:
globally or per-job in the [`variables`](../yaml/index.md#variables) section:
```yaml
variables:
......@@ -281,7 +281,7 @@ The `kubernetes` executor always clones into an temporary directory.
A Git strategy of `none` also re-uses the local working copy, but skips all Git
operations normally done by GitLab. GitLab Runner pre-clone scripts are also skipped,
if present. This strategy could mean you need to add `fetch` and `checkout` commands
to [your `.gitlab-ci.yml` script](../yaml/README.md#script).
to [your `.gitlab-ci.yml` script](../yaml/index.md#script).
It can be used for jobs that operate exclusively on artifacts, like a deployment job.
Git repository data may be present, but it's likely out of date. You should only
......@@ -293,7 +293,7 @@ rely on files brought into the local working copy from cache or artifacts.
The `GIT_SUBMODULE_STRATEGY` variable is used to control if / how Git
submodules are included when fetching the code before a build. You can set them
globally or per-job in the [`variables`](../yaml/README.md#variables) section.
globally or per-job in the [`variables`](../yaml/index.md#variables) section.
There are three possible values: `none`, `normal`, and `recursive`:
......@@ -332,7 +332,7 @@ For this feature to work correctly, the submodules must be configured
The `GIT_CHECKOUT` variable can be used when the `GIT_STRATEGY` is set to either
`clone` or `fetch` to specify whether a `git checkout` should be run. If not
specified, it defaults to true. You can set them globally or per-job in the
[`variables`](../yaml/README.md#variables) section.
[`variables`](../yaml/index.md#variables) section.
If set to `false`, the runner:
......@@ -360,7 +360,7 @@ script:
The `GIT_CLEAN_FLAGS` variable is used to control the default behavior of
`git clean` after checking out the sources. You can set it globally or per-job in the
[`variables`](../yaml/README.md#variables) section.
[`variables`](../yaml/index.md#variables) section.
`GIT_CLEAN_FLAGS` accepts all possible options of the [`git clean`](https://git-scm.com/docs/git-clean)
command.
......@@ -386,7 +386,7 @@ script:
> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/-/issues/4142) in GitLab Runner 13.1.
The `GIT_FETCH_EXTRA_FLAGS` variable is used to control the behavior of
`git fetch`. You can set it globally or per-job in the [`variables`](../yaml/README.md#variables) section.
`git fetch`. You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section.
`GIT_FETCH_EXTRA_FLAGS` accepts all options of the [`git fetch`](https://git-scm.com/docs/git-fetch) command. However, `GIT_FETCH_EXTRA_FLAGS` flags are appended after the default flags that can't be modified.
......@@ -450,7 +450,7 @@ variables:
GIT_DEPTH: "3"
```
You can set it globally or per-job in the [`variables`](../yaml/README.md#variables) section.
You can set it globally or per-job in the [`variables`](../yaml/index.md#variables) section.
### Custom build directories
......@@ -559,7 +559,7 @@ variables:
GET_SOURCES_ATTEMPTS: 3
```
You can set them globally or per-job in the [`variables`](../yaml/README.md#variables) section.
You can set them globally or per-job in the [`variables`](../yaml/index.md#variables) section.
## System calls not available on GitLab.com shared runners
......
doc/ci/runners/index.md
View file @ 8c7fae1f
......@@ -273,12 +273,12 @@ test:
for maintenance or updates.
- The Windows shared runner virtual machine instances do not use the
GitLab Docker executor. This means that you can't specify
[`image`](../../ci/yaml/README.md#image) or [`services`](../../ci/yaml/README.md#services) in
[`image`](../../ci/yaml/index.md#image) or [`services`](../../ci/yaml/index.md#services) in
your pipeline configuration.
- For the beta release, we have included a set of software packages in
the base VM image. If your CI job requires additional software that's
not included in this list, then you must add installation
commands to [`before_script`](../../ci/yaml/README.md#before_script) or [`script`](../../ci/yaml/README.md#script) to install the required
commands to [`before_script`](../../ci/yaml/index.md#before_script) or [`script`](../../ci/yaml/index.md#script) to install the required
software. Note that each job runs on a new VM instance, so the
installation of additional software packages needs to be repeated for
each job in your pipeline.
......
doc/ci/secrets/index.md
View file @ 8c7fae1f
......@@ -14,7 +14,7 @@ sensitive information can be items like API tokens, database credentials, or pri
Secrets are sourced from your secrets provider.
Unlike CI/CD variables, which are always presented to a job, secrets must be explicitly
required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/README.md#secrets)
required by a job. Read [GitLab CI/CD pipeline configuration reference](../yaml/index.md#secrets)
for more information about the syntax.
GitLab has selected [Vault by HashiCorp](https://www.vaultproject.io) as the
......@@ -117,7 +117,7 @@ The path to this file is stored in a CI/CD variable named `DATABASE_PASSWORD`,
similar to [variables of type `file`](../variables/index.md#cicd-variable-types).
For more information about the supported syntax, read the
[`.gitlab-ci.yml` reference](../yaml/README.md#secretsvault).
[`.gitlab-ci.yml` reference](../yaml/index.md#secretsvault).
## Configure Vault server roles
......
doc/ci/ssh_keys/index.md
View file @ 8c7fae1f
......@@ -94,7 +94,7 @@ to access it. This is where an SSH key pair comes in handy.
# - git config --global user.name "User name"
```
The [`before_script`](../yaml/README.md#before_script) can be set globally
The [`before_script`](../yaml/index.md#before_script) can be set globally
or per-job.
1. Make sure the private server's [SSH host keys are verified](#verifying-the-ssh-host-keys).
......
doc/ci/triggers/index.md
View file @ 8c7fae1f
......@@ -26,7 +26,7 @@ depending on which trigger method is used.
| `pipeline` | Using the `trigger:` keyword in the CI/CD configuration file, or using the trigger API with `$CI_JOB_TOKEN`. |
| `trigger` | Using the trigger API using a generated trigger token |
This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/README.md#only--except).
This also applies when using the `pipelines` or `triggers` keywords with the legacy [`only/except` basic syntax](../yaml/index.md#only--except).
### Trigger token
......@@ -218,7 +218,7 @@ Using trigger variables can be proven useful for a variety of reasons:
a certain variable is present.
Consider the following `.gitlab-ci.yml` where we set three
[stages](../yaml/README.md#stages) and the `upload_package` job is run only
[stages](../yaml/index.md#stages) and the `upload_package` job is run only
when all jobs from the test and build stages pass. When the `UPLOAD_TO_S3`
variable is non-zero, `make upload` is run.
......
doc/ci/troubleshooting.md
View file @ 8c7fae1f
......@@ -49,7 +49,7 @@ and check if their values are what you expect.
## GitLab CI/CD documentation
The [complete `gitlab-ci.yml` reference](yaml/README.md) contains a full list of
The [complete `gitlab-ci.yml` reference](yaml/index.md) contains a full list of
every keyword you may need to use to configure your pipelines.
You can also look at a large number of pipeline configuration [examples](examples/index.md)
......@@ -105,7 +105,7 @@ If a pipeline does not seem to run at all, with no error message, it may also be
due to `rules` or `only/except` configuration, or the `workflow: rules` keyword.
If you are converting from `only/except` to the `rules` keyword, you should check
the [`rules` configuration details](yaml/README.md#rules) carefully. The behavior
the [`rules` configuration details](yaml/index.md#rules) carefully. The behavior
of `only/except` and `rules` is different and can cause unexpected behavior when migrating
between the two.
......@@ -123,8 +123,8 @@ This is usually caused by the `rules` configuration, and there are several ways
#### A job is not in the pipeline
GitLab determines if a job is added to a pipeline based on the [`only/except`](yaml/README.md#only--except)
or [`rules`](yaml/README.md#rules) defined for the job. If it didn't run, it's probably
GitLab determines if a job is added to a pipeline based on the [`only/except`](yaml/index.md#only--except)
or [`rules`](yaml/index.md#rules) defined for the job. If it didn't run, it's probably
not evaluating as you expect.
#### No pipeline or the wrong type of pipeline runs
......@@ -141,7 +141,7 @@ be checked to make sure the jobs are added to the correct pipeline type. For
example, if a merge request pipeline did not run, the jobs may have been added to
a branch pipeline instead.
It's also possible that your [`workflow: rules`](yaml/README.md#workflow) configuration
It's also possible that your [`workflow: rules`](yaml/index.md#workflow) configuration
blocked the pipeline, or allowed the wrong pipeline type.
### A job runs unexpectedly
......@@ -150,8 +150,8 @@ A common reason a job is added to a pipeline unexpectedly is because the `change
keyword always evaluates to true in certain cases. For example, `changes` is always
true in certain pipeline types, including scheduled pipelines and pipelines for tags.
The `changes` keyword is used in combination with [`only/except`](yaml/README.md#onlychanges--exceptchanges)
or [`rules`](yaml/README.md#ruleschanges)). It's recommended to use `changes` with
The `changes` keyword is used in combination with [`only/except`](yaml/index.md#onlychanges--exceptchanges)
or [`rules`](yaml/index.md#ruleschanges)). It's recommended to use `changes` with
`rules` or `only/except` configuration that ensures the job is only added to branch
pipelines or merge request pipelines.
......@@ -249,17 +249,17 @@ If the merge train pipeline was canceled before the merge request was merged, wi
Pipeline configuration warnings are shown when you:
- [Validate configuration with the CI Lint tool](yaml/README.md).
- [Validate configuration with the CI Lint tool](yaml/index.md).
- [Manually run a pipeline](pipelines/index.md#run-a-pipeline-manually).
### "Job may allow multiple pipelines to run for a single action" warning
When you use [`rules`](yaml/README.md#rules) with a `when:` clause without an `if:`
When you use [`rules`](yaml/index.md#rules) with a `when:` clause without an `if:`
clause, multiple pipelines may run. Usually this occurs when you push a commit to
a branch that has an open merge request associated with it.
To [prevent duplicate pipelines](jobs/job_control.md#avoid-duplicate-pipelines), use
[`workflow: rules`](yaml/README.md#workflow) or rewrite your rules to control
[`workflow: rules`](yaml/index.md#workflow) or rewrite your rules to control
which pipelines can run.
### Console workaround if job using resource_group gets stuck
......
doc/ci/unit_test_reports.md
View file @ 8c7fae1f
......@@ -41,7 +41,7 @@ Consider the following workflow:
## How it works
First, GitLab Runner uploads all [JUnit report format XML files](https://www.ibm.com/support/knowledgecenter/en/SSQ2R2_14.1.0/com.ibm.rsar.analysis.codereview.cobol.doc/topics/cac_useresults_junit.html)
as [artifacts](yaml/README.md#artifactsreportsjunit) to GitLab. Then, when you visit a merge request, GitLab starts
as [artifacts](yaml/index.md#artifactsreportsjunit) to GitLab. Then, when you visit a merge request, GitLab starts
comparing the head and base branch's JUnit report format XML files, where:
- The base branch is the target branch (usually the default branch).
......@@ -77,7 +77,7 @@ If a test failed in the project's default branch in the last 14 days, a message
## How to set it up
To enable the Unit test reports in merge requests, you need to add
[`artifacts:reports:junit`](yaml/README.md#artifactsreportsjunit)
[`artifacts:reports:junit`](yaml/index.md#artifactsreportsjunit)
in `.gitlab-ci.yml`, and specify the path(s) of the generated test reports.
The reports must be `.xml` files, otherwise [GitLab returns an Error 500](https://gitlab.com/gitlab-org/gitlab/-/issues/216575).
......@@ -87,8 +87,8 @@ XML reports are stored in GitLab as artifacts and their results are shown in the
merge request widget.
To make the Unit test report output files browsable, include them with the
[`artifacts:paths`](yaml/README.md#artifactspaths) keyword as well, as shown in the [Ruby example](#ruby-example).
To upload the report even if the job fails (for example if the tests do not pass), use the [`artifacts:when:always`](yaml/README.md#artifactswhen)
[`artifacts:paths`](yaml/index.md#artifactspaths) keyword as well, as shown in the [Ruby example](#ruby-example).
To upload the report even if the job fails (for example if the tests do not pass), use the [`artifacts:when:always`](yaml/index.md#artifactswhen)
keyword.
You cannot have multiple tests with the same name and class in your JUnit report format XML file.
......@@ -355,7 +355,7 @@ If parsing JUnit report XML results in an error, an indicator is shown next to t
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/202114) in GitLab 13.0 behind the `:junit_pipeline_screenshots_view` feature flag, disabled by default.
> - The feature flag was removed and was [made generally available](https://gitlab.com/gitlab-org/gitlab/-/issues/216979) in GitLab 13.12.
Upload your screenshots as [artifacts](yaml/README.md#artifactsreportsjunit) to GitLab. If JUnit
Upload your screenshots as [artifacts](yaml/index.md#artifactsreportsjunit) to GitLab. If JUnit
report format XML files contain an `attachment` tag, GitLab parses the attachment. Note that:
- The `attachment` tag **must** contain the relative path to `$CI_PROJECT_DIR` of the screenshots you uploaded. For
......@@ -368,7 +368,7 @@ report format XML files contain an `attachment` tag, GitLab parses the attachmen
```
- You should set the job that uploads the screenshot to
[`artifacts:when: always`](yaml/README.md#artifactswhen) so that it still uploads a screenshot
[`artifacts:when: always`](yaml/index.md#artifactswhen) so that it still uploads a screenshot
when a test fails.
A link to the test case attachment appears in the test case details in
......
doc/ci/variables/index.md
View file @ 8c7fae1f
......@@ -73,7 +73,7 @@ Make sure each variable is defined for the [scope you want to use it in](where_v
### Create a custom CI/CD variable in the `.gitlab-ci.yml` file
To create a custom variable in the [`.gitlab-ci.yml`](../yaml/README.md#variables) file,
To create a custom variable in the [`.gitlab-ci.yml`](../yaml/index.md#variables) file,
define the variable and value with `variables` keyword.
You can use the `variables` keyword in a job or at the top level of the `.gitlab-ci.yml` file.
......@@ -119,7 +119,7 @@ script:
- 'eval "$LS_CMD"' # Executes 'ls -al $TMP_DIR'
```
Use the [`value` and `description`](../yaml/README.md#prefill-variables-in-manual-pipelines)
Use the [`value` and `description`](../yaml/index.md#prefill-variables-in-manual-pipelines)
keywords to define [variables that are prefilled](../pipelines/index.md#prefill-variables-in-manual-pipelines)
for [manually-triggered pipelines](../pipelines/index.md#run-a-pipeline-manually).
......@@ -493,13 +493,13 @@ These variables cannot be used as CI/CD variables to configure a pipeline, but
they can be used in job scripts.
1. In the job script, save the variable as a `.env` file.
1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/README.md#artifactsreportsdotenv)
1. Save the `.env` file as an [`artifacts:reports:dotenv`](../yaml/index.md#artifactsreportsdotenv)
artifact.
1. Set a job in a later stage to receive the artifact by using the [`dependencies`](../yaml/README.md#dependencies)
or the [`needs`](../yaml/README.md#artifact-downloads-with-needs) keywords.
1. Set a job in a later stage to receive the artifact by using the [`dependencies`](../yaml/index.md#dependencies)
or the [`needs`](../yaml/index.md#artifact-downloads-with-needs) keywords.
1. The later job can then [use the variable in scripts](#use-cicd-variables-in-job-scripts).
For example, with the [`dependencies`](../yaml/README.md#dependencies) keyword:
For example, with the [`dependencies`](../yaml/index.md#dependencies) keyword:
```yaml
build:
......@@ -518,7 +518,7 @@ deploy:
- build
```
For example, with the [`needs`](../yaml/README.md#artifact-downloads-with-needs) keyword:
For example, with the [`needs`](../yaml/index.md#artifact-downloads-with-needs) keyword:
```yaml
build:
......
doc/ci/variables/predefined_variables.md
View file @ 8c7fae1f
......@@ -49,10 +49,10 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu
| `CI_DEPLOY_PASSWORD` | 10.8 | all | The authentication password of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. |
| `CI_DEPLOY_USER` | 10.8 | all | The authentication username of the [GitLab Deploy Token](../../user/project/deploy_tokens/index.md#gitlab-deploy-token), if the project has one. |
| `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Only available if the job is executed in a disposable environment (something that is created only for this job and disposed of/destroyed after the execution - all executors except `shell` and `ssh`). `true` when available. |
| `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/README.md#environmentname) is set. |
| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/README.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). |
| `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/README.md#environmenturl) is set. |
| `CI_ENVIRONMENT_ACTION` | 13.11 | all | The action annotation specified for this job's environment. Available if [`environment:action`](../yaml/README.md#environmentaction) is set. Can be `start`, `prepare`, or `stop`. |
| `CI_ENVIRONMENT_NAME` | 8.15 | all | The name of the environment for this job. Available if [`environment:name`](../yaml/index.md#environmentname) is set. |
| `CI_ENVIRONMENT_SLUG` | 8.15 | all | The simplified version of the environment name, suitable for inclusion in DNS, URLs, Kubernetes labels, and so on. Available if [`environment:name`](../yaml/index.md#environmentname) is set. The slug is [truncated to 24 characters](https://gitlab.com/gitlab-org/gitlab/-/issues/20941). |
| `CI_ENVIRONMENT_URL` | 9.3 | all | The URL of the environment for this job. Available if [`environment:url`](../yaml/index.md#environmenturl) is set. |
| `CI_ENVIRONMENT_ACTION` | 13.11 | all | The action annotation specified for this job's environment. Available if [`environment:action`](../yaml/index.md#environmentaction) is set. Can be `start`, `prepare`, or `stop`. |
| `CI_ENVIRONMENT_TIER` | 14.0 | all | The [deployment tier of the environment](../environments/index.md#deployment-tier-of-environments) for this job. |
| `CI_HAS_OPEN_REQUIREMENTS` | 13.1 | all | Only available if the pipeline's project has an open [requirement](../../user/project/requirements/index.md). `true` when available. |
| `CI_JOB_ID` | 9.0 | all | The internal ID of the job, unique across all jobs in the GitLab instance. |
......@@ -61,13 +61,13 @@ There are also [Kubernetes-specific deployment variables](../../user/project/clu
| `CI_JOB_MANUAL` | 8.12 | all | `true` if a job was started manually. |
| `CI_JOB_NAME` | 9.0 | 0.5 | The name of the job. |
| `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the job's stage. |
| `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/README.md#after_script). Can be `success`, `failed`, or `canceled`. |
| `CI_JOB_STATUS` | all | 13.5 | The status of the job as each runner stage is executed. Use with [`after_script`](../yaml/index.md#after_script). Can be `success`, `failed`, or `canceled`. |
| `CI_JOB_TOKEN` | 9.0 | 1.2 | A token to authenticate with [certain API endpoints](../../api/index.md#gitlab-cicd-job-token). The token is valid as long as the job is running. |
| `CI_JOB_URL` | 11.1 | 0.5 | The job details URL. |
| `CI_JOB_STARTED_AT` | 13.10 | all | The UTC datetime when a job started, in [ISO 8601](https://tools.ietf.org/html/rfc3339#appendix-A) format. |
| `CI_KUBERNETES_ACTIVE` | 13.0 | all | Only available if the pipeline has a Kubernetes cluster available for deployments. `true` when available. |
| `CI_NODE_INDEX` | 11.5 | all | The index of the job in the job set. Only available if the job uses [`parallel`](../yaml/README.md#parallel). |
| `CI_NODE_TOTAL` | 11.5 | all | The total number of instances of this job running in parallel. Set to `1` if the job does not use [`parallel`](../yaml/README.md#parallel). |
| `CI_NODE_INDEX` | 11.5 | all | The index of the job in the job set. Only available if the job uses [`parallel`](../yaml/index.md#parallel). |
| `CI_NODE_TOTAL` | 11.5 | all | The total number of instances of this job running in parallel. Set to `1` if the job does not use [`parallel`](../yaml/index.md#parallel). |
| `CI_OPEN_MERGE_REQUESTS` | 13.8 | all | A comma-separated list of up to four merge requests that use the current branch and project as the merge request source. Only available in branch and merge request pipelines if the branch has an associated merge request. For example, `gitlab-org/gitlab!333,gitlab-org/gitlab-foss!11`. |
| `CI_PAGES_DOMAIN` | 11.8 | all | The configured domain that hosts GitLab Pages. |
| `CI_PAGES_URL` | 11.8 | all | The URL for a GitLab Pages site. Always a subdomain of `CI_PAGES_DOMAIN`. |
......
doc/ci/variables/where_variables_can_be_used.md
View file @ 8c7fae1f
......@@ -149,7 +149,7 @@ In the case of `after_script` scripts, they can:
- Not use variables defined in `before_script` and `script`.
These restrictions exist because `after_script` scripts are executed in a
[separated shell context](../yaml/README.md#after_script).
[separated shell context](../yaml/index.md#after_script).
## Persisted variables
......
doc/ci/yaml/README.md
View file @ 8c7fae1f
This source diff could not be displayed because it is too large. You can view the blob instead.
doc/ci/yaml/gitlab_ci_yaml.md
View file @ 8c7fae1f
......@@ -13,7 +13,7 @@ type: reference
To use GitLab CI/CD, you need:
- Application code hosted in a Git repository.
- A file called [`.gitlab-ci.yml`](README.md) in the root of your repository, which
- A file called [`.gitlab-ci.yml`](index.md) in the root of your repository, which
contains the CI/CD configuration.
In the `.gitlab-ci.yml` file, you can define:
......@@ -27,7 +27,7 @@ In the `.gitlab-ci.yml` file, you can define:
The scripts are grouped into **jobs**, and jobs run as part of a larger
**pipeline**. You can group multiple independent jobs into **stages** that run in a defined order.
The CI/CD configuration needs at least one job that is [not hidden](README.md#hide-jobs).
The CI/CD configuration needs at least one job that is [not hidden](index.md#hide-jobs).
You should organize your jobs in a sequence that suits your application and is in accordance with
the tests you wish to perform. To [visualize](../pipeline_editor/index.md#visualize-ci-configuration) the process, imagine
......@@ -89,4 +89,4 @@ If anything goes wrong, you can
![rollback button](img/rollback.png)
[View the full syntax for the `.gitlab-ci.yml` file](README.md).
[View the full syntax for the `.gitlab-ci.yml` file](index.md).
doc/ci/yaml/includes.md
View file @ 8c7fae1f
......@@ -7,8 +7,8 @@ type: reference
# GitLab CI/CD include examples **(FREE)**
In addition to the [`includes` examples](README.md#include) listed in the
[GitLab CI YAML reference](README.md), this page lists more variations of `include`
In addition to the [`includes` examples](index.md#include) listed in the
[GitLab CI YAML reference](index.md), this page lists more variations of `include`
usage.
## Single string or array of multiple values
......
doc/ci/yaml/index.md 0 → 100644
View file @ 8c7fae1f
This source diff could not be displayed because it is too large. You can view the blob instead.
doc/ci/yaml/script.md
View file @ 8c7fae1f
......@@ -7,7 +7,7 @@ type: reference
# GitLab CI/CD script syntax **(FREE)**
You can use special syntax in [`script`](README.md#script) sections to:
You can use special syntax in [`script`](index.md#script) sections to:
- [Split long commands](#split-long-commands) into multiline commands.
- [Use color codes](#add-color-codes-to-script-output) to make job logs easier to review.
......
doc/development/auto_devops.md
View file @ 8c7fae1f
......@@ -18,7 +18,7 @@ is also available on YouTube.
Auto DevOps builds on top of GitLab CI/CD to create an automatic pipeline
based on your project contents. When Auto DevOps is enabled for a
project, the user does not need to explicitly include any pipeline configuration
through a [`.gitlab-ci.yml` file](../ci/yaml/README.md).
through a [`.gitlab-ci.yml` file](../ci/yaml/index.md).
In the absence of a `.gitlab-ci.yml` file, the [Auto DevOps CI
template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
......
doc/development/cicd/cicd_reference_documentation_guide.md
View file @ 8c7fae1f
......@@ -91,7 +91,7 @@ Keyword description and main details.
### YAML reference style example
See the [`only:changes` / `except:changes`](../../ci/yaml/README.md#onlychanges--exceptchanges)
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:
......
doc/development/cicd/index.md
View file @ 8c7fae1f
......@@ -12,7 +12,7 @@ Development guides that are specific to CI/CD are listed here.
If you are creating new CI/CD templates, please read [the development guide for GitLab CI/CD templates](templates.md).
See the [CI/CD YAML reference documentation guide](cicd_reference_documentation_guide.md)
to learn how to update the [reference page](../../ci/yaml/README.md).
to learn how to update the [reference page](../../ci/yaml/index.md).
## CI Architecture overview
......@@ -33,7 +33,7 @@ On the left side we have the events that can trigger a pipeline based on various
- When project is [subscribed to an upstream project](../../ci/multi_project_pipelines.md#trigger-a-pipeline-when-an-upstream-project-is-rebuilt).
- When [Auto DevOps](../../topics/autodevops/index.md) is enabled.
- When GitHub integration is used with [external pull requests](../../ci/ci_cd_for_external_repos/index.md#pipelines-for-external-pull-requests).
- When an upstream pipeline contains a [bridge job](../../ci/yaml/README.md#trigger) which triggers a downstream pipeline.
- When an upstream pipeline contains a [bridge job](../../ci/yaml/index.md#trigger) which triggers a downstream pipeline.
Triggering any of these events invokes the [`CreatePipelineService`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/app/services/ci/create_pipeline_service.rb)
which takes as input event data and the user triggering it, then attempts to create a pipeline.
......@@ -42,7 +42,7 @@ The `CreatePipelineService` relies heavily on the [`YAML Processor`](https://git
component, which is responsible for taking in a YAML blob as input and returns the abstract data structure of a
pipeline (including stages and all jobs). This component also validates the structure of the YAML while
processing it, and returns any syntax or semantic errors. The `YAML Processor` component is where we define
[all the keywords](../../ci/yaml/README.md) available to structure a pipeline.
[all the keywords](../../ci/yaml/index.md) available to structure a pipeline.
The `CreatePipelineService` receives the abstract data structure returned by the `YAML Processor`,
which then converts it to persisted models (pipeline, stages, jobs, etc.). After that, the pipeline is ready
......@@ -79,12 +79,12 @@ case the runner downloads them using a dedicated API endpoint.
Artifacts are stored in object storage, while metadata is kept in the database. An important example of artifacts
are reports (JUnit, SAST, DAST, etc.) which are parsed and rendered in the merge request.
Job status transitions are not all automated. A user may run [manual jobs](../../ci/yaml/README.md#whenmanual), cancel a pipeline, retry
Job status transitions are not all automated. A user may run [manual jobs](../../ci/yaml/index.md#whenmanual), cancel a pipeline, retry
specific failed jobs or the entire pipeline. Anything that
causes a job to change status triggers `ProcessPipelineService`, as it's responsible for
tracking the status of the entire pipeline.
A special type of job is the [bridge job](../../ci/yaml/README.md#trigger) which is executed server-side
A special type of job is the [bridge job](../../ci/yaml/index.md#trigger) which is executed server-side
when transitioning to the `pending` state. This job is responsible for creating a downstream pipeline, such as
a multi-project or child pipeline. The workflow loop starts again
from the `CreatePipelineService` every time a downstream pipeline is triggered.
......
doc/development/cicd/templates.md
View file @ 8c7fae1f
......@@ -16,7 +16,7 @@ Before submitting a merge request with a new or updated CI/CD template, you must
- Place the template in the correct [directory](#template-directories).
- Follow the [CI/CD template authoring guidelines](#template-authoring-guidelines).
- Name the template following the `*.gitlab-ci.yml` format.
- Use valid [`.gitlab-ci.yml` syntax](../../ci/yaml/README.md). Verify it's valid
- Use valid [`.gitlab-ci.yml` syntax](../../ci/yaml/index.md). Verify it's valid
with the [CI/CD lint tool](../../ci/lint.md).
- Include [a changelog](../changelog.md) if the merge request introduces a user-facing change.
- Follow the [template review process](#contribute-cicd-template-merge-requests).
......@@ -59,8 +59,8 @@ don't have any other `.gitlab-ci.yml` files.
When authoring pipeline templates:
- Place any [global keywords](../../ci/yaml/README.md#global-keywords) like `image`
or `before_script` in a [`default`](../../ci/yaml/README.md#custom-default-keyword-values)
- Place any [global keywords](../../ci/yaml/index.md#global-keywords) like `image`
or `before_script` in a [`default`](../../ci/yaml/index.md#custom-default-keyword-values)
section at the top of the template.
- Note clearly in the [code comments](#explain-the-template-with-comments) if the
template is designed to be used with the `includes` keyword in an existing
......@@ -68,7 +68,7 @@ When authoring pipeline templates:
A **job template** provides specific jobs that can be added to an existing CI/CD
workflow to accomplish specific tasks. It usually should be used by adding it to
an existing `.gitlab-ci.yml` file by using the [`includes`](../../ci/yaml/README.md#global-keywords)
an existing `.gitlab-ci.yml` file by using the [`includes`](../../ci/yaml/index.md#global-keywords)
keyword. You can also copy and paste the contents into an existing `.gitlab-ci.yml` file.
Configure job templates so that users can add them to their current pipeline with very
......@@ -77,7 +77,7 @@ other pipeline configuration.
When authoring job templates:
- Do not use [global](../../ci/yaml/README.md#global-keywords) or [`default`](../../ci/yaml/README.md#custom-default-keyword-values)
- Do not use [global](../../ci/yaml/index.md#global-keywords) or [`default`](../../ci/yaml/index.md#custom-default-keyword-values)
keywords. When a root `.gitlab-ci.yml` includes a template, global or default keywords
might be overridden and cause unexpected behavior. If a job template requires a
specific stage, explain in the code comments that users must manually add the stage
......@@ -127,8 +127,8 @@ job2:
#### Use `rules` instead of `only` or `except`
Avoid using [`only` or `except`](../../ci/yaml/README.md#only--except) if possible.
Only and except is not being developed any more, and [`rules`](../../ci/yaml/README.md#rules)
Avoid using [`only` or `except`](../../ci/yaml/index.md#only--except) if possible.
Only and except is not being developed any more, and [`rules`](../../ci/yaml/index.md#rules)
is now the preferred syntax:
```yaml
......
doc/development/documentation/index.md
View file @ 8c7fae1f
......@@ -123,7 +123,7 @@ following:
- `tutorial`: Learn a process/concept by doing.
[Example page](../../gitlab-basics/start-using-git.md).
- `reference`: A collection of information used as a reference to use a feature
or a functionality. [Example page](../../ci/yaml/README.md).
or a functionality. [Example page](../../ci/yaml/index.md).
### Redirection metadata
......@@ -475,10 +475,10 @@ If you want to know the in-depth details, here's what's really happening:
The following GitLab features are used among others:
- [Manual actions](../../ci/yaml/README.md#whenmanual)
- [Manual actions](../../ci/yaml/index.md#whenmanual)
- [Multi project pipelines](../../ci/multi_project_pipelines.md)
- [Review Apps](../../ci/review_apps/index.md)
- [Artifacts](../../ci/yaml/README.md#artifacts)
- [Artifacts](../../ci/yaml/index.md#artifacts)
- [Specific runner](../../ci/runners/runners_scope.md#prevent-a-specific-runner-from-being-enabled-for-other-projects)
- [Pipelines for merge requests](../../ci/merge_request_pipelines/index.md)
......
doc/development/integrations/secure.md
View file @ 8c7fae1f
......@@ -7,7 +7,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
# Security scanner integration
Integrating a security scanner into GitLab consists of providing end users
with a [CI job definition](../../ci/yaml/README.md)
with a [CI job definition](../../ci/yaml/index.md)
they can add to their CI configuration files to scan their GitLab projects.
This CI job should then output its results in a GitLab-specified format. These results are then
automatically presented in various places in GitLab, such as the Pipeline view, Merge Request
......@@ -23,7 +23,7 @@ scanner, as well as requirements and guidelines for the Docker image.
This section describes several important fields to add to the security scanner's job
definition file. Full documentation on these and other available fields can be viewed
in the [CI documentation](../../ci/yaml/README.md#image).
in the [CI documentation](../../ci/yaml/index.md#image).
### Name
......@@ -34,41 +34,41 @@ For instance, the dependency scanning job based on the "MySec" scanner would be
### Image
The [`image`](../../ci/yaml/README.md#image) keyword is used to specify
The [`image`](../../ci/yaml/index.md#image) keyword is used to specify
the [Docker image](../../ci/docker/using_docker_images.md#what-is-an-image)
containing the security scanner.
### Script
The [`script`](../../ci/yaml/README.md#script) keyword
The [`script`](../../ci/yaml/index.md#script) keyword
is used to specify the commands to run the scanner.
Because the `script` entry can't be left empty, it must be set to the command that performs the scan.
It is not possible to rely on the predefined `ENTRYPOINT` and `CMD` of the Docker image
to perform the scan automatically, without passing any command.
The [`before_script`](../../ci/yaml/README.md#before_script)
The [`before_script`](../../ci/yaml/index.md#before_script)
should not be used in the job definition because users may rely on this to prepare their projects before performing the scan.
For instance, it is common practice to use `before_script` to install system libraries
a particular project needs before performing SAST or Dependency Scanning.
Similarly, [`after_script`](../../ci/yaml/README.md#after_script)
Similarly, [`after_script`](../../ci/yaml/index.md#after_script)
should not be used in the job definition, because it may be overridden by users.
### Stage
For consistency, scanning jobs should belong to the `test` stage when possible.
The [`stage`](../../ci/yaml/README.md#stage) keyword can be omitted because `test` is the default value.
The [`stage`](../../ci/yaml/index.md#stage) keyword can be omitted because `test` is the default value.
### Fail-safe
To be aligned with the [GitLab Security paradigm](https://about.gitlab.com/direction/secure/#security-paradigm),
scanning jobs should not block the pipeline when they fail,
so the [`allow_failure`](../../ci/yaml/README.md#allow_failure) parameter should be set to `true`.
so the [`allow_failure`](../../ci/yaml/index.md#allow_failure) parameter should be set to `true`.
### Artifacts
Scanning jobs must declare a report that corresponds to the type of scanning they perform,
using the [`artifacts:reports`](../../ci/yaml/README.md#artifactsreports) keyword.
using the [`artifacts:reports`](../../ci/yaml/index.md#artifactsreports) keyword.
Valid reports are: `dependency_scanning`, `container_scanning`, `dast`, `api_fuzzing`, `coverage_fuzzing`, and `sast`.
For example, here is the definition of a SAST job that generates a file named `gl-sast-report.json`,
......@@ -209,7 +209,7 @@ It is recommended to name the output file after the type of scanning, and to use
Since all Secure reports are JSON files, it is recommended to use `.json` as a file extension.
For instance, a suggested filename for a Dependency Scanning report is `gl-dependency-scanning.json`.
The [`artifacts:reports`](../../ci/yaml/README.md#artifactsreports) keyword
The [`artifacts:reports`](../../ci/yaml/index.md#artifactsreports) keyword
of the job definition must be consistent with the file path where the Security report is written.
For instance, if a Dependency Scanning analyzer writes its report to the CI project directory,
and if this report filename is `depscan.json`,
......
doc/development/integrations/secure_partner_integration.md
View file @ 8c7fae1f
......@@ -83,7 +83,7 @@ and complete an integration with the Secure stage.
1. Ensure your pipeline jobs create a report artifact that GitLab can process
to successfully display your own product's results with the rest of GitLab.
- See detailed [technical directions](secure.md) for this step.
- Read more about [job report artifacts](../../ci/yaml/README.md#artifactsreports).
- Read more about [job report artifacts](../../ci/yaml/index.md#artifactsreports).
- Read about [job artifacts](../../ci/pipelines/job_artifacts.md).
- Your report artifact must be in one of our currently supported formats.
For more information, see the [documentation on reports](secure.md#report).
......
doc/development/pipelines.md
View file @ 8c7fae1f
......@@ -14,12 +14,12 @@ which itself includes files under
for easier maintenance.
We're striving to [dogfood](https://about.gitlab.com/handbook/engineering/#dogfooding)
GitLab [CI/CD features and best-practices](../ci/yaml/README.md)
GitLab [CI/CD features and best-practices](../ci/yaml/index.md)
as much as possible.
## Overview
Pipelines for the GitLab project are created using the [`workflow:rules` keyword](../ci/yaml/README.md#workflow)
Pipelines for the GitLab project are created using the [`workflow:rules` keyword](../ci/yaml/index.md#workflow)
feature of the GitLab CI/CD.
Pipelines are always created for the following scenarios:
......@@ -49,7 +49,7 @@ depending on the changes made in the MR:
- [Frontend-only MR pipeline](#frontend-only-mr-pipeline): This is typically created for an MR that only changes frontend code.
- [QA-only MR pipeline](#qa-only-mr-pipeline): This is typically created for an MR that only changes end to end tests related code.
We use the [`rules:`](../ci/yaml/README.md#rules) and [`needs:`](../ci/yaml/README.md#needs) keywords extensively
We use the [`rules:`](../ci/yaml/index.md#rules) and [`needs:`](../ci/yaml/index.md#needs) keywords extensively
to determine the jobs that need to be run in a pipeline. Note that an MR that includes multiple types of changes would
have a pipelines that include jobs from multiple types (e.g. a combination of docs-only and code-only pipelines).
......@@ -537,7 +537,7 @@ the `gitlab-org/gitlab-foss` project.
### Interruptible pipelines
By default, all jobs are [interruptible](../ci/yaml/README.md#interruptible), except the
By default, all jobs are [interruptible](../ci/yaml/index.md#interruptible), except the
`dont-interrupt-me` job which runs automatically on `main`, and is `manual`
otherwise.
......@@ -717,13 +717,13 @@ each pipeline includes default variables defined in
### Common job definitions
Most of the jobs [extend from a few CI definitions](../ci/yaml/README.md#extends)
Most of the jobs [extend from a few CI definitions](../ci/yaml/index.md#extends)
defined in [`.gitlab/ci/global.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/global.gitlab-ci.yml)
that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-keywords).
that are scoped to a single [configuration keyword](../ci/yaml/index.md#job-keywords).
| Job definitions | Description |
|------------------|-------------|
| `.default-retry` | Allows a job to [retry](../ci/yaml/README.md#retry) upon `unknown_failure`, `api_failure`, `runner_system_failure`, `job_execution_timeout`, or `stuck_or_timeout_failure`. |
| `.default-retry` | Allows a job to [retry](../ci/yaml/index.md#retry) upon `unknown_failure`, `api_failure`, `runner_system_failure`, `job_execution_timeout`, or `stuck_or_timeout_failure`. |
| `.default-before_script` | Allows a job to use a default `before_script` definition suitable for Ruby/Rails tasks that may need a database running (e.g. tests). |
| `.setup-test-env-cache` | Allows a job to use a default `cache` definition suitable for setting up test environment for subsequent Ruby/Rails tasks. |
| `.rails-cache` | Allows a job to use a default `cache` definition suitable for Ruby/Rails tasks. |
......@@ -742,16 +742,16 @@ that are scoped to a single [configuration keyword](../ci/yaml/README.md#job-key
### `rules`, `if:` conditions and `changes:` patterns
We're using the [`rules` keyword](../ci/yaml/README.md#rules) extensively.
We're using the [`rules` keyword](../ci/yaml/index.md#rules) extensively.
All `rules` definitions are defined in
[`rules.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml),
then included in individual jobs via [`extends`](../ci/yaml/README.md#extends).
then included in individual jobs via [`extends`](../ci/yaml/index.md#extends).
The `rules` definitions are composed of `if:` conditions and `changes:` patterns,
which are also defined in
[`rules.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/.gitlab/ci/rules.gitlab-ci.yml)
and included in `rules` definitions via [YAML anchors](../ci/yaml/README.md#anchors)
and included in `rules` definitions via [YAML anchors](../ci/yaml/index.md#anchors)
#### `if:` conditions
......
doc/index.md
View file @ 8c7fae1f
......@@ -40,7 +40,7 @@ Have a look at some of our most popular topics:
|:-------------------------------------------------------------------------------------------|:------------|
| [Two-factor authentication](user/profile/account/two_factor_authentication.md) | Improve the security of your GitLab account. |
| [GitLab groups](user/group/index.md) | Manage projects together. |
| [GitLab CI/CD pipeline configuration reference](ci/yaml/README.md) | Available configuration options for `.gitlab-ci.yml` files. |
| [GitLab CI/CD pipeline configuration reference](ci/yaml/index.md) | Available configuration options for `.gitlab-ci.yml` files. |
| [Activate GitLab EE with a license](user/admin_area/license.md) | Activate GitLab Enterprise Edition functionality with a license. |
| [Back up and restore GitLab](raketasks/backup_restore.md) | Rake tasks for backing up and restoring GitLab self-managed instances. |
| [GitLab release and maintenance policy](policy/maintenance.md) | Policies for version naming and cadence, and also upgrade recommendations. |
......
doc/topics/autodevops/customize.md
View file @ 8c7fae1f
......@@ -187,11 +187,11 @@ to the desired environment. See [Limit environment scope of CI/CD variables](../
Auto DevOps is completely customizable because the
[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
is just an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/README.md) file,
is just an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/index.md) file,
and uses only features available to any implementation of `.gitlab-ci.yml`.
To modify the CI/CD pipeline used by Auto DevOps,
[`include` the template](../../ci/yaml/README.md#includetemplate), and customize
[`include` the template](../../ci/yaml/index.md#includetemplate), and customize
it as needed by adding a `.gitlab-ci.yml` file to the root of your repository
containing the following:
......@@ -202,7 +202,7 @@ include:
Add your changes, and your additions are merged with the
[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
using the behavior described for [`include`](../../ci/yaml/README.md#include).
using the behavior described for [`include`](../../ci/yaml/index.md#include).
If you need to specifically remove a part of the file, you can also copy and paste the contents of the
[Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml)
......@@ -254,13 +254,13 @@ include:
See the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) for information on available jobs.
WARNING:
Auto DevOps templates using the [`only`](../../ci/yaml/README.md#only--except) or
[`except`](../../ci/yaml/README.md#only--except) syntax have switched
to the [`rules`](../../ci/yaml/README.md#rules) syntax, starting in
Auto DevOps templates using the [`only`](../../ci/yaml/index.md#only--except) or
[`except`](../../ci/yaml/index.md#only--except) syntax have switched
to the [`rules`](../../ci/yaml/index.md#rules) syntax, starting in
[GitLab 13.0](https://gitlab.com/gitlab-org/gitlab/-/issues/213336).
If your `.gitlab-ci.yml` extends these Auto DevOps templates and override the `only` or
`except` keywords, you must migrate your templates to use the
[`rules`](../../ci/yaml/README.md#rules) syntax after the
[`rules`](../../ci/yaml/index.md#rules) syntax after the
base template is migrated to use the `rules` syntax.
For users who cannot migrate just yet, you can alternatively pin your templates to
the [GitLab 12.10 based templates](https://gitlab.com/gitlab-org/auto-devops-v12-10).
......
doc/topics/autodevops/index.md
View file @ 8c7fae1f
......@@ -63,7 +63,7 @@ Since [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/-/issues/26655),
Auto DevOps runs on pipelines automatically only if a [`Dockerfile` or matching buildpack](stages.md#auto-build)
exists.
If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the
If a [CI/CD configuration file](../../ci/yaml/index.md) is present in the
project, it isn't changed and won't be affected by Auto DevOps.
### At the project level
......
doc/topics/autodevops/requirements.md
View file @ 8c7fae1f
......@@ -125,7 +125,7 @@ only the deployment to Kubernetes runs.
WARNING:
Setting the `AUTO_DEVOPS_PLATFORM_TARGET` variable to `ECS` triggers jobs
defined in the [`Jobs/Deploy/ECS.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy/ECS.gitlab-ci.yml).
However, it's not recommended to [include](../../ci/yaml/README.md#includetemplate)
However, it's not recommended to [include](../../ci/yaml/index.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. Do not override these jobs' names in your
......
doc/topics/autodevops/upgrading_auto_deploy_dependencies.md
View file @ 8c7fae1f
......@@ -31,11 +31,11 @@ are using. First verify which template is in use:
- [The GitLab.com stable Auto Deploy template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.gitlab-ci.yml)
is being used if **one** of the following is true:
- Your Auto DevOps project doesn't have a `.gitlab-ci.yml` file.
- Your Auto DevOps project has a `.gitlab-ci.yml` and [includes](../../ci/yaml/README.md#includetemplate)
- Your Auto DevOps project has a `.gitlab-ci.yml` and [includes](../../ci/yaml/index.md#includetemplate)
the `Auto-DevOps.gitlab-ci.yml` template.
- [The latest Auto Deploy template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Jobs/Deploy.latest.gitlab-ci.yml)
is being used if **both** of the following is true:
- Your Auto DevOps project has a `.gitlab-ci.yml` file and [includes](../../ci/yaml/README.md#includetemplate)
- Your Auto DevOps project has a `.gitlab-ci.yml` file and [includes](../../ci/yaml/index.md#includetemplate)
the `Auto-DevOps.gitlab-ci.yml` template.
- It also includes [the latest Auto Deploy template](#early-adopters)
......
doc/user/admin_area/settings/continuous_integration.md
View file @ 8c7fae1f
......@@ -88,7 +88,7 @@ The setting at all levels is only available to GitLab administrators.
The default expiration time of the [job artifacts](../../../administration/job_artifacts.md)
can be set in the Admin Area of your GitLab instance. The syntax of duration is
described in [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in)
described in [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in)
and the default value is `30 days`.
1. On the top bar, select **Menu >** **{admin}** **Admin**.
......@@ -97,7 +97,7 @@ and the default value is `30 days`.
1. Click **Save changes** for the changes to take effect.
This setting is set per job and can be overridden in
[`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in).
[`.gitlab-ci.yml`](../../../ci/yaml/index.md#artifactsexpire_in).
To disable the expiration, set it to `0`. The default unit is in seconds.
NOTE:
......@@ -233,13 +233,13 @@ use a template from:
NOTE:
When you use a configuration defined in an instance template repository,
nested [`include:`](../../../ci/yaml/README.md#include) keywords
nested [`include:`](../../../ci/yaml/index.md#include) keywords
(including `include:file`, `include:local`, `include:remote`, and `include:template`)
[do not work](https://gitlab.com/gitlab-org/gitlab/-/issues/35345).
The project CI/CD configuration merges into the required pipeline configuration when
a pipeline runs. The merged configuration is the same as if the required pipeline configuration
added the project configuration with the [`include` keyword](../../../ci/yaml/README.md#include).
added the project configuration with the [`include` keyword](../../../ci/yaml/index.md#include).
To view a project's full merged configuration, [View the merged YAML](../../../ci/pipeline_editor/index.md#view-expanded-configuration)
in the pipeline editor.
......
doc/user/admin_area/settings/index.md
View file @ 8c7fae1f
......@@ -68,7 +68,7 @@ To access the default page for Admin Area settings:
| Option | Description |
| ------ | ----------- |
| [Continuous Integration and Deployment](continuous_integration.md) | Auto DevOps, runners and job artifacts. |
| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM SELF)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/README.md). This pipeline configuration is run after the project's own configuration. |
| [Required pipeline configuration](continuous_integration.md#required-pipeline-configuration) **(PREMIUM SELF)** | Set an instance-wide auto included [pipeline configuration](../../../ci/yaml/index.md). This pipeline configuration is run after the project's own configuration. |
| [Package Registry](continuous_integration.md#package-registry-configuration) | Settings related to the use and experience of using the GitLab Package Registry. Note there are [risks involved](../../packages/container_registry/index.md#use-with-external-container-registries) in enabling some of these settings. |
## Reporting
......
doc/user/analytics/value_stream_analytics.md
View file @ 8c7fae1f
......@@ -112,7 +112,7 @@ environments is configured.
1. Push branch, and create a merge request that contains the [issue closing pattern](../project/issues/managing_issues.md#closing-issues-automatically)
in its description at 14:00 (stop of **Code** stage and start of **Test** and
**Review** stages).
1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/README.md) and
1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../ci/yaml/index.md) and
takes 5 minutes (stop of **Test** stage).
1. Review merge request, ensure that everything is okay, and then merge the merge
request at 19:00 (stop of **Review** stage and start of **Staging** stage).
......
doc/user/application_security/api_fuzzing/index.md
View file @ 8c7fae1f
......@@ -134,7 +134,7 @@ To configure API fuzzing in GitLab with an OpenAPI Specification:
1. Add the `fuzz` stage to your `.gitlab-ci.yml` file.
1. [Include](../../../ci/yaml/README.md#includetemplate)
1. [Include](../../../ci/yaml/index.md#includetemplate)
the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml)
in your `.gitlab-ci.yml` file.
......@@ -200,7 +200,7 @@ To configure API fuzzing to use a HAR file:
1. Add the `fuzz` stage to your `.gitlab-ci.yml` file.
1. [Include](../../../ci/yaml/README.md#includetemplate)
1. [Include](../../../ci/yaml/index.md#includetemplate)
the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml)
in your `.gitlab-ci.yml` file.
......@@ -271,7 +271,7 @@ To configure API fuzzing to use a Postman Collection file:
1. Add the `fuzz` stage to your `.gitlab-ci.yml` file.
1. [Include](../../../ci/yaml/README.md#includetemplate)
1. [Include](../../../ci/yaml/index.md#includetemplate)
the [`API-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/API-Fuzzing.gitlab-ci.yml)
in your `.gitlab-ci.yml` file.
......
doc/user/application_security/container_scanning/index.md
View file @ 8c7fae1f
......@@ -59,7 +59,7 @@ To enable container scanning in your pipeline, you need the following:
How you enable container scanning depends on your GitLab version:
- GitLab 11.9 and later: [Include](../../../ci/yaml/README.md#includetemplate) the
- GitLab 11.9 and later: [Include](../../../ci/yaml/index.md#includetemplate) the
[`Container-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Container-Scanning.gitlab-ci.yml)
that comes with your GitLab installation.
- GitLab versions earlier than 11.9: Copy and use the job from the
......@@ -73,8 +73,8 @@ Other changes:
[`centos:centos8`](https://hub.docker.com/_/centos)
as the new base. It also removes the use of the [start.sh](https://gitlab.com/gitlab-org/security-products/analyzers/klar/-/merge_requests/77)
script and instead executes the analyzer by default. Any customizations made to the
`container_scanning` job's [`before_script`](../../../ci/yaml/README.md#before_script)
and [`after_script`](../../../ci/yaml/README.md#after_script)
`container_scanning` job's [`before_script`](../../../ci/yaml/index.md#before_script)
and [`after_script`](../../../ci/yaml/index.md#after_script)
blocks may not work with the new version. To roll back to the previous [`alpine:3.11.3`](https://hub.docker.com/_/alpine)-based
Docker image, you can specify the major version through the [`CS_MAJOR_VERSION`](#available-cicd-variables)
variable.
......@@ -101,7 +101,7 @@ The included template:
(see [requirements](#requirements)) and scans it for possible vulnerabilities.
GitLab saves the results as a
[Container Scanning report artifact](../../../ci/yaml/README.md#artifactsreportscontainer_scanning)
[Container Scanning report artifact](../../../ci/yaml/index.md#artifactsreportscontainer_scanning)
that you can download and analyze later. When downloading, you always receive the most-recent
artifact.
......@@ -130,12 +130,12 @@ include:
There may be cases where you want to customize how GitLab scans your containers. For example, you
may want to enable more verbose output, access a Docker registry that requires
authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/README.md#variables)
authentication, and more. To change such settings, use the [`variables`](../../../ci/yaml/index.md#variables)
parameter in your `.gitlab-ci.yml` to set [CI/CD variables](#available-cicd-variables).
The variables you set in your `.gitlab-ci.yml` overwrite those in
`Container-Scanning.gitlab-ci.yml`.
This example [includes](../../../ci/yaml/README.md#include) the container scanning template and
This example [includes](../../../ci/yaml/index.md#include) the container scanning template and
enables verbose output for the analyzer:
```yaml
......@@ -190,8 +190,8 @@ container_scanning:
```
WARNING:
GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/README.md#only--except).
When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules)
GitLab 13.0 and later doesn't support [`only` and `except`](../../../ci/yaml/index.md#only--except).
When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules)
instead.
### Change scanners
......
doc/user/application_security/coverage_fuzzing/index.md
View file @ 8c7fae1f
......@@ -38,7 +38,7 @@ Docker image with the fuzz engine to run your app.
## Configuration
To enable fuzzing, you must
[include](../../../ci/yaml/README.md#includetemplate)
[include](../../../ci/yaml/index.md#includetemplate)
the [`Coverage-Fuzzing.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Coverage-Fuzzing.gitlab-ci.yml)
provided as part of your GitLab installation.
......@@ -59,8 +59,8 @@ my_fuzz_target:
- ./gitlab-cov-fuzz run --regression=$REGRESSION -- <your fuzz target>
```
The included template makes available the [hidden job](../../../ci/yaml/README.md#hide-jobs)
`.fuzz_base`, which you must [extend](../../../ci/yaml/README.md#extends) for each of your fuzz
The included template makes available the [hidden job](../../../ci/yaml/index.md#hide-jobs)
`.fuzz_base`, which you must [extend](../../../ci/yaml/index.md#extends) for each of your fuzz
targets. Each fuzz target **must** have a separate job. For example, the
[go-fuzzing-example project](https://gitlab.com/gitlab-org/security-products/demos/go-fuzzing-example)
contains one job that extends `.fuzz_base` for its single fuzz target.
......
doc/user/application_security/dast/index.md
View file @ 8c7fae1f
......@@ -202,7 +202,7 @@ To include the DAST template:
1. Add the template to GitLab, based on your version of GitLab:
- In GitLab 11.9 and later, [include](../../../ci/yaml/README.md#includetemplate)
- In GitLab 11.9 and later, [include](../../../ci/yaml/index.md#includetemplate)
the template by adding the following to your `.gitlab-ci.yml` file:
```yaml
......@@ -218,7 +218,7 @@ To include the DAST template:
1. Define the URL to be scanned by DAST by using one of these methods:
- Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/README.md#variables).
- Set the `DAST_WEBSITE` [CI/CD variable](../../../ci/yaml/index.md#variables).
If set, this value takes precedence.
- Add the URL in an `environment_url.txt` file at the root of your project. This is
......@@ -247,7 +247,7 @@ The included template creates a `dast` job in your CI/CD pipeline and scans
your project's running application for possible vulnerabilities.
The results are saved as a
[DAST report artifact](../../../ci/yaml/README.md#artifactsreportsdast)
[DAST report artifact](../../../ci/yaml/index.md#artifactsreportsdast)
that you can later download and analyze. Due to implementation limitations, we
always take the latest DAST artifact available. Behind the scenes, the
[GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast)
......@@ -487,11 +487,11 @@ To view details of vulnerabilities detected by DAST:
### Customizing the DAST settings
WARNING:
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
The DAST settings can be changed through CI/CD variables by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
These variables are documented in [available variables](#available-cicd-variables).
For example:
......@@ -505,7 +505,7 @@ variables:
DAST_SPIDER_MINS: 120
```
Because the template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
Because the template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline
configuration, the last mention of the variable takes precedence.
#### Enabling and disabling rules
......
doc/user/application_security/dast_api/index.md
View file @ 8c7fae1f
......@@ -85,7 +85,7 @@ the body generation is limited to these body types:
Follow these steps to configure DAST API in GitLab with an OpenAPI specification:
1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate)
1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate)
the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml)
that's provided as part of your GitLab installation. Add the following to your
`.gitlab-ci.yml` file:
......@@ -184,7 +184,7 @@ cookies. We recommend that you review the HAR file contents before adding them t
Follow these steps to configure DAST API to use a HAR file that provides information about the
target API to test:
1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate)
1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate)
the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml)
that's provided as part of your GitLab installation. To do so, add the following to your
`.gitlab-ci.yml` file:
......@@ -284,7 +284,7 @@ them to a repository.
Follow these steps to configure DAST API to use a Postman Collection file that provides
information about the target API to test:
1. To use DAST API, you must [include](../../../ci/yaml/README.md#includetemplate)
1. To use DAST API, you must [include](../../../ci/yaml/index.md#includetemplate)
the [`DAST-API.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/DAST-API.gitlab-ci.yml)
that's provided as part of your GitLab installation. To do so, add the following to your
`.gitlab-ci.yml` file:
......
doc/user/application_security/dependency_scanning/index.md
View file @ 8c7fae1f
......@@ -55,7 +55,7 @@ is **not** `19.03.0`. See [troubleshooting information](#error-response-from-dae
## Supported languages and package managers
GitLab relies on [`rules`](../../../ci/yaml/README.md#rules) to start relevant analyzers depending on the languages detected in the repository.
GitLab relies on [`rules`](../../../ci/yaml/index.md#rules) to start relevant analyzers depending on the languages detected in the repository.
The current detection logic limits the maximum search depth to two levels. For example, the `gemnasium-dependency_scanning` job is enabled if a repository contains either a `Gemfile` or `api/Gemfile` file, but not if the only supported dependency file is `api/client/Gemfile`.
The following languages and dependency managers are supported:
......@@ -90,7 +90,7 @@ The [Security Scanner Integration](../../../development/integrations/secure.md)
## Configuration
To enable dependency scanning for GitLab 11.9 and later, you must
[include](../../../ci/yaml/README.md#includetemplate) the
[include](../../../ci/yaml/index.md#includetemplate) the
[`Dependency-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
that is provided as a part of your GitLab installation.
For GitLab versions earlier than 11.9, you can copy and use the job as defined
......@@ -106,14 +106,14 @@ include:
The included template creates dependency scanning jobs in your CI/CD
pipeline and scans your project's source code for possible vulnerabilities.
The results are saved as a
[dependency scanning report artifact](../../../ci/yaml/README.md#artifactsreportsdependency_scanning)
[dependency scanning report artifact](../../../ci/yaml/index.md#artifactsreportsdependency_scanning)
that you can later download and analyze. Due to implementation limitations, we
always take the latest dependency scanning artifact available.
### Customizing the dependency scanning settings
The dependency scanning settings can be changed through [CI/CD variables](#available-cicd-variables) by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
For example:
```yaml
......@@ -124,14 +124,14 @@ variables:
SECURE_LOG_LEVEL: error
```
Because template is [evaluated before](../../../ci/yaml/README.md#include) the pipeline
Because template is [evaluated before](../../../ci/yaml/index.md#include) the pipeline
configuration, the last mention of the variable takes precedence.
### Overriding dependency scanning jobs
WARNING:
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
To override a job definition (for example, to change properties like `variables` or `dependencies`),
declare a new job with the same name as the one to override. Place this new job after the template
......@@ -596,7 +596,7 @@ Generally, the approach is the following:
1. Define a dedicated converter job in your `.gitlab-ci.yml` file.
Use a suitable Docker image, script, or both to facilitate the conversion.
1. Let that job upload the converted, supported file as an artifact.
1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/README.md#dependencies)
1. Add [`dependencies: [<your-converter-job>]`](../../../ci/yaml/index.md#dependencies)
to your `dependency_scanning` job to make use of the converted definitions files.
For example, the currently unsupported `poetry.lock` file can be
......@@ -643,7 +643,7 @@ For information on this, see the [general Application Security troubleshooting s
### Limitation when using rules:exists
The [dependency scanning CI template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/Dependency-Scanning.gitlab-ci.yml)
uses the [`rules:exists`](../../../ci/yaml/README.md#rulesexists)
uses the [`rules:exists`](../../../ci/yaml/index.md#rulesexists)
syntax. This directive is limited to 10000 checks and always returns `true` after reaching this
number. Because of this, and depending on the number of files in your repository, a dependency
scanning job might be triggered even if the scanner doesn't support your project.
......
doc/user/application_security/index.md
View file @ 8c7fae1f
......@@ -129,7 +129,7 @@ All jobs are permitted to fail by default. This means that if they fail it do no
If you want to prevent vulnerabilities from being merged, you should do this by adding [Security Approvals in Merge Requests](#security-approvals-in-merge-requests) which prevents unknown, high or critical findings from being merged without an approval from a specific group of people that you choose.
We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/README.md#allow_failure) as that fails the entire pipeline.
We do not recommend changing the job [`allow_failure` setting](../../ci/yaml/index.md#allow_failure) as that fails the entire pipeline.
### JSON Artifact
......@@ -357,7 +357,7 @@ You can do it quickly by following the hyperlink given to run a new pipeline.
### Getting error message `sast job: stage parameter should be [some stage name here]`
When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template
When [including](../../ci/yaml/index.md#includetemplate) a `.gitlab-ci.yml` template
like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml),
the following error may occur, depending on your GitLab CI/CD configuration:
......@@ -410,7 +410,7 @@ This provides useful information to investigate further.
### Getting error message `sast job: config key may not be used with 'rules': only/except`
When [including](../../ci/yaml/README.md#includetemplate) a `.gitlab-ci.yml` template
When [including](../../ci/yaml/index.md#includetemplate) a `.gitlab-ci.yml` template
like [`SAST.gitlab-ci.yml`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml),
the following error may occur, depending on your GitLab CI/CD configuration:
......@@ -421,7 +421,7 @@ Found errors in your .gitlab-ci.yml:
```
This error appears when the included job's `rules` configuration has been [overridden](sast/index.md#overriding-sast-jobs)
with [the deprecated `only` or `except` syntax.](../../ci/yaml/README.md#only--except)
with [the deprecated `only` or `except` syntax.](../../ci/yaml/index.md#only--except)
To fix this issue, you must either:
- [Transition your `only/except` syntax to `rules`](#transitioning-your-onlyexcept-syntax-to-rules).
......@@ -432,8 +432,8 @@ To fix this issue, you must either:
#### Transitioning your `only/except` syntax to `rules`
When overriding the template to control job execution, previous instances of
[`only` or `except`](../../ci/yaml/README.md#only--except) are no longer compatible
and must be transitioned to [the `rules` syntax](../../ci/yaml/README.md#rules).
[`only` or `except`](../../ci/yaml/index.md#only--except) are no longer compatible
and must be transitioned to [the `rules` syntax](../../ci/yaml/index.md#rules).
If your override is aimed at limiting jobs to only run on `master`, the previous syntax
would look similar to:
......@@ -489,11 +489,11 @@ spotbugs-sast:
- if: $CI_COMMIT_TAG == null
```
[Learn more on the usage of `rules`](../../ci/yaml/README.md#rules).
[Learn more on the usage of `rules`](../../ci/yaml/index.md#rules).
#### Pin your templates to the deprecated versions
To ensure the latest support, we **strongly** recommend that you migrate to [`rules`](../../ci/yaml/README.md#rules).
To ensure the latest support, we **strongly** recommend that you migrate to [`rules`](../../ci/yaml/index.md#rules).
If you're unable to immediately update your CI configuration, there are several workarounds that
involve pinning to the previous template versions, for example:
......
doc/user/application_security/offline_deployments/index.md
View file @ 8c7fae1f
......@@ -108,7 +108,7 @@ example of such a transfer:
### Using the official GitLab template
GitLab provides a [vendored template](../../../ci/yaml/README.md#includetemplate)
GitLab provides a [vendored template](../../../ci/yaml/index.md#includetemplate)
to ease this process.
This template should be used in a new, empty project, with a `gitlab-ci.yml` file containing:
......
doc/user/application_security/sast/index.md
View file @ 8c7fae1f
......@@ -162,7 +162,7 @@ To configure SAST for a project you can:
### Configure SAST manually
For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/README.md#includetemplate)
For GitLab 11.9 and later, to enable SAST you must [include](../../../ci/yaml/index.md#includetemplate)
the [`SAST.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/SAST.gitlab-ci.yml)
provided as a part of your GitLab installation. For GitLab versions earlier than 11.9, you
can copy and use the job as defined that template.
......@@ -178,7 +178,7 @@ The included template creates SAST jobs in your CI/CD pipeline and scans
your project's source code for possible vulnerabilities.
The results are saved as a
[SAST report artifact](../../../ci/yaml/README.md#artifactsreportssast)
[SAST report artifact](../../../ci/yaml/index.md#artifactsreportssast)
that you can later download and analyze. Due to implementation limitations, we
always take the latest SAST artifact available.
......@@ -206,7 +206,7 @@ page:
The SAST settings can be changed through [CI/CD variables](#available-cicd-variables)
by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
In the following example, we include the SAST template and at the same time we
set the `SAST_GOSEC_LEVEL` variable to `2`:
......@@ -218,14 +218,14 @@ variables:
SAST_GOSEC_LEVEL: 2
```
Because the template is [evaluated before](../../../ci/yaml/README.md#include)
Because the template is [evaluated before](../../../ci/yaml/index.md#include)
the pipeline configuration, the last mention of the variable takes precedence.
### Overriding SAST jobs
WARNING:
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
To override a job definition, (for example, change properties like `variables` or `dependencies`),
declare a job with the same name as the SAST job to override. Place this new job after the template
......@@ -556,7 +556,7 @@ The SAST tool emits a JSON report file. For more information, see the
[schema for this report](https://gitlab.com/gitlab-org/security-products/security-report-schemas/-/blob/master/dist/sast-report-format.json).
The JSON report file can be downloaded from the CI pipelines page, or the
pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/README.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
pipelines tab on merge requests by [setting `artifacts: paths`](../../../ci/yaml/index.md#artifactspaths) to `gl-sast-report.json`. For more information see [Downloading artifacts](../../../ci/pipelines/job_artifacts.md).
Here's an example SAST report:
......@@ -765,7 +765,7 @@ uses the `rules:exists` parameter. For performance reasons, a maximum number of
against the given glob pattern. If the number of matches exceeds the maximum, the `rules:exists`
parameter returns `true`. Depending on the number of files in your repository, a SAST job might be
triggered even if the scanner doesn't support your project. For more details about this issue, see
the [`rules:exists` documentation](../../../ci/yaml/README.md#rulesexists).
the [`rules:exists` documentation](../../../ci/yaml/index.md#rulesexists).
### SpotBugs UTF-8 unmappable character errors
......@@ -791,7 +791,7 @@ For Maven builds, add the following to your `pom.xml` file:
### Flawfinder encoding error
This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/README.md#before_script) feature.
This occurs when Flawfinder encounters an invalid UTF-8 character. To fix this, convert all source code in your project to UTF-8 character encoding. This can be done with [`cvt2utf`](https://github.com/x1angli/cvt2utf) or [`iconv`](https://www.gnu.org/software/libiconv/documentation/libiconv-1.13/iconv.1.html) either over the entire project or per job using the [`before_script`](../../../ci/yaml/index.md#before_script) feature.
### Semgrep slowness, unexpected results, or other errors
......
doc/user/application_security/secret_detection/index.md
View file @ 8c7fae1f
......@@ -133,7 +133,7 @@ The included template creates Secret Detection jobs in your CI/CD pipeline and s
your project's source code for secrets.
The results are saved as a
[Secret Detection report artifact](../../../ci/yaml/README.md#artifactsreportssecret_detection)
[Secret Detection report artifact](../../../ci/yaml/index.md#artifactsreportssecret_detection)
that you can later download and analyze. Due to implementation limitations, we
always take the latest Secret Detection artifact available.
......@@ -166,15 +166,15 @@ that you can review and merge to complete the configuration.
The Secret Detection scan settings can be changed through [CI/CD variables](#available-cicd-variables)
by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
To override a job definition, (for example, change properties like `variables` or `dependencies`),
declare a job with the same name as the SAST job to override. Place this new job after the template
inclusion and specify any additional keys under it.
WARNING:
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
#### GIT_DEPTH
......@@ -197,7 +197,7 @@ secret_detection:
SECRET_DETECTION_HISTORIC_SCAN: "true"
```
Because the template is [evaluated before](../../../ci/yaml/README.md#include)
Because the template is [evaluated before](../../../ci/yaml/index.md#include)
the pipeline configuration, the last mention of the variable takes precedence.
#### Available CI/CD variables
......
doc/user/application_security/security_dashboard/index.md
View file @ 8c7fae1f
......@@ -39,7 +39,7 @@ The security dashboard and vulnerability report displays information about vulne
1. At least one project inside a group must be configured with at least one of
the [supported reports](#supported-reports).
1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/README.md#artifactsreports).
1. The configured jobs must use the [new `reports` syntax](../../../ci/yaml/index.md#artifactsreports).
1. [GitLab Runner](https://docs.gitlab.com/runner/) 11.5 or newer must be used.
If you're using the shared runners on GitLab.com, this is already the case.
......
doc/user/clusters/management_project.md
View file @ 8c7fae1f
......@@ -58,7 +58,7 @@ To select a cluster management project to use:
### Configuring your pipeline
After designating a project as the management project for the cluster,
write a [`.gitlab-ci.yml`](../../ci/yaml/README.md) in that project. For example:
write a [`.gitlab-ci.yml`](../../ci/yaml/index.md) in that project. For example:
```yaml
configure cluster:
......@@ -87,7 +87,7 @@ to a management project:
| Production | `production` |
The following environments set in
[`.gitlab-ci.yml`](../../ci/yaml/README.md) deploy to the
[`.gitlab-ci.yml`](../../ci/yaml/index.md) deploy to the
Development, Staging, and Production cluster respectively.
```yaml
......
doc/user/compliance/license_compliance/index.md
View file @ 8c7fae1f
......@@ -90,11 +90,11 @@ To run a License Compliance scanning job, you need GitLab Runner with the
## Configuration
For GitLab 12.8 and later, to enable License Compliance, you must
[include](../../../ci/yaml/README.md#includetemplate) the
[include](../../../ci/yaml/index.md#includetemplate) the
[`License-Scanning.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Security/License-Scanning.gitlab-ci.yml)
that's provided as a part of your GitLab installation.
For older versions of GitLab from 11.9 to 12.7, you must
[include](../../../ci/yaml/README.md#includetemplate) the
[include](../../../ci/yaml/index.md#includetemplate) the
[`License-Management.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/d2cc841c55d65bc8134bfb3a467e66c36ac32b0a/lib/gitlab/ci/templates/Security/License-Management.gitlab-ci.yml).
For GitLab versions earlier than 11.9, you can copy and use the job as defined
that template.
......@@ -115,14 +115,14 @@ the `license_management` job, so you must migrate to the `license_scanning` job
`License-Scanning.gitlab-ci.yml` template.
The results are saved as a
[License Compliance report artifact](../../../ci/yaml/README.md#artifactsreportslicense_scanning)
[License Compliance report artifact](../../../ci/yaml/index.md#artifactsreportslicense_scanning)
that you can later download and analyze. Due to implementation limitations, we
always take the latest License Compliance artifact available. Behind the scenes, the
[GitLab License Compliance Docker image](https://gitlab.com/gitlab-org/security-products/analyzers/license-finder)
is used to detect the languages/frameworks and in turn analyzes the licenses.
The License Compliance settings can be changed through [CI/CD variables](#available-cicd-variables) by using the
[`variables`](../../../ci/yaml/README.md#variables) parameter in `.gitlab-ci.yml`.
[`variables`](../../../ci/yaml/index.md#variables) parameter in `.gitlab-ci.yml`.
### When License Compliance runs
......@@ -180,8 +180,8 @@ directory of your project.
### Overriding the template
WARNING:
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/README.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/README.md#rules) instead.
Beginning in GitLab 13.0, the use of [`only` and `except`](../../../ci/yaml/index.md#only--except)
is no longer supported. When overriding the template, you must use [`rules`](../../../ci/yaml/index.md#rules) instead.
If you want to override the job definition (for example, change properties like
`variables` or `dependencies`), you need to declare a `license_scanning` job
......@@ -441,7 +441,7 @@ documentation for a list of settings that you can apply.
The `license_scanning` job runs in a [Debian 10](https://www.debian.org/releases/buster/) Docker
image. The supplied image ships with some build tools such as [CMake](https://cmake.org/) and [GCC](https://gcc.gnu.org/).
However, not all project types are supported by default. To install additional tools needed to
compile dependencies, use a [`before_script`](../../../ci/yaml/README.md#before_script)
compile dependencies, use a [`before_script`](../../../ci/yaml/index.md#before_script)
to install the necessary build tools using the [`apt`](https://wiki.debian.org/PackageManagementTools)
package manager. For a comprehensive list, consult [the Conan documentation](https://docs.conan.io/en/latest/introduction.html#all-platforms-all-build-systems-and-compilers).
......
doc/user/gitlab_com/index.md
View file @ 8c7fae1f
......@@ -111,7 +111,7 @@ the related documentation.
| Setting | GitLab.com | Default |
|-------------------------------------|------------|---------|
| Artifacts maximum size (compressed) | 1 GB | 100 MB |
| Artifacts [expiry time](../../ci/yaml/README.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified |
| Artifacts [expiry time](../../ci/yaml/index.md#artifactsexpire_in) | From June 22, 2020, deleted after 30 days unless otherwise specified (artifacts created before that date have no expiry). | deleted after 30 days unless otherwise specified |
| Scheduled Pipeline Cron | `*/5 * * * *` | `3-59/10 * * * *` |
| [Max jobs in active pipelines](../../administration/instance_limits.md#number-of-jobs-in-active-pipelines) | `500` for Free tier, unlimited otherwise | Unlimited |
| [Max CI/CD subscriptions to a project](../../administration/instance_limits.md#number-of-cicd-subscriptions-to-a-project) | `2` | Unlimited |
......
doc/user/group/clusters/index.md
View file @ 8c7fae1f
......@@ -122,7 +122,7 @@ For example, if your project has the following Kubernetes clusters:
| Test | `test` | Group |
| Development| `*` | Group |
And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/README.md):
And the following environments are set in [`.gitlab-ci.yml`](../../../ci/yaml/index.md):
```yaml
stages:
......
doc/user/group/value_stream_analytics/index.md
View file @ 8c7fae1f
......@@ -133,7 +133,7 @@ Value Stream Analytics dashboard does not present any data for:
## How the production environment is identified
Value Stream Analytics identifies production environments by looking for project
[environments](../../../ci/yaml/README.md#environment) with a name matching any of these patterns:
[environments](../../../ci/yaml/index.md#environment) with a name matching any of these patterns:
- `prod` or `prod/*`
- `production` or `production/*`
......@@ -162,7 +162,7 @@ environments is configured.
1. Push branch and create a merge request that contains the [issue closing pattern](../../project/issues/managing_issues.md#closing-issues-automatically)
in its description at 14:00 (stop of **Code** stage / start of **Test** and
**Review** stages).
1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/README.md) and
1. The CI starts running your scripts defined in [`.gitlab-ci.yml`](../../../ci/yaml/index.md) and
takes 5min (stop of **Test** stage).
1. Review merge request, ensure that everything is OK and merge the merge
request at 19:00. (stop of **Review** stage / start of **Staging** stage).
......
doc/user/infrastructure/mr_integration.md
View file @ 8c7fae1f
......@@ -10,7 +10,7 @@ Collaborating around Infrastructure as Code (IaC) changes requires both code cha
## Output Terraform Plan information into a merge request
Using the [GitLab Terraform Report artifact](../../ci/yaml/README.md#artifactsreportsterraform),
Using the [GitLab Terraform Report artifact](../../ci/yaml/index.md#artifactsreportsterraform),
you can expose details from `terraform plan` runs directly into a merge request widget,
enabling you to see statistics about the resources that Terraform creates,
modifies, or destroys.
......@@ -57,7 +57,7 @@ To manually configure a GitLab Terraform Report artifact requires the following
1. Define a `script` that runs `terraform plan` and `terraform show`. These commands
pipe the output and convert the relevant bits into a store variable `PLAN_JSON`.
This JSON is used to create a
[GitLab Terraform Report artifact](../../ci/yaml/README.md#artifactsreportsterraform).
[GitLab Terraform Report artifact](../../ci/yaml/index.md#artifactsreportsterraform).
The Terraform report obtains a Terraform `tfplan.json` file. The collected
Terraform plan report is uploaded to GitLab as an artifact, and is shown in merge requests.
......
doc/user/packages/container_registry/index.md
View file @ 8c7fae1f
......@@ -135,7 +135,7 @@ To view these commands, go to your project's **Packages & Registries > Container
## Build and push by using GitLab CI/CD
Use [GitLab CI/CD](../../../ci/yaml/README.md) to build and push images to the
Use [GitLab CI/CD](../../../ci/yaml/index.md) to build and push images to the
Container Registry. Use it to test, build, and deploy your project from the Docker
image you created.
......@@ -309,7 +309,7 @@ in addition to the steps in the
[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section:
1. Update the `image` and `service` to point to your registry.
1. Add a service [alias](../../../ci/yaml/README.md#servicesalias).
1. Add a service [alias](../../../ci/yaml/index.md#servicesalias).
Below is an example of what your `.gitlab-ci.yml` should look like:
......@@ -339,7 +339,7 @@ in addition to the steps in the
[Docker-in-Docker](../../../ci/docker/using_docker_build.md#use-the-docker-executor-with-the-docker-image-docker-in-docker) section:
1. Update the `image` and `service` to point to your registry.
1. Add a service [alias](../../../ci/yaml/README.md#servicesalias).
1. Add a service [alias](../../../ci/yaml/index.md#servicesalias).
Below is an example of what your `.gitlab-ci.yml` should look like:
......
doc/user/packages/dependency_proxy/index.md
View file @ 8c7fae1f
......@@ -134,13 +134,13 @@ To store a Docker image in Dependency Proxy storage:
1. Use one of these commands. In these examples, the image is `alpine:latest`.
1. You can also pull images by digest to specify exactly which version of an image to pull.
- Pull an image by tag by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image) file:
- Pull an image by tag by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/index.md#image) file:
```shell
image: gitlab.example.com/groupname/dependency_proxy/containers/alpine:latest
```
- Pull an image by digest by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/README.md#image) file:
- Pull an image by digest by adding the image to your [`.gitlab-ci.yml`](../../../ci/yaml/index.md#image) file:
```shell
image: ${CI_DEPENDENCY_PROXY_GROUP_IMAGE_PREFIX}/alpine@sha256:c9375e662992791e3f39e919b26f510e5254b42792519c180aad254e6b38f4dc
......
doc/user/project/clusters/multiple_kubernetes_clusters.md
View file @ 8c7fae1f
......@@ -35,7 +35,7 @@ For example, let's say the following Kubernetes clusters exist in a project:
| Production | `production` |
And the following environments are set in
[`.gitlab-ci.yml`](../../../ci/yaml/README.md):
[`.gitlab-ci.yml`](../../../ci/yaml/index.md):
```yaml
stages:
......
doc/user/project/clusters/serverless/aws.md
View file @ 8c7fae1f
......@@ -381,7 +381,7 @@ control to AWS Lambda, API Gateway, CloudFormation, and IAM resources.
### Crafting the `.gitlab-ci.yml` file
In a [`.gitlab-ci.yml`](../../../../ci/yaml/README.md) file in the root of your project,
In a [`.gitlab-ci.yml`](../../../../ci/yaml/index.md) file in the root of your project,
add the following and replace `<S3_bucket_name>` with the name of the S3 bucket where you
want to store your package:
......
doc/user/project/deploy_boards.md
View file @ 8c7fae1f
......@@ -59,7 +59,7 @@ specific environment, there are a lot of use cases. To name a few:
- You want to promote what's running in staging, to production. You go to the
environments list, verify that what's running in staging is what you think is
running, then click on the [manual action](../../ci/yaml/README.md#whenmanual) to deploy to production.
running, then click on the [manual action](../../ci/yaml/index.md#whenmanual) to deploy to production.
- You trigger a deploy, and you have many containers to upgrade so you know
this takes a while (you've also throttled your deploy to only take down X
containers at a time). But you need to tell someone when it's deployed, so you
......
doc/user/project/integrations/mattermost_slash_commands.md
View file @ 8c7fae1f
......@@ -141,7 +141,7 @@ The available slash commands for Mattermost are:
| ------- | ----------- | ------- |
| <kbd>/&lt;trigger&gt; issue new &lt;title&gt; <kbd>⇧ Shift</kbd>+<kbd>↵ Enter</kbd> &lt;description&gt;</kbd> | Create a new issue in the project that `<trigger>` is tied to. `<description>` is optional. | `/gitlab issue new We need to change the homepage` |
| <kbd>/&lt;trigger&gt; issue show &lt;issue-number&gt;</kbd> | Show the issue with ID `<issue-number>` from the project that `<trigger>` is tied to. | `/gitlab issue show 42` |
| <kbd>/&lt;trigger&gt; deploy &lt;environment&gt; to &lt;environment&gt;</kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/README.md). | `/gitlab deploy staging to production` |
| <kbd>/&lt;trigger&gt; deploy &lt;environment&gt; to &lt;environment&gt;</kbd> | Start the CI job that deploys from one environment to another, for example `staging` to `production`. CI/CD must be [properly configured](../../../ci/yaml/index.md). | `/gitlab deploy staging to production` |
To see a list of available commands to interact with GitLab, type the
trigger word followed by <kbd>help</kbd>. Example: `/gitlab help`
......
doc/user/project/merge_requests/accessibility_testing.md
View file @ 8c7fae1f
......@@ -37,7 +37,7 @@ This example shows how to run [pa11y](https://pa11y.org/)
on your code with GitLab CI/CD using the [GitLab Accessibility Docker image](https://gitlab.com/gitlab-org/ci-cd/accessibility).
For GitLab 12.9 and later, to define the `a11y` job, you must
[include](../../../ci/yaml/README.md#includetemplate) the
[include](../../../ci/yaml/index.md#includetemplate) the
[`Accessibility.gitlab-ci.yml` template](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/gitlab/ci/templates/Verify/Accessibility.gitlab-ci.yml)
included with your GitLab installation, as shown below.
......
doc/user/project/merge_requests/browser_performance_testing.md
View file @ 8c7fae1f
......@@ -40,7 +40,7 @@ Consider the following workflow:
## How browser performance testing works
First, define a job in your `.gitlab-ci.yml` file that generates the
[Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance).
[Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance).
GitLab then checks this report, compares key performance metrics for each page
between the source and target branches, and shows the information in the merge request.
......@@ -89,7 +89,7 @@ The above example:
GitLab 12.3 or earlier, you must [add the configuration manually](#gitlab-versions-132-and-earlier).
The template uses the [GitLab plugin for sitespeed.io](https://gitlab.com/gitlab-org/gl-performance),
and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/README.md#artifactsreportsbrowser_performance)
and it saves the full HTML sitespeed.io report as a [Browser Performance report artifact](../../../ci/yaml/index.md#artifactsreportsbrowser_performance)
that you can later download and analyze. This implementation always takes the latest
Browser Performance artifact available. If [GitLab Pages](../pages/index.md) is enabled,
you can view the report directly in your browser.
......
doc/user/project/merge_requests/code_quality.md
View file @ 8c7fae1f
......@@ -111,7 +111,7 @@ include:
The above example creates a `code_quality` job in your CI/CD pipeline which
scans your source code for code quality issues. The report is saved as a
[Code Quality report artifact](../../../ci/yaml/README.md#artifactsreportscodequality)
[Code Quality report artifact](../../../ci/yaml/index.md#artifactsreportscodequality)
that you can later download and analyze.
It's also possible to override the URL to the Code Quality image by
......@@ -282,7 +282,7 @@ run on [pipelines for merge requests](../../../ci/merge_request_pipelines/index.
If pipelines for merge requests is enabled, the `code_quality:rules` must be redefined.
The template has these [`rules`](../../../ci/yaml/README.md#rules) for the `code quality` job:
The template has these [`rules`](../../../ci/yaml/index.md#rules) for the `code quality` job:
```yaml
code_quality:
......@@ -292,7 +292,7 @@ code_quality:
- if: '$CI_COMMIT_TAG || $CI_COMMIT_BRANCH'
```
If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/README.md#workflow))
If you are using merge request pipelines, your `rules` (or [`workflow: rules`](../../../ci/yaml/index.md#workflow))
might look like this example:
```yaml
......@@ -334,7 +334,7 @@ do this:
1. Define a job in your `.gitlab-ci.yml` file that generates the
[Code Quality report
artifact](../../../ci/yaml/README.md#artifactsreportscodequality).
artifact](../../../ci/yaml/index.md#artifactsreportscodequality).
1. Configure your tool to generate the Code Quality report artifact as a JSON
file that implements a subset of the [Code Climate
spec](https://github.com/codeclimate/platform/blob/master/spec/analyzers/SPEC.md#data-types).
......@@ -535,7 +535,7 @@ This can be due to multiple reasons:
- Your pipeline is not set to run the code quality job on your target branch. If there is no report generated from the target branch, your MR branch reports have nothing to compare to.
- If no [degradation or error is detected](https://docs.codeclimate.com/docs/maintainability#section-checks),
nothing is displayed.
- The [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) CI/CD
- The [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in) CI/CD
setting can cause the Code Quality artifact(s) to expire faster than desired.
- The widgets use the pipeline of the latest commit to the target branch. If commits are made to the default branch that do not run the code quality job, this may cause the merge request widget to have no base report for comparison.
- If you use the [`REPORT_STDOUT` environment variable](https://gitlab.com/gitlab-org/ci-cd/codequality#environment-variables), no report file is generated and nothing displays in the merge request.
......
doc/user/project/merge_requests/fail_fast_testing.md
View file @ 8c7fae1f
......@@ -19,7 +19,7 @@ that it believes to be relevant to the input files.
`tff` is designed for Ruby on Rails projects, so the `Verify/FailFast` template is
configured to run when changes to Ruby files are detected. By default, it runs in
the [`.pre` stage](../../../ci/yaml/README.md#pre-and-post) of a GitLab CI/CD pipeline,
the [`.pre` stage](../../../ci/yaml/index.md#pre-and-post) of a GitLab CI/CD pipeline,
before all other stages.
## Example use case
......@@ -62,7 +62,7 @@ rspec-complete:
- bundle exec rspec
```
To run the most relevant specs first instead of the whole suite, [`include`](../../../ci/yaml/README.md#include)
To run the most relevant specs first instead of the whole suite, [`include`](../../../ci/yaml/index.md#include)
the template by adding the following to your CI/CD configuration:
```yaml
......
doc/user/project/merge_requests/index.md
View file @ 8c7fae1f
......@@ -119,7 +119,7 @@ For a software developer working in a team:
1. Pushes a commit with their final review.
1. [Approves the merge request](approvals/index.md).
1. Sets it to [merge when pipeline succeeds](merge_when_pipeline_succeeds.md).
1. Your changes get deployed to production with [manual actions](../../../ci/yaml/README.md#whenmanual) for GitLab CI/CD.
1. Your changes get deployed to production with [manual actions](../../../ci/yaml/index.md#whenmanual) for GitLab CI/CD.
1. Your implementations were successfully shipped to your customer.
For a web developer writing a webpage for your company's website:
......
doc/user/project/merge_requests/load_performance_testing.md
View file @ 8c7fae1f
......@@ -28,7 +28,7 @@ GET calls to a popular API endpoint in your application to see how it performs.
## How Load Performance Testing works
First, define a job in your `.gitlab-ci.yml` file that generates the
[Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance).
[Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance).
GitLab checks this report, compares key load performance metrics
between the source and target branches, and then shows the information in a merge request widget:
......@@ -140,7 +140,7 @@ For example, you can override the duration of the test with a CLI option:
GitLab only displays the key performance metrics in the MR widget if k6's results are saved
via [summary export](https://k6.io/docs/results-visualization/json#summary-export)
as a [Load Performance report artifact](../../../ci/yaml/README.md#artifactsreportsload_performance).
as a [Load Performance report artifact](../../../ci/yaml/index.md#artifactsreportsload_performance).
The latest Load Performance artifact available is always used, using the
summary values from the test.
......
doc/user/project/merge_requests/merge_when_pipeline_succeeds.md
View file @ 8c7fae1f
......@@ -67,8 +67,8 @@ You should be careful to configure CI/CD so that pipelines run for every merge r
### Limitations
When this setting is enabled, a merge request is prevented from being merged if there
is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/README.md#only--except)
or [`rules`](../../../ci/yaml/README.md#rules) are used and they don't generate any pipelines.
is no pipeline. This may conflict with some use cases where [`only/except`](../../../ci/yaml/index.md#only--except)
or [`rules`](../../../ci/yaml/index.md#rules) are used and they don't generate any pipelines.
You should ensure that [there is always a pipeline](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/54226)
and that it's successful.
......@@ -101,7 +101,7 @@ for details on avoiding two pipelines for a single merge request.
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/211482) in GitLab 13.1.
When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/README.md#skip-pipeline) prevent
When the **Pipelines must succeed** checkbox is checked, [skipped pipelines](../../../ci/yaml/index.md#skip-pipeline) prevent
merge requests from being merged. To change this behavior:
1. Navigate to your project's **Settings > General** page.
......
doc/user/project/merge_requests/test_coverage_visualization.md
View file @ 8c7fae1f
......@@ -21,14 +21,14 @@ MR is merged.
## How test coverage visualization works
Collecting the coverage information is done via GitLab CI/CD's
[artifacts reports feature](../../../ci/yaml/README.md#artifactsreports).
[artifacts reports feature](../../../ci/yaml/index.md#artifactsreports).
You can specify one or more coverage reports to collect, including wildcard paths.
GitLab then takes the coverage information in all the files and combines it
together.
For the coverage analysis to work, you have to provide a properly formatted
[Cobertura XML](https://cobertura.github.io/cobertura/) report to
[`artifacts:reports:cobertura`](../../../ci/yaml/README.md#artifactsreportscobertura).
[`artifacts:reports:cobertura`](../../../ci/yaml/index.md#artifactsreportscobertura).
This format was originally developed for Java, but most coverage analysis frameworks
for other languages have plugins to add support for it, like:
......@@ -129,7 +129,7 @@ The `source` is ignored if the path does not follow this pattern. The parser ass
### JavaScript example
The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example uses [Mocha](https://mochajs.org/)
The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example uses [Mocha](https://mochajs.org/)
JavaScript testing and [nyc](https://github.com/istanbuljs/nyc) coverage-tooling to
generate the coverage artifact:
......@@ -147,7 +147,7 @@ test:
#### Maven example
The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/)
The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Maven](https://maven.apache.org/)
to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to
generate the coverage artifact.
You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image.
......@@ -185,7 +185,7 @@ coverage-jdk11:
#### Gradle example
The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Java or Kotlin uses [Gradle](https://gradle.org/)
The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Java or Kotlin uses [Gradle](https://gradle.org/)
to build the project and [JaCoCo](https://www.eclemma.org/jacoco/) coverage-tooling to
generate the coverage artifact.
You can check the [Docker image configuration and scripts](https://gitlab.com/haynes/jacoco2cobertura) if you want to build your own image.
......@@ -223,7 +223,7 @@ coverage-jdk11:
### Python example
The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths.
The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for Python uses [pytest-cov](https://pytest-cov.readthedocs.io/) to collect test coverage data and [coverage.py](https://coverage.readthedocs.io/) to convert the report to use full relative paths.
The information isn't displayed without the conversion.
This example assumes that the code for your package is in `src/` and your tests are in `tests.py`:
......@@ -243,7 +243,7 @@ run tests:
### C/C++ example
The following [`gitlab-ci.yml`](../../../ci/yaml/README.md) example for C/C++ with
The following [`gitlab-ci.yml`](../../../ci/yaml/index.md) example for C/C++ with
`gcc` or `g++` as the compiler uses [`gcovr`](https://gcovr.com/en/stable/) to generate the coverage
output file in Cobertura XML format.
......
doc/user/project/merge_requests/testing_and_reports_in_merge_requests.md
View file @ 8c7fae1f
......@@ -17,7 +17,7 @@ or link to useful information directly from merge requests:
| [Browser Performance Testing](browser_performance_testing.md) **(PREMIUM)** | Quickly determine the browser performance impact of pending code changes. |
| [Load Performance Testing](load_performance_testing.md) **(PREMIUM)** | Quickly determine the server performance impact of pending code changes. |
| [Code Quality](code_quality.md) | Analyze your source code quality using the [Code Climate](https://codeclimate.com/) analyzer and show the Code Climate report right in the merge request widget area. |
| [Display arbitrary job artifacts](../../../ci/yaml/README.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. |
| [Display arbitrary job artifacts](../../../ci/yaml/index.md#artifactsexpose_as) | Configure CI pipelines with the `artifacts:expose_as` parameter to directly link to selected [artifacts](../../../ci/pipelines/job_artifacts.md) in merge requests. |
| [GitLab CI/CD](../../../ci/index.md) | Build, test, and deploy your code in a per-branch basis with built-in CI/CD. |
| [Unit test reports](../../../ci/unit_test_reports.md) | Configure your CI jobs to use Unit test reports, and let GitLab display a report on the merge request so that it's easier and faster to identify the failure without having to check the entire job log. |
| [License Compliance](../../compliance/license_compliance/index.md) **(ULTIMATE)** | Manage the licenses of your dependencies. |
......
doc/user/project/pages/getting_started/pages_from_scratch.md
View file @ 8c7fae1f
......@@ -158,7 +158,7 @@ When it succeeds, go to **Settings > Pages** to view the URL where your site
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 validate
with [any of the available settings](../../../../ci/yaml/index.md). You can validate
your `.gitlab-ci.yml` file with the [CI Lint](../../../../ci/lint.md) tool that's included with GitLab.
After successful execution of this `pages` job, a special `pages:deploy` job appears in the
......
doc/user/project/pages/introduction.md
View file @ 8c7fae1f
......@@ -22,7 +22,7 @@ In brief, this is what you need to upload your website in GitLab Pages:
1. Domain of the instance: domain name that is used for GitLab Pages
(ask your administrator).
1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/README.md#pages) in the root directory of your repository.
1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`](../../../ci/yaml/index.md#pages) in the root directory of your repository.
1. A directory called `public` in your site's repository containing the content
to be published.
1. GitLab Runner enabled for the project.
......@@ -129,7 +129,7 @@ See this document for a [step-by-step guide](getting_started/pages_from_scratch.
Remember that GitLab Pages are by default branch/tag agnostic and their
deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit
the `pages` job with the [`only` parameter](../../../ci/yaml/README.md#only--except),
the `pages` job with the [`only` parameter](../../../ci/yaml/index.md#only--except),
whenever a new commit is pushed to a branch used specifically for your
pages.
......
doc/user/project/releases/index.md
View file @ 8c7fae1f
......@@ -79,7 +79,7 @@ To create a new release through the GitLab UI:
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/19298) in GitLab 12.7.
You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/README.md#release)
You can [create a release directly from the GitLab CI pipeline](../../../ci/yaml/index.md#release)
by using a `release` node in the job definition.
The release is created only if the job processes without error. If the Rails API returns an error
......@@ -428,14 +428,14 @@ Evidence collection snapshots are visible on the Releases page, along with the t
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/32773) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.
When you create a release, if [job artifacts](../../../ci/yaml/README.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence.
When you create a release, if [job artifacts](../../../ci/yaml/index.md#artifactsreports) are included in the last pipeline that ran, they are automatically included in the release as release evidence.
Although job artifacts normally expire, artifacts included in release evidence do not expire.
To enable job artifact collection you need to specify both:
1. [`artifacts:paths`](../../../ci/yaml/README.md#artifactspaths)
1. [`artifacts:reports`](../../../ci/yaml/README.md#artifactsreports)
1. [`artifacts:paths`](../../../ci/yaml/index.md#artifactspaths)
1. [`artifacts:reports`](../../../ci/yaml/index.md#artifactsreports)
```yaml
ruby:
......@@ -455,7 +455,7 @@ release evidence.
If you [schedule release evidence collection](#schedule-release-evidence-collection),
some artifacts may already be expired by the time of evidence collection. To avoid this you can use
the [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in)
the [`artifacts:expire_in`](../../../ci/yaml/index.md#artifactsexpire_in)
keyword. Learn more in [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/222351).
### Schedule release evidence collection
......
doc/user/project/repository/index.md
View file @ 8c7fae1f
......@@ -41,7 +41,7 @@ to a branch in the repository. When you use the command line, you can commit mul
If the project is configured with [GitLab CI/CD](../../../ci/index.md),
you trigger a pipeline per push, not per commit.
- **Skip pipelines:**
Add the [`ci skip`](../../../ci/yaml/README.md#skip-pipeline) keyword to
Add the [`ci skip`](../../../ci/yaml/index.md#skip-pipeline) keyword to
your commit message to make GitLab CI/CD skip the pipeline.
- **Cross-link issues and merge requests:**
Use [cross-linking](../issues/crosslinking_issues.md#from-commit-messages)
......
doc/user/project/requirements/index.md
View file @ 8c7fae1f
......@@ -122,7 +122,7 @@ You can also sort the requirements list by:
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/2859) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.1.
> - [Added](https://gitlab.com/gitlab-org/gitlab/-/issues/215514) ability to specify individual requirements and their statuses in [GitLab Ultimate](https://about.gitlab.com/pricing/) 13.2.
GitLab supports [requirements test reports](../../../ci/yaml/README.md#artifactsreportsrequirements) now.
GitLab supports [requirements test reports](../../../ci/yaml/index.md#artifactsreportsrequirements) now.
You can add a job to your CI pipeline that, when triggered, marks all existing
requirements as Satisfied (you may manually satisfy a requirement in the edit form [edit a requirement](#edit-a-requirement)).
......
doc/user/project/settings/index.md
View file @ 8c7fae1f
......@@ -165,7 +165,7 @@ cannot change them:
- Includes any jobs that drive the logic of your job.
- Explicitly set the container image file to run the job in. This ensures that your script
steps execute in the correct environment.
- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/README.md#job-keywords).
- Explicitly set any relevant GitLab pre-defined [job keywords](../../../ci/yaml/index.md#job-keywords).
This ensures that your job uses the settings you intend and that they are not overriden by
project-level pipelines.
......
doc/user/project/web_ide/index.md
View file @ 8c7fae1f
......@@ -331,7 +331,7 @@ The [File Sync](#file-syncing-to-web-terminal) feature is supported on Kubernete
In order to enable the Web IDE terminals you need to create the file
`.gitlab/.gitlab-webide.yml` inside the repository's root. This
file is fairly similar to the [CI configuration file](../../../ci/yaml/README.md)
file is fairly similar to the [CI configuration file](../../../ci/yaml/index.md)
syntax but with some restrictions:
- No global blocks (such as `before_script` or `after_script`) can be defined.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7