Skip to content
Snippets Groups Projects
Commit b0be58a1 authored by Brett Walker's avatar Brett Walker Committed by Sean McGivern
Browse files

Resolve "CE documentation is not CommonMark compliant"

parent 2d16f479
No related branches found
No related tags found
1 merge request!10495Merge Requests - Assignee
Hide whitespace changes
Inline Side-by-side
Showing
with 275 additions and 267 deletions
doc/api/jobs.md
+ 4
− 2
View file @ b0be58a1
@@ -319,7 +319,8 @@ Example of response
## Get job artifacts
 
> **Notes**:
- [Introduced][ce-2893] in GitLab 8.5.
>
> - [Introduced][ce-2893] in GitLab 8.5.
 
Get job artifacts of a project.
 
@@ -350,7 +351,8 @@ Response:
## Download the artifacts archive
 
> **Notes**:
- [Introduced][ce-5347] in GitLab 8.10.
>
> - [Introduced][ce-5347] in GitLab 8.10.
 
Download the artifacts archive from the given reference name and job provided the
job finished successfully.
doc/api/services.md
+ 4
− 4
View file @ b0be58a1
@@ -544,10 +544,10 @@ GET /projects/:id/services/jira
 
Set JIRA service for a project.
 
>**Notes:**
- Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and
`project_url` are replaced by `project_key`, `url`. If you are using an
older version, [follow this documentation][old-jira-api].
> **Notes:**
> - Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and
> `project_url` are replaced by `project_key`, `url`. If you are using an
> older version, [follow this documentation][old-jira-api].
 
