diff options
| author | Marcia Ramos <virtua.creative@gmail.com> | 2019-04-10 17:05:46 +0100 |
|---|---|---|
| committer | Marcia Ramos <virtua.creative@gmail.com> | 2019-04-10 17:05:46 +0100 |
| commit | cbd6841cac8185f181a5dcec33704f6e7c040732 (patch) | |
| tree | 423bbc4fb873ab51590d0be4ae594769c80b739b /doc | |
| parent | 3402f8c817e9798eed9d86555f3f85fd10f49abf (diff) | |
| parent | 490b31f740d23b54a62588cd9fd0e0cf7fdd9370 (diff) | |
| download | gitlab-ce-docs-pages-intro.tar.gz | |
Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce into docs-pages-introdocs-pages-intro
Diffstat (limited to 'doc')
55 files changed, 760 insertions, 315 deletions
diff --git a/doc/README.md b/doc/README.md index aead50ea97e..14a1eeffda0 100644 --- a/doc/README.md +++ b/doc/README.md @@ -288,7 +288,7 @@ The following documentation relates to the DevOps **Configure** stage: | [GitLab ChatOps](ci/chatops/README.md) | Interact with CI/CD jobs through chat services. | | [Installing Applications](user/project/clusters/index.md#installing-applications) | Deploy Helm, Ingress, and Prometheus on Kubernetes. | | [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) | Enable and use slash commands from within Mattermost. | -| [Protected variables](ci/variables/README.md#protected-variables) | Restrict variables to protected branches and tags. | +| [Protected variables](ci/variables/README.md#protected-environment-variables) | Restrict variables to protected branches and tags. | | [Serverless](user/project/clusters/serverless/index.md) | Run serverless workloads on Kubernetes. | | [Slack slash commands](user/project/integrations/slack_slash_commands.md) | Enable and use slash commands from within Slack. | diff --git a/doc/administration/auth/okta.md b/doc/administration/auth/okta.md index 638405126a5..aa4e1b0d2e0 100644 --- a/doc/administration/auth/okta.md +++ b/doc/administration/auth/okta.md @@ -92,18 +92,23 @@ Now that the Okta app is configured, it's time to enable it in GitLab. 1. Add the provider configuration. >**Notes:** + > >- Change the value for `assertion_consumer_service_url` to match the HTTPS endpoint of GitLab (append `users/auth/saml/callback` to the HTTPS URL of your GitLab installation to generate the correct value). + > >- To get the `idp_cert_fingerprint` fingerprint, first download the certificate from the Okta app you registered and then run: `openssl x509 -in okta.cert -noout -fingerprint`. Substitute `okta.cert` with the location of your certificate. + > >- Change the value of `idp_sso_target_url`, with the value of the **Identity Provider Single Sign-On URL** from the step when you configured the Okta app. - >- Change the value of `issuer` to a unique name, which will identify the application + > + >- Change the value of `issuer` to the value of the **Audience Restriction** from your Okta app configuration. This will identify GitLab to the IdP. + > >- Leave `name_identifier_format` as-is. **For Omnibus GitLab installations** diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 058346df56d..1b01419e062 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -30,7 +30,7 @@ the `pushes_since_gc` value is 200 a `git gc` will be run. `git add`. - `git repack` ([man page][man-repack]) re-organize existing packs into a single, more efficient pack. -You can find this option under your **[Project] > Edit Project**. +You can find this option under your project's **Settings > General > Advanced**. --- diff --git a/doc/administration/img/housekeeping_settings.png b/doc/administration/img/housekeeping_settings.png Binary files differindex acc4506993a..356de51f0cc 100644 --- a/doc/administration/img/housekeeping_settings.png +++ b/doc/administration/img/housekeeping_settings.png diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 25d85d1687b..2596e3fe68b 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -11,7 +11,7 @@ One of the things it uses these credentials for is providing access to ## How it works A detailed overview of the architecture of web terminals and how they work -can be found in [this document](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/doc/terminal.md). +can be found in [this document](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/doc/channel.md). In brief: - GitLab relies on the user to provide their own Kubernetes credentials, and to diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index c293df3fc57..f8d58c6ce28 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -58,6 +58,9 @@ sudo service sshd reload Confirm that SSH is working by removing your user's SSH key in the UI, adding a new one, and attempting to pull a repo. +> **Note:** For Omnibus Docker, `AuthorizedKeysCommand` is setup by default in +GitLab 11.11 and later. + > **Warning:** Do not disable writes until SSH is confirmed to be working perfectly, because the file will quickly become out-of-date. diff --git a/doc/api/commits.md b/doc/api/commits.md index e205307eeca..92f53c7b5e6 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -130,6 +130,7 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Cont ``` Example response: + ```json { "id": "ed899a2f4b50b4370feeea94676502b42383c746", @@ -162,21 +163,21 @@ curl --request POST \ --form "branch=master" \ --form "commit_message=some commit message" \ --form "start_branch=master" \ - --form "actions[][action]=create" \ - --form "actions[][file_path]=foo/bar" \ - --form "actions[][content]=</path/to/local.file" \ - --form "actions[][action]=delete" \ - --form "actions[][file_path]=foo/bar2" \ - --form "actions[][action]=move" \ - --form "actions[][file_path]=foo/bar3" \ - --form "actions[][previous_path]=foo/bar4" \ - --form "actions[][content]=</path/to/local1.file" \ - --form "actions[][action]=update" \ + --form "actions[][action]=create" \ + --form "actions[][file_path]=foo/bar" \ + --form "actions[][content]=</path/to/local.file" \ + --form "actions[][action]=delete" \ + --form "actions[][file_path]=foo/bar2" \ + --form "actions[][action]=move" \ + --form "actions[][file_path]=foo/bar3" \ + --form "actions[][previous_path]=foo/bar4" \ + --form "actions[][content]=</path/to/local1.file" \ + --form "actions[][action]=update" \ --form "actions[][file_path]=foo/bar5" \ - --form "actions[][content]=</path/to/local2.file" \ - --form "actions[][action]=chmod" \ + --form "actions[][content]=</path/to/local2.file" \ + --form "actions[][action]=chmod" \ --form "actions[][file_path]=foo/bar5" \ - --form "actions[][execute_filemode]=true" \ + --form "actions[][execute_filemode]=true" \ --header "PRIVATE-TOKEN: <your_access_token>" \ "https://gitlab.example.com/api/v4/projects/1/repository/commits" ``` diff --git a/doc/api/environments.md b/doc/api/environments.md index 4a38dd73747..ebcdc546d08 100644 --- a/doc/api/environments.md +++ b/doc/api/environments.md @@ -29,6 +29,111 @@ Example response: ] ``` +## Get a specific environment + +``` +GET /projects/:id/environments/:environment_id +``` + +| Attribute | Type | Required | Description | +|-----------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `environment_id` | integer | yes | The ID of the environment | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/environments/1" +``` + +Example of response + +```json +{ + "id": 1, + "name": "review/fix-foo", + "slug": "review-fix-foo-dfjre3", + "external_url": "https://review-fix-foo-dfjre3.example.gitlab.com" + "last_deployment": { + "id": 100, + "iid": 34, + "ref": "fdroid", + "sha": "416d8ea11849050d3d1f5104cf8cf51053e790ab", + "created_at": "2019-03-25T18:55:13.252Z", + "user": { + "id": 1, + "name": "Administrator", + "state": "active", + "username": "root", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://localhost:3000/root" + } + "deployable": { + "id": 710, + "status": "success", + "stage": "deploy", + "name": "staging", + "ref": "fdroid", + "tag": false, + "coverage": null, + "created_at": "2019-03-25T18:55:13.215Z", + "started_at": "2019-03-25T12:54:50.082Z", + "finished_at": "2019-03-25T18:55:13.216Z", + "duration": 21623.13423, + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://gitlab.dev/root", + "created_at": "2015-12-21T13:14:24.077Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": null + } + "commit": { + "id": "416d8ea11849050d3d1f5104cf8cf51053e790ab", + "short_id": "416d8ea1", + "created_at": "2016-01-02T15:39:18.000Z", + "parent_ids": [ + "e9a4449c95c64358840902508fc827f1a2eab7df" + ], + "title": "Removed fabric to fix #40", + "message": "Removed fabric to fix #40\n", + "author_name": "Administrator", + "author_email": "admin@example.com", + "authored_date": "2016-01-02T15:39:18.000Z", + "committer_name": "Administrator", + "committer_email": "admin@example.com", + "committed_date": "2016-01-02T15:39:18.000Z" + }, + "pipeline": { + "id": 34, + "sha": "416d8ea11849050d3d1f5104cf8cf51053e790ab", + "ref": "fdroid", + "status": "success", + "web_url": "http://localhost:3000/Commit451/lab-coat/pipelines/34" + }, + "web_url": "http://localhost:3000/Commit451/lab-coat/-/jobs/710", + "artifacts": [ + { + "file_type": "trace", + "size": 1305, + "filename": "job.log", + "file_format": null + } + ], + "runner": null, + "artifacts_expire_at": null + } + } +} +``` + ## Create a new environment Creates a new environment with the given name and external_url. diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 43bbf463c8d..1a4310ef328 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -93,6 +93,36 @@ Example of response } ``` +### Get variables of a pipeline + +``` +GET /projects/:id/pipelines/:pipeline_id/variables +``` + +| Attribute | Type | Required | Description | +|------------|---------|----------|---------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `pipeline_id` | integer | yes | The ID of a pipeline | + +``` +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/pipelines/46/variables" +``` + +Example of response + +```json +[ + { + "key": "RUN_NIGHTLY_BUILD", + "value": "true" + }, + { + "key": "foo", + "value": "bar" + } +] +``` + ## Create a new pipeline > [Introduced][ce-7209] in GitLab 8.14 diff --git a/doc/ci/README.md b/doc/ci/README.md index 913e9d4d789..a7ad2018b09 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -62,6 +62,7 @@ into more features: | [ChatOps](chatops/README.md) | Trigger CI jobs from chat, with results sent back to the channel. | | [Interactive web terminals](interactive_web_terminal/index.md) | Open an interactive web terminal to debug the running jobs. | | [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes in a per-branch basis. | +| [Optimizing GitLab for large repositories](large_repositories/index.md) | Useful tips on how to optimize GitLab and GitLab Runner for big repositories. | | [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) **[PREMIUM]** | Check the current health and status of each CI/CD environment running on Kubernetes. | | [GitLab CI/CD for external repositories](https://docs.gitlab.com/ee/ci/ci_cd_for_external_repos/index.html) **[PREMIUM]** | Get the benefits of GitLab CI/CD combined with repositories in GitHub and BitBucket Cloud. | diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index a06fe6961a7..5ecdf0f8c54 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -24,7 +24,7 @@ Since ChatOps is built upon GitLab CI/CD, the job has all the same features and * It is strongly recommended to set `only: [chat]` so the job does not run as part of the standard CI pipeline. * If the job is set to `when: manual`, the pipeline will be created however the job will wait to be started. -* It is important to keep in mind that there is very limited support for access control. If the user who triggered the slash command is a developer in the project, the job will run. The job itself can utilize existing [CI/CD variables](../variables/README.html#predefined-environment-variables) like `GITLAB_USER_ID` to perform additional rights validation, however these variables can be [overridden](https://docs.gitlab.com/ce/ci/variables/README.html#priority-of-variables). +* It is important to keep in mind that there is very limited support for access control. If the user who triggered the slash command is a developer in the project, the job will run. The job itself can utilize existing [CI/CD variables](../variables/README.html#predefined-environment-variables) like `GITLAB_USER_ID` to perform additional rights validation, however these variables can be [overridden](../variables/README.html#priority-of-environment-variables). ### Controlling the ChatOps reply diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index 9266c4511be..5222cc45bc4 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -303,20 +303,19 @@ services: - docker:dind variables: - CONTAINER_IMAGE: registry.gitlab.com/$CI_PROJECT_PATH DOCKER_HOST: tcp://docker:2375 DOCKER_DRIVER: overlay2 before_script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY build: stage: build script: - - docker pull $CONTAINER_IMAGE:latest || true - - docker build --cache-from $CONTAINER_IMAGE:latest --tag $CONTAINER_IMAGE:$CI_COMMIT_SHA --tag $CONTAINER_IMAGE:latest . - - docker push $CONTAINER_IMAGE:$CI_COMMIT_SHA - - docker push $CONTAINER_IMAGE:latest + - docker pull $CI_REGISTRY_IMAGE:latest || true + - docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest . + - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA + - docker push $CI_REGISTRY_IMAGE:latest ``` The steps in the `script` section for the `build` stage can be summed up to: @@ -324,7 +323,7 @@ The steps in the `script` section for the `build` stage can be summed up to: 1. The first command tries to pull the image from the registry so that it can be used as a cache for the `docker build` command. 1. The second command builds a Docker image using the pulled image as a - cache (notice the `--cache-from $CONTAINER_IMAGE:latest` argument) if + cache (notice the `--cache-from $CI_REGISTRY_IMAGE:latest` argument) if available, and tags it. 1. The last two commands push the tagged Docker images to the container registry so that they may also be used as cache for subsequent builds. @@ -421,14 +420,14 @@ and depend on the visibility of your project. For all projects, mostly suitable for public ones: -- **Using the special `gitlab-ci-token` user**: This user is created for you in order to +- **Using the special `$CI_REGISTRY_USER` variable**: The user specified by this variable is created for you in order to push to the Registry connected to your project. Its password is automatically - set with the `$CI_JOB_TOKEN` variable. This allows you to automate building and deploying + set with the `$CI_REGISTRY_PASSWORD` variable. This allows you to automate building and deploying your Docker images and has read/write access to the Registry. This is ephemeral, so it's only valid for one job. You can use the following example as-is: ```sh - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY ``` For private and internal projects: @@ -436,8 +435,10 @@ For private and internal projects: - **Using a personal access token**: You can create and use a [personal access token](../../user/profile/personal_access_tokens.md) in case your project is private: - - For read (pull) access, the scope should be `read_registry`. - - For read/write (pull/push) access, use `api`. + + - For read (pull) access, the scope should be `read_registry`. + - For read/write (pull/push) access, use `api`. + Replace the `<username>` and `<access_token>` in the following example: ```sh @@ -469,9 +470,9 @@ could look like: DOCKER_DRIVER: overlay2 stage: build script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com - - docker build -t registry.example.com/group/project/image:latest . - - docker push registry.example.com/group/project/image:latest + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY + - docker build -t $CI_REGISTRY/group/project/image:latest . + - docker push $CI_REGISTRY/group/project/image:latest ``` You can also make use of [other variables](../variables/README.md) to avoid hardcoding: @@ -486,7 +487,7 @@ variables: IMAGE_TAG: $CI_REGISTRY_IMAGE:$CI_COMMIT_REF_SLUG before_script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY build: stage: build @@ -526,7 +527,7 @@ variables: CONTAINER_RELEASE_IMAGE: $CI_REGISTRY_IMAGE:latest before_script: - - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN $CI_REGISTRY + - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY build: stage: build diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 3314c76d234..13c26bc5f47 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -500,7 +500,7 @@ To configure access for `registry.example.com:5000`, follow these steps: bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ= ``` -1. Create a [variable] `DOCKER_AUTH_CONFIG` with the content of the +1. Create a [variable](../variables/README.md#gitlab-cicd-environment-variables) `DOCKER_AUTH_CONFIG` with the content of the Docker configuration file as the value: ```json @@ -642,7 +642,6 @@ creation. [postgres-hub]: https://hub.docker.com/r/_/postgres/ [mysql-hub]: https://hub.docker.com/r/_/mysql/ [runner-priv-reg]: http://docs.gitlab.com/runner/configuration/advanced-configuration.html#using-a-private-container-registry -[variable]: ../variables/README.md#variables [entrypoint]: https://docs.docker.com/engine/reference/builder/#entrypoint [cmd]: https://docs.docker.com/engine/reference/builder/#cmd [register]: https://docs.gitlab.com/runner/register/ diff --git a/doc/ci/environments.md b/doc/ci/environments.md index eaafc7bc1c0..3e52cc786dd 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -224,7 +224,7 @@ The `name` and `url` parameters for dynamic environments can use most available including: - [Predefined environment variables](variables/README.md#predefined-environment-variables) -- [Project and group variables](variables/README.md#variables) +- [Project and group variables](variables/README.md#gitlab-cicd-environment-variables) - [`.gitlab-ci.yml` variables](yaml/README.md#variables) However, you cannot use variables defined: diff --git a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md index 0f809ed05ca..f56d5429fb7 100644 --- a/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md +++ b/doc/ci/examples/laravel_with_gitlab_and_envoy/index.md @@ -116,7 +116,7 @@ cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys cat ~/.ssh/id_rsa ``` -Now, let's add it to your GitLab project as a [variable](../../variables/README.md#variables). +Now, let's add it to your GitLab project as a [variable](../../variables/README.md#gitlab-cicd-environment-variables). Variables are user-defined variables and are stored out of `.gitlab-ci.yml`, for security purposes. They can be added per project by navigating to the project's **Settings** > **CI/CD**. diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index fa18cb22aed..e1164b8d03a 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -69,5 +69,5 @@ in the `.gitlab-ci.yml` file with your application's name. ## Heroku API key You can look up your Heroku API key in your -[account](https://dashboard.heroku.com/account). Add a [protected variable](../variables/README.md#protected-variables) with +[account](https://dashboard.heroku.com/account). Add a [protected variable](../variables/README.md#protected-environment-variables) with this value in **Project ➔ Variables** with key `HEROKU_API_KEY`. diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index 1a909e8892a..4a5fda661df 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -11,7 +11,7 @@ last_updated: 2019-03-06 [Phoenix][phoenix-site] is a web development framework written in [Elixir][elixir-site], which is a functional language designed for productivity and maintainability that runs on the -[Erlang VM][erlang-site]. Erlang VM is really really fast and can handle very large numbers of +[Erlang VM](https://www.erlang.org). Erlang VM is really really fast and can handle very large numbers of simultaneous users. That's why we're hearing so much about Phoenix today. @@ -27,7 +27,7 @@ and GitLab UI._ ### What is Phoenix? [Phoenix][phoenix-site] is a web development framework written in [Elixir][elixir-site] very useful - to build fast, reliable, and high-performance applications, as it uses [Erlang VM][erlang-site]. + to build fast, reliable, and high-performance applications, as it uses [Erlang VM](https://www.erlang.org). Many components and concepts are similar to Ruby on Rails or Python's Django. High developer productivity and high application performance are only a few advantages on learning how to use it. @@ -406,7 +406,6 @@ other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams [elixir-site]: http://elixir-lang.org/ "Elixir" [elixir-mix]: http://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix" [elixir-docs]: http://elixir-lang.org/getting-started/introduction.html "Elixir Documentation" -[erlang-site]: http://erlang.org "Erlang" [elixir-install]: https://elixir-lang.org/install.html "Elixir Installation" [ecto]: http://hexdocs.pm/ecto "Ecto" [ecto-repo]: https://hexdocs.pm/ecto/Ecto.html#module-repositories "Ecto Repositories" diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md new file mode 100644 index 00000000000..cfe638c0a22 --- /dev/null +++ b/doc/ci/large_repositories/index.md @@ -0,0 +1,235 @@ +# Optimizing GitLab for large repositories + +Large repositories consisting of more than 50k files in a worktree +often require special consideration because of +the time required to clone and check out. + +GitLab and GitLab Runner handle this scenario well +but require optimized configuration to efficiently perform its +set of operations. + +The general guidelines for handling big repositories are simple. +Each guideline is described in more detail in the sections below: + +- Always fetch incrementally. Do not clone in a way that results in recreating all of the worktree. +- Always use shallow clone to reduce data transfer. Be aware that this puts more burden + on GitLab instance due to higher CPU impact. +- Control the clone directory if you heavily use a fork-based workflow. +- Optimize `git clean` flags to ensure that you remove or keep data that might affect or speed-up your build. + +## Shallow cloning + +> Introduced in GitLab Runner 8.9. + +GitLab and GitLab Runner always perform a full clone by default. +While it means that all changes from GitLab are received, +it often results in receiving extra commit logs. + +Ideally, you should always use `GIT_DEPTH` with a small number +like 10. This will instruct GitLab Runner to perform shallow clones. +Shallow clones makes Git request only the latest set of changes for a given branch, +up to desired number of commits as defined by the `GIT_DEPTH` variable. + +This significantly speeds up fetching of changes from Git repositories, +especially if the repository has a very long backlog consisting of number +of big files as we effectively reduce amount of data transfer. + +The following example makes GitLab Runner shallow clone to fetch only a given branch, +it does not fetch any other branches nor tags. + +```yaml +variables: + GIT_DEPTH: 10 + +test: + script: + - ls -al +``` + +## Git strategy + +> Introduced in GitLab Runner 8.9. + +By default, GitLab is configured to always prefer the `GIT_STRATEGY: fetch` strategy. +The `GIT_STRATEGY: fetch` strategy will re-use existing worktrees if found +on disk. This is different to the `GIT_STRATEGY: clone` strategy +as in case of clones, if a worktree is found, it is removed before clone. + +Usage of `fetch` is preferred because it reduces the amount of data to transfer and +does not really impact the operations that you might do on a repository from CI. + +However, `fetch` does require access to the previous worktree. This works +well when using the `shell` or `docker` executor because these +try to preserve worktrees and try to re-use them by default. + +This does not work today for `kubernetes` executor and has limitations when using +`docker+machine`. `kubernetes` executor today always clones into ephemeral directory. + +GitLab also offers the `GIT_STRATEGY: none` strategy. This disables any `fetch` and `checkout` commands +done by GitLab, requiring you to do them. + +## Git clone path + +> Introduced in GitLab Runner 11.10. + +`GIT_CLONE_PATH` allows you to control where you clone your sources. +This can have implications if you heavily use big repositories with fork workflow. + +Fork workflow from GitLab Runner's perspective is stored as a separate repository +with separate worktree. That means that GitLab Runner cannot optimize the usage +of worktrees and you might have to instruct GitLab Runner to use that. + +In such cases, ideally you want to make the GitLab Runner executor be used only used only +for the given project and not shared across different projects to make this +process more efficient. + +The `GIT_CLONE_PATH` has to be within the `$CI_BUILDS_DIR`. Currently, +it is impossible to pick any path from disk. + +## Git clean flags + +> Introduced in GitLab Runner 11.10. + +`GIT_CLEAN_FLAGS` allows you to control whether or not you require +the `git clean` command to be executed for each CI job. +By default, GitLab ensures that you have your worktree on the given SHA, +and that your repository is clean. + +`GIT_CLEAN_FLAGS` is disabled when set to `none`. On very big repositories, this +might be desired because `git clean` is disk I/O intensive. Controlling that +with `GIT_CLEAN_FLAGS: -ffdx -e .build/`, for example, allows you to control and +disable removal of some directories within the worktree between subsequent runs, +which can speed-up the incremental builds. This has the biggest effect +if you re-use existing machines, and have an existing worktree that you can re-use +for builds. + +For exact parameters accepted by `GIT_CLEAN_FLAGS`, see the documentation +for [git clean](https://git-scm.com/docs/git-clean). The +available parameters are dependent on Git version. + +## Fork-based workflow + +> Introduced in GitLab Runner 11.10. + +Following the guidelines above, lets imagine that we want to: + +- Optimize for a big project (more than 50k files in directory). +- Use forks-based workflow for contributing. +- Reuse existing worktrees. Have preconfigured runners that are pre-cloned with repositories. +- Runner assigned only to project and all forks. + +Lets consider the following two examples, one using `shell` executor and +other using `docker` executor. + +### `shell` executor example + +Lets assume that you have the following [config.toml](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "shell" + builds_dir = "/builds" + cache_dir = "/cache" + + [runners.custom_build_dir] + enabled = true +``` + +This `config.toml`: + +- Uses the `shell` executor, +- Specifies a custom `/builds` directory where all clones will be stored. +- Enables the ability to specify `GIT_CLONE_PATH`, +- Runs at most 4 jobs at once. + +### `docker` executor example + +Lets assume that you have the following [config.toml](https://docs.gitlab.com/runner/configuration/advanced-configuration.html). + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "docker" + builds_dir = "/builds" + cache_dir = "/cache" + + [runners.docker] + volumes = ["/builds:/builds", "/cache:/cache"] +``` + +This `config.toml`: + +- Uses the `docker` executor, +- Specifies a custom `/builds` directory on disk where all clones will be stored. + We host mount the `/builds` directory to make it reusable between subsequent runs + and be allowed to override the cloning strategy. +- Doesn't enable the ability to specify `GIT_CLONE_PATH` as it is enabled by default. +- Runs at most 4 jobs at once. + +### Our `.gitlab-ci.yml` + +Once we have the executor configured, we need to fine tune our `.gitlab-ci.yml`. + +Our pipeline will be most performant if we use the following `.gitlab-ci.yml`: + +```yaml +variables: + GIT_DEPTH: 10 + GIT_CLONE_PATH: $CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME + +build: + script: ls -al +``` + +The above configures a: + +- Shallow clone of 10, to speed up subsequent `git fetch` commands. +- Custom clone path to make it possible to re-use worktrees between parent project and all forks + because we use the same clone path for all forks. + +Why use `$CI_CONCURRENT_ID`? The main reason is to ensure that worktrees used are not conflicting +between projects. The `$CI_CONCURRENT_ID` represents a unique identifier within the given executor, +so as long as we use it to construct the path, it is guaranteed that this directory will not conflict +with other concurrent jobs running. + +### Store custom clone options in `config.toml` + +Ideally, all job-related configuration should be stored in `.gitlab-ci.yml`. +However, sometimes it is desirable to make these schemes part of Runner configuration. + +In the above example of Forks, making this configuration discoverable for users may be preferred, +but this brings administrative overhead as the `.gitlab-ci.yml` needs to be updated for each branch. +In such cases, it might be desirable to keep the `.gitlab-ci.yml` clone path agnostic, but make it +a configuration of Runner. + +We can extend our [config.toml](https://docs.gitlab.com/runner/configuration/advanced-configuration.html) +with the following specification that will be used by Runner if `.gitlab-ci.yml` will not override it: + +```toml +concurrent = 4 + +[[runners]] + url = "GITLAB_URL" + token = "TOKEN" + executor = "docker" + builds_dir = "/builds" + cache_dir = "/cache" + + environment = [ + "GIT_DEPTH=10", + "GIT_CLONE_PATH=$CI_BUILDS_DIR/$CI_CONCURRENT_ID/$CI_PROJECT_NAME" + ] + + [runners.docker] + volumes = ["/builds:/builds", "/cache:/cache"] +``` + +This makes the cloning configuration to be part of given Runner, +and does not require us to update each `.gitlab-ci.yml`. diff --git a/doc/ci/ssh_keys/README.md b/doc/ci/ssh_keys/README.md index ff63d0bd69f..9ed1ec5aa5c 100644 --- a/doc/ci/ssh_keys/README.md +++ b/doc/ci/ssh_keys/README.md @@ -49,7 +49,7 @@ to access it. This is where an SSH key pair comes in handy. **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). +1. Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables). As **Key** enter the name `SSH_PRIVATE_KEY` and in the **Value** field paste the content of your _private_ key that you created earlier. @@ -157,7 +157,7 @@ ssh-keyscan example.com ssh-keyscan 1.2.3.4 ``` -Create a new [variable](../variables/README.md#variables) with +Create a new [variable](../variables/README.md#gitlab-cicd-environment-variables) with `SSH_KNOWN_HOSTS` as "Key", and as a "Value" add the output of `ssh-keyscan`. NOTE: **Note:** diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index 398b017277f..0e72bdddee7 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -20,7 +20,7 @@ A unique trigger token can be obtained when [adding a new trigger](#adding-a-new DANGER: **Danger:** Passing plain text tokens in public projects is a security issue. Potential attackers can impersonate the user that exposed their trigger token publicly in -their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#variables) +their `.gitlab-ci.yml` file. Use [variables](../variables/README.md#gitlab-cicd-environment-variables) to protect trigger tokens. ## Adding a new trigger diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 592fdfd2873..61d1a904f76 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -3,7 +3,6 @@ table_display_block: true --- # GitLab CI/CD environment variables -{: #variables} After a brief overview over the use of environment variables, this document teaches you how to use GitLab CI/CD's @@ -65,7 +64,7 @@ To get started, choose one of the existing to be output by the Runner. For example, let's say that you want a given job you're running through your script to output the stage that job is running for. In your `.gitlab-ci.yml` file, -call the variable from your script according to the [syntaxes](#syntax-of-variables-in-job-scripts) available. To +call the variable from your script according to the [syntaxes](#syntax-of-environment-variables-in-job-scripts) available. To output the job stage, use the predefined variable `CI_JOB_STAGE`: ```yaml @@ -145,7 +144,6 @@ settings](../../user/project/pipelines/settings.md#visibility-of-pipelines). Follow the discussion in issue [#13784][ce-13784] for masking the variables. ### Syntax of environment variables in job scripts -{: #syntax-of-variables-in-job-scripts} All variables are set as environment variables in the build environment, and they are accessible with normal methods that are used to access such variables. @@ -278,7 +276,6 @@ script: ``` ### Group-level environment variables -{: #group-level-variables} > Introduced in GitLab 9.4. @@ -297,19 +294,18 @@ Any variables of [subgroups](../../user/group/subgroups/index.md) will be inheri Once you set them, they will be available for all subsequent pipelines. ## Priority of environment variables -{: #priority-of-variables} Variables of different types can take precedence over other variables, depending on where they are defined. The order of precedence for variables is (from highest to lowest): -1. [Trigger variables](../triggers/README.md#making-use-of-trigger-variables) or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#making-use-of-scheduled-pipeline-variables). -1. Project-level [variables](#creating-a-custom-environment-variable) or [protected variables](#protected-variables). -1. Group-level [variables](#group-level-variables) or [protected variables](#protected-variables). +1. [Trigger variables](../triggers/README.md#making-use-of-trigger-variables) or [scheduled pipeline variables](../../user/project/pipelines/schedules.md#using-variables). +1. Project-level [variables](#creating-a-custom-environment-variable) or [protected variables](#protected-environment-variables). +1. Group-level [variables](#group-level-environment-variables) or [protected variables](#protected-environment-variables). 1. YAML-defined [job-level variables](../yaml/README.md#variables). 1. YAML-defined [global variables](../yaml/README.md#variables). -1. [Deployment variables](#deployment-variables). +1. [Deployment variables](#deployment-environment-variables). 1. [Predefined environment variables](predefined_variables.md). For example, if you define: @@ -329,7 +325,6 @@ about which variables are [not supported](where_variables_can_be_used.md). ## Advanced use ### Protected environment variables -{: #protected-variables} > Introduced in GitLab 9.3. @@ -345,7 +340,6 @@ Protected variables can be added by going to your project's Once you set them, they will be available for all subsequent pipelines. ### Deployment environment variables -{: #deployment-variables} > Introduced in GitLab 8.15. @@ -382,7 +376,7 @@ limitations with the current Auto DevOps scripting environment. [Manually triggered pipelines](../pipelines.md#manually-executing-pipelines) allow you to override the value of a current variable. For instance, suppose you added a -[custom variable `$TEST`](#creating-a-custom-variable) +[custom variable `$TEST`](#creating-a-custom-environment-variable) as exemplified above and you want to override it in a manual pipeline. Navigate to your project's **CI/CD > Pipelines** and click **Run pipeline**. Choose the branch you want to run the pipeline for, then add a new variable @@ -396,7 +390,6 @@ value you set for this specific pipeline:  ## Environment variables expressions -{: #variables-expressions} > Introduced in GitLab 10.7. diff --git a/doc/ci/variables/img/ci_job_stage_output_example.png b/doc/ci/variables/img/ci_job_stage_output_example.png Binary files differindex 056238d5693..056238d5693 100755..100644 --- a/doc/ci/variables/img/ci_job_stage_output_example.png +++ b/doc/ci/variables/img/ci_job_stage_output_example.png diff --git a/doc/ci/variables/img/custom_variable_output.png b/doc/ci/variables/img/custom_variable_output.png Binary files differindex 50f3bceff9a..50f3bceff9a 100755..100644 --- a/doc/ci/variables/img/custom_variable_output.png +++ b/doc/ci/variables/img/custom_variable_output.png diff --git a/doc/ci/variables/img/new_custom_variable_example.png b/doc/ci/variables/img/new_custom_variable_example.png Binary files differindex d169c5f1806..d169c5f1806 100755..100644 --- a/doc/ci/variables/img/new_custom_variable_example.png +++ b/doc/ci/variables/img/new_custom_variable_example.png diff --git a/doc/ci/variables/img/override_value_via_manual_pipeline_output.png b/doc/ci/variables/img/override_value_via_manual_pipeline_output.png Binary files differindex 02369d57fb8..02369d57fb8 100755..100644 --- a/doc/ci/variables/img/override_value_via_manual_pipeline_output.png +++ b/doc/ci/variables/img/override_value_via_manual_pipeline_output.png diff --git a/doc/ci/variables/img/override_variable_manual_pipeline.png b/doc/ci/variables/img/override_variable_manual_pipeline.png Binary files differindex 3bcd354e096..3bcd354e096 100755..100644 --- a/doc/ci/variables/img/override_variable_manual_pipeline.png +++ b/doc/ci/variables/img/override_variable_manual_pipeline.png diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index b429dc8c8be..846c539daab 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -36,7 +36,7 @@ future GitLab releases.** | `CI_COMMIT_TAG` | 9.0 | 0.5 | The commit tag name. Present only when building tags. | | `CI_COMMIT_TITLE` | 10.8 | all | The title of the commit - the full first line of the message | | `CI_CONFIG_PATH` | 9.4 | 0.5 | The path to CI config file. Defaults to `.gitlab-ci.yml` | -| `CI_DEBUG_TRACE` | all | 1.7 | Whether [debug tracing](#debug-tracing) is enabled | +| `CI_DEBUG_TRACE` | all | 1.7 | Whether [debug tracing](README.md#debug-tracing) is enabled | | `CI_DEPLOY_PASSWORD` | 10.8 | all | Authentication password of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| | `CI_DEPLOY_USER` | 10.8 | all | Authentication username of the [GitLab Deploy Token][gitlab-deploy-token], only present if the Project has one related.| | `CI_DISPOSABLE_ENVIRONMENT` | all | 10.1 | Marks that 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`). If the environment is disposable, it is set to true, otherwise it is not defined at all. | diff --git a/doc/ci/variables/where_variables_can_be_used.md b/doc/ci/variables/where_variables_can_be_used.md index 1218ac0b071..091ddcb0bae 100644 --- a/doc/ci/variables/where_variables_can_be_used.md +++ b/doc/ci/variables/where_variables_can_be_used.md @@ -111,4 +111,4 @@ They are: - Script execution shell. - Not supported: - For definitions where the ["Expansion place"](#gitlab-ciyml-file) is GitLab. - - In the `only` and `except` [variables expressions](README.md#variables-expressions). + - In the `only` and `except` [variables expressions](README.md#environment-variables-expressions). diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 1d76f911943..5e44de13b51 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -518,7 +518,7 @@ end-to-end: - $CI_COMMIT_MESSAGE =~ /skip-end-to-end-tests/ ``` -Learn more about [variables expressions](../variables/README.md#variables-expressions). +Learn more about [variables expressions](../variables/README.md#environment-variables-expressions). #### `only:changes`/`except:changes` @@ -2249,7 +2249,7 @@ Runner itself](../variables/README.md#predefined-environment-variables). One example would be `CI_COMMIT_REF_NAME` which has the value of the branch or tag name for which project is built. Apart from the variables you can set in `.gitlab-ci.yml`, there are also the so called -[Variables](../variables/README.md#variables) +[Variables](../variables/README.md#gitlab-cicd-environment-variables) which can be set in GitLab's UI. Learn more about [variables and their priority][variables]. diff --git a/doc/development/contributing/index.md b/doc/development/contributing/index.md index b39c302453b..8b1d014e101 100644 --- a/doc/development/contributing/index.md +++ b/doc/development/contributing/index.md @@ -3,9 +3,6 @@ Thank you for your interest in contributing to GitLab. This guide details how to contribute to GitLab in a way that is easy for everyone. -We want to create a welcoming environment for everyone who is interested in contributing. -Please visit our [Code of Conduct page](https://about.gitlab.com/contributing/code-of-conduct) to learn more about our commitment to an open and welcoming environment. - For a first-time step-by-step guide to the contribution process, please see ["Contributing to GitLab"](https://about.gitlab.com/contributing/). @@ -33,8 +30,8 @@ vulnerabilities. ## Code of conduct -Our code of conduct can be found on the -["Contributing to GitLab"](https://about.gitlab.com/contributing/) page. +We want to create a welcoming environment for everyone who is interested in contributing. +Please visit our [Code of Conduct page](https://about.gitlab.com/community/contribute/code-of-conduct/) to learn more about our commitment to an open and welcoming environment. ## Closing policy for issues and merge requests diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index a4da34a50ce..4a2ff64807e 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -48,29 +48,21 @@ as its markdown rendering engine. See the [GitLab Markdown Guide](https://about. Adhere to the [Documentation Style Guide](styleguide.md). If a style standard is missing, you are welcome to suggest one via a merge request. -## Documentation directory structure +## Documentation types and organization The documentation is structured based on the GitLab UI structure itself, separated by [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), [`administrator`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`contributor`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development). -In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, -all docs should be linked. Every new document should be cross-linked to its related documentation, and linked from its topic-related index, when existent. - -The directories `/workflow/`, `/gitlab-basics/`, `/university/`, and `/articles/` have -been **deprecated** and the majority their docs have been moved to their correct location -in small iterations. Please do not create new docs in these folders. Organize docs by product area and subject, not type. +Organize docs by product area and subject, not type. For example, do not create groupings of similar media types +(e.g. indexes of all articles, videos, etc.). -### Documentation files - -- When you create a new directory, always start with an `index.md` file. - Do not use another file name and **do not** create `README.md` files. -- **Do not** use special chars and spaces, or capital letters in file names, - directory names, branch names, and anything that generates a path. -- Max screenshot size: 100KB. -- We do not support videos (yet). +Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes +it difficult to browse for the information you need and difficult to maintain up-to-date content. +Instead, organize content by its subject (e.g. everything related to CI goes together) +and cross-link between any related content. -### Location and naming documents +### Location and naming of files Our goal is to have a clear hierarchical structure with meaningful URLs like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, @@ -78,16 +70,8 @@ you can immediately tell that you are navigating to user-related documentation about project features; specifically about merge requests. Our site's paths match those of our repository, so the clear structure also makes documentation easier to update. -While the documentation is home to a variety of content types, we do not organize by content type. -For example, do not create groupings of similar media types (e.g. indexes of all articles, videos, etc.). -Similarly, we do not use glossaries or FAQs. Such grouping of content by type makes -it difficult to browse for the information you need and difficult to maintain up-to-date content. -Instead, organize content by its subject (e.g. everything related to CI goes together) -and cross-link between any related content. - -Do not simply link out to GitLab technical blog posts. There should be an up-to-date -single source of truth on the topic within the documentation, and the top of the -blog post should be updated to link to that doc. +In order to have a [solid site structure](https://searchengineland.com/seo-benefits-developing-solid-site-structure-277456) for our documentation, +all docs should be linked at least from its higher-level index page if not also from other relevant locations. The table below shows what kind of documentation goes where. @@ -102,13 +86,18 @@ The table below shows what kind of documentation goes where. | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | | `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | -**General rules & best practices:** +**Rules and best practices:** +1. When you create a new directory, always start with an `index.md` file. + Do not use another file name and **do not** create `README.md` files. +1. **Do not** use special chars and spaces, or capital letters in file names, + directory names, branch names, and anything that generates a path. 1. When creating a new document and it has more than one word in its name, make sure to use underscores instead of spaces or dashes (`-`). For example, a proper naming would be `import_projects_from_github.md`. The same rule applies to images. -1. Start a new directory with an `index.md` file. +1. For image files, do not exceed 100KB. +1. We do not yet support embedded videos. Please link out. 1. There are four main directories, `user`, `administration`, `api` and `development`. 1. The `doc/user/` directory has five main subdirectories: `project/`, `group/`, `profile/`, `dashboard/` and `admin_area/`. @@ -129,6 +118,9 @@ The table below shows what kind of documentation goes where. 1. The `doc/topics/` directory holds topic-related technical content. Create `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. General user- and admin- related documentation, should be placed accordingly. +1. The directories `/workflow/`, `/university/`, and `/articles/` have +been **deprecated** and the majority their docs have been moved to their correct location +in small iterations. If you are unsure where a document or a content addition should live, this should not stop you from authoring and contributing. You can use your best judgment and diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index c0386290785..1cefe48b4c1 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -14,9 +14,8 @@ For programmatic help adhering to the guidelines, see [linting](index.md#linting ## Files -- [Directory structure](index.md#location-and-naming-documents): place the docs - in the correct location. -- [Documentation files](index.md#documentation-files): name the files accordingly. +See the [Documentation types and organization](index.md#documentation-types-and-organization) section +on the index page for information on how to structure and name files across the GitLab documentation. DANGER: **Attention:** **Do not** use capital letters, spaces, or special chars in file names, @@ -28,41 +27,43 @@ a test that will fail if it spots a new `README.md` file. ### Markdown -The [documentation website](https://docs.gitlab.com) had its markdown engine migrated from [Redcarpet to GitLab Kramdown](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108) -in October 2018. +The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its Markdown rendering engine [as of October 2018](https://gitlab.com/gitlab-com/gitlab-docs/merge_requests/108). For a complete Kramdown reference, see the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). The [`gitlab-kramdown`](https://gitlab.com/gitlab-org/gitlab_kramdown) gem will support all [GFM markup](../../user/markdown.md) in the future. For now, -use regular markdown markup, following the rules on this style guide. For a complete -Kramdown reference, check the [GitLab Markdown Kramdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/). -Use Kramdown markup wisely: do not overuse its specific markup (e.g., `{:.class}`) as it will not render properly in -[`/help`](index.md#gitlab-help). +use regular markdown markup, following the rules in the linked style guide. + +Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly in on GitLab instances in [`/help`](index.md#gitlab-help). ## Content These guidelines help toward the goal of having every user's search of documentation yield a useful result, and ensuring content is helpful and easy to consume. -- What to include: - - Any and all helpful information, processes, and tips for implementing, - using, and troubleshooting GitLab features. [The documentation is the single source of truth](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) - for this information. - - 'Risky' or niche problem-solving steps. There is no reason to withhold these or - store them elsewhere; simply include them along with the rest of the docs including all necessary - detail, such as specific warnings and caveats about potential ramifications. - - Any content types/sources, if relevant to users or admins. You can freely - include presentations, videos, etc.; no matter who it was originally written for, - if it is helpful to any of our audiences, we can include it. If an outside source - that's under copyright, rephrase, or summarize and link out; do not copy and paste. - - All applicable subsections as described on the [structure and template](structure.md) page, - with files organized in the [correct directory](index.md#documentation-directory-structure). +### Subject matter + +[The documentation is the single source of truth (SSOT)](https://about.gitlab.com/handbook/documentation/#documentation-as-single-source-of-truth-ssot) for any and all helpful information and processes needed to learn about, implement, use, and troubleshoot GitLab features. Note that this includes problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided. See the SSOT link for more detail. + +### Media types and sources + +Include any media types/sources, if relevant to readers. You can freely include or link presentations, diagrams, videos, etc.; no matter who it was originally composed for, if it is helpful to any of our audiences, we can include it. + + - If you use an image that has a separate source file (for example, a vector or diagram format), link the image to the source file so that it may be reused or updated by anyone. + - Do not copy and paste content from other sources unless it is a limited quotation with the source cited. Typically it is better to either rephrase relevant information in your own words or link out to the other source. + +### Structure across documents + +- Place files in the correct directory per the [Documentation directory structure](index.md#documentation-types-and-organization) guidelines. +- To avoid duplication, do not include the same information in multiple places. Instead, choose one 'single source of truth (SSOT)' location and link from other relevant locations. +- When referencing other GitLab products and features, link to their respective docs. +- When referencing third-party products or technologies, link out to their external sites, documentation, and resources. + +### Structure within documents + +- Include any and all applicable subsections as described on the [structure and template](structure.md) page, - To ensure discoverability, link to each doc from its higher-level index page and other related pages. -- When referencing other GitLab products and features, link to their - respective docs; when referencing third-party products or technologies, - link out to their external sites, documentation, and resources. -- Do not duplicate information. - Structure content in alphabetical order in tables, lists, etc., unless there is - a logical reason not to (for example, when mirroring the UI or an ordered sequence). + a logical reason not to (for example, when mirroring the UI or an otherwise ordered sequence). ## Language diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 9452593c510..c5a1d915be6 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -19,6 +19,11 @@ CE specs should remain untouched as much as possible and extra specs should be added for EE. Licensed features can be stubbed using the spec helper `stub_licensed_features` in `EE::LicenseHelpers`. +You can force Webpack to act as CE by either deleting the `ee/` directory or by +setting the [`IS_GITLAB_EE` environment variable](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/config/helpers/is_ee_env.js) +to something that evaluates as `false`. The same works for running tests +(for example `IS_GITLAB_EE=0 yarn jest`). + [ee-as-ce]: https://gitlab.com/gitlab-org/gitlab-ee/issues/2500 ## Separation of EE code diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index a34d1fcec89..437ce9abc7d 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -38,7 +38,7 @@ _For consistency purposes, we recommend you to follow the same structure._ Let's look into each of them: -### A `index.js` file +### An `index.js` file This is the index file of your new feature. This is where the root Vue instance of the new feature should be. @@ -46,7 +46,7 @@ of the new feature should be. The Store and the Service should be imported and initialized in this file and provided as a prop to the main component. -Don't forget to follow [these steps][page_specific_javascript]. +Be sure to read about [page-specific JavaScript][page_specific_javascript]. ### Bootstrapping Gotchas #### Providing data from HAML to JavaScript @@ -240,7 +240,7 @@ One should apply to be a Vue.js expert by opening an MR when the Merge Request's [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards [environments-table]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/environments -[page_specific_javascript]: https://docs.gitlab.com/ce/development/frontend.html#page-specific-javascript +[page_specific_javascript]: ./performance.md#page-specific-javascript [component-system]: https://vuejs.org/v2/guide/#Composing-with-Components [state-management]: https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch [one-way-data-flow]: https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow diff --git a/doc/development/fe_guide/vuex.md b/doc/development/fe_guide/vuex.md index 7b54fa6289c..7d52cac5f7e 100644 --- a/doc/development/fe_guide/vuex.md +++ b/doc/development/fe_guide/vuex.md @@ -83,7 +83,7 @@ In this file, we will write the actions that will call the respective mutations: export const requestUsers = ({ commit }) => commit(types.REQUEST_USERS); export const receiveUsersSuccess = ({ commit }, data) => commit(types.RECEIVE_USERS_SUCCESS, data); - export const receiveUsersError = ({ commit }, error) => commit(types.REQUEST_USERS_ERROR, error); + export const receiveUsersError = ({ commit }, error) => commit(types.RECEIVE_USERS_ERROR, error); export const fetchUsers = ({ state, dispatch }) => { dispatch('requestUsers'); @@ -175,7 +175,7 @@ Remember that actions only describe that something happened, they don't describe state.users = data; state.isLoading = false; }, - [types.REQUEST_USERS_ERROR](state, error) { + [types.RECEIVE_USERS_ERROR](state, error) { state.isLoading = false; }, [types.REQUEST_ADD_USER](state, user) { diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 27b69ba8278..bfde26dbe4a 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -6,7 +6,7 @@ Workhorse and GitLab-Shell. ## Beginner's guide Start by reading the gitaly repository's -[Beginner's guide to Gitaly contributions](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/beginners_guide.md). +[Beginner's guide to Gitaly contributions](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/beginners_guide.md). It describes how to setup gitaly, the various components of gitaly and what they do, and how to run its test suites. ## Developing new Git features @@ -192,7 +192,7 @@ GITALY_REPO_URL=https://gitlab+deploy-token-1000:token-here@gitlab.com/nick.thom To use a custom Gitaly repository in CI, for instance if you want your GitLab fork to always use your own Gitaly fork, set `GITALY_REPO_URL` -as a [CI environment variable](../ci/variables/README.md#variables). +as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment-variables). --- diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 7262c04d746..e41148360f2 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -216,8 +216,10 @@ project, one project will do for the entire file. This can be achieved by using reloads or recreates the model, _only_ if needed. That is, when you changed properties or destroyed the object. -There is one gotcha; you can't reference a model defined in a `let` block in a -`set` block. +Note that you can't reference a model defined in a `let` block in a `set` block. + +Also, `set` is not supported in `:js` specs since those don't use transactions +to clean up database state after each example. ### Time-sensitive tests diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md index 818a03a6f02..6e2a09fc030 100644 --- a/doc/gitlab-basics/create-issue.md +++ b/doc/gitlab-basics/create-issue.md @@ -1,5 +1,5 @@ --- -redirect_to: '../user/project/issues/index.md#new-issue' +redirect_to: '../user/project/issues/index.md#issue-actions' --- -This document was moved to [another location](../user/project/issues/index.md#new-issue). +This document was moved to [another location](../user/project/issues/index.md#issue-actions). diff --git a/doc/gitlab-basics/fork-project.md b/doc/gitlab-basics/fork-project.md index 6c232fe6086..a128a7c7dd3 100644 --- a/doc/gitlab-basics/fork-project.md +++ b/doc/gitlab-basics/fork-project.md @@ -1,8 +1,8 @@ # How to fork a project -A fork is a copy of an original repository that you can put in another namespace -where you can experiment and apply changes that you can later decide if -publishing or not, without affecting your original project. +A fork is a copy of an original repository that you put in another namespace +where you can experiment and apply changes that you can later decide whether or +not to share, without affecting the original project. It takes just a few steps to fork a project in GitLab. diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 574ba961cb0..56db7b5eb3a 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -409,7 +409,7 @@ an access key from the Google console first: 1. Select "Interoperability" and create an access key 1. Make note of the "Access Key" and "Secret" and replace them in the configurations below -1. In the buckets advanced settings ensure the Access Control option "Set object-level +1. In the buckets advanced settings ensure the Access Control option "Set object-level and bucket-level permissions" is selected 1. Make sure you already have a bucket created @@ -632,7 +632,7 @@ directory (repositories, uploads). To restore a backup, you will also need to restore `/etc/gitlab/gitlab-secrets.json` (for Omnibus packages) or `/home/git/gitlab/.secret` (for installations from source). This file contains the database encryption key, -[CI/CD variables](../ci/variables/README.md#variables), and +[CI/CD variables](../ci/variables/README.md#gitlab-cicd-environment-variables), and variables used for [two-factor authentication](../user/profile/account/two_factor_authentication.md). If you fail to restore this encryption key file along with the application data backup, users with two-factor authentication enabled and GitLab Runners will @@ -848,15 +848,24 @@ including (but not restricted to): * [Project mirroring](../workflow/repository_mirroring.md) * [Web hooks](../user/project/integrations/webhooks.md) -In the case of CI/CD, variables, you might experience some weird behavior, like -stuck jobs or 500 errors. In that case, you can try removing contents of the -`ci_group_variables` and `ci_project_variables` tables from the database. +In cases like CI/CD variables and Runner authentication, you might +experience some unexpected behavior such as: + +- Stuck jobs. +- 500 errors. + +In this case, you are required to reset all the tokens for CI/CD variables +and Runner Authentication, which is described in more detail below. After +resetting the tokens, you should be able to visit your project and the jobs +will have started running again. CAUTION: **Warning:** Use the following commands at your own risk, and make sure you've taken a backup beforehand. -1. Enter the Rails console: +#### Reset CI/CD variables + +1. Enter the DB console: For Omnibus GitLab packages: @@ -889,8 +898,39 @@ backup beforehand. 1. You may need to reconfigure or restart GitLab for the changes to take effect. -You should now be able to visit your project, and the jobs will start -running again. + +#### Reset Runner registration tokens + +1. Enter the DB console: + + For Omnibus GitLab packages: + + ```sh + sudo gitlab-rails dbconsole + ``` + + For installations from source: + + ```sh + sudo -u git -H bundle exec rails dbconsole RAILS_ENV=production + ``` + +1. Clear all the tokens for projects, groups, and the whole instance: + +CAUTION: **Caution:** +The last UPDATE operation will stop the runners being able to pick up +new jobs. You must register new runners. + + ```sql + -- Clear project tokens + UPDATE projects SET runners_token = null, runners_token_encrypted = null; + -- Clear group tokens + UPDATE namespaces SET runners_token = null, runners_token_encrypted = null; + -- Clear instance tokens + UPDATE application_settings SET runners_registration_token_encrypted = null; + -- Clear runner tokens + UPDATE ci_runners SET token = null, token_encrypted = null; + ``` A similar strategy can be employed for the remaining features - by removing the data that cannot be decrypted, GitLab can be brought back into working order, diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 9060360e6a2..1df492ba82c 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -141,7 +141,7 @@ in any of the following places: NOTE: **Note** The Auto DevOps base domain variable (`KUBE_INGRESS_BASE_DOMAIN`) follows the same order of precedence -as other environment [variables](../../ci/variables/README.md#priority-of-variables). +as other environment [variables](../../ci/variables/README.md#priority-of-environment-variables). A wildcard DNS A record matching the base domain(s) is required, for example, given a base domain of `example.com`, you'd need a DNS entry like: @@ -669,7 +669,7 @@ repo or by specifying a project variable: file in it, Auto DevOps will detect the chart and use it instead of the [default one](https://gitlab.com/charts/auto-deploy-app). This can be a great way to control exactly how your application is deployed. -- **Project variable** - Create a [project variable](../../ci/variables/README.md#variables) +- **Project variable** - Create a [project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) `AUTO_DEVOPS_CHART` with the URL of a custom chart to use or create two project variables `AUTO_DEVOPS_CHART_REPOSITORY` with the URL of a custom chart repository and `AUTO_DEVOPS_CHART` with the path to the chart. ### Custom Helm chart per environment **[PREMIUM]** @@ -770,7 +770,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac TIP: **Tip:** Set up the replica variables using a -[project variable](../../ci/variables/README.md#variables) +[project variable](../../ci/variables/README.md#gitlab-cicd-environment-variables) and scale your application by just redeploying it! CAUTION: **Caution:** diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index 1906655dfa5..01d5073ab7e 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -83,7 +83,7 @@ our newly created VPC. ### Internet Gateway Now still on the same dashboard head over to Internet Gateways and -create a new one. After its created pres on the `Attach to VPC` button and +create a new one. After its created press on the `Attach to VPC` button and select our VPC.  diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 9c3f6fcec9b..74735886350 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -58,7 +58,7 @@ By doing so: ## Issues and merge requests within a group Issues and merge requests are part of projects. For a given group, view all the -[issues](../project/issues/index.md#issues-per-group) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all the projects in that group, +[issues](../project/issues/index.md#issues-list) and [merge requests](../project/merge_requests/index.md#merge-requests-per-group) across all the projects in that group, together in a single list view. ## Create a new group diff --git a/doc/user/index.md b/doc/user/index.md index d408504249e..626246447f3 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -38,8 +38,8 @@ GitLab is a Git-based platform that integrates a great number of essential tools - Hosting code in repositories with version control. - Tracking proposals for new implementations, bug reports, and feedback with a - fully featured [Issue Tracker](project/issues/index.md#issue-tracker). -- Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-board). + fully featured [Issue Tracker](project/issues/index.md#issues-list). +- Organizing and prioritizing with [Issue Boards](project/issues/index.md#issue-boards). - Reviewing code in [Merge Requests](project/merge_requests/index.md) with live-preview changes per branch with [Review Apps](../ci/review_apps/index.md). - Building, testing, and deploying with built-in [Continuous Integration](../ci/README.md). diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 8239742969a..9891a43aa61 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -578,11 +578,11 @@ Alt-H2 ------ ``` -### Header IDs and links +#### Header IDs and links -All Markdown-rendered headers automatically get IDs, except in comments. +All Markdown-rendered headers automatically get IDs, which can be linked to, except in comments. -On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to give it to someone else. +On hover, a link to those IDs becomes visible to make it easier to copy the link to the header to use it somewhere else. The IDs are generated from the content of the header according to the following rules: @@ -609,8 +609,8 @@ Would generate the following link IDs: 1. `this-header-has-spaces-in-it` 1. `this-header-has-a-in-it` 1. `this-header-has-unicode-in-it-한글` -1. `this-header-has-spaces-in-it` 1. `this-header-has-spaces-in-it-1` +1. `this-header-has-spaces-in-it-2` 1. `this-header-has-3-5-in-it-and-parentheses` Note that the Emoji processing happens before the header IDs are generated, so the Emoji is converted to an image which then gets removed from the ID. @@ -715,25 +715,25 @@ Becomes: There are two ways to create links, inline-style and reference-style. - [I'm an inline-style link](https://www.google.com) - - [I'm a reference-style link][Arbitrary case-insensitive reference text] - - [I'm a relative reference to a repository file](LICENSE) - - [I am an absolute reference within the repository](/doc/user/markdown.md) - - [I link to the Milestones page](/../milestones) +```markdown +[I'm an inline-style link](https://www.google.com) +[I'm a link to a repository file in the same directory](index.md) +[I am an absolute reference within the repository](/doc/user/index.md) +[I'm a relative link to the Milestones page](../README.md) - [You can use numbers for reference-style link definitions][1] +[I link to a section on a different markdown page, using a header ID](index.md#overview) +[I link to a different section on the same page, using the header ID](#header-ids-and-links) - Or leave it empty and use the [link text itself][] +[I'm a reference-style link][Arbitrary case-insensitive reference text] +[You can use numbers for reference-style link definitions][1] +Or leave it empty and use the [link text itself][] - Some text to show that the reference links can follow later. +Some text to show that the reference links can follow later. - [arbitrary case-insensitive reference text]: https://www.mozilla.org - [1]: http://slashdot.org - [link text itself]: https://www.reddit.com +[arbitrary case-insensitive reference text]: https://www.mozilla.org +[1]: http://slashdot.org +[link text itself]: https://www.reddit.com +``` >**Note:** Relative links do not allow referencing project files in a wiki page or wiki diff --git a/doc/user/profile/index.md b/doc/user/profile/index.md index b216b9f255c..61a30a775b0 100644 --- a/doc/user/profile/index.md +++ b/doc/user/profile/index.md @@ -33,6 +33,7 @@ From there, you can: - Set a [custom status](#current-status) for your profile - Manage your [commit email](#commit-email) for your profile - Manage [2FA](account/two_factor_authentication.md) +- Add details of [external accounts](#add-details-of-external-accounts). - Change your username and [delete your account](account/delete_account.md) - Manage applications that can [use GitLab as an OAuth provider](../../integration/oauth_provider.md#introduction-to-oauth) @@ -92,6 +93,16 @@ To enable private profile: NOTE: **Note:** You and GitLab admins can see your the abovementioned information on your profile even if it is private. +## Add details of external accounts + +GitLab allows you to add links to certain other external accounts you might have, like Skype and Twitter. They can help other users connect with you on other platforms. + +To add links to other accounts: + +1. Navigate to your **User Settings > Profile**. +1. In the **Main settings** section, locate and fill out fields for links to external accounts like Skype and Twitter. +1. Click the **Update profile settings** button. + ## Private contributions > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/14078) in GitLab 11.3. diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 878d30dddaa..1983513174c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -314,7 +314,7 @@ install it manually. ## Installing applications -GitLab provides a one-click install for various applications which can +GitLab provides **GitLab Managed Apps**, a one-click install for various applications which can be added directly to your configured cluster. Those applications are needed for [Review Apps](../../../ci/review_apps/index.md) and [deployments](../../../ci/environments.md). You can install them after you @@ -545,7 +545,7 @@ The result will then be: ## Deployment variables The Kubernetes cluster integration exposes the following -[deployment variables](../../../ci/variables/README.md#deployment-variables) in the +[deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the GitLab CI/CD build environment. | Variable | Description | @@ -573,7 +573,7 @@ However, sometimes GitLab can not create them. In such instances, your job will This job failed because the necessary resources were not successfully created. ``` -To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#sidekiqlog). +To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). Common reasons for failure include: diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index ca19ce4d328..ad47b848bea 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -42,7 +42,7 @@ below. ## How it works The Issue Board builds on GitLab's existing -[issue tracking functionality](issues/index.md#issue-tracker) and +[issue tracking functionality](issues/index.md#issues-list) and leverages the power of [labels](labels.md) by utilizing them as lists of the scrum board. With the Issue Board you can have a different view of your issues while diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index 40040e44d64..9a147deecd4 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -7,7 +7,7 @@ the information illustrated on the image below.  -Read through the [issues functionalities documentation](issues_functionalities.md#issues-functionalities) +Read through the [issue data and actions documentation](issue_data_and_actions.md#parts-of-an-issue) to understand these fields one by one. ## New issue from the Issue Tracker diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 675c280a12a..c82b7f100d2 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -1,170 +1,135 @@ # Issues -The GitLab Issue Tracker is an advanced and complete tool -for tracking the evolution of a new idea or the process -of solving a problem. +Issues are the fundamental medium for collaborating on ideas and planning work in GitLab. -It allows you, your team, and your collaborators to share -and discuss proposals before and while implementing them. +## Overview -GitLab Issues and the GitLab Issue Tracker are available in all -[GitLab Products](https://about.gitlab.com/pricing/) as -part of the [GitLab Workflow](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/). +The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, and planning work. -## Use cases +Issues can allow you, your team, and your collaborators to share and discuss proposals before and during their implementation. +However, they can be used for a variety of other purposes, customized to your needs and workflow. -Issues can have endless applications. Just to exemplify, these are -some cases for which creating issues are most used: +Issues are always associated with a specific project, but if you have multiple projects in a group, +you can also view all the issues collectively at the group level. + +**Common use cases include:** - Discussing the implementation of a new idea -- Submitting feature proposals -- Asking questions -- Reporting bugs and malfunction -- Obtaining support +- Tracking tasks and work status +- Accepting feature proposals, questions, support requests, or bug reports - Elaborating new code implementations See also the blog post "[Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)". -### Keep private things private - -For instance, let's assume you have a public project but want to start a discussion on something -you don't want to be public. With [Confidential Issues](#confidential-issues), -you can discuss private matters among the project members, and still keep -your project public, open to collaboration. - -### Streamline collaboration - -With [Multiple Assignees for Issues](https://docs.gitlab.com/ee/user/project/issues/multiple_assignees_for_issues.html), -available in [GitLab Starter](https://about.gitlab.com/pricing/) -you can streamline collaboration and allow shared responsibilities to be clearly displayed. -All assignees are shown across your workflows and receive notifications (as they -would as single assignees), simplifying communication and ownership. - -### Consistent collaboration - -Create [issue templates](#issue-templates) to make collaboration consistent and -containing all information you need. For example, you can create a template -for feature proposals and another one for bug reports. - -## Issue Tracker - -The Issue Tracker is the collection of opened and closed issues created in a project. -It is available for all projects, from the moment the project is created. - -Find the issue tracker by navigating to your **Project's homepage** > **Issues**. - -### Issues per project - -When you access your project's issues, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed issues. - - - -You can also [search and filter](../../search/index.md#issues-and-merge-requests-per-project) the results more deeply with GitLab's search capacities. - -### Issues per group - -View issues in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Issues** to view these issues. This view also has the open and closed issues tabs. - - - -## GitLab Issues Functionalities - -The image bellow illustrates how an issue looks like: +## Parts of an issue + +Issues contain a variety of content and metadata, enabling a large range of flexibility in how they are used. Each issue can contain the following attributes, though some items may remain unset. + +<table class="borderless-table fixed-table"> +<tr> + <td> + <ul> + <li>Content</li> + <ul> + <li>Title</li> + <li>Description and tasks</li> + <li>Comments and other activity</li> + </ul> + <li>People</li> + <ul> + <li>Author</li> + <li>Assignee(s)</li> + </ul> + <li>State</li> + <ul> + <li>Status (open/closed)</li> + <li>Confidentiality</li> + <li>Tasks (completed vs. outstanding)</li> + </ul> + </ul> + </td> + <td> + <ul> + <li>Planning and tracking</li> + <ul> + <li>Milestone</li> + <li>Due date</li> + <li>Weight</li> + <li>Time tracking</li> + <li>Labels</li> + <li>Votes</li> + <li>Reaction emoji</li> + <li>Linked issues</li> + <li>Assigned epic</li> + <li>Unique issue number and URL</li> + </ul> + </ul> + </td> +</tr> +</table> + +## Viewing and managing issues + +While you can view and manage the full detail of an issue at its URL, you can also work with multiple issues at a time using the Issues List, Issue Boards, Epics **[ULTIMATE]**, and issue references. + +### Issue page  -Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md). - -## New issue +On an issue’s page, you can view all aspects of the issue, and you can also modify them if you you have the necessary [permissions](../../permissions.md). -Read through the [documentation on creating issues](create_new_issue.md). +For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page. -## Closing issues +### Issues list -Learn distinct ways to [close issues](closing_issues.md) in GitLab. - -## Moving issues - -Read through the [documentation on moving issues](moving_issues.md). - -## Deleting issues + -Read through the [documentation on deleting issues](deleting_issues.md) +On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the issue list by [any search query](../../search/index.md#issues-and-merge-requests-per-project) and/or specific metadata, such as label(s), assignees(s), status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. -## Create a merge request from an issue +For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page. -Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md#18-new-merge-request). +### Issue boards -## Search for an issue + -Learn how to [find an issue](../../search/index.md) by searching for and filtering them. +Issue boards are Kanban boards with columns that display issues based on their labels or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using highly customizable workflows. -## Advanced features +You can reorder issues within a column, or drag an issue card to another column; its associated label or assignee will change to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label. -### Confidential Issues +For more information, see the [Issue Boards](../issue_board.md) page. -Whenever you want to keep the discussion presented in a -issue within your team only, you can make that -[issue confidential](confidential_issues.md). Even if your project -is public, that issue will be preserved. The browser will -respond with a 404 error whenever someone who is not a project -member with at least [Reporter level](../../permissions.md#project-members-permissions) tries to -access that issue's URL. +### Epics **[ULTIMATE]** -Learn more about them on the [confidential issues documentation](confidential_issues.md). +Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones. -### Issue templates +For more information, see the [Epics](https://docs.gitlab.com/ee/user/group/epics/) page. -Create templates for every new issue. They will be available from -the dropdown menu **Choose a template** when you create a new issue: +### Related issues **[STARTER]** - +You can mark two issues as related, so that when viewing each one, the other is always listed in its Related Issues section. This can help display important context, such as past work, dependencies, or duplicates. -Learn more about them on the [issue templates documentation](../../project/description_templates.md#creating-issue-templates). +For more information, see [Related Issues](https://docs.gitlab.com/ee/user/project/issues/related_issues.html). ### Crosslinking issues -Learn more about [crosslinking](crosslinking_issues.md) issues and merge requests. - -### Issue Board - -The [GitLab Issue Board](https://about.gitlab.com/features/issueboard/) is a way to -enhance your workflow by organizing and prioritizing issues in GitLab. - - - -Find GitLab Issue Boards by navigating to your **Project's Dashboard** > **Issues** > **Board**. - -Read through the documentation for [Issue Boards](../issue_board.md) -to find out more about this feature. - -With [GitLab Starter](https://about.gitlab.com/pricing/), you can also -create various boards per project with [Multiple Issue Boards](../issue_board.html#multiple-issue-boards-starter). - -### Import Issues from CSV - -You can import a CSV file containing issue titles and descriptions to create -a batch of issues simultaneously. - -When you navigate to the Issues list page, an import button is displayed. - -For further details, see [Importing issues from CSV](csv_import.md) - -### External Issue Tracker - -Alternatively to GitLab's built-in Issue Tracker, you can also use an [external -tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, -YouTrack, or Bugzilla. - -### Issue API +When you reference an issue from another issue or merge request by including its URL or ID, the referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR. -See the [API documentation](../../../api/issues.md). +For more information, see [Crosslinking issues](crosslinking_issues.md). -### Bulk editing issues +## Issue actions -See the [bulk editing issues](../../project/bulk_editing.md) page. +- [Create an issue](create_new_issue.md) +- [Create an issue from a template](../../project/description_templates.md#using-the-templates) +- [Close an issue](closing_issues.md) +- [Move an issue](moving_issues.md) +- [Delete an issue](deleting_issues.md) +- [Create a merge request from an issue](issue_data_and_actions.md#18-new-merge-request) -### Similar issues +## Advanced issue management -See the [similar issues](similar_issues.md) page. +- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk. +- [Import issues](csv_import.md) +- [Export issues](https://docs.gitlab.com/ee/user/project/issues/csv_export.html) **[STARTER]** +- [Issues API](../../../api/issues.md) +- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, +or Bugzilla. diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issue_data_and_actions.md index 27b9dc51760..653bd94e513 100644 --- a/doc/user/project/issues/issues_functionalities.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -1,8 +1,8 @@ -# GitLab Issues Functionalities +# Issue Data and Actions Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. -## Issues Functionalities +## Parts of an Issue The image below illustrates what an issue looks like: @@ -77,7 +77,7 @@ can be changed as many times as needed. Categorize issues by giving them [labels](../labels.md). They help to organize workflows, and they enable you to work with the -[GitLab Issue Board](index.md#issue-board). +[GitLab Issue Board](index.md#issue-boards). Group Labels, which allow you to use the same labels for a group of projects, can be also given to issues. They work exactly the same, diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 01a3a5bbbe1..ba7d05a7ad7 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -219,6 +219,64 @@ apply the patches. The target branch can be specified using the [`/target_branch` quick action](../quick_actions.md). If the source branch already exists, the patches will be applied on top of it. +## Git push options + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26752) in GitLab 11.10. + +NOTE: **Note:** +Git push options are only available with Git 2.10 or newer. + +GitLab supports using +[Git push options](https://git-scm.com/docs/git-push#Documentation/git-push.txt--oltoptiongt) +to perform the following actions against merge requests at the same time +as pushing changes: + +- Create a new merge request for the pushed branch. +- Set the target of the merge request to a particular branch. +- Set the merge request to merge when its pipeline succeeds. + +### Create a new merge request using git push options + +To create a new merge request for a branch, use the +`merge_request.create` push option: + +```sh +git push -o merge_request.create +``` + +### Set the target branch of a merge request using git push options + +To update an existing merge request's target branch, use the +`merge_request.target=<branch_name>` push option: + +```sh +git push -o merge_request.target=branch_name +``` + +You can also create a merge request and set its target branch at the +same time using a `-o` flag per push option: + +```sh +git push -o merge_request.create -o merge_request.target=branch_name +``` + +### Set merge when pipeline succeeds using git push options + +To set an existing merge request to +[merge when its pipeline succeeds](merge_when_pipeline_succeeds.md), use +the `merge_request.merge_when_pipeline_succeeds` push option: + +```sh +git push -o merge_request.merge_when_pipeline_succeeds +``` + +You can also create a merge request and set it to merge when its +pipeline succeeds at the same time using a `-o` flag per push option: + +```sh +git push -o merge_request.create -o merge_request.merge_when_pipeline_succeeds +``` + ## Find the merge request that introduced a change > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2383) in GitLab 10.5. @@ -254,7 +312,7 @@ To prevent merge requests from accidentally being accepted before they're completely ready, GitLab blocks the "Accept" button for merge requests that have been marked as a **Work In Progress**. -[Learn more about settings a merge request as "Work In Progress".](work_in_progress_merge_requests.md) +[Learn more about setting a merge request as "Work In Progress".](work_in_progress_merge_requests.md) ## Merge request diff file navigation diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index ba57b61f70a..9f2bc281f85 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -115,6 +115,8 @@ If using a [DNS A record](#dns-a-record), you can place the TXT record directly under the domain. If using a [DNS CNAME record](#dns-cname-record), the two record types won't co-exist, so you need to place the TXT record in a special subdomain of its own. +If the domain cannot be verified for 7 days, it will be removed from the GitLab project. + #### TL;DR For root domains (`domain.com`), set a DNS `A` record and verify your @@ -149,7 +151,7 @@ verify your domain's ownership with a TXT record: Once you've set the DNS record, you'll need navigate to your project's **Setting > Pages** and click **+ New domain** to add your custom domain to GitLab Pages. You can choose whether to add an [SSL/TLS certificate](#ssltls-certificates) -to make your website accessible under HTTPS or leave it blank. If don't add a certificate, +to make your website accessible under HTTPS or leave it blank. If you don't add a certificate, your site will be accessible only via HTTP:  diff --git a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md index f639188684b..ea22f3e905b 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -134,14 +134,14 @@ Now that your certificate has been issued, let's add it to your Pages site: sudo cat /etc/letsencrypt/live/example.com/fullchain.pem | pbcopy ``` -1. Copy and paste the public key into the second field **Key (PEM)**: +1. Copy and paste the private key into the second field **Key (PEM)**: ```bash sudo cat /etc/letsencrypt/live/example.com/privkey.pem | pbcopy ``` 1. Click **Save changes** to apply them to your website. -1. Wait a few minutes for DNS propagation. +1. Wait a few minutes for the configuration changes to take effect. 1. Visit your website at `https://example.com`. To force `https` connections on your site, navigate to your diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 4a989afad4d..8b762307ac4 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -182,4 +182,4 @@ https://example.gitlab.com/<namespace>/<project>/badges/<branch>/coverage.svg?st ## Environment Variables -[Environment variables](../../../ci/variables/README.html#variables) can be set in an environment to be available to a runner. +[Environment variables](../../../ci/variables/README.html#gitlab-cicd-environment-variables) can be set in an environment to be available to a runner. |