```
PUT /projects/:id/services/jira
doc/api/v3_to_v4.md
+ 2
− 2
View file @ b0be58a1
@@ -76,8 +76,8 @@ Below are the changes made between V3 and V4.
- Simplify project payload exposed on Environment endpoints [!9675](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9675)
- API uses merge request `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the merge requests, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530)
- API uses issue `IID`s (internal ID, as in the web UI) rather than `ID`s. This affects the issues, award emoji, todos, and time tracking APIs. [!9530](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9530)
- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679] (https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Change initial page from `0` to `1` on `GET /projects/:id/repository/commits` (like on the rest of the API) [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Return correct `Link` header data for `GET /projects/:id/repository/commits` [!9679](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9679)
- Update endpoints for repository files [!9637](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9637)
- Moved `GET /projects/:id/repository/files?file_path=:file_path` to `GET /projects/:id/repository/files/:file_path` (`:file_path` should be URL-encoded)
- `GET /projects/:id/repository/blobs/:sha` now returns JSON attributes for the blob identified by `:sha`, instead of finding the commit identified by `:sha` and returning the raw content of the blob in that commit identified by the required `?filepath=:filepath`
doc/ci/docker/using_docker_build.md
+ 8
− 7
View file @ b0be58a1
@@ -381,17 +381,18 @@ environment = ["DOCKER_DRIVER=overlay2"]
If you're running multiple Runners you will have to modify all configuration files.
 
> **Notes:**
- More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/).
- For more information about using OverlayFS with Docker, you can read
[Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/).
>
> - More information about the Runner configuration is available in the [Runner documentation](https://docs.gitlab.com/runner/configuration/).
> - For more information about using OverlayFS with Docker, you can read
> [Use the OverlayFS storage driver](https://docs.docker.com/engine/userguide/storagedriver/overlayfs-driver/).
 
## Using the GitLab Container Registry
 
> **Notes:**
- This feature requires GitLab 8.8 and GitLab Runner 1.2.
- Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
to pass a [personal access token][pat] instead of your password in order to
login to GitLab's Container Registry.
> - This feature requires GitLab 8.8 and GitLab Runner 1.2.
> - Starting from GitLab 8.12, if you have [2FA] enabled in your account, you need
> to pass a [personal access token][pat] instead of your password in order to
> login to GitLab's Container Registry.
 
Once you've built a Docker image, you can push it up to the built-in
[GitLab Container Registry](../../user/project/container_registry.md). For example,
doc/ci/docker/using_docker_images.md
+ 36
− 35
View file @ b0be58a1
@@ -452,13 +452,14 @@ that runner.
## Define an image from a private Container Registry
 
> **Notes:**
- This feature requires GitLab Runner **1.8** or higher
- For GitLab Runner versions **>= 0.6, <1.8** there was a partial
support for using private registries, which required manual configuration
of credentials on runner's host. We recommend to upgrade your Runner to
at least version **1.8** if you want to use private registries.
- If the repository is private you need to authenticate your GitLab Runner in the
registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg].
>
> - This feature requires GitLab Runner **1.8** or higher
> - For GitLab Runner versions **>= 0.6, <1.8** there was a partial
> support for using private registries, which required manual configuration
> of credentials on runner's host. We recommend to upgrade your Runner to
> at least version **1.8** if you want to use private registries.
> - If the repository is private you need to authenticate your GitLab Runner in the
> registry. Learn more about how [GitLab Runner works in this case][runner-priv-reg].
 
As an example, let's assume that you want to use the `registry.example.com/private/image:latest`
image which is private and requires you to login into a private container registry.
@@ -475,57 +476,57 @@ To configure access for `registry.example.com`, follow these steps:
 
1. Find what the value of `DOCKER_AUTH_CONFIG` should be. There are two ways to
accomplish this:
- **First way -** Do a `docker login` on your local machine:
- **First way -** Do a `docker login` on your local machine:
 
```bash
docker login registry.example.com --username my_username --password my_password
```
```bash
docker login registry.example.com --username my_username --password my_password
```
 
Then copy the content of `~/.docker/config.json`.
- **Second way -** In some setups, it's possible that Docker client will use
Then copy the content of `~/.docker/config.json`.
- **Second way -** In some setups, it's possible that Docker client will use
the available system keystore to store the result of `docker login`. In
that case, it's impossible to read `~/.docker/config.json`, so you will
need to prepare the required base64-encoded version of
`${username}:${password}` manually. Open a terminal and execute the
following command:
 
```bash
echo -n "my_username:my_password" | base64
```bash
echo -n "my_username:my_password" | base64
 
# Example output to copy
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
```
# Example output to copy
bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=
```
 
1. Create a [variable] `DOCKER_AUTH_CONFIG` with the content of the
Docker configuration file as the value:
 
```json
{
"auths": {
"registry.example.com": {
"auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
}
}
}
```
```json
{
"auths": {
"registry.example.com": {
"auth": "bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ="
}
}
}
```
 
1. Optionally,if you followed the first way of finding the `DOCKER_AUTH_CONFIG`
value, do a `docker logout` on your computer if you don't need access to the
registry from it:
 
```bash
docker logout registry.example.com
```
```bash
docker logout registry.example.com
```
 
1. You can now use any private image from `registry.example.com` defined in
`image` and/or `services` in your `.gitlab-ci.yml` file:
 
```yaml
image: my.registry.tld:5000/namespace/image:tag
```
```yaml
image: my.registry.tld:5000/namespace/image:tag
```
 
In the example above, GitLab Runner will look at `my.registry.tld:5000` for the
image `namespace/image:tag`.
In the example above, GitLab Runner will look at `my.registry.tld:5000` for the
image `namespace/image:tag`.
 
You can add configuration for as many registries as you want, adding more
registries to the `"auths"` hash as described above.
doc/ci/environments.md
+ 27
− 26
View file @ b0be58a1
@@ -87,18 +87,18 @@ will later see, is exposed in various places within GitLab. Each time a job that
has an environment specified and succeeds, a deployment is recorded, remembering
the Git SHA and environment name.
 
>**Note:**
Starting with GitLab 8.15, the environment name is exposed to the Runner in
two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is
the name given in `.gitlab-ci.yml` (with any variables expanded), while the
second is a "cleaned-up" version of the name, suitable for use in URLs, DNS,
etc.
>**Note:**
Starting with GitLab 9.3, the environment URL is exposed to the Runner via
`$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if
the URL was not defined there, the external URL from the environment would be
used.
> **Note:**
> Starting with GitLab 8.15, the environment name is exposed to the Runner in
> two forms: `$CI_ENVIRONMENT_NAME`, and `$CI_ENVIRONMENT_SLUG`. The first is
> the name given in `.gitlab-ci.yml` (with any variables expanded), while the
> second is a "cleaned-up" version of the name, suitable for use in URLs, DNS,
> etc.
>
> **Note:**
> Starting with GitLab 9.3, the environment URL is exposed to the Runner via
> `$CI_ENVIRONMENT_URL`. The URL would be expanded from `.gitlab-ci.yml`, or if
> the URL was not defined there, the external URL from the environment would be
> used.
 
To sum up, with the above `.gitlab-ci.yml` we have achieved that:
 
@@ -134,14 +134,15 @@ There's a bunch of information there, specifically you can see:
- A button that re-deploys the latest deployment, meaning it runs the job
defined by the environment name for that specific commit
 
>**Notes:**
- While you can create environments manually in the web interface, we recommend
that you define your environments in `.gitlab-ci.yml` first. They will
be automatically created for you after the first deploy.
- The environments page can only be viewed by Reporters and above. For more
information on the permissions, see the [permissions documentation][permissions].
- Only deploys that happen after your `.gitlab-ci.yml` is properly configured
will show up in the "Environment" and "Last deployment" lists.
> **Notes:**
>
> - While you can create environments manually in the web interface, we recommend
> that you define your environments in `.gitlab-ci.yml` first. They will
> be automatically created for you after the first deploy.
> - The environments page can only be viewed by Reporters and above. For more
> information on the permissions, see the [permissions documentation][permissions].
> - Only deploys that happen after your `.gitlab-ci.yml` is properly configured
> will show up in the "Environment" and "Last deployment" lists.
 
The information shown in the Environments page is limited to the latest
deployments, but as you may have guessed an environment can have multiple
@@ -563,13 +564,13 @@ exist, you should see something like:
 
## Monitoring environments
 
>**Notes:**
> **Notes:**
>
- For the monitoring dashboard to appear, you need to:
- Have enabled the [Prometheus integration][prom]
- Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md)
- With GitLab 9.2, all deployments to an environment are shown directly on the
monitoring dashboard
> - For the monitoring dashboard to appear, you need to:
> - Have enabled the [Prometheus integration][prom]
> - Configured Prometheus to collect at least one [supported metric](../user/project/integrations/prometheus_library/metrics.md)
> - With GitLab 9.2, all deployments to an environment are shown directly on the
> monitoring dashboard
 
If you have enabled [Prometheus for monitoring system and response metrics](https://docs.gitlab.com/ee/user/project/integrations/prometheus.html), you can monitor the performance behavior of your app running in each environment.
 
doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md
+ 2
− 2
View file @ b0be58a1
@@ -85,7 +85,7 @@ When asked, answer `Y` to fetch and install dependencies.
 
If everything went fine, you'll get an output like this:
 
![`mix phoenix.new`](img/mix-phoenix-new.png)
![mix phoenix.new](img/mix-phoenix-new.png)
 
Now, our project is located inside the directory with the same name we pass to `mix` command, for
example, `~/GitLab/hello_gitlab_ci`.
@@ -145,7 +145,7 @@ Now, we have our app running locally. We can preview it directly on our browser.
not work, open [`127.0.0.1:4000`](http://127.0.0.1:4000) instead and later, configure your OS to
point `localhost` to `127.0.0.1`.
 
![`mix phoenix.server`](img/mix-phoenix-server.png)
![mix phoenix.server](img/mix-phoenix-server.png)
 
Great, now we have a local Phoenix Server running our app.
 
doc/ci/git_submodules.md
+ 10
− 9
View file @ b0be58a1
# Using Git submodules with GitLab CI
 
> **Notes:**
- GitLab 8.12 introduced a new [CI job permissions model][newperms] and you
are encouraged to upgrade your GitLab instance if you haven't done already.
If you are **not** using GitLab 8.12 or higher, you would need to work your way
around submodules in order to access the sources of e.g., `gitlab.com/group/project`
with the use of [SSH keys](ssh_keys/README.md).
- With GitLab 8.12 onward, your permissions are used to evaluate what a CI job
can access. More information about how this system works can be found in the
[Jobs permissions model](../user/permissions.md#job-permissions).
- The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance.
>
> - GitLab 8.12 introduced a new [CI job permissions model][newperms] and you
> are encouraged to upgrade your GitLab instance if you haven't done already.
> If you are **not** using GitLab 8.12 or higher, you would need to work your way
> around submodules in order to access the sources of e.g., `gitlab.com/group/project`
> with the use of [SSH keys](ssh_keys/README.md).
> - With GitLab 8.12 onward, your permissions are used to evaluate what a CI job
> can access. More information about how this system works can be found in the
> [Jobs permissions model](../user/permissions.md#job-permissions).
> - The HTTP(S) Git protocol [must be enabled][gitpro] in your GitLab instance.
 
## Configuring the `.gitmodules` file
 
doc/ci/review_apps/index.md
+ 4
− 5
View file @ b0be58a1
# Getting started with Review Apps
 
>
- [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab
8.13 and 8.14.
- Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by
[Fourchette].
> - [Introduced][ce-21971] in GitLab 8.12. Further additions were made in GitLab
> 8.13 and 8.14.
> - Inspired by [Heroku's Review Apps][heroku-apps] which itself was inspired by
> [Fourchette].
 
The basis of Review Apps is the [dynamic environments] which allow you to create
a new environment (dynamically) for each one of your branches.
doc/ci/runners/README.md
+ 2
− 3
View file @ b0be58a1
@@ -144,9 +144,8 @@ An admin can enable/disable a specific Runner for projects:
 
## Protected Runners
 
>
[Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194)
in GitLab 10.0.
> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13194)
> in GitLab 10.0.
 
You can protect Runners from revealing sensitive information.
Whenever a Runner is protected, the Runner picks only jobs created on
doc/ci/ssh_keys/README.md
+ 2
− 2
View file @ b0be58a1
@@ -46,7 +46,7 @@ to access it. This is where an SSH key pair comes in handy.
 
1. You will first need to create an SSH key pair. For more information, follow
the instructions to [generate an SSH key](../../ssh/README.md#generating-a-new-ssh-key-pair).
**Do not** add a passphrase to the SSH key, or the `before_script` will\
**Do not** add a passphrase to the SSH key, or the `before_script` will
prompt for it.
 
1. Create a new [variable](../variables/README.md#variables).
@@ -175,7 +175,7 @@ Now that the `SSH_KNOWN_HOSTS` variable is created, in addition to the
[content of `.gitlab-ci.yml`](#ssh-keys-when-using-the-docker-executor)
above, here's what more you need to add:
 
```yaml
```yaml
before_script:
##
## Assuming you created the SSH_KNOWN_HOSTS variable, uncomment the
doc/ci/triggers/README.md
+ 16
− 13
View file @ b0be58a1
# Triggering pipelines through the API
 
> **Notes**:
- [Introduced][ci-229] in GitLab CE 7.14.
- GitLab 8.12 has a completely redesigned job permissions system. Read all
about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers).
>
> - [Introduced][ci-229] in GitLab CE 7.14.
> - GitLab 8.12 has a completely redesigned job permissions system. Read all
> about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers).
 
Triggers can be used to force a pipeline rerun of a specific `ref` (branch or
tag) with an API call.
@@ -49,11 +50,12 @@ The action is irreversible.
## Triggering a pipeline
 
> **Notes**:
- Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
it will not trigger a job.
- If your project is public, passing the token in plain text is probably not the
wisest idea, so you might want to use a
[variable](../variables/README.md#variables) for that purpose.
>
> - Valid refs are only the branches and tags. If you pass a commit SHA as a ref,
> it will not trigger a job.
> - If your project is public, passing the token in plain text is probably not the
> wisest idea, so you might want to use a
> [variable](../variables/README.md#variables) for that purpose.
 
To trigger a job you need to send a `POST` request to GitLab's API endpoint:
 
@@ -122,11 +124,12 @@ Now, whenever a new tag is pushed on project A, the job will run and the
## Triggering a pipeline from a webhook
 
> **Notes**:
- Introduced in GitLab 8.14.
- `ref` should be passed as part of the URL in order to take precedence over
`ref` from the webhook body that designates the branch ref that fired the
trigger in the source repository.
- `ref` should be URL-encoded if it contains slashes.
>
> - Introduced in GitLab 8.14.
> - `ref` should be passed as part of the URL in order to take precedence over
> `ref` from the webhook body that designates the branch ref that fired the
> trigger in the source repository.
> - `ref` should be URL-encoded if it contains slashes.
 
To trigger a job from a webhook of another project you need to add the following
webhook URL for Push and Tag events (change the project ID, ref and token):
doc/ci/yaml/README.md
+ 47
− 46
View file @ b0be58a1
@@ -383,7 +383,7 @@ except master.
## `only` and `except` (complex)
 
> `refs` and `kubernetes` policies introduced in GitLab 10.0
>
> `variables` policy introduced in 10.7
 
CAUTION: **Warning:**
@@ -583,9 +583,10 @@ The above script will:
### `when:manual`
 
> **Notes:**
- Introduced in GitLab 8.10.
- Blocking manual actions were introduced in GitLab 9.0.
- Protected actions were introduced in GitLab 9.2.
>
> - Introduced in GitLab 8.10.
> - Blocking manual actions were introduced in GitLab 9.0.
> - Protected actions were introduced in GitLab 9.2.
 
Manual actions are a special type of job that are not executed automatically,
they need to be explicitly started by a user. An example usage of manual actions
@@ -616,11 +617,11 @@ have ability to merge to this branch.
 
## `environment`
 
> **Notes:**
>
**Notes:**
- Introduced in GitLab 8.9.
- You can read more about environments and find more examples in the
[documentation about environments][environment].
> - Introduced in GitLab 8.9.
> - You can read more about environments and find more examples in the
> [documentation about environments][environment].
 
`environment` is used to define that a job deploys to a specific environment.
If `environment` is specified and no environment under that name exists, a new
@@ -641,15 +642,15 @@ deployment to the `production` environment.
 
### `environment:name`
 
> **Notes:**
>
**Notes:**
- Introduced in GitLab 8.11.
- Before GitLab 8.11, the name of an environment could be defined as a string like
`environment: production`. The recommended way now is to define it under the
`name` keyword.
- The `name` parameter can use any of the defined CI variables,
including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
You however cannot use variables defined under `script`.
> - Introduced in GitLab 8.11.
> - Before GitLab 8.11, the name of an environment could be defined as a string like
> `environment: production`. The recommended way now is to define it under the
> `name` keyword.
> - The `name` parameter can use any of the defined CI variables,
> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
> You however cannot use variables defined under `script`.
 
The `environment` name can contain:
 
@@ -680,14 +681,14 @@ deploy to production:
 
### `environment:url`
 
> **Notes:**
>
**Notes:**
- Introduced in GitLab 8.11.
- Before GitLab 8.11, the URL could be added only in GitLab's UI. The
recommended way now is to define it in `.gitlab-ci.yml`.
- The `url` parameter can use any of the defined CI variables,
including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
You however cannot use variables defined under `script`.
> - Introduced in GitLab 8.11.
> - Before GitLab 8.11, the URL could be added only in GitLab's UI. The
> recommended way now is to define it in `.gitlab-ci.yml`.
> - The `url` parameter can use any of the defined CI variables,
> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
> You however cannot use variables defined under `script`.
 
This is an optional value that when set, it exposes buttons in various places
in GitLab which when clicked take you to the defined URL.
@@ -707,12 +708,12 @@ deploy to production:
 
### `environment:on_stop`
 
> **Notes:**
>
**Notes:**
- [Introduced][ce-6669] in GitLab 8.13.
- Starting with GitLab 8.14, when you have an environment that has a stop action
defined, GitLab will automatically trigger a stop action when the associated
branch is deleted.
> - [Introduced][ce-6669] in GitLab 8.13.
> - Starting with GitLab 8.14, when you have an environment that has a stop action
> defined, GitLab will automatically trigger a stop action when the associated
> branch is deleted.
 
Closing (stoping) environments can be achieved with the `on_stop` keyword defined under
`environment`. It declares a different job that runs in order to close
@@ -763,13 +764,13 @@ The `stop_review_app` job is **required** to have the following keywords defined
 
### Dynamic environments
 
> **Notes:**
>
**Notes:**
- [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
- The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
- The `name` and `url` parameters can use any of the defined CI variables,
including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
You however cannot use variables defined under `script`.
> - [Introduced][ce-6323] in GitLab 8.12 and GitLab Runner 1.6.
> - The `$CI_ENVIRONMENT_SLUG` was [introduced][ce-7983] in GitLab 8.15.
> - The `name` and `url` parameters can use any of the defined CI variables,
> including predefined, secure variables and `.gitlab-ci.yml` [`variables`](#variables).
> You however cannot use variables defined under `script`.
 
For example:
 
@@ -799,13 +800,13 @@ as Review Apps. You can see a simple example using Review Apps at
 
## `cache`
 
> **Notes:**
>
**Notes:**
- Introduced in GitLab Runner v0.7.0.
- `cache` can be set globally and per-job.
- From GitLab 9.0, caching is enabled and shared between pipelines and jobs
by default.
- From GitLab 9.2, caches are restored before [artifacts](#artifacts).
> - Introduced in GitLab Runner v0.7.0.
> - `cache` can be set globally and per-job.
> - From GitLab 9.0, caching is enabled and shared between pipelines and jobs
> by default.
> - From GitLab 9.2, caches are restored before [artifacts](#artifacts).
 
TIP: **Learn more:**
Read how caching works and find out some good practices in the
@@ -967,13 +968,13 @@ skip the download step.
 
## `artifacts`
 
> **Notes:**
>
**Notes:**
- Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
- Windows support was added in GitLab Runner v.1.0.0.
- From GitLab 9.2, caches are restored before artifacts.
- Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
- Job artifacts are only collected for successful jobs by default.
> - Introduced in GitLab Runner v0.7.0 for non-Windows platforms.
> - Windows support was added in GitLab Runner v.1.0.0.
> - From GitLab 9.2, caches are restored before artifacts.
> - Not all executors are [supported](https://docs.gitlab.com/runner/executors/#compatibility-chart).
> - Job artifacts are only collected for successful jobs by default.
 
`artifacts` is used to specify a list of files and directories which should be
attached to the job after success.
doc/development/automatic_ce_ee_merge.md
+ 18
− 18
View file @ b0be58a1
@@ -9,16 +9,16 @@ This merge is done automatically in a
## What to do if you are pinged in a `CE Upstream` merge request to resolve a conflict?
 
1. Please resolve the conflict as soon as possible or ask someone else to do it
- It's ok to resolve more conflicts than the one that you are asked to resolve.
In that case, it's a good habit to ask for a double-check on your resolution
by someone who is familiar with the code you touched.
- It's ok to resolve more conflicts than the one that you are asked to resolve.
In that case, it's a good habit to ask for a double-check on your resolution
by someone who is familiar with the code you touched.
1. Once you have resolved your conflicts, push to the branch (no force-push)
1. Assign the merge request to the next person that has to resolve a conflict
1. If all conflicts are resolved after your resolution is pushed, keep the merge
request assigned to you: **you are now responsible for the merge request to be
green**
request assigned to you: **you are now responsible for the merge request to be
green**
1. If you need any help, you can ping the current [release managers], or ask in
the `#ce-to-ee` Slack channel
the `#ce-to-ee` Slack channel
 
A few notes about the automatic CE->EE merge job:
 
@@ -127,19 +127,19 @@ Now, every time you create an MR for CE and EE:
 
1. Open two terminal windows, one in CE, and another one in EE
1. In the CE terminal:
1. Create the CE branch, e.g., `branch-example`
1. Make your changes and push a commit (commit A)
1. Create the CE merge request in GitLab
1. Create the CE branch, e.g., `branch-example`
1. Make your changes and push a commit (commit A)
1. Create the CE merge request in GitLab
1. In the EE terminal:
1. Create the EE-equivalent branch ending with `-ee`, e.g.,
`git checkout -b branch-example-ee`
1. Fetch the CE branch: `git fetch ce branch-example`
1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA`
1. If Git prompts you to fix the conflicts, do a `git status`
to check which files contain conflicts, fix them, save the files
1. Add the changes with `git add .` but **DO NOT commit** them
1. Continue cherry-picking: `git cherry-pick --continue`
1. Push to EE: `git push origin branch-example-ee`
1. Create the EE-equivalent branch ending with `-ee`, e.g.,
`git checkout -b branch-example-ee`
1. Fetch the CE branch: `git fetch ce branch-example`
1. Cherry-pick the commit A: `git cherry-pick commit-A-SHA`
1. If Git prompts you to fix the conflicts, do a `git status`
to check which files contain conflicts, fix them, save the files
1. Add the changes with `git add .` but **DO NOT commit** them
1. Continue cherry-picking: `git cherry-pick --continue`
1. Push to EE: `git push origin branch-example-ee`
1. Create the EE-equivalent MR and link to the CE MR from the
description "Ports [CE-MR-LINK] to EE"
1. Once all the jobs are passing in both CE and EE, you've addressed the
doc/development/background_migrations.md
+ 20
− 20
View file @ b0be58a1
@@ -10,10 +10,10 @@ migrations automatically reschedule themselves for a later point in time.
 
## When To Use Background Migrations
 
>**Note:**
When adding background migrations _you must_ make sure they are announced in the
monthly release post along with an estimate of how long it will take to complete
the migrations.
> **Note:**
> When adding background migrations _you must_ make sure they are announced in the
> monthly release post along with an estimate of how long it will take to complete
> the migrations.
 
In the vast majority of cases you will want to use a regular Rails migration
instead. Background migrations should _only_ be used when migrating _data_ in
@@ -127,23 +127,23 @@ big JSON blob) to column `bar` (containing a string). The process for this would
roughly be as follows:
 
1. Release A:
1. Create a migration class that perform the migration for a row with a given ID.
1. Deploy the code for this release, this should include some code that will
schedule jobs for newly created data (e.g. using an `after_create` hook).
1. Schedule jobs for all existing rows in a post-deployment migration. It's
possible some newly created rows may be scheduled twice so your migration
should take care of this.
1. Create a migration class that perform the migration for a row with a given ID.
1. Deploy the code for this release, this should include some code that will
schedule jobs for newly created data (e.g. using an `after_create` hook).
1. Schedule jobs for all existing rows in a post-deployment migration. It's
possible some newly created rows may be scheduled twice so your migration
should take care of this.
1. Release B:
1. Deploy code so that the application starts using the new column and stops
scheduling jobs for newly created data.
1. In a post-deployment migration you'll need to ensure no jobs remain.
1. Use `Gitlab::BackgroundMigration.steal` to process any remaining
jobs in Sidekiq.
1. Reschedule the migration to be run directly (i.e. not through Sidekiq)
on any rows that weren't migrated by Sidekiq. This can happen if, for
instance, Sidekiq received a SIGKILL, or if a particular batch failed
enough times to be marked as dead.
1. Remove the old column.
1. Deploy code so that the application starts using the new column and stops
scheduling jobs for newly created data.
1. In a post-deployment migration you'll need to ensure no jobs remain.
1. Use `Gitlab::BackgroundMigration.steal` to process any remaining
jobs in Sidekiq.
1. Reschedule the migration to be run directly (i.e. not through Sidekiq)
on any rows that weren't migrated by Sidekiq. This can happen if, for
instance, Sidekiq received a SIGKILL, or if a particular batch failed
enough times to be marked as dead.
1. Remove the old column.
 
This may also require a bump to the [import/export version][import-export], if
importing a project from a prior version of GitLab requires the data to be in
doc/development/code_review.md
+ 49
− 49
View file @ b0be58a1
@@ -5,30 +5,30 @@
There are a few rules to get your merge request accepted:
 
1. Your merge request should only be **merged by a [maintainer][team]**.
1. If your merge request includes only backend changes [^1], it must be
**approved by a [backend maintainer][projects]**.
1. If your merge request includes only frontend changes [^1], it must be
**approved by a [frontend maintainer][projects]**.
1. If your merge request includes UX changes [^1], it must
be **approved by a [UX team member][team]**.
1. If your merge request includes adding a new JavaScript library [^1], it must be
**approved by a [frontend lead][team]**.
1. If your merge request includes adding a new UI/UX paradigm [^1], it must be
**approved by a [UX lead][team]**.
1. If your merge request includes frontend and backend changes [^1], it must
be **approved by a [frontend and a backend maintainer][projects]**.
1. If your merge request includes UX and frontend changes [^1], it must
be **approved by a [UX team member and a frontend maintainer][team]**.
1. If your merge request includes UX, frontend and backend changes [^1], it must
be **approved by a [UX team member, a frontend and a backend maintainer][team]**.
1. If your merge request includes a new dependency or a filesystem change, it must
be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/)
1. If your merge request includes only backend changes [^1], it must be
**approved by a [backend maintainer][projects]**.
1. If your merge request includes only frontend changes [^1], it must be
**approved by a [frontend maintainer][projects]**.
1. If your merge request includes UX changes [^1], it must
be **approved by a [UX team member][team]**.
1. If your merge request includes adding a new JavaScript library [^1], it must be
**approved by a [frontend lead][team]**.
1. If your merge request includes adding a new UI/UX paradigm [^1], it must be
**approved by a [UX lead][team]**.
1. If your merge request includes frontend and backend changes [^1], it must
be **approved by a [frontend and a backend maintainer][projects]**.
1. If your merge request includes UX and frontend changes [^1], it must
be **approved by a [UX team member and a frontend maintainer][team]**.
1. If your merge request includes UX, frontend and backend changes [^1], it must
be **approved by a [UX team member, a frontend and a backend maintainer][team]**.
1. If your merge request includes a new dependency or a filesystem change, it must
be *approved by a [Distribution team member][team]*. See how to work with the [Distribution team for more details.](https://about.gitlab.com/handbook/engineering/dev-backend/distribution/)
1. To lower the amount of merge requests maintainers need to review, you can
ask or assign any [reviewers][projects] for a first review.
1. If you need some guidance (e.g. it's your first merge request), feel free
to ask one of the [Merge request coaches][team].
1. The reviewer will assign the merge request to a maintainer once the
reviewer is satisfied with the state of the merge request.
ask or assign any [reviewers][projects] for a first review.
1. If you need some guidance (e.g. it's your first merge request), feel free
to ask one of the [Merge request coaches][team].
1. The reviewer will assign the merge request to a maintainer once the
reviewer is satisfied with the state of the merge request.
1. Keep in mind that maintainers are also going to perform a final code review.
The ideal scenario is that the reviewer has already addressed any concerns
the maintainer would have found, and the maintainer only has to perform the
@@ -160,41 +160,41 @@ Enterprise Edition instance. This has some implications:
 
1. **Query changes** should be tested to ensure that they don't result in worse
performance at the scale of GitLab.com:
1. Generating large quantities of data locally can help.
2. Asking for query plans from GitLab.com is the most reliable way to validate
these.
1. Generating large quantities of data locally can help.
2. Asking for query plans from GitLab.com is the most reliable way to validate
these.
2. **Database migrations** must be:
1. Reversible.
2. Performant at the scale of GitLab.com - ask a maintainer to test the
migration on the staging environment if you aren't sure.
3. Categorised correctly:
- Regular migrations run before the new code is running on the instance.
- [Post-deployment migrations](post_deployment_migrations.md) run _after_
the new code is deployed, when the instance is configured to do that.
- [Background migrations](background_migrations.md) run in Sidekiq, and
should only be done for migrations that would take an extreme amount of
time at GitLab.com scale.
1. Reversible.
2. Performant at the scale of GitLab.com - ask a maintainer to test the
migration on the staging environment if you aren't sure.
3. Categorised correctly:
- Regular migrations run before the new code is running on the instance.
- [Post-deployment migrations](post_deployment_migrations.md) run _after_
the new code is deployed, when the instance is configured to do that.
- [Background migrations](background_migrations.md) run in Sidekiq, and
should only be done for migrations that would take an extreme amount of
time at GitLab.com scale.
3. **Sidekiq workers**
[cannot change in a backwards-incompatible way](sidekiq_style_guide.md#removing-or-renaming-queues):
1. Sidekiq queues are not drained before a deploy happens, so there will be
workers in the queue from the previous version of GitLab.
2. If you need to change a method signature, try to do so across two releases,
and accept both the old and new arguments in the first of those.
3. Similarly, if you need to remove a worker, stop it from being scheduled in
one release, then remove it in the next. This will allow existing jobs to
execute.
4. Don't forget, not every instance will upgrade to every intermediate version
(some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so
try to be liberal in accepting the old format if it is cheap to do so.
1. Sidekiq queues are not drained before a deploy happens, so there will be
workers in the queue from the previous version of GitLab.
2. If you need to change a method signature, try to do so across two releases,
and accept both the old and new arguments in the first of those.
3. Similarly, if you need to remove a worker, stop it from being scheduled in
one release, then remove it in the next. This will allow existing jobs to
execute.
4. Don't forget, not every instance will upgrade to every intermediate version
(some people may go from X.1.0 to X.10.0, or even try bigger upgrades!), so
try to be liberal in accepting the old format if it is cheap to do so.
4. **Cached values** may persist across releases. If you are changing the type a
cached value returns (say, from a string or nil to an array), change the
cache key at the same time.
5. **Settings** should be added as a
[last resort](https://about.gitlab.com/handbook/product/#convention-over-configuration).
If you're adding a new setting in `gitlab.yml`:
1. Try to avoid that, and add to `ApplicationSetting` instead.
2. Ensure that it is also
[added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml).
1. Try to avoid that, and add to `ApplicationSetting` instead.
2. Ensure that it is also
[added to Omnibus](https://docs.gitlab.com/omnibus/settings/gitlab.yml.html#adding-a-new-setting-to-gitlab-yml).
6. **Filesystem access** can be slow, so try to avoid
[shared files](shared_files.md) when an alternative solution is available.
 
doc/development/contributing/index.md
+ 1
− 1
View file @ b0be58a1
@@ -16,7 +16,7 @@
- [Milestone labels](#milestone-labels)
- [Bug Priority labels](#bug-priority-labels)
- [Bug Severity labels](#bug-severity-labels)
- [Severity impact guidance](#severity-impact-guidance)
- [Severity impact guidance](#severity-impact-guidance)
- [Label for community contributors](#label-for-community-contributors)
- [Implement design & UI elements](#implement-design--ui-elements)
- [Issue tracker](#issue-tracker)
doc/development/contributing/issue_workflow.md
+ 2
− 2
View file @ b0be58a1
@@ -9,7 +9,7 @@
- [Release Scoping labels](#release-scoping-labels)
- [Priority labels](#priority-labels)
- [Severity labels](#severity-labels)
- [Severity impact guidance](#severity-impact-guidance)
- [Severity impact guidance](#severity-impact-guidance)
- [Label for community contributors](#label-for-community-contributors)
- [Issue triaging](#issue-triaging)
- [Feature proposals](#feature-proposals)
@@ -250,7 +250,7 @@ code snippet right after your description in a new line: `~"feature proposal"`.
Please keep feature proposals as small and simple as possible, complex ones
might be edited to make them small and simple.
 
Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature Proposal.md) provided on the issue tracker.
Please submit Feature Proposals using the ['Feature Proposal' issue template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab/issue_templates/Feature%20Proposal.md) provided on the issue tracker.
 
For changes in the interface, it is helpful to include a mockup. Issues that add to, or change, the interface should
be given the ~"UX" label. This will allow the UX team to provide input and guidance. You may
doc/development/contributing/merge_request_workflow.md
+ 16
− 16
View file @ b0be58a1
@@ -55,30 +55,30 @@ request is as follows:
organized commits by [squashing them][git-squash]
1. Push the commit(s) to your fork
1. Submit a merge request (MR) to the `master` branch
1. Your merge request needs at least 1 approval but feel free to require more.
For instance if you're touching backend and frontend code, it's a good idea
to require 2 approvals: 1 from a backend maintainer and 1 from a frontend
maintainer
1. You don't have to select any approvers, but you can if you really want
specific people to approve your merge request
1. Your merge request needs at least 1 approval but feel free to require more.
For instance if you're touching backend and frontend code, it's a good idea
to require 2 approvals: 1 from a backend maintainer and 1 from a frontend
maintainer
1. You don't have to select any approvers, but you can if you really want
specific people to approve your merge request
1. The MR title should describe the change you want to make
1. The MR description should give a motive for your change and the method you
used to achieve it.
1. If you are contributing code, fill in the template already provided in the
"Description" field.
1. If you are contributing documentation, choose `Documentation` from the
"Choose a template" menu and fill in the template.
1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
`Closes #XXX` syntax to auto-close the issue(s) once the merge request will
be merged.
1. If you are contributing code, fill in the template already provided in the
"Description" field.
1. If you are contributing documentation, choose `Documentation` from the
"Choose a template" menu and fill in the template.
1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or
`Closes #XXX` syntax to auto-close the issue(s) once the merge request will
be merged.
1. If you're allowed to, set a relevant milestone and labels
1. If the MR changes the UI it should include *Before* and *After* screenshots
1. If the MR changes CSS classes please include the list of affected pages,
`grep css-class ./app -R`
1. Be prepared to answer questions and incorporate feedback even if requests
for this arrive weeks or months after your MR submission
1. If a discussion has been addressed, select the "Resolve discussion" button
beneath it to mark it resolved.
1. If a discussion has been addressed, select the "Resolve discussion" button
beneath it to mark it resolved.
1. If your MR touches code that executes shell commands, reads or opens files or
handles paths to files on disk, make sure it adheres to the
[shell command guidelines](../shell_commands.md)
@@ -138,7 +138,7 @@ When having your code reviewed and when reviewing merge requests please take the
making and testing future changes
1. Changes do not adversely degrade performance.
- Avoid repeated polling of endpoints that require a significant amount of overhead
- Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/mer ge_request_performance_guidelines.html)
- Check for N+1 queries via the SQL log or [`QueryRecorder`](https://docs.gitlab.com/ce/development/merge_request_performance_guidelines.html)
- Avoid repeated access of filesystem
1. If you need polling to support real-time features, please use
[polling with ETag caching][polling-etag].
doc/development/diffs.md
+ 5
− 5
View file @ b0be58a1
@@ -26,11 +26,11 @@ In order to present diffs information on the Merge Request diffs page, we:
 
1. Fetch all diff files from database `merge_request_diff_files`
2. Fetch the _old_ and _new_ file blobs in batch to:
1. Highlight old and new file content
2. Know which viewer it should use for each file (text, image, deleted, etc)
3. Know if the file content changed
4. Know if it was stored externally
5. Know if it had storage errors
1. Highlight old and new file content
2. Know which viewer it should use for each file (text, image, deleted, etc)
3. Know if the file content changed
4. Know if it was stored externally
5. Know if it had storage errors
3. If the diff file is cacheable (text-based), it's cached on Redis
using `Gitlab::Diff::FileCollection::MergeRequestDiff`
 
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