diff options
Diffstat (limited to 'doc')
79 files changed, 1203 insertions, 898 deletions
diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md index 15276d364a0..8d81b32e721 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md @@ -145,7 +145,7 @@ Securing LDAP (enabling LDAPS) on Windows Server 2012 involves installing a vali > By default a LDAP service listens for connections on TCP and UDP port 389. LDAPS (LDAP over SSL) listens on port 636 -### Testing you AD server +### Testing your AD server #### Using **AdFind** (Windows) diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index f406163aea0..72341a5c777 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -145,7 +145,6 @@ mountpoint └── gitlab-data ├── builds ├── git-data - ├── home-git ├── shared └── uploads ``` @@ -158,16 +157,11 @@ configuration to move each data location to a subdirectory: ```ruby git_data_dirs({"default" => { "path" => "/gitlab-nfs/gitlab-data/git-data"} }) -user['home'] = '/gitlab-nfs/gitlab-data/home' gitlab_rails['uploads_directory'] = '/gitlab-nfs/gitlab-data/uploads' gitlab_rails['shared_path'] = '/gitlab-nfs/gitlab-data/shared' gitlab_ci['builds_directory'] = '/gitlab-nfs/gitlab-data/builds' ``` -To move the `git` home directory, all GitLab services must be stopped. Run -`gitlab-ctl stop && initctl stop gitlab-runsvdir`. Then continue with the -reconfigure. - Run `sudo gitlab-ctl reconfigure` to start using the central location. Please be aware that if you had existing data you will need to manually copy/rsync it to these new locations and then restart GitLab. @@ -197,14 +191,13 @@ are empty before attempting a restore. Read more about the ## Multiple NFS mounts -When using default Omnibus configuration you will need to share 5 data locations +When using default Omnibus configuration you will need to share 4 data locations between all GitLab cluster nodes. No other locations should be shared. The -following are the 5 locations need to be shared: +following are the 4 locations need to be shared: | Location | Description | Default configuration | | -------- | ----------- | --------------------- | | `/var/opt/gitlab/git-data` | Git repository data. This will account for a large portion of your data | `git_data_dirs({"default" => { "path" => "/var/opt/gitlab/git-data"} })` -| `/var/opt/gitlab/.ssh` | SSH `authorized_keys` file and keys used to import repositories from some other Git services | `user['home'] = '/var/opt/gitlab/'` | `/var/opt/gitlab/gitlab-rails/uploads` | User uploaded attachments | `gitlab_rails['uploads_directory'] = '/var/opt/gitlab/gitlab-rails/uploads'` | `/var/opt/gitlab/gitlab-rails/shared` | Build artifacts, GitLab Pages, LFS objects, temp files, etc. If you're using LFS this may also account for a large portion of your data | `gitlab_rails['shared_path'] = '/var/opt/gitlab/gitlab-rails/shared'` | `/var/opt/gitlab/gitlab-ci/builds` | GitLab CI build traces | `gitlab_ci['builds_directory'] = '/var/opt/gitlab/gitlab-ci/builds'` diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index f2ac155a694..222ac0b3ae1 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -96,13 +96,15 @@ To use an external Prometheus server: 1. Set each bundled service's [exporter](#bundled-software-metrics) to listen on a network address, for example: - ```ruby + ```ruby gitlab_monitor['listen_address'] = '0.0.0.0' + sidekiq['listen_address'] = '0.0.0.0' gitlab_monitor['listen_port'] = '9168' - gitaly['prometheus_listen_addr'] = "0.0.0.0:9236" node_exporter['listen_address'] = '0.0.0.0:9100' redis_exporter['listen_address'] = '0.0.0.0:9121' postgres_exporter['listen_address'] = '0.0.0.0:9187' + gitaly['prometheus_listen_addr'] = "0.0.0.0:9236" + gitlab_workhorse['prometheus_listen_addr'] = "0.0.0.0:9229" ``` 1. Install and set up a dedicated Prometheus instance, if necessary, using the [official installation instructions](https://prometheus.io/docs/prometheus/latest/installation/). @@ -112,6 +114,18 @@ To use an external Prometheus server: gitlab_rails['monitoring_whitelist'] = ['127.0.0.0/8', '192.168.0.1'] ``` +1. To scrape nginx metrics, you'll also need to configure nginx to allow the Prometheus server + IP. For example: + + ```ruby + nginx['status']['options'] = { + "server_tokens" => "off", + "access_log" => "off", + "allow" => "192.168.0.1", + "deny" => "all", + } + ``` + 1. [Reconfigure GitLab][reconfigure] to apply the changes 1. Edit the Prometheus server's configuration file. 1. Add each node's exporters to the Prometheus server's diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index 17d72b96a51..1373bd56fe3 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -174,6 +174,10 @@ behavior: 1. [Reconfigure GitLab][reconfigure]. +NOTE: **Note:** +`inplace_chroot` option might not work with the other features, such as [Pages Access Control](#access-control). +The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) has more information about caveats and workarounds. + ## Advanced configuration In addition to the wildcard domains, you can also have the option to configure diff --git a/doc/administration/repository_storage_types.md b/doc/administration/repository_storage_types.md index 4e1e363888d..88bf55296b2 100644 --- a/doc/administration/repository_storage_types.md +++ b/doc/administration/repository_storage_types.md @@ -110,7 +110,7 @@ enabled for all new projects. To start a migration, enable Hashed Storage for new projects: -1. Go to **Admin > Settings** and expand the **Repository Storage** section. +1. Go to **Admin > Settings > Repository** and expand the **Repository Storage** section. 2. Select the **Use hashed storage paths for newly created and renamed projects** checkbox. Check if the change breaks any existing integration you may have that @@ -138,7 +138,7 @@ source-based installation. Similar to the migration, to disable Hashed Storage for new projects: -1. Go to **Admin > Settings** and expand the **Repository Storage** section. +1. Go to **Admin > Settings > Repository** and expand the **Repository Storage** section. 2. Uncheck the **Use hashed storage paths for newly created and renamed projects** checkbox. To schedule a complete rollback, see the diff --git a/doc/api/discussions.md b/doc/api/discussions.md index 7d68d0ae744..67bbd4cc1ac 100644 --- a/doc/api/discussions.md +++ b/doc/api/discussions.md @@ -2,6 +2,15 @@ Discussions are set of related notes on snippets, issues, merge requests or commits. +This includes system notes, which are notes about changes to the object (for example, when a milestone changes, there will be a corresponding system note). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). + +## Discussions pagination + +By default, `GET` requests return 20 results at a time because the API results +are paginated. + +Read more on [pagination](README.md#pagination). + ## Issues ### List project issue discussions diff --git a/doc/api/notes.md b/doc/api/notes.md index dd4e18b14e6..dfde80c6441 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -2,6 +2,15 @@ Notes are comments on snippets, issues or merge requests. +This includes system notes, which are notes about changes to the object (for example, when a milestone changes, there will be a corresponding system note). Label notes are not part of this API, but recorded as separate events in [resource label events](resource_label_events.md). + +## Notes pagination + +By default, `GET` requests return 20 results at a time because the API results +are paginated. + +Read more on [pagination](README.md#pagination). + ## Issues ### List project issue notes diff --git a/doc/api/projects.md b/doc/api/projects.md index 0a950352ecf..951961e45ff 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -494,7 +494,9 @@ GET /projects/:id "name": "Diaspora", "path": "diaspora", "kind": "group", - "full_path": "diaspora" + "full_path": "diaspora", + "avatar_url": "http://localhost:3000/uploads/group/avatar/3/foo.jpg", + "web_url": "http://localhost:3000/groups/diaspora" }, "import_status": "none", "import_error": null, @@ -561,6 +563,8 @@ GET /projects/:id } ``` +**Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced][ce-27427] in GitLab 11.11. + If the project is a fork, and you provide a valid token to authenticate, the `forked_from_project` field will appear in the response. @@ -1587,3 +1591,4 @@ GET /projects/:id/snapshot [eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium" [ee-6137]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137 +[ce-27427]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27427 diff --git a/doc/api/runners.md b/doc/api/runners.md index 46f7b1d2a25..2d91428d1c1 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -486,6 +486,7 @@ POST /runners | `locked` | boolean| no | Whether the Runner should be locked for current project | | `run_untagged` | boolean | no | Whether the Runner should handle untagged jobs | | `tag_list` | Array[String] | no | List of Runner's tags | +| `access_level` | string | no | The access_level of the runner; `not_protected` or `ref_protected` | | `maximum_timeout` | integer | no | Maximum timeout set when this Runner will handle the job | ``` diff --git a/doc/api/services.md b/doc/api/services.md index 1f84e2de7de..742abccb69e 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -449,6 +449,45 @@ Get Hangouts Chat service settings for a project. GET /projects/:id/services/hangouts-chat ``` +## HipChat + +Private group chat and IM + +### Create/Edit HipChat service + +Set HipChat service for a project. + +``` +PUT /projects/:id/services/hipchat +``` + +Parameters: + +| Parameter | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | true | Room token | +| `color` | string | false | The room color | +| `notify` | boolean | false | Enable notifications | +| `room` | string | false |Room name or ID | +| `api_version` | string | false | Leave blank for default (v2) | +| `server` | string | false | Leave blank for default. For example, `https://hipchat.example.com`. | + +### Delete HipChat service + +Delete HipChat service for a project. + +``` +DELETE /projects/:id/services/hipchat +``` + +### Get HipChat service settings + +Get HipChat service settings for a project. + +``` +GET /projects/:id/services/hipchat +``` + ## Irker (IRC gateway) Send IRC messages, on update, to a list of recipients through an Irker gateway. @@ -506,7 +545,7 @@ GET /projects/:id/services/jira Set JIRA service for a project. > Starting with GitLab 8.14, `api_url`, `issues_url`, `new_issue_url` and -> `project_url` are replaced by `project_key`, `url`. If you are using an +> `project_url` are replaced by `url`. If you are using an > older version, [follow this documentation][old-jira-api]. ``` @@ -518,7 +557,7 @@ Parameters: | Parameter | Type | Required | Description | | --------- | ---- | -------- | ----------- | | `url` | string | yes | The URL to the JIRA project which is being linked to this GitLab project. For example, `https://jira.example.com`. | -| `project_key` | string | yes | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. | +| `api_url` | string | no | The base URL to the JIRA instance API. Web URL value will be used if not set. For example, `https://jira-api.example.com`. | | `username` | string | yes | The username of the user created to be used with GitLab/JIRA. | | `password` | string | yes | The password of the user created to be used with GitLab/JIRA. | | `active` | boolean | no | Activates or deactivates the service. Defaults to false (deactivated). | diff --git a/doc/ci/README.md b/doc/ci/README.md index a7ad2018b09..123a5e50f14 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -38,30 +38,27 @@ implementing CI/CD. Auto DevOps: For complete control, you can manually configure GitLab CI/CD. -### Usage +### Configuration and Usage -With basic knowledge of how GitLab CI/CD works, the following documentation extends your knowledge -into more features: +The following topics contain configuration and usage information for all features of GitLab CI/CD: | Topic | Description | |:--------------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------------------| | [Creating and using CI/CD pipelines](pipelines.md) | Understand, visualize, create, and use CI/CD pipelines. | -| [CI/CD Variables](variables/README.md) | How environment variables can be configured and made available in pipelines. | -| [Where variables can be used](variables/where_variables_can_be_used.md) | A deeper look into where and how CI/CD variables can be used. | -| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions | Learn about the access levels a user can have for performing certain CI actions. | -| [Configuring GitLab Runners](runners/README.md) | Documentation for configuring [GitLab Runner](https://docs.gitlab.com/runner/). | +| [CI/CD Variables](variables/README.md) | Configuring and using environment variables in pipelines. | +| [Where variables can be used](variables/where_variables_can_be_used.md) | Where and how CI/CD variables can be used. | +| [User](../user/permissions.md#gitlab-cicd-permissions) and [job](../user/permissions.md#job-permissions) permissions | User access levels for performing certain CI actions. | +| [Configuring GitLab Runners](runners/README.md) | Configuring [GitLab Runner](https://docs.gitlab.com/runner/). | | [Environments and deployments](environments.md) | Deploy the output of jobs into environments for reviewing, staging, and production. | -| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Learn about the output of jobs. | -| [Cache dependencies in GitLab CI/CD](caching/index.md) | Discover how to speed up pipelines using caching. | +| [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. | +| [Job artifacts](../user/project/pipelines/job_artifacts.md) | Using the output of jobs. | +| [Cache dependencies in GitLab CI/CD](caching/index.md) | Speed up pipelines using caching. | | [Using Git submodules with GitLab CI](git_submodules.md) | How to run your CI jobs when using Git submodules. | -| [Pipelines for merge requests](merge_request_pipelines/index.md) | Create pipelines specifically for merge requests. | | [Using SSH keys with GitLab CI/CD](ssh_keys/README.md) | Use SSH keys in your build environment. | | [Triggering pipelines through the API](triggers/README.md) | Use the GitLab API to trigger a pipeline. | -| [Pipeline schedules](../user/project/pipelines/schedules.md) | Trigger pipelines on a schedule. | | [Connecting GitLab with a Kubernetes cluster](../user/project/clusters/index.md) | Integrate one or more Kubernetes clusters to your project. | | [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/examples/code_quality.md b/doc/ci/examples/code_quality.md index 3e7d6e7e3f7..186d4527bb6 100644 --- a/doc/ci/examples/code_quality.md +++ b/doc/ci/examples/code_quality.md @@ -1,7 +1,7 @@ # Analyze your project's Code Quality CAUTION: **Caution:** -The job definition shown below is supported on GitLab 11.5 and later versions. +The job definition shown below is supported on GitLab 11.11 and later versions. It also requires the GitLab Runner 11.5 or later. For earlier versions, use the [previous job definitions](#previous-job-definitions). @@ -11,27 +11,11 @@ and Docker. First, you need GitLab Runner with [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). -Once you set up the Runner, add a new job to `.gitlab-ci.yml` that -generates the expected report: +Once you set up the Runner, include the CodeQuality template in your CI config: ```yaml -code_quality: - image: docker:stable - variables: - DOCKER_DRIVER: overlay2 - allow_failure: true - services: - - docker:stable-dind - script: - - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') - - docker run - --env SOURCE_CODE="$PWD" - --volume "$PWD":/code - --volume /var/run/docker.sock:/var/run/docker.sock - "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code - artifacts: - reports: - codequality: gl-code-quality-report.json +include: + - template: Code-Quality.gitlab-ci.yml ``` The above example will create a `code_quality` job in your CI/CD pipeline which @@ -54,6 +38,28 @@ While these old job definitions are still maintained they have been deprecated and may be removed in next major release, GitLab 12.0. You are advised to update your current `.gitlab-ci.yml` configuration to reflect that change. +For GitLab 11.5 and earlier, the job should look like: + +```yaml +code_quality: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + allow_failure: true + services: + - docker:stable-dind + script: + - export SP_VERSION=$(echo "$CI_SERVER_VERSION" | sed 's/^\([0-9]*\)\.\([0-9]*\).*/\1-\2-stable/') + - docker run + --env SOURCE_CODE="$PWD" + --volume "$PWD":/code + --volume /var/run/docker.sock:/var/run/docker.sock + "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code + artifacts: + reports: + codequality: gl-code-quality-report.json +``` + For GitLab 11.4 and earlier, the job should look like: ```yaml diff --git a/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png b/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png Binary files differnew file mode 100644 index 00000000000..5089a1088c5 --- /dev/null +++ b/doc/ci/introduction/img/gitlab_workflow_example_extended_11_11.png diff --git a/doc/ci/introduction/img/job_running.png b/doc/ci/introduction/img/job_running.png Binary files differindex d5f922ceb8c..d5f922ceb8c 100755..100644 --- a/doc/ci/introduction/img/job_running.png +++ b/doc/ci/introduction/img/job_running.png diff --git a/doc/ci/introduction/img/pipeline_status.png b/doc/ci/introduction/img/pipeline_status.png Binary files differindex 96881f072e1..96881f072e1 100755..100644 --- a/doc/ci/introduction/img/pipeline_status.png +++ b/doc/ci/introduction/img/pipeline_status.png diff --git a/doc/ci/introduction/img/rollback.png b/doc/ci/introduction/img/rollback.png Binary files differindex 38e0552f4f1..38e0552f4f1 100755..100644 --- a/doc/ci/introduction/img/rollback.png +++ b/doc/ci/introduction/img/rollback.png diff --git a/doc/ci/introduction/index.md b/doc/ci/introduction/index.md index 6055d8c282a..14ea648c00b 100644 --- a/doc/ci/introduction/index.md +++ b/doc/ci/introduction/index.md @@ -133,8 +133,8 @@ At the end, if anything goes wrong, you can easily ### Basic CI/CD workflow -This is a very simple example for how GitLab CI/CD fits in a common -development workflow. +Consider the following example for how GitLab CI/CD fits in a +common development workflow. Assume that you have discussed a code implementation in an issue and worked locally on your proposed changes. Once you push your @@ -154,7 +154,7 @@ Once you're happy with your implementation: - GitLab CI/CD deploys your changes automatically to a production environment. - And finally, you and your team can easily roll it back if something goes wrong. -<img src="img/gitlab_workflow_example_11_9.png" alt="GitLab workflow example" class="image-noshadow"> + GitLab CI/CD is capable of a doing a lot more, but this workflow exemplifies GitLab's ability to track the entire process, @@ -162,6 +162,48 @@ without the need of any external tool to deliver your software. And, most usefully, you can visualize all the steps through the GitLab UI. +#### A deeper look into the CI/CD basic workflow + +If we take a deeper look into the basic workflow, we can see +the features available in GitLab at each stage of the DevOps +lifecycle, as shown on the illustration below. + + + +If you look at the image from the left to the right, +you'll see some of the features available in GitLab +according to each stage (Verify, Package, Release). + +1. **Verify**: + - Automatically build and test your application with Continuous Integration. + - Analyze your source code quality with [GitLab Code Quality](https://docs.gitlab.com/ee/user/project/merge_requests/code_quality.html). **[STARTER]** + - Determine the performance impact of code changes with [Browser Performance Testing](https://docs.gitlab.com/ee/user/project/merge_requests/browser_performance_testing.html). **[PREMIUM]** + - Perform a series of tests, such as [Container Scanning](https://docs.gitlab.com/ee/ci/examples/container_scanning.html) **[ULTIMATE]**, [Dependency Scanning](https://docs.gitlab.com/ee/ci/examples/dependency_scanning.html) **[ULTIMATE]**, and [JUnit tests](../junit_test_reports.md). + - Deploy your changes with [Review Apps](../review_apps/index.md) to preview the app changes on every branch. +1. **Package**: + - Store Docker images with [Container Registry](../../user/project/container_registry.md). + - Store NPM packages with [NPM Registry](https://docs.gitlab.com/ee/user/project/packages/npm_registry.html). **[PREMIUM]** + - Store Maven artifacts with [Maven Repository](https://docs.gitlab.com/ee/user/project/packages/maven_repository.html). **[PREMIUM]** +1. **Release**: + - Continuous Deployment, automatically deploying your app to production. + - Continuous Delivery, manually click to deploy your app to production. + - Deploy static websites with [GitLab Pages](../../user/project/pages/index.md). + - Ship features to only a portion of your pods and let a percentage of your user base to visit the temporarily deployed feature with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html). **[PREMIUM]** + - Deploy your features behind [Feature Flags](https://docs.gitlab.com/ee/user/project/operations/feature_flags.html). **[PREMIUM]** + - Add release notes to any Git tag with [GitLab Releases](../../user/project/releases/index.md). + - View of the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html). **[PREMIUM]** + - Deploy your application to a production environment in a Kubernetes cluster with [Auto Deploy](../../topics/autodevops/index.md#auto-deploy). + +With GitLab CI/CD you can also: + +- Easily set up your app's entire lifecycle with [Auto DevOps](../../topics/autodevops/index.md). +- Deploy your app to different [environments](../environments.md). +- Install your own [GitLab Runner](https://docs.gitlab.com/runner/). +- [Schedule pipelines](../../user/project/pipelines/schedules.md). +- Check for app vulnerabilities with [Security Test reports](https://docs.gitlab.com/ee/user/project/merge_requests/#security-reports-ultimate). **[ULTIMATE]** + +To see all CI/CD features, navigate back to the [CI/CD index](../README.md). + ### Setting up GitLab CI/CD for the first time To get started with GitLab CI/CD, you need to familiarize yourself @@ -178,16 +220,3 @@ existing one) for any application. For a deep view of GitLab's CI/CD configuration options, check the [`.gitlab-ci.yml` full reference](../yaml/README.md). - -### GitLab CI/CD feature set - -- Easily set up your app's entire lifecycle with [Auto DevOps](../../topics/autodevops/index.md). -- Deploy static websites with [GitLab Pages](../../user/project/pages/index.md). -- Deploy your app to different [environments](../environments.md). -- Preview changes per merge request with [Review Apps](../review_apps/index.md). -- Develop secure and private Docker images with [Container Registry](../../user/project/container_registry.md). -- Install your own [GitLab Runner](https://docs.gitlab.com/runner/). -- [Schedule pipelines](../../user/project/pipelines/schedules.md). -- Check for app vulnerabilities with [Security Test reports](https://docs.gitlab.com/ee/user/project/merge_requests/#security-reports-ultimate). **[ULTIMATE]** - -To see all CI/CD features, navigate back to the [CI/CD index](../README.md). diff --git a/doc/ci/large_repositories/index.md b/doc/ci/large_repositories/index.md index cfe638c0a22..244ccbb92b0 100644 --- a/doc/ci/large_repositories/index.md +++ b/doc/ci/large_repositories/index.md @@ -72,8 +72,9 @@ done by GitLab, requiring you to do them. > 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. +[`GIT_CLONE_PATH`](../yaml/README.md#custom-build-directories) 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 @@ -83,29 +84,31 @@ In such cases, ideally you want to make the GitLab Runner executor be 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. +The [`GIT_CLONE_PATH`](../yaml/README.md#custom-build-directories) 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, +[`GIT_CLEAN_FLAGS`](../yaml/README.md#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. +[`GIT_CLEAN_FLAGS`](../yaml/README.md#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`](../yaml/README.md#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 diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 4f61e97bd8a..3c26a38e3de 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -1,5 +1,11 @@ # Pipelines for merge requests +NOTE: **Note**: +As of GitLab 11.10, pipelines for merge requests require GitLab Runner 11.9 +or higher due to the [recent refspecs +changes](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/25504). +Anything lower will cause the pipeline to fail. + > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6. Usually, when you create a new merge request, a pipeline runs with the @@ -61,14 +67,14 @@ when a merge request was created or updated. For example:  -## Combined ref pipelines **[PREMIUM]** +## Pipelines for Merged Results **[PREMIUM]** -> [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. It's possible for your source and target branches to diverge, which can result in the scenario that source branch's pipeline was green, the target's pipeline was green, but the combined output fails. By having your merge request pipeline automatically -create a new ref that contains the merge result of the source and target branch +create a new ref that contains the merge result of the source and target branch (then running a pipeline on that ref), we can better test that the combined result is also valid. @@ -87,7 +93,7 @@ The detached state serves to warn you that you are working in a situation subjected to merge problems, and helps to highlight that you should get out of WIP status or resolve merge conflicts as soon as possible. -### Enabling combined ref pipelines +### Enabling Pipelines for Merged Results This feature disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186). It can be enabled at the project level: @@ -97,7 +103,7 @@ This feature disabled by default until we resolve issues with [contention handli  -### Combined ref pipeline's limitations +### Pipelines for Merged Result's limitations - This feature requires [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. - This feature requires [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 2fc1e14f02e..1a71c5fd258 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -3,12 +3,10 @@ > - [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/21971) in GitLab 8.12. Further additions were made in GitLab 8.13 and 8.14. > - Inspired by [Heroku's Review Apps](https://devcenter.heroku.com/articles/github-integration-review-apps), which itself was inspired by [Fourchette](https://github.com/rainforestapp/fourchette). -For a video introduction to Review Apps, see [8.14 Webcast: Review Apps & Time Tracking Beta (EE) - GitLab Release](https://www.youtube.com/watch?v=CteZol_7pxo). - -## Overview - Review Apps are a collaboration tool that takes the hard work out of providing an environment to showcase product changes. +## Introduction + Review Apps: - Provide an automatic live preview of changes made in a feature branch by spinning up a dynamic environment for your merge requests. @@ -18,103 +16,60 @@ Review Apps:  -Reviewing anything, from performance to interface changes, becomes much easier with a live environment and so Review Apps can make a large impact on your development flow. +In the above example: -## What are Review Apps? +- A Review App is built every time a commit is pushed to`topic branch`. +- The reviewer fails two reviews before passing the third review. +- Once the review as passed, `topic branch` is merged into `master` where it's deploy to staging. +- After been approved in staging, the changes that were merged into `master` are deployed in to production. -A Review App is a mapping of a branch with an [environment](../environments.md). The following is an example of a merge request with an environment set dynamically. +### How Review Apps work + +A Review App is a mapping of a branch with an [environment](../environments.md). +Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. + +The following is an example of a merge request with an environment set dynamically.  -In this example, you can see a branch was: +In this example, a branch was: - Successfully built. - Deployed under a dynamic environment that can be reached by clicking on the **View app** button. -## How do Review Apps work? - -The basis of Review Apps in GitLab is [dynamic environments](../environments.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch. - -Access to the Review App is made available as a link on the [merge request](../../user/project/merge_requests.md) relevant to the branch. Review Apps enable you to review all changes proposed by the merge request in live environment. - -## Use cases - -Some supported use cases include the: - -- Simple case of deploying a simple static HTML website. -- More complicated case of an application that uses a database. Deploying a branch on a temporary instance and booting up this instance with all required software and services automatically on the fly is not a trivial task. However, it is possible, especially if you use Docker or a configuration management tool like Chef, Puppet, Ansible, or Salt. - -Review Apps usually make sense with web applications, but you can use them any way you'd like. - -## Implementing Review Apps - -Implementing Review Apps depends on your: - -- Technology stack. -- Deployment process. - -### Prerequisite Knowledge - -To get a better understanding of Review Apps, review documentation on how environments and deployments work. Before you implement your own Review Apps: - -1. Learn about [environments](../environments.md) and their role in the development workflow. -1. Learn about [CI variables](../variables/README.md) and how they can be used in your CI jobs. -1. Explore the [`environment` syntax](../yaml/README.md#environment) as defined in `.gitlab-ci.yml`. This will become a primary reference. -1. Additionally, find out about [manual actions](../environments.md#configuring-manual-deployments) and how you can use them to deploy to critical environments like production with the push of a button. -1. Follow the [example tutorials](#examples). These will guide you through setting up infrastructure and using Review Apps. - -### Configuring dynamic environments - -Configuring Review Apps dynamic environments depends on your technology stack and infrastructure. - -For more information, see [dynamic environments](../environments.md#configuring-dynamic-environments) documentation to understand how to define and create them. - -### Creating and destroying Review Apps - -Creating and destroying Review Apps is defined in `.gitlab-ci.yml` at a job level under the `environment` keyword. +## Configuring Review Apps -For more information, see [Introduction to environments and deployments](../environments.md). +Review Apps are built on [dynamic environments](../environments.md#configuring-dynamic-environments), which allow you to dynamically create a new environment for each branch. -### Adding Review Apps to your workflow - -The process of adding Review Apps in your workflow is as follows: +The process of configuring Review Apps is as follows: 1. Set up the infrastructure to host and deploy the Review Apps. 1. [Install](https://docs.gitlab.com/runner/install/) and [configure](https://docs.gitlab.com/runner/commands/) a Runner to do deployment. 1. Set up a job in `.gitlab-ci.yml` that uses the [predefined CI environment variable](../variables/README.md) `${CI_COMMIT_REF_NAME}` to create dynamic environments and restrict it to run only on branches. 1. Optionally, set a job that [manually stops](../environments.md#stopping-an-environment) the Review Apps. -After adding Review Apps to your workflow, you follow the branched Git flow. That is: +### Examples -1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job. -1. Wait for the Runner to build and deploy your web application. -1. Click on the link that provided in the merge request related to the branch to see the changes live. - -## Limitations - -Check the [environments limitations](../environments.md#limitations). - -## Examples - -The following are example projects that use Review Apps with: +The following are example projects that demonstrate Review App configuration: - [NGINX](https://gitlab.com/gitlab-examples/review-apps-nginx). - [OpenShift](https://gitlab.com/gitlab-examples/review-apps-openshift). See also the video [Demo: Cloud Native Development with GitLab](https://www.youtube.com/watch?v=jfIyQEwrocw), which includes a Review Apps example. -## Route Maps +### Route Maps -> Introduced in GitLab 8.17. In GitLab 11.5 the file links -are surfaced to the merge request widget. +> Introduced in GitLab 8.17. In GitLab 11.5, the file links are available in the merge request widget. Route Maps allows you to go directly from source files to public pages on the [environment](../environments.md) defined for -Review Apps. Once set up, the review app link in the merge request +Review Apps. + +Once set up, the review app link in the merge request widget can take you directly to the pages changed, making it easier and faster to preview proposed modifications. -All you need to do is to tell GitLab how the paths of files +Configuring Route Maps involves telling GitLab how the paths of files in your repository map to paths of pages on your website using a Route Map. Once set, GitLab will display **View on ...** buttons, which will take you to the pages changed directly from merge requests. @@ -123,9 +78,9 @@ To set up a route map, add a a file inside the repository at `.gitlab/route-map. which contains a YAML array that maps `source` paths (in the repository) to `public` paths (on the website). -### Route Maps example +#### Route Maps example -Below there's an example of a route map for [Middleman](https://middlemanapp.com), +The following is an example of a route map for [Middleman](https://middlemanapp.com), a static site generator (SSG) used to build [GitLab's website](https://about.gitlab.com), deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitlab-com): @@ -147,18 +102,17 @@ deployed from its [project on GitLab.com](https://gitlab.com/gitlab-com/www-gitl public: '\1' # images/blogimages/around-the-world-in-6-releases-cover.png ``` -Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, we have a hash map with two keys: +Mappings are defined as entries in the root YAML array, and are identified by a `-` prefix. Within an entry, there is a hash map with two keys: - `source` - - a string, starting and ending with `'`, for an exact match - - a regular expression, starting and ending with `/`, for a pattern match - - The regular expression needs to match the entire source path - `^` and `$` anchors are implied. - - Can include capture groups denoted by `()` that can be referred to in the `public` path. - - Slashes (`/`) can, but don't have to, be escaped as `\/`. - - Literal periods (`.`) should be escaped as `\.`. -- `public` - - a string, starting and ending with `'`. - - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`. + - A string, starting and ending with `'`, for an exact match. + - A regular expression, starting and ending with `/`, for a pattern match: + - The regular expression needs to match the entire source path - `^` and `$` anchors are implied. + - Can include capture groups denoted by `()` that can be referred to in the `public` path. + - Slashes (`/`) can, but don't have to, be escaped as `\/`. + - Literal periods (`.`) should be escaped as `\.`. +- `public`, a string starting and ending with `'`. + - Can include `\N` expressions to refer to capture groups in the `source` regular expression in order of their occurrence, starting with `\1`. The public path for a source path is determined by finding the first `source` expression that matches it, and returning the corresponding @@ -171,12 +125,12 @@ will match `/source\/(.+?\.html).*/` instead of `/source\/(.*)/`, and will result in a public path of `index.html`, instead of `index.html.haml`. -Once you have the route mapping set up, it will be exposed in a few places: +Once you have the route mapping set up, it will take effect in the following locations: -- In the merge request widget. The **View app** button will take you to the - environment URL you have set up in `.gitlab-ci.yml`. The dropdown will render - the first 5 matched items from the route map, but you can filter them if more - than 5 are available. +- In the merge request widget. The: + - **View app** button will take you to the environment URL set in `.gitlab-ci.yml`. + - Dropdown will list the first 5 matched items from the route map, but you can filter them if more + than 5 are available.  @@ -187,3 +141,15 @@ Once you have the route mapping set up, it will be exposed in a few places: - In the blob file view.  + +## Working with Review Apps + +After adding Review Apps to your workflow, you follow the branched Git flow. That is: + +1. Push a branch and let the Runner deploy the Review App based on the `script` definition of the dynamic environment job. +1. Wait for the Runner to build and deploy your web application. +1. Click on the link that provided in the merge request related to the branch to see the changes live. + +## Limitations + +Review App limitations are the same as [environments limitations](../environments.md#limitations). diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 61d1a904f76..9983b015b31 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -136,12 +136,21 @@ The output will be:  -CAUTION: **Important:** -Be aware that variables are not masked, and their values can be shown -in the job logs if explicitly asked to do so. If your project is public or -internal, you can set the pipelines private from your [project's Pipelines -settings](../../user/project/pipelines/settings.md#visibility-of-pipelines). -Follow the discussion in issue [#13784][ce-13784] for masking the variables. +### Masked Variables + +By default, variables will be created as masked variables. +This means that the value of the variable will be hidden in job logs, +though it must match certain requirements to do so: + +- The value must be in a single line. +- The value must not have escape characters. +- The value must not use variables. +- The value must not have any whitespace. +- The value must be at least 8 characters long. + +If the value does not meet the requirements above, then the CI variable will fail to save. +In order to save, either alter the value to meet the masking requirements +or disable `Masked` for the variable. ### Syntax of environment variables in job scripts @@ -425,8 +434,9 @@ Below you can find supported syntax reference: 1. Equality matching using a string > Example: `$VARIABLE == "some value"` + > Example: `$VARIABLE != "some value"` _(added in 11.11)_ - You can use equality operator `==` to compare a variable content to a + You can use equality operator `==` or `!=` to compare a variable content to a string. We support both, double quotes and single quotes to define a string value, so both `$VARIABLE == "some value"` and `$VARIABLE == 'some value'` are supported. `"some value" == $VARIABLE` is correct too. @@ -434,22 +444,26 @@ Below you can find supported syntax reference: 1. Checking for an undefined value > Example: `$VARIABLE == null` + > Example: `$VARIABLE != null` _(added in 11.11)_ It sometimes happens that you want to check whether a variable is defined or not. To do that, you can compare a variable to `null` keyword, like `$VARIABLE == null`. This expression is going to evaluate to truth if - variable is not defined. + variable is not defined when `==` is used, or to falsey if `!=` is used. 1. Checking for an empty variable > Example: `$VARIABLE == ""` + > Example: `$VARIABLE != ""` _(added in 11.11)_ If you want to check whether a variable is defined, but is empty, you can - simply compare it against an empty string, like `$VAR == ''`. + simply compare it against an empty string, like `$VAR == ''` or non-empty + string `$VARIABLE != ""`. 1. Comparing two variables > Example: `$VARIABLE_1 == $VARIABLE_2` + > Example: `$VARIABLE_1 != $VARIABLE_2` _(added in 11.11)_ It is possible to compare two variables. This is going to compare values of these variables. @@ -468,9 +482,11 @@ Below you can find supported syntax reference: 1. Pattern matching _(added in 11.0)_ > Example: `$VARIABLE =~ /^content.*/` + > Example: `$VARIABLE_1 !~ /^content.*/` _(added in 11.11)_ It is possible perform pattern matching against a variable and regular - expression. Expression like this evaluates to truth if matches are found. + expression. Expression like this evaluates to truth if matches are found + when using `=~`. It evaluates to truth if matches are not found when `!~` is used. Pattern matching is case-sensitive by default. Use `i` flag modifier, like `/pattern/i` to make a pattern case-insensitive. diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 05bde5ed4c8..40458137752 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -49,23 +49,23 @@ future GitLab releases.** | `CI_JOB_STAGE` | 9.0 | 0.5 | The name of the stage as defined in `.gitlab-ci.yml` | | `CI_JOB_TOKEN` | 9.0 | 1.2 | Token used for authenticating with the [GitLab Container Registry][registry] and downloading [dependent repositories][dependent-repositories] | | `CI_JOB_URL` | 11.1 | 0.5 | Job details URL | -| `CI_MERGE_REQUEST_ID` | 11.6 | all | The ID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_IID` | 11.6 | all | The IID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_PROJECT_ID` | 11.6 | all | The ID of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_PROJECT_PATH` | 11.6 | all | The path of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `namespace/awesome-project`) | -| `CI_MERGE_REQUEST_PROJECT_URL` | 11.6 | all | The URL of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`) | -| `CI_MERGE_REQUEST_REF_PATH` | 11.6 | all | The ref path of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`) | -| `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | 11.6 | all | The source branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD sha of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | 11.6 | all | The ID of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | 11.6 | all | The path of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | 11.6 | all | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD sha of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of usernames of assignees for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). [Multiple assignees for merge requests](https://gitlab.com/gitlab-org/gitlab-ee/issues/2004) is scheduled for a future release | -| `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | -| `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) | +| `CI_MERGE_REQUEST_ID` | 11.6 | all | The ID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_IID` | 11.6 | all | The IID of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_PROJECT_ID` | 11.6 | all | The ID of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_PROJECT_PATH` | 11.6 | all | The path of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `namespace/awesome-project`). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_PROJECT_URL` | 11.6 | all | The URL of the project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md) (e.g. `http://192.168.10.15:3000/namespace/awesome-project`). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_REF_PATH` | 11.6 | all | The ref path of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). (e.g. `refs/merge-requests/1/head`). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_BRANCH_NAME` | 11.6 | all | The source branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_BRANCH_SHA` | 11.9 | all | The HEAD sha of the source branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_PROJECT_ID` | 11.6 | all | The ID of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_PROJECT_PATH` | 11.6 | all | The path of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_SOURCE_PROJECT_URL` | 11.6 | all | The URL of the source project of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD sha of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_ASSIGNEES` | 11.9 | all | Comma-separated list of username(s) of assignee(s) for the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_MILESTONE` | 11.9 | all | The milestone title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_LABELS` | 11.9 | all | Comma-separated label names of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_NODE_INDEX` | 11.5 | all | Index of the job in the job set. If the job is not parallelized, this variable is not set. | | `CI_NODE_TOTAL` | 11.5 | all | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. | | `CI_API_V4_URL` | 11.7 | all | The GitLab API v4 root URL | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 5e44de13b51..2e85e34f17b 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -437,10 +437,6 @@ Feature.enable(:allow_unsafe_ruby_regexp) ### `only`/`except` (advanced) -> - `refs` and `kubernetes` policies introduced in GitLab 10.0. -> - `variables` policy introduced in GitLab 10.7. -> - `changes` policy [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/19232) in GitLab 11.4. - CAUTION: **Warning:** This an _alpha_ feature, and it is subject to change at any time without prior notice! @@ -461,6 +457,8 @@ If you use multiple keys under `only` or `except`, they act as an AND. The logic #### `only:refs`/`except:refs` +> `refs` policy introduced in GitLab 10.0. + The `refs` strategy can take the same values as the [simplified only/except configuration](#onlyexcept-basic). @@ -477,6 +475,8 @@ deploy: #### `only:kubernetes`/`except:kubernetes` +> `kubernetes` policy introduced in GitLab 10.0. + The `kubernetes` strategy accepts only the `active` keyword. In the example below, the `deploy` job is going to be created only when the @@ -490,6 +490,8 @@ deploy: #### `only:variables`/`except:variables` +> `variables` policy introduced in GitLab 10.7. + The `variables` keyword is used to define variables expressions. In other words, you can use predefined variables / project / group or environment-scoped variables to define an expression GitLab is going to @@ -522,6 +524,8 @@ Learn more about [variables expressions](../variables/README.md#environment-vari #### `only:changes`/`except:changes` +> `changes` policy [introduced][ce-19232] in GitLab 11.4. + Using the `changes` keyword with `only` or `except` makes it possible to define if a job should be created based on files modified by a git push event. @@ -2468,18 +2472,18 @@ Use [`stage`](#stage) instead. ## Custom build directories -> [Introduced][https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267] in Gitlab Runner 11.10 +> [Introduced](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1267) in Gitlab Runner 11.10 NOTE: **Note:** This can only be used when `custom_build_dir` is enabled in the [Runner's configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runnerscustom_build_dir-section). This is the default configuration for `docker` and `kubernetes` executor. -By default, GitLab Runner clones the repository in a unique subpath of the `$CI_BUILDS_DIR` directory. -However, sometimes your project might require the code in a specific directory, -but sometimes your project might require to have the code in a specific directory, -like Go projects, for example. In that case, you can specify the `GIT_CLONE_PATH` variable -to tell the Runner in which directory to clone the repository: +By default, GitLab Runner clones the repository in a unique subpath of the +`$CI_BUILDS_DIR` directory. However, your project might require the code in a +specific directory (Go projects, for example). In that case, you can specify +the `GIT_CLONE_PATH` variable to tell the Runner in which directory to clone the +repository: ```yml variables: @@ -2697,6 +2701,15 @@ Not to be confused with [`trigger`](#trigger-premium). [Read more in the triggers documentation.](../triggers/README.md) +## Processing Git pushes + +GitLab will create at most 4 branch and tags pipelines when +doing pushing multiple changes in single `git push` invocation. + +This limitation does not affect any of the updated Merge Request pipelines, +all updated Merge Requests will have a pipeline created when using +[pipelines for merge requests](../merge_request_pipelines/index.md). + ## Skipping jobs If your commit message contains `[ci skip]` or `[skip ci]`, using any @@ -2714,6 +2727,7 @@ git push -o ci.skip [ce-7983]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7983 [ce-7447]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7447 [ce-12909]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12909 +[ce-19232]: https://gitlab.com/gitlab-org/gitlab-ce/issues/19232 [environment]: ../environments.md "CI/CD environments" [schedules]: ../../user/project/pipelines/schedules.md "Pipelines schedules" [variables]: ../variables/README.md "CI/CD variables" diff --git a/doc/development/code_review.md b/doc/development/code_review.md index b1a32e0ed26..4e2213f7742 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -132,14 +132,6 @@ If a developer who happens to also be a maintainer was involved in a merge reque as a domain expert and/or reviewer, it is recommended that they are not also picked as the maintainer to ultimately approve and merge it. -Try to review in a timely manner; doing so allows everyone involved in the merge -request to iterate faster as the context is fresh in memory. Further, this -improves contributors' experiences significantly. Reviewers should aim to review -within two working days from the date they were assigned the merge request. If -you don't think you'll be able to review a merge request within that time, let -the author know as soon as possible. When the author of the merge request has not -heard anything after two days, a new reviewer should be assigned. - Maintainers should check before merging if the merge request is approved by the required approvers. @@ -220,6 +212,37 @@ It is responsibility of the author of a merge request that the merge request is Developers who have capacity can regularly check the list of [merge requests to review](https://gitlab.com/groups/gitlab-org/-/merge_requests?scope=all&utf8=%E2%9C%93&state=opened&label_name%5B%5D=ready%20for%20review) and assign any merge request they want to review. +### Review turnaround time + +Since [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization), +reviewers are expected to review assigned merge requests in a timely manner, +even when this may negatively impact their other tasks and priorities. +Doing so allows everyone involved in the merge request to iterate faster as the +context is fresh in memory, improves contributors' experiences significantly, +and gives authors more time to address feedback and iterate on their work before +the [feature freeze](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md#feature-freeze-on-the-7th-for-the-release-on-the-22nd). + +A turnaround time of two working days is usually acceptable, since engineers +will typically have other things to work on while they're waiting for review, +but don't hesitate to ask the author if it's unclear what time frame would be +acceptable, how urgent the review is, or how significant the blockage. Authors +are also encouraged to provide this information up-front to reviewers, but are +expected to be mindful of the [guidelines on when to ask for review on MRs that +are intended to go in before the feature freeze](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/PROCESS.md#between-the-1st-and-the-7th), +and realistic in their expectations if these were not followed. + +If you don't think you'll be able to review a merge request within a reasonable +time frame, let the author know as soon as possible and try to help them find +another reviewer or maintainer who will be able to, so that they can be unblocked +and get on with their work quickly. Of course, if you are out of office and have +[communicated](https://about.gitlab.com/handbook/paid-time-off/#communicating-your-time-off) +this through your GitLab.com Status, authors are expected to realize this and +find a different reviewer themselves. + +When a merge request author feels like they have been blocked for longer than +is reasonable, they are free to remind the reviewer through Slack or assign +another reviewer. + ### Reviewing code Understand why the change is necessary (fixes a bug, improves the user diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index 4c53643ed9c..0e1ab8663ed 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -62,10 +62,12 @@ The current team labels are: - ~Configure - ~Create +- ~Defend - ~Distribution - ~Documentation - ~Geo - ~Gitaly +- ~Growth - ~Manage - ~Monitor - ~Plan @@ -99,6 +101,8 @@ The current stage labels are: - ~"devops:configure" - ~"devops:monitor" - ~"devops:secure" +- ~"devops:defend" +- ~"devops:enablement" These labels should be mutually exclusive. If an issue belongs to multiple stages, the most relevant should be used. @@ -336,13 +340,14 @@ addressed. In order to track things that can be improved in GitLab's codebase, we use the ~"technical debt" label in [GitLab's issue tracker][ce-tracker]. -For user experience improvements, we use the ~"UX debt" label. +For missed user experience requirements, we use the ~"UX debt" label. These labels should be added to issues that describe things that can be improved, shortcuts that have been taken, features that need additional attention, and all other things that have been left behind due to high velocity of development. For example, code that needs refactoring should use the ~"technical debt" label, -user experience refinements should use the ~"UX debt" label. +something that didn't ship according to our Design System guidelines should +use the ~"UX debt" label. Everyone can create an issue, though you may need to ask for adding a specific label, if you do not have permissions to do it by yourself. Additional labels diff --git a/doc/development/contributing/style_guides.md b/doc/development/contributing/style_guides.md index 45104a1f91d..f319d00d7fe 100644 --- a/doc/development/contributing/style_guides.md +++ b/doc/development/contributing/style_guides.md @@ -10,7 +10,7 @@ 1. [Testing][testing] 1. [JavaScript styleguide][js-styleguide] 1. [SCSS styleguide][scss-styleguide] -1. [Shell commands](../shell_commands.md) created by GitLab +1. [Shell commands (Ruby)](../shell_commands.md) created by GitLab contributors to enhance security 1. [Database Migrations](../migration_style_guide.md) 1. [Markdown](http://www.cirosantilli.com/markdown-styleguide) diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 4a2ff64807e..52a4bb27817 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -16,13 +16,13 @@ In addition to this page, the following resources to help craft and contribute d - [Markdown Guide](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) - A reference for the markdown implementation used by GitLab's documentation site and about.gitlab.com. - [Site architecture](site_architecture/index.md) - How docs.gitlab.com is built. -## Source and rendered locations +## Source files and rendered web locations Documentation for GitLab Community Edition (CE) and Enterprise Edition (EE), along with GitLab Runner and Omnibus, is published to [docs.gitlab.com](https://docs.gitlab.com). The documentation for CE and EE is also published within the application at `/help` on the domain of the GitLab instance. At `/help`, only content for your current edition and version is included, whereas multiple versions' content is available at docs.gitlab.com. -The source of the documentation is maintained in the following repository locations: +The source of the documentation exists within the codebase of each GitLab application in the following repository locations: | Project | Path | | --- | --- | @@ -48,87 +48,11 @@ 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 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). - -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.). - -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 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, -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. - -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. - -| Directory | What belongs here | -|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here including `/admin`. | -| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface go under `doc/user/admin_area/`. | -| `doc/api/` | API related documentation. | -| `doc/development/` | Documentation related to the development of GitLab. Related process and style guides should go here. | -| `doc/legal/` | Legal documents about contributing to GitLab. | -| `doc/install/` | Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | -| `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) | - -**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. 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/`. - 1. `doc/user/project/` should contain all project related documentation. - 1. `doc/user/group/` should contain all group related documentation. - 1. `doc/user/profile/` should contain all profile related documentation. - Every page you would navigate under `/profile` should have its own document, - i.e. `account.md`, `applications.md`, `emails.md`, etc. - 1. `doc/user/dashboard/` should contain all dashboard related documentation. - 1. `doc/user/admin_area/` should contain all admin related documentation - describing what can be achieved by accessing GitLab's admin interface - (_not to be confused with `doc/administration` where server access is - required_). - 1. Every category under `/admin/application_settings` should have its - own document located at `doc/user/admin_area/settings/`. For example, - the **Visibility and Access Controls** category should have a document - located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. -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 -then ask the reviewer of your MR to confirm your decision, and/or ask a technical writer -at any stage in the process. The techncial writing team will review all documentation -changes, regardless, and can move content if there is a better place for it. - -### Changing document location +## Folder structure and files + +See the [Structure](styleguide.md#structure) section of the [Documentation Style Guide](styleguide.md). + +## Changing document location Changing a document's location requires specific steps to be followed to ensure that users can seamlessly access the new doc page, whether they are accesing content @@ -186,7 +110,7 @@ Things to note: built-in help page, that's why we omit it in `git grep`. - Use the checklist on the "Change documentation location" MR description template. -#### Alternative redirection method +### Alternative redirection method Alternatively to the method described above, you can simply replace the content of the old file with a frontmatter containing a redirect link: @@ -204,7 +128,7 @@ This redirection method will not provide a redirect fallback on GitLab `/help`. it, make sure to add a link to the new page on the doc, otherwise it's a dead end for users that land on the doc via `/help`. -#### Redirections for pages with Disqus comments +### Redirections for pages with Disqus comments If the documentation page being relocated already has any Disqus comments, we need to preserve the Disqus thread. @@ -389,7 +313,7 @@ to merge changes that will break `master` from a merge request with a successful ## Docs site architecture See the [Docs site architecture](site_architecture/index.md) page to learn -how we build and deploy the site at [docs.gitlab.com](https://docs.gitlab.com), and +how we build and deploy the site at [docs.gitlab.com](https://docs.gitlab.com) and to review all the assets and libraries in use. ### Global navigation diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 1cefe48b4c1..fbca99fbfea 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -4,64 +4,190 @@ description: 'Writing styles, markup, formatting, and other standards for GitLab # Documentation Style Guide -The documentation style guide defines the markup structure used in -GitLab documentation. Check the -[documentation guidelines](index.md) for general development instructions. +This document defines the standards for GitLab's documentation content and files. -See the GitLab handbook for the [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines). +For broader information about the documentation, see the [Documentation guidelines](index.md). For programmatic help adhering to the guidelines, see [linting](index.md#linting). -## Files +See the GitLab handbook for further [writing style guidelines](https://about.gitlab.com/handbook/communication/#writing-style-guidelines) +that apply to all GitLab content, not just documentation. -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. +## Documentation is the single source of truth (SSOT) -DANGER: **Attention:** -**Do not** use capital letters, spaces, or special chars in file names, -branch names, directory names, headings, or in anything that generates a path. +### Why a single source of truth -NOTE: **Note:** -**Do not** create new `README.md` files, name them `index.md` instead. There's -a test that will fail if it spots a new `README.md` file. - -### Markdown +The documentation is the SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features. It evolves continually, in keeping with new products and features, and with improvements for clarity, accuracy, and completeness. -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 in the linked style guide. +This policy prevents information silos, ensuring that it remains easy to find information about GitLab products. -Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly in on GitLab instances in [`/help`](index.md#gitlab-help). +It also informs decisions about the kinds of content we include in our documentation. -## Content +The documentation is a continually evolving SSOT for all information related to the implementation, usage, and troubleshooting of GitLab products and features. -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. +### All information -### Subject matter +Include problem-solving actions that may address rare cases or be considered 'risky', so long as proper context is provided in the form of fully detailed warnings and caveats. This kind of content should be included as it could be helpful to others and, when properly explained, its benefits outweigh the risks. If you think you have found an exception to this rule, contact the Technical Writing team. -[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. +We will add all troubleshooting information to the documentation, no matter how unlikely a user is to encounter a situation. +For the Troubleshooting sections, people in GitLab Support can merge additions themselves. -### Media types and sources +### All media types -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. +Include any media types/sources if the content is 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 +### No special types + +In the software industry, it is a best practice to organize documentatioin in different types. For example, [Divio recommends](https://www.divio.com/blog/documentation/): + +1. Tutorials +2. How-to guides +3. Explanation +4. Reference (for example, a glossary) + +At GitLab, we have so many product changes in our monthly releases that we can't afford to continually update multiple types of information. +If we have multiple types, the information will become outdated. Therefore, we have a [single template](structure.md) for documentation. + +We currently do not distinguish specific document types, although we are open to reconsidering this policy +once the documentation has reached a future stage of maturity and quality. If you are reading this, then despite our +continual improvement efforts, that point hasn't been reached. + +### Link instead of summarize + +There is a temptation to summarize the information on another page. +This will cause the information to live in two places. +Instead, link to the SSOT and explain why it is important to consume the information. + +### Organize by topic, not by type + +Beyond top-level audience-type folders (e.g. `administration`), we organize content by topic, not by type, so that it can be located as easily as possible within the single-source-of-truth (SSOT) section for the subject matter. + +For example, do not create groupings of similar media types (e.g. glossaries, FAQs, or sets of all articles or videos). + +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. -- 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. +### Docs-first methodology + +We employ a **docs-first methodology** to help ensure that the docs remain a complete and trusted resource, and to make communicating about the use of GitLab more efficient. + +* If the answer to a question exists in documentation, share the link to the docs instead of rephrasing the information. +* When you encounter new information not available in GitLab’s documentation (for example, when working on a support case or testing a feature), your first step should be to create a merge request to add this information to the docs. You can then share the MR in order to communicate this information. + +New information that would be useful toward the future usage or troubleshooting of GitLab should not be written directly in a forum or other messaging system, but added to a docs MR and then referenced, as described above. Note that among any other doc changes, you can always add a Troubleshooting section to a doc if none exists, or un-comment and use the placeholder Troubleshooting section included as part of our [doc template](structure.md#template-for-new-docs), if present. + +The more we reflexively add useful information to the docs, the more (and more successfully) the docs will be used to efficiently accomplish tasks and solve problems. + +If you have questions when considering, authoring, or editing docs, ask the Technical Writing team on Slack in `#docs` or in GitLab by mentioning the writer for the applicable [DevOps stage](https://about.gitlab.com/handbook/product/categories/#devops-stages). Otherwise, forge ahead with your best effort. It does not need to be perfect; the team is happy to review and improve upon your content. Please review the [Documentation guidelines](index.md) before you begin your first documentation MR. + +Having a knowledge base is any form that is separate from the documentation would be against the docs-first methodology because the content would overlap with the documentation. + +## Markdown + +All GitLab documentation is written using [Markdown](https://en.wikipedia.org/wiki/Markdown). + +The [documentation website](https://docs.gitlab.com) uses GitLab Kramdown as its Markdown rendering engine. 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) +Ruby gem will support all [GFM markup](../../user/markdown.md) in the future. That is, +all markup that is supported for display in the GitLab application itself. For now, +use regular Markdown markup, following the rules in the linked style guide. + +Note that Kramdown-specific markup (e.g., `{:.class}`) will not render properly on GitLab instances under [`/help`](index.md#gitlab-help). + +## Structure + +### Organize by topic, not by type + +Because we want documentation to be a SSOT, we should [organize by topic, not by type](#organize-by-topic-not-by-type). + +### Folder structure overview + +The documentation is separated by top-level audience folders [`user`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/user), +[`administration`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/administration), and [`development`](https://gitlab.com/gitlab-org/gitlab-ce/tree/master/doc/development) (contributing) folders. + +Beyond that, we primarily follow the structure of the GitLab user interface or API. + +Our goal is to have a clear hierarchical structure with meaningful URLs +like `docs.gitlab.com/user/project/merge_requests/`. With this pattern, +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. + +The table below shows what kind of documentation goes where. + +| Directory | What belongs here | +|:----------------------|:---------------------------------------------------------------------------------------------------------------------------------| +| `doc/user/` | User related documentation. Anything that can be done within the GitLab UI goes here, including usage of the `/admin` interface. | +| `doc/administration/` | Documentation that requires the user to have access to the server where GitLab is installed. The admin settings that can be accessed via GitLab's interface exist under `doc/user/admin_area/`. | +| `doc/api/` | API related documentation. | +| `doc/development/` | Documentation related to the development of GitLab, whether contributing code or docs. Related process and style guides should go here. | +| `doc/legal/` | Legal documents about contributing to GitLab. | +| `doc/install/` | Contains instructions for installing GitLab. | +| `doc/update/` | Contains instructions for updating GitLab. | +| `doc/topics/` | Indexes per topic (`doc/topics/topic-name/index.md`): all resources for that topic. | + +### Working with directories and files + +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 characters 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. 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/`. + 1. `doc/user/project/` should contain all project related documentation. + 1. `doc/user/group/` should contain all group related documentation. + 1. `doc/user/profile/` should contain all profile related documentation. + Every page you would navigate under `/profile` should have its own document, + i.e. `account.md`, `applications.md`, `emails.md`, etc. + 1. `doc/user/dashboard/` should contain all dashboard related documentation. + 1. `doc/user/admin_area/` should contain all admin related documentation + describing what can be achieved by accessing GitLab's admin interface + (_not to be confused with `doc/administration` where server access is + required_). + 1. Every category under `/admin/application_settings` should have its + own document located at `doc/user/admin_area/settings/`. For example, + the **Visibility and Access Controls** category should have a document + located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. +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 +then ask the reviewer of your MR to confirm your decision, and/or ask a technical writer +at any stage in the process. The techncial writing team will review all documentation +changes, regardless, and can move content if there is a better place for it. + +### Avoid duplication + +Do not include the same information in multiple places. [Link to a SSOT instead.](#link-instead-of-summarize) + +### References across documents + +- Give each folder an index.md page that introduces the topic, introduces the pages within, and links to the pages within (including to the index pages of any next-level subpaths). +- To ensure discoverability, ensure each new or renamed doc is linked from its higher-level index page and other related pages. +- When making reference to other GitLab products and features, link to their respective docs, at least on first mention. +- When making reference to 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. +- Include any and all applicable subsections as described on the [structure and template](structure.md) page. - 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 otherwise ordered sequence). @@ -95,7 +221,7 @@ Include any media types/sources, if relevant to readers. You can freely include - List item 2 ``` -### Tables overlapping the ToC +### Tables overlapping the TOC By default, all tables have a width of 100% on docs.gitlab.com. In a few cases, the table will overlap the table of contents (ToC). @@ -525,6 +651,12 @@ keyword "only": - For GitLab Premium: `**[PREMIUM ONLY]**`. - For GitLab Ultimate: `**[ULTIMATE ONLY]**`. +For GitLab.com only tiers (when the feature is not available for self-hosted instances): + +- For GitLab Bronze and higher tiers: `**[BRONZE ONLY]**`. +- For GitLab Silver and higher tiers: `**[SILVER ONLY]**`. +- For GitLab Gold: `**[GOLD ONLY]**`. + The tier should be ideally added to headers, so that the full badge will be displayed. However, it can be also mentioned from paragraphs, list items, and table cells. For these cases, the tier mention will be represented by an orange question mark that will show the tiers on hover. @@ -533,6 +665,7 @@ For example: - `**[STARTER]**` renders as **[STARTER]** - `**[STARTER ONLY]**` renders as **[STARTER ONLY]** +- `**[SILVER ONLY]**` renders as **[SILVER ONLY]** The absence of tiers' mentions mean that the feature is available in GitLab Core, GitLab.com Free, and all higher tiers. diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index c5a1d915be6..9853b38b8e9 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -922,7 +922,7 @@ import mixin from 'ee_else_ce/path/mixin'; mixins: [mixin] } ``` - + - Computed Properties/methods and getters only used in the child import still need a counterpart in CE - For store modules, we will need a CE counterpart too. @@ -933,47 +933,27 @@ import mixin from 'ee_else_ce/path/mixin'; - Since we are using the async loading to check which component to load, we'd still use the component's name, check [this example](#child-component-only-used-in-ee). * **EE extra HTML** - - For the templates that have extra HTML in EE we will use the `ifEE` mixin with the `v-if` directive. - - You can either use the `template` tag as a wrapper or directly in the element, if there is only one element to be rendered in EE: - -```html - <template v-if="ifEE"> - <p>Several</p> - <p>non wrapper</p> - <p>elements</p> - <p>that are rendered</p> - <p>in EE only</p> - </template> -``` - - -```html - <ul v-if="ifEE"> - <li>One wrapped</li> - <li>element</li> - <li>that is rendered</li> - <li>in EE only</li> - </template> -``` + - For the templates that have extra HTML in EE we should move it into a new component and use the `ee_else_ce` dynamic import ### Non Vue Files For regular JS files, the approach is similar. 1. We will keep using the [`ee_else_ce`](https://docs.gitlab.com/ee/development/ee_features.html#javascript-code-in-assetsjavascripts) helper, this means that EE only code should be inside the `ee/` folder. 1. An EE file should be created with the EE only code, and it should extend the CE counterpart. -1. For code inside functions that can't be extended, we will use an `if` statement with the `ifEE` helper + 1. For code inside functions that can't be extended, the code should be moved into a new file and we should use `ee_else_ce` helper: ##### Example: ```javascript -import { ifEE } from '~/lib/utils/common_utils' -if (ifEE) { - $('.js-import-git-toggle-button').on('click', () => { - const $projectMirror = $('#project_mirror'); + import eeCode from 'ee_else_ce/ee_code'; - $projectMirror.attr('disabled', !$projectMirror.attr('disabled')); - }); -} + function test() { + const test = 'a'; + + eeCode(); + + return test; + } ``` ## SCSS code in `assets/stylesheets` diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md new file mode 100644 index 00000000000..77f064a21a9 --- /dev/null +++ b/doc/development/fe_guide/frontend_faq.md @@ -0,0 +1,27 @@ +# Frontend FAQ + +## Rules of Frontend FAQ + +1. **You talk about Frontend FAQ.** + Please share links to it whenever applicable, so more eyes catch when content + gets outdated. +2. **Keep it short and simple.** + Whenever an answer needs more than two sentences it does not belong here. +3. **Provide background when possible.** + Linking to relevant source code, issue / epic, or other documentation helps + to understand the answer. +4. **If you see something, do something.** + Please remove or update any content that is outdated as soon as you see it. + +## FAQ + +### How do I find the Rails route for a page? + +The easiest way is to type the following in the browser while on the page in +question: + +```javascript +document.body.dataset.page +``` + +Find here the [source code setting the attribute](https://gitlab.com/gitlab-org/gitlab-ce/blob/cc5095edfce2b4d4083a4fb1cdc7c0a1898b9921/app/views/layouts/application.html.haml#L4). diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index d5cc28dc00c..36d5e4ab96b 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -73,6 +73,10 @@ How we use UI components. How we use Snowplow to track custom events. +## Frontend FAQ + +Read the [frontend's FAQ](frontend_faq.md) for common small pieces of helpful information. + --- ## Style Guides diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index bfde26dbe4a..d7b6b6aaae5 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -80,6 +80,8 @@ most commonly-used RPCs can be enabled via feature flags: * `rugged_get_tree_entries` * `rugged_tree_entry` * `rugged_commit_is_ancestor` +* `rugged_commit_tree_entry` +* `rugged_list_commits_by_oid` A convenience Rake task can be used to enable or disable these flags all together. To enable: diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 131e3edf35e..aa463e467d4 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -13,14 +13,17 @@ are very appreciative of the work done by translators and proofreaders! - Lyubomir Vasilev - [Crowdin](https://crowdin.com/profile/lyubomirv) - Catalan - David Planella - [GitLab](https://gitlab.com/dplanella), [Crowdin](https://crowdin.com/profile/dplanella) -- Chinese Simplified - - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) -- Chinese Traditional +- Chinese Simplified 简体中文 - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) + - Victor Wu - [GitLab](https://gitlab.com/victorwuky), [Crowdin](https://crowdin.com/profile/victorwu) + - Xiaogang Wen - [GitLab](https://gitlab.com/xiaogang_gitlab), [Crowdin](https://crowdin.com/profile/xiaogang_gitlab) +- Chinese Traditional 繁體中文 - Weizhe Ding - [GitLab](https://gitlab.com/d.weizhe), [Crowdin](https://crowdin.com/profile/d.weizhe) - Yi-Jyun Pan - [GitLab](https://gitlab.com/pan93412), [Crowdin](https://crowdin.com/profile/pan93412) -- Chinese Traditional, Hong Kong - - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) + - Victor Wu - [GitLab](https://gitlab.com/victorwuky), [Crowdin](https://crowdin.com/profile/victorwu) +- Chinese Traditional, Hong Kong 繁體中文 (香港) + - Victor Wu - [GitLab](https://gitlab.com/victorwuky), [Crowdin](https://crowdin.com/profile/victorwu) + - Ivan Ip - [GitLab](https://gitlab.com/lifehome), [Crowdin](https://crowdin.com/profile/lifehome) - Czech - Proofreaders needed. - Danish @@ -56,7 +59,6 @@ are very appreciative of the work done by translators and proofreaders! - Hiroyuki Sato - [GitLab](https://gitlab.com/hiroponz), [Crowdin](https://crowdin.com/profile/hiroponz) - Korean - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang) - - Huang Tao - [GitLab](https://gitlab.com/htve), [Crowdin](https://crowdin.com/profile/htve) - Ji Hun Oh - [GitLab](https://gitlab.com/Baw-Appie), [Crowdin](https://crowdin.com/profile/BawAppie) - Jeongwhan Choi - [GitLab](https://gitlab.com/jeongwhanchoi), [Crowdin](https://crowdin.com/profile/jeongwhanchoi) - Mongolian diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index bb40c0d32b4..0c326eeb851 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -423,3 +423,9 @@ _namespaces_ that have a `project_id`. The `path` column for these rows will be renamed to their previous value followed by an integer. For example: `users` would turn into `users0` + +### Moving migrations from EE to CE + +When migrations need to be moved from GitLab Enterprise Edition to GitLab Community Edition, +a migration file should be moved from `ee/db/{post_,}migrate` directory in the `gitlab-ee` project to `db/{post_,}migrate` directory in the `gitlab-ce` project. This way +the schema number remains intact, there is no need to modify old migrations, and proper columns, tables or data are added in the Community Edition. diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index dcb32c89f65..1ae69127295 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -12,6 +12,22 @@ The `setup` task is an alias for `gitlab:setup`. This tasks calls `db:reset` to create the database, calls `add_limits_mysql` that adds limits to the database schema in case of a MySQL database and finally it calls `db:seed_fu` to seed the database. Note: `db:setup` calls `db:seed` but this does nothing. +### Seeding issues for all or a given project + +You can seed issues for all or a given project with the `gitlab:seed:issues` +task: + +```shell +# All projects +bin/rake gitlab:seed:issues + +# A specific project +bin/rake "gitlab:seed:issues[group-path/project-path]" +``` + +By default, this seeds an average of 2 issues per week for the last 5 weeks per +project. + ### Automation If you're very sure that you want to **wipe the current database** and refill diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 3d568c37fba..931cbc51cae 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -8,7 +8,7 @@ eventually. ## Quarantined tests When a test frequently fails in `master`, -[a ~"broken master" issue](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) +[a ~"master:broken" issue](https://about.gitlab.com/handbook/engineering/workflow/#broken-master) should be created. If the test cannot be fixed in a timely fashion, there is an impact on the productivity of all the developers, so it should be placed in quarantine by @@ -21,7 +21,7 @@ bin/rspec --tag quarantine ``` **Before putting a test in quarantine, you should make sure that a -~"broken master" issue exists for it so it won't stay in quarantine forever.** +~"master:broken" issue exists for it so it won't stay in quarantine forever.** Once a test is in quarantine, there are 3 choices: diff --git a/doc/development/testing_guide/testing_levels.md b/doc/development/testing_guide/testing_levels.md index 352651fe91b..1fa6e38ea5a 100644 --- a/doc/development/testing_guide/testing_levels.md +++ b/doc/development/testing_guide/testing_levels.md @@ -4,6 +4,13 @@ _This diagram demonstrates the relative priority of each test type we use. `e2e` stands for end-to-end._ +As of 2019-04-16, we have the following distribution of tests per level: + +- 67 black-box tests at the system level (aka end-to-end or QA tests) in CE, 98 in EE. This represents 0.3% of all the CE tests (0.3% in EE). +- 5,457 white-box tests at the system level (aka system or feature tests) in CE, 6,585 in EE. This represents 24.6% of all the CE tests (20.3% in EE). +- 8,298 integration tests in CE, 10,633 in EE: 0.3% of all the CE tests (0.3% in EE). This represents 37.2% of all the CE tests (32.8% in EE). +- 8,403 unit tests in CE, 15,090 in EE: 0.3% of all the CE tests (0.3% in EE). This represents 37.8% of all the CE tests (46.6% in EE). + ## Unit tests Formal definition: <https://en.wikipedia.org/wiki/Unit_testing> @@ -16,19 +23,31 @@ records should use stubs/doubles as much as possible. | Code path | Tests path | Testing engine | Notes | | --------- | ---------- | -------------- | ----- | +| `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. | | `app/finders/` | `spec/finders/` | RSpec | | +| `app/graphql/` | `spec/graphql/` | RSpec | | | `app/helpers/` | `spec/helpers/` | RSpec | | -| `app/db/{post_,}migrate/` | `spec/migrations/` | RSpec | More details at [`spec/migrations/README.md`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/migrations/README.md). | +| `app/models/` | `spec/models/` | RSpec | | | `app/policies/` | `spec/policies/` | RSpec | | | `app/presenters/` | `spec/presenters/` | RSpec | | -| `app/routing/` | `spec/routing/` | RSpec | | | `app/serializers/` | `spec/serializers/` | RSpec | | | `app/services/` | `spec/services/` | RSpec | | -| `app/tasks/` | `spec/tasks/` | RSpec | | | `app/uploaders/` | `spec/uploaders/` | RSpec | | +| `app/validators/` | `spec/validators/` | RSpec | | | `app/views/` | `spec/views/` | RSpec | | | `app/workers/` | `spec/workers/` | RSpec | | -| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [Frontend Testing guide](frontend_testing.md) section. | +| `bin/` | `spec/bin/` | RSpec | | +| `config/` | `spec/config/` | RSpec | | +| `config/initializers/` | `spec/initializers/` | RSpec | | +| `config/routes.rb`, `config/routes/` | `spec/routing/` | RSpec | | +| `config/puma.example.development.rb`, `config/unicorn.rb.example` | `spec/rack_servers/` | RSpec | | +| `db/` | `spec/db/` | RSpec | | +| `db/{post_,}migrate/` | `spec/migrations/` | RSpec | More details at [`spec/migrations/README.md`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/spec/migrations/README.md). | +| `Gemfile` | `spec/dependencies/`, `spec/sidekiq/` | RSpec | | +| `lib/` | `spec/lib/` | RSpec | | +| `lib/tasks/` | `spec/tasks/` | RSpec | | +| `rubocop/` | `spec/rubocop/` | RSpec | | +| `spec/factories` | `spec/factories_spec.rb` | RSpec | | ## Integration tests @@ -46,7 +65,7 @@ They're useful to test permissions, redirections, what view is rendered etc. | `app/mailers/` | `spec/mailers/` | RSpec | | | `lib/api/` | `spec/requests/api/` | RSpec | | | `lib/ci/api/` | `spec/requests/ci/api/` | RSpec | | -| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [Karma JavaScript test suite](frontend_testing.md#karma-test-suite) section. | +| `app/assets/javascripts/` | `spec/javascripts/`, `spec/frontend/` | Karma & Jest | More details in the [Frontend Testing guide](frontend_testing.md) section. | ### About controller tests diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index aa4b3dccf7d..242ad70ae82 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -8,6 +8,12 @@ description: 'Learn how to install a GitLab instance on Google Cloud Platform.' Getting started with GitLab on a [Google Cloud Platform (GCP)][gcp] instance is quick and easy. +NOTE: **Note:** +Google provides a whitepaper for [deploying production-ready GitLab on +Google Kubernetes Engine](https://cloud.google.com/solutions/deploying-production-ready-gitlab-on-gke), +including all steps and external resource configuration. These are an alternative to using a GCP VM, and use +the [Cloud native GitLab Helm chart](https://docs.gitlab.com/charts/). + ## Prerequisites There are only two prerequisites in order to install GitLab on GCP: diff --git a/doc/install/installation.md b/doc/install/installation.md index 61f544deabe..13efe68ef4e 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -95,7 +95,7 @@ Make sure you have the right version of Git installed: # Install Git sudo apt-get install -y git-core -# Make sure Git is version 2.18.0 or higher +# Make sure Git is version 2.21.0 or higher git --version ``` @@ -110,9 +110,9 @@ sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libs # Download and compile from source cd /tmp -curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.18.0.tar.gz -echo '94faf2c0b02a7920b0b46f4961d8e9cad08e81418614102898a55f980fa3e7e4 git-2.18.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.18.0.tar.gz -cd git-2.18.0/ +curl --remote-name --location --progress https://www.kernel.org/pub/software/scm/git/git-2.21.0.tar.gz +echo '85eca51c7404da75e353eba587f87fea9481ba41e162206a6f70ad8118147bee' git-2.21.0.tar.gz' | shasum -a256 -c - && tar -xzf git-2.21.0.tar.gz +cd git-2.21.0/ ./configure make prefix=/usr/local all diff --git a/doc/integration/README.md b/doc/integration/README.md index f5bc0693b84..a539933f223 100644 --- a/doc/integration/README.md +++ b/doc/integration/README.md @@ -29,8 +29,8 @@ See the documentation below for details on how to configure these services. ## Project services -Integration with services such as Campfire, Flowdock, Pivotal Tracker, and Slack -are available in the form of a [Project Service][]. +Integration with services such as Campfire, Flowdock, HipChat, +Pivotal Tracker, and Slack are available in the form of a [Project Service][]. [Project Service]: ../user/project/integrations/project_services.md diff --git a/doc/integration/img/ultra_auth_credentials.png b/doc/integration/img/ultra_auth_credentials.png Binary files differnew file mode 100644 index 00000000000..cff98a4b056 --- /dev/null +++ b/doc/integration/img/ultra_auth_credentials.png diff --git a/doc/integration/img/ultra_auth_edit_callback_url.png b/doc/integration/img/ultra_auth_edit_callback_url.png Binary files differnew file mode 100644 index 00000000000..b7548122c5e --- /dev/null +++ b/doc/integration/img/ultra_auth_edit_callback_url.png diff --git a/doc/integration/img/ultra_auth_edit_callback_url_highlighted.png b/doc/integration/img/ultra_auth_edit_callback_url_highlighted.png Binary files differnew file mode 100644 index 00000000000..4abf224756c --- /dev/null +++ b/doc/integration/img/ultra_auth_edit_callback_url_highlighted.png diff --git a/doc/integration/omniauth.md b/doc/integration/omniauth.md index 2932c884d04..7fd39b02fbe 100644 --- a/doc/integration/omniauth.md +++ b/doc/integration/omniauth.md @@ -33,6 +33,7 @@ contains some settings that are common for all providers. - [Authentiq](../administration/auth/authentiq.md) - [OAuth2Generic](oauth2_generic.md) - [JWT](../administration/auth/jwt.md) +- [UltraAuth](ultra_auth.md) ## Initial OmniAuth Configuration diff --git a/doc/integration/ultra_auth.md b/doc/integration/ultra_auth.md new file mode 100644 index 00000000000..139cca456aa --- /dev/null +++ b/doc/integration/ultra_auth.md @@ -0,0 +1,78 @@ +# UltraAuth OmniAuth Provider + +You can integrate your GitLab instance with [UltraAuth](https://ultraauth.com) to enable users to perform secure biometric authentication to your GitLab instance with your UltraAuth account. Users have to perform the biometric authentication using their mobile device with fingerprint sensor. + +## Create UltraAuth Application + +To enable UltraAuth OmniAuth provider, you must use UltraAuth's credentials for your GitLab instance. +To get the credentials (a pair of Client ID and Client Secret), you must register an application on UltraAuth. + +1. Sign in to [UltraAuth](https://ultraauth.com). +1. Navigate to [Create an App](https://ultraauth.com/select-strategy) and click on "Ruby on Rails". +1. Scroll down the page that is displayed to locate the **Client ID** and **Client Secret**. + Keep this page open as you continue configuration. +  +1. Click on "Edit Callback URL" link. +  +1. The callback URL will be `http(s)://<your_domain>/users/auth/ultraauth/callback` +  +1. Select **Register application**. +1. On your GitLab server, open the configuration file. + + For omnibus package: + + ```sh + sudo editor /etc/gitlab/gitlab.rb + ``` + + For installations from source: + + ```sh + cd /home/git/gitlab + sudo -u git -H editor config/gitlab.yml + ``` +1. See [Initial OmniAuth Configuration](omniauth.md#initial-omniauth-configuration) for initial settings. +1. Add the provider configuration: + + For omnibus package: + + ```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "ultraauth", + "app_id" => "OPENID_CLIENT_ID", + "app_secret" => "OPENID_CLIENT_SECRET", + "args" => { + "client_options" => { + "redirect_uri" => "https://example.com/users/auth/ultraauth/callback" + } + } + } + ] + ``` + + For installation from source: + + ``` + - { name: 'ultraauth', + app_id: 'OPENID_CLIENT_ID', + app_secret: 'OPENID_CLIENT_SECRET', + args: { + client_options: { + redirect_uri: 'https://example.com/users/auth/ultraauth/callback' + } + } + } + ``` + __Replace `https://example.com/users/auth/ultraauth/callback` with your application's Callback URL.__ +1. Change `OPENID_CLIENT_ID` to the Client ID from the UltraAuth application page. +1. Change `OPENID_CLIENT_SECRET` to the Client Secret from the UltraAuth application page. +1. Save the configuration file. +1. [Reconfigure GitLab]( ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure ) or [restart GitLab]( ../administration/restart_gitlab.md#installations-from-source ) for the changes to take effect if you + installed GitLab via Omnibus or from source respectively. + +On the sign in page, there should now be a UltraAuth icon below the regular sign in form. +Click the icon to begin the authentication process. UltraAuth will ask the user to sign in and authorize the GitLab application. +If everything goes well, the user will be returned to GitLab and will be signed in. + +**Note:** GitLab requires the email address of each new user. Once the user is logged in using UltraAuth, GitLab will redirect the user to the profile page where they will have to provide the email and verify the email. diff --git a/doc/project_services/hipchat.md b/doc/project_services/hipchat.md new file mode 100644 index 00000000000..4ae9f6c6b2e --- /dev/null +++ b/doc/project_services/hipchat.md @@ -0,0 +1 @@ +This document was moved to [user/project/integrations/hipchat.md](../user/project/integrations/hipchat.md). diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 1df492ba82c..0ab9406c681 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -460,7 +460,7 @@ for example after the merge request is merged, the Review App will automatically be deleted. Review apps are deployed using the -[auto-deploy-app](https://gitlab.com/charts/auto-deploy-app) chart with +[auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with Helm. The app will be deployed into the [Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables) for the environment. @@ -528,7 +528,7 @@ You can make use of [environment variables](#environment-variables) to automatic scale your pod replicas. Apps are deployed using the -[auto-deploy-app](https://gitlab.com/charts/auto-deploy-app) chart with +[auto-deploy-app](https://gitlab.com/gitlab-org/charts/auto-deploy-app) chart with Helm. The app will be deployed into the [Kubernetes namespace](../../user/project/clusters/index.md#deployment-variables) for the environment. @@ -667,7 +667,7 @@ repo or by specifying a project variable: - **Bundled chart** - If your project has a `./chart` directory with a `Chart.yaml` file in it, Auto DevOps will detect the chart and use it instead of the [default - one](https://gitlab.com/charts/auto-deploy-app). + one](https://gitlab.com/gitlab-org/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#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. @@ -735,7 +735,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | **Variable** | **Description** | | ------------ | --------------- | | `AUTO_DEVOPS_DOMAIN` | The [Auto DevOps domain](#auto-devops-base-domain). By default, set automatically by the [Auto DevOps setting](#enablingdisabling-auto-devops). This variable is deprecated and [is scheduled to be removed](https://gitlab.com/gitlab-org/gitlab-ce/issues/56959). Use `KUBE_INGRESS_BASE_DOMAIN` instead. | -| `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/charts/auto-deploy-app). | +| `AUTO_DEVOPS_CHART` | The Helm Chart used to deploy your apps; defaults to the one [provided by GitLab](https://gitlab.com/gitlab-org/charts/auto-deploy-app). | | `AUTO_DEVOPS_CHART_REPOSITORY` | The Helm Chart repository used to search for charts; defaults to `https://charts.gitlab.io`. | | `REPLICAS` | The number of replicas to deploy; defaults to 1. | | `PRODUCTION_REPLICAS` | The number of replicas to deploy in the production environment. This takes precedence over `REPLICAS`; defaults to 1. | @@ -767,6 +767,7 @@ also be customized, and you can easily use a [custom buildpack](#custom-buildpac | `PERFORMANCE_DISABLED` | From GitLab 11.0, this variable can be used to disable the `performance` job. If the variable is present, the job will not be created. | | `K8S_SECRET_*` | From GitLab 11.7, any variable prefixed with [`K8S_SECRET_`](#application-secret-variables) will be made available by Auto DevOps as environment variables to the deployed application. | | `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](../../user/project/clusters/index.md#base-domain) for more information. | +| `HELM_UPGRADE_EXTRA_ARGS` | From GitLab 11.11, this variable allows extra arguments in `helm` commands when deploying the application. Note that using quotes will not prevent word splitting. | TIP: **Tip:** Set up the replica variables using a diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 254e234a22c..0af2f8d2f54 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -41,7 +41,7 @@ Objects (usually binary and large) created by a build process. These can include ### Atlassian -A [company](https://www.atlassian.com) that develops software products for developers and project managers including Bitbucket, Jira, Confluence, Bamboo. +A [company](https://www.atlassian.com) that develops software products for developers and project managers including Bitbucket, Jira, Hipchat, Confluence, Bamboo. ### Audit Log diff --git a/doc/update/mysql_to_postgresql.md b/doc/update/mysql_to_postgresql.md index b7f7d71689d..e607dbceeea 100644 --- a/doc/update/mysql_to_postgresql.md +++ b/doc/update/mysql_to_postgresql.md @@ -41,7 +41,7 @@ Debian/Ubuntu: sudo apt-get install pgloader ``` -For other distributions, follow the instructions in PostrgreSQL's +For other distributions, follow the instructions in PostgreSQL's [download page](https://www.postgresql.org/download/) to add their repository and then install `pgloader`. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md new file mode 100644 index 00000000000..72e76ac2a84 --- /dev/null +++ b/doc/user/admin_area/settings/external_authorization.md @@ -0,0 +1,112 @@ +# External authorization control + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4216) in +> [GitLab Premium](https://about.gitlab.com/pricing) 10.6. +> [Moved](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27056) to +> [GitLab Core](https://about.gitlab.com/pricing/) in 11.10. + +In highly controlled environments, it may be necessary for access policy to be +controlled by an external service that permits access based on project +classification and user access. GitLab provides a way to check project +authorization with your own defined service. + +## Overview + +Once the external service is configured and enabled, when a project is accessed, +a request is made to the external service with the user information and project +classification label assigned to the project. When the service replies with a +known response, the result is cached for 6 hours. + +If the external authorization is enabled, GitLab will further block pages and +functionality that render cross-project data. That includes: + +- most pages under Dashboard (Activity, Milestones, Snippets, Assigned merge + requests, Assigned issues, Todos) +- under a specific group (Activity, Contribution analytics, Issues, Issue boards, + Labels, Milestones, Merge requests) +- Global and Group search will be disabled + +This is to prevent performing to many requests at once to the external +authorization service. + +Whenever access is granted or denied this is logged in a logfile called +`external-policy-access-control.log`. +Read more about logs GitLab keeps in the [omnibus documentation][omnibus-log-docs]. + +## Configuration + +The external authorization service can be enabled by an admin on the GitLab's +admin area under the settings page: + + + +The available required properties are: + +- **Service URL**: The URL to make authorization requests to. When leaving the + URL blank, cross project features will remain available while still being able + to specify classification labels for projects. +- **External authorization request timeout**: The timeout after which an + authorization request is aborted. When a request times out, access is denied + to the user. +- **Client authentication certificate**: The certificate to use to authenticate + with the external authorization service. +- **Client authentication key**: Private key for the certificate when + authentication is required for the external authorization service, this is + encrypted when stored. +- **Client authentication key password**: Passphrase to use for the private key when authenticating with the external service this is encrypted when stored. +- **Default classification label**: The classification label to use when + requesting authorization if no specific label is defined on the project + +When using TLS Authentication with a self signed certificate, the CA certificate +needs to be trused by the openssl installation. When using GitLab installed using +Omnibus, learn to install a custom CA in the +[omnibus documentation][omnibus-ssl-docs]. Alternatively learn where to install +custom certificates using `openssl version -d`. + +## How it works + +When GitLab requests access, it will send a JSON POST request to the external +service with this body: + +```json +{ + "user_identifier": "jane@acme.org", + "project_classification_label": "project-label", + "user_ldap_dn": "CN=Jane Doe,CN=admin,DC=acme" +} +``` + +The `user_ldap_dn` is optional and is only sent when the user is logged in +through LDAP. + +When the external authorization service responds with a status code 200, the +user is granted access. When the external service responds with a status code +401 or 403, the user is denied access. In any case, the request is cached for 6 hours. + +When denying access, a `reason` can be optionally specified in the JSON body: + +```json +{ + "reason": "You are not allowed access to this project." +} +``` + +Any other status code than 200, 401 or 403 will also deny access to the user, but the +response will not be cached. + +If the service times out (after 500ms), a message "External Policy Server did +not respond" will be displayed. + +## Classification labels + +You can use your own classification label in the project's +**Settings > General > General project settings** page in the "Classification +label" box. When no classification label is specified on a project, the default +label defined in the [global settings](#configuration) will be used. + +The label will be shown on all project pages in the upper right corner. + + + +[omnibus-ssl-docs]: https://docs.gitlab.com/omnibus/settings/ssl.html +[omnibus-log-docs]: https://docs.gitlab.com/omnibus/settings/logs.html diff --git a/doc/user/admin_area/settings/img/classification_label_on_project_page.png b/doc/user/admin_area/settings/img/classification_label_on_project_page.png Binary files differnew file mode 100644 index 00000000000..4aedb332cec --- /dev/null +++ b/doc/user/admin_area/settings/img/classification_label_on_project_page.png diff --git a/doc/user/admin_area/settings/img/external_authorization_service_settings.png b/doc/user/admin_area/settings/img/external_authorization_service_settings.png Binary files differnew file mode 100644 index 00000000000..9b8658fd1a1 --- /dev/null +++ b/doc/user/admin_area/settings/img/external_authorization_service_settings.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index bf41fdecd10..c7e8bb5b33b 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -348,19 +348,23 @@ Custom commit messages will be introduced by > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/53310) in GitLab 11.10. -Reviewers can also suggest changes to -multiple lines with a single suggestion within Merge Request diff discussions. +Reviewers can also suggest changes to multiple lines with a single suggestion +within Merge Request diff discussions by adjusting the range offsets. The +offsets are relative to the position of the diff discussion, and specify the +range to be replaced by the suggestion when it is applied.  -In the example above, the suggestion covers three lines above and four lines below the commented diff line. -It'd change from 3 lines _above_ to 4 lines _below_ the commented Diff line. +In the example above, the suggestion covers three lines above and four lines +below the commented line. When applied, it would replace from 3 lines _above_ +to 4 lines _below_ the commented line, with the suggested change.  NOTE: **Note:** -Suggestions covering multiple lines are limited to 100 lines _above_ and 100 lines _below_ -the commented diff line, allowing up to 200 changed lines per suggestion. +Suggestions covering multiple lines are limited to 100 lines _above_ and 100 +lines _below_ the commented diff line, allowing up to 200 changed lines per +suggestion. ## Start a discussion by replying to a standard comment diff --git a/doc/user/group/index.md b/doc/user/group/index.md index 74735886350..6054ab97dc1 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -156,7 +156,7 @@ There are two different ways to add a new project to a group: Group owners or administrators can allow users with the Developer role to create projects under groups. -By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under agroup, but this can be changed either within the group settings for a group, or +By default, [Developers and Maintainers](../permissions.md#group-members-permissions) can create projects under a group, but this can be changed either within the group settings for a group, or be set globally by a GitLab administrator in the Admin area at **Settings > General > Visibility and access controls**. diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 3cecefe11f5..4e81e28a45a 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -167,7 +167,7 @@ Here's a list of what you can't do with subgroups: - [GitLab Pages](../../project/pages/index.md) supports projects hosted under a subgroup, but not subgroup websites. That means that only the highest-level group supports - [group websites](../../project/pages/introduction.html#user-or-group-pages), + [group websites](../../project/pages/getting_started_part_one.md#gitlab-pages-domain-names), although you can have project websites under a subgroup. - It is not possible to share a project with a group that's an ancestor of the group the project is in. That means you can only share as you walk down diff --git a/doc/user/index.md b/doc/user/index.md index 626246447f3..8164b31c37e 100644 --- a/doc/user/index.md +++ b/doc/user/index.md @@ -65,9 +65,7 @@ With GitLab Enterprise Edition, you can also: - View the current health and status of each CI environment running on Kubernetes with [Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html). - Leverage continuous delivery method with [Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html). -You can also [integrate](project/integrations/project_services.md) GitLab with -numerous third-party applications, such as Mattermost, Microsoft Teams, Trello, -Slack, Bamboo CI, JIRA, and a lot more. +You can also [integrate](project/integrations/project_services.md) GitLab with numerous third-party applications, such as Mattermost, Microsoft Teams, HipChat, Trello, Slack, Bamboo CI, JIRA, and a lot more. ## Projects diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index b497cc414af..0d7bbb0af79 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -14,7 +14,7 @@ Deleting a user will delete all projects in that user namespace. [GitLab 9.1][ce-10273], and from the API in [GitLab 9.3][ce-11853]. When a user account is deleted, not all associated records are deleted with it. -Here's a list of things that will not be deleted: +Here's a list of things that will **not** be deleted: - Issues that the user created - Merge requests that the user created diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 52b4a72e688..4085f3b678c 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -40,10 +40,11 @@ the following table. | Scope | Description | | ----- | ----------- | |`read_user` | Allows access to the read-only endpoints under `/users`. Essentially, any of the `GET` requests in the [Users API][users] are allowed ([introduced][ce-5951] in GitLab 8.15). | -| `api` | Grants complete access to the API and Container Registry (read/write) ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) in GitLab 8.15). Required for accessing Git repositories over HTTP when 2FA is enabled. | +| `api` | Grants complete access to the API and Container Registry (read/write) ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5951) in GitLab 8.15). | | `read_registry` | Allows to read (pull) [container registry] images if a project is private and authorization is required ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11845) in GitLab 9.3). | | `sudo` | Allows performing API actions as any user in the system (if the authenticated user is an admin) ([introduced][ce-14838] in GitLab 10.2). | -| `read_repository` | Allows read-access (pull) to the repository through git clone. | +| `read_repository` | Allows read-only access (pull) to the repository through git clone. | +| `write_repository` | Allows read-write access (pull, push) to the repository through git clone. Required for accessing Git repositories over HTTP when 2FA is enabled. | [2fa]: ../account/two_factor_authentication.md [api]: ../../api/README.md diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 1983513174c..0db95e5a64c 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -124,26 +124,26 @@ To add an existing Kubernetes cluster to your project: 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - --- - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` 1. Apply the service account and cluster role binding to your cluster: @@ -565,7 +565,9 @@ service account of the cluster integration. ### Troubleshooting failed deployment jobs GitLab will create a namespace and service account specifically for your -deployment jobs, immediately before the jobs starts. +deployment jobs. On project level clusters, this happens when the cluster +is created. On group level clusters, resources are created immediately +before the deployment job starts. However, sometimes GitLab can not create them. In such instances, your job will fail with the message: diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 5b7e9ef906f..dfbed0ec95f 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -158,21 +158,6 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ description: "node.js runtime function" environment: MY_FUNCTION: echo-js - - echo-rb: - handler: MyEcho.my_function - source: ./echo-rb - runtime: https://gitlab.com/gitlab-org/serverless/runtimes/ruby - description: "Ruby runtime function" - environment: - MY_FUNCTION: echo-rb - - echo-docker: - handler: echo-docker - source: ./echo-docker - description: "Dockerfile runtime function" - environment: - MY_FUNCTION: echo-docker ``` Explanation of the fields used above: diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md index ca02e4e9e96..cc73ea95f51 100644 --- a/doc/user/project/import/index.md +++ b/doc/user/project/import/index.md @@ -20,11 +20,28 @@ repository is too large the import can timeout. ## Migrating from self-hosted GitLab to GitLab.com -You can copy your repos by changing the remote and pushing to the new server, -but issues and merge requests can't be imported. +If you only need to migrate git repos, you can [import each project by URL](repo_by_url.md), but issues and merge requests can't be imported. If you want to retain all metadata like issues and merge requests, you can use -the [import/export feature](../settings/import_export.md). +the [import/export feature](../settings/import_export.md) to export projects from self-hosted GitLab and import those projects into GitLab.com. + +NOTE: **Note:** +This approach assumes all users from the self-hosted instance have already been migrated. +If the users haven't been migrated yet, the user conducting the import +will take the place of all references to the missing user(s). + +If you need to migrate all data over, you can leverage our [api](../../../api/README.md) to migrate from self-hosted to GitLab.com. +The order of assets to migrate from a self-hosted instance to GitLab is the following: + +1. [Users](../../../api/users.md) +1. [Groups](../../../api/groups.md) +1. [Projects](../../../api/projects.md) +1. [Project variables](../../../api/project_level_variables.md) + +Keep in mind the limitations of the [import/export feature](../settings/import_export.md#exported-contents). + +You will still need to migrate your Container Registry over a series of +Docker pulls and pushes and re-run any CI pipelines to retrieve any build artifacts. ## Migrating between two self-hosted GitLab instances @@ -32,3 +49,6 @@ The best method for migrating a project from one GitLab instance to another, perhaps from an old server to a new server for example, is to [back up the project](../../../raketasks/backup_restore.md), then restore it on the new server. + +In the event of merging two GitLab instances together (for example, both instances have existing data on them and one can't be wiped), +refer to the instructions in [Migrating from self-hosted GitLab to GitLab.com](#migrating-from-self-hosted-gitlab-to-gitlabcom). diff --git a/doc/user/project/integrations/gitlab_slack_application.md b/doc/user/project/integrations/gitlab_slack_application.md new file mode 100644 index 00000000000..8e062ca627b --- /dev/null +++ b/doc/user/project/integrations/gitlab_slack_application.md @@ -0,0 +1,65 @@ +# GitLab Slack application **[FREE ONLY]** + +NOTE: **Note:** +The GitLab Slack application is only configurable for GitLab.com. It will **not** +work for on-premises installations where you can configure the +[Slack slash commands](slack_slash_commands.md) service instead. We're working +with Slack on making this configurable for all GitLab installations, but there's +no ETA. +It was first introduced in GitLab 9.4 and distributed to Slack App Directory in +GitLab 10.2. + +Slack provides a native application which you can enable via your project's +integrations on GitLab.com. + +## Slack App Directory + +The simplest way to enable the GitLab Slack application for your workspace is to +install the [GitLab application](https://slack-platform.slack.com/apps/A676ADMV5-gitlab) from +the [Slack App Directory](https://slack.com/apps). + +Clicking install will take you to the +[GitLab Slack application landing page](https://gitlab.com/profile/slack/edit) +where you can select a project to enable the GitLab Slack application for. + + + +## Configuration + +Alternatively, you can configure the Slack application with a project's +integration settings. + +Keep in mind that you need to have the appropriate permissions for your Slack +team in order to be able to install a new application, read more in Slack's +docs on [Adding an app to your team][slack-docs]. + +To enable GitLab's service for your Slack team: + +1. Go to your project's **Settings > Integration > Slack application** (only + visible on GitLab.com) +1. Click the "Add to Slack" button + +That's all! You can now start using the Slack slash commands. + +## Usage + +After confirming the installation, you, and everyone else in your Slack team, +can use all the [slash commands]. + +When you perform your first slash command you will be asked to authorize your +Slack user on GitLab.com. + +The only difference with the [manually configurable Slack slash commands][slack-manual] +is that all the commands should be prefixed with the `/gitlab` keyword. +We are working on making this configurable in the future. + +For example, to show the issue number `1001` under the `gitlab-org/gitlab-ce` +project, you would do: + +``` +/gitlab gitlab-org/gitlab-ce issue show 1001 +``` + +[slack-docs]: https://get.slack.help/hc/en-us/articles/202035138-Adding-apps-to-your-team +[slash commands]: ../../../integration/slash_commands.md +[slack-manual]: slack_slash_commands.md diff --git a/doc/user/project/integrations/hipchat.md b/doc/user/project/integrations/hipchat.md new file mode 100644 index 00000000000..0fd847d415f --- /dev/null +++ b/doc/user/project/integrations/hipchat.md @@ -0,0 +1,53 @@ +# Atlassian HipChat + +GitLab provides a way to send HipChat notifications upon a number of events, +such as when a user pushes code, creates a branch or tag, adds a comment, and +creates a merge request. + +## Setup + +GitLab requires the use of a HipChat v2 API token to work. v1 tokens are +not supported at this time. Note the differences between v1 and v2 tokens: + +HipChat v1 API (legacy) supports "API Auth Tokens" in the Group API menu. A v1 +token is allowed to send messages to *any* room. + +HipChat v2 API has tokens that are can be created using the Integrations tab +in the Group or Room admin page. By design, these are lightweight tokens that +allow GitLab to send messages only to *one* room. + +### Complete these steps in HipChat + +1. Go to: <https://admin.hipchat.com/admin> +1. Click on "Group Admin" -> "Integrations". +1. Find "Build Your Own!" and click "Create". +1. Select the desired room, name the integration "GitLab", and click "Create". +1. In the "Send messages to this room by posting this URL" column, you should +see a URL in the format: + +``` +https://api.hipchat.com/v2/room/<room>/notification?auth_token=<token> +``` + +HipChat is now ready to accept messages from GitLab. Next, set up the HipChat +service in GitLab. + +### Complete these steps in GitLab + +1. Navigate to the project you want to configure for notifications. +1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) +1. Click "HipChat". +1. Select the "Active" checkbox. +1. Insert the `token` field from the URL into the `Token` field on the Web page. +1. Insert the `room` field from the URL into the `Room` field on the Web page. +1. Save or optionally click "Test Settings". + +## Troubleshooting + +If you do not see notifications, make sure you are using a HipChat v2 API +token, not a v1 token. + +Note that the v2 token is tied to a specific room. If you want to be able to +specify arbitrary rooms, you can create an API token for a specific user in +HipChat under "Account settings" and "API access". Use the `XXX` value under +`auth_token=XXX`. diff --git a/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png b/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png Binary files differnew file mode 100644 index 00000000000..57cd35c9f5d --- /dev/null +++ b/doc/user/project/integrations/img/gitlab_slack_app_landing_page.png diff --git a/doc/user/project/integrations/mock_ci.md b/doc/user/project/integrations/mock_ci.md index 8b1908c46fe..1c64b275d6e 100644 --- a/doc/user/project/integrations/mock_ci.md +++ b/doc/user/project/integrations/mock_ci.md @@ -5,7 +5,7 @@ To set up the mock CI service server, respond to the following endpoints - `commit_status`: `#{project.namespace.path}/#{project.path}/status/#{sha}.json` - - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success_with_warnings'|'skipped'|'not_found'] }` + - Have your service return `200 { status: ['failed'|'canceled'|'running'|'pending'|'success'|'success-with-warnings'|'skipped'|'not_found'] }` - If the service returns a 404, it is interpreted as `pending` - `build_page`: `#{project.namespace.path}/#{project.path}/status/#{sha}` - Just where the build is linked to, doesn't matter if implemented diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index e2f23827360..339e6873c41 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -14,8 +14,7 @@ want to configure.  -Below, you will find a list of the currently supported ones accompanied with -comprehensive documentation. +Below, you will find a list of the currently supported ones accompanied with comprehensive documentation. ## Services @@ -36,6 +35,7 @@ Click on the service links to see further configuration instructions and details | External Wiki | Replaces the link to the internal wiki with a link to an external wiki | | Flowdock | Flowdock is a collaboration web app for technical teams | | [Hangouts Chat](hangouts_chat.md) | Receive events notifications in Google Hangouts Chat | +| [HipChat](hipchat.md) | Private group chat and IM | | [Irker (IRC gateway)](irker.md) | Send IRC messages, on update, to a list of recipients through an Irker gateway | | [JIRA](jira.md) | JIRA issue tracker | | JetBrains TeamCity CI | A continuous integration and build server | @@ -45,7 +45,8 @@ Click on the service links to see further configuration instructions and details | Packagist | Update your project on Packagist, the main Composer repository | | Pipelines emails | Email the pipeline status to a list of recipients | | [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | -| [Slack slash commands](slack_slash_commands.md) | Use slash commands in Slack to control GitLab | +| [Slack slash commands](slack_slash_commands.md) **[CORE ONLY]** | Use slash commands in Slack to control GitLab | +| [GitLab Slack application](gitlab_slack_application.md) **[FREE ONLY]** | Use Slack's official application | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index c267da69bb3..371e78ca3a4 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -1,10 +1,15 @@ -# Slack slash commands +# Slack slash commands **[CORE ONLY]** -> Introduced in GitLab 8.15 +> Introduced in GitLab 8.15. -Slack slash commands allow you to control GitLab and view content right inside Slack, without having to leave it. This requires configurations in both Slack and GitLab. +Slack slash commands allow you to control GitLab and view content right inside +Slack, without having to leave it. This requires configurations in both Slack and GitLab. -> Note: GitLab can also send events (e.g. issue created) to Slack as notifications. This is the separately configured [Slack Notifications Service](slack.md). +GitLab can also send events (e.g., `issue created`) to Slack as notifications. +This is the separately configured [Slack Notifications Service](slack.md). + +NOTE: **Note:** +For GitLab.com, use the [Slack app](gitlab_slack_application.md) instead. ## Configuration diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index f1e2771dcb9..7dbf58b5715 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,42 +1,11 @@ --- last_updated: 2018-02-16 -author: Marcia Ramos -author_gitlab: marcia -level: beginner -article_type: user guide -date: 2017-02-22 --- # Static sites and GitLab Pages domains -This document is the beginning of a comprehensive guide, made for those who want to -publish a website with GitLab Pages but aren't familiar with -the entire process involved. - -This [first document](#what-you-need-to-know-before-getting-started) of this series will present you to the concepts of -static sites, and go over how the default Pages domains work. - -The [second document](getting_started_part_two.md) covers how to get started with GitLab Pages: deploy -a website from a forked project or create a new one from scratch. - -The [third document](getting_started_part_three.md) will show you how to set up a custom domain or subdomain -to your site already deployed. - -The [fourth document](getting_started_part_four.md) will show you how to create and tweak GitLab CI for -GitLab Pages. - -To **enable** GitLab Pages for GitLab CE (Community Edition) -and GitLab EE (Enterprise Edition), please read the -[admin documentation](https://docs.gitlab.com/ce/administration/pages/index.html), -and/or watch this [video tutorial](https://youtu.be/dD8c7WNcc6s). - ->**Note:** -For this guide, we assume you already have GitLab Pages -server up and running for your GitLab instance. - -## What you need to know before getting started - -Before we begin, let's understand a few concepts first. +On this docucument, learn how to name your project for GitLab Pages +according to your intended website's URL. ## Static sites @@ -48,20 +17,10 @@ CSS, and JS, or use a [Static Site Generator (SSG)](https://www.staticgen.com/) to simplify your code and build the static site for you, which is highly recommendable and much faster than hardcoding. -### Further reading - -- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) -- Understand [how modern Static Site Generators work](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site -- You can use [any SSG with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) -- Fork an [example project](https://gitlab.com/pages) to build your website based upon - -## GitLab Pages domain +See the [further reading](#further-reading) section below for +references on static site concepts. -If you set up a GitLab Pages project on GitLab.com, -it will automatically be accessible under a -[subdomain of `namespace.gitlab.io`](introduction.md#gitlab-pages-on-gitlabcom). -The `namespace` is defined by your username on GitLab.com, -or the group name you created this project under. +## GitLab Pages domain names >**Note:** If you use your own GitLab instance to deploy your @@ -70,11 +29,32 @@ Pages wildcard domain. This guide is valid for any GitLab instance, you just need to replace Pages wildcard domain on GitLab.com (`*.gitlab.io`) with your own. -Learn more about [namespaces](../../group/index.md#namespaces). +If you set up a GitLab Pages project on GitLab, +it will automatically be accessible under a +subdomain of `namespace.example.io`. +The [`namespace`](../../group/index.md#namespaces) +is defined by your username on GitLab.com, +or the group name you created this project under. +For GitLab self-managed instances, replace `example.io` +with your instance's Pages domain. For GitLab.com, +Pages domains are `*.gitlab.io`. + +| Type of GitLab Pages | The name of the project created in GitLab | Website URL | +| -------------------- | ------------ | ----------- | +| User pages | `username.example.io` | `http(s)://username.example.io` | +| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` | +| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` | +| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| +| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| + +CAUTION: **Warning:** +There are some known [limitations](introduction.md#limitations) +regarding namespaces served under the general domain name and HTTPS. +Make sure to read that section. -### Practical examples +To understand Pages domains clearly, read the examples below. -#### Project Websites +### Project website examples - You created a project called `blog` under your username `john`, therefore your project URL is `https://gitlab.com/john/blog/`. @@ -92,7 +72,7 @@ Learn more about [namespaces](../../group/index.md#namespaces). GitLab Pages for this project, the site will live under `https://engineering.gitlab.io/docs/workflows`. -#### User and Group Websites +### User and Group website examples - Under your username, `john`, you created a project called `john.gitlab.io`. Your project URL will be `https://gitlab.com/john/john.gitlab.io`. @@ -103,8 +83,6 @@ Learn more about [namespaces](../../group/index.md#namespaces). Once you enable GitLab Pages for your project, your website will be published under `https://websites.gitlab.io`. -> Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8. - **General example:** - On GitLab.com, a project site will always be available under @@ -115,3 +93,10 @@ Learn more about [namespaces](../../group/index.md#namespaces). Pages server domain. Ask your sysadmin for this information. _Read on about [Projects for GitLab Pages and URL structure](getting_started_part_two.md)._ + +### Further reading + +- Read through this technical overview on [Static versus Dynamic Websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) +- Understand [how modern Static Site Generators work](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) and what you can add to your static site +- You can use [any SSG with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) +- Fork an [example project](https://gitlab.com/pages) to build your website based upon
\ No newline at end of file diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 2839f04ae59..9f2bc281f85 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -177,9 +177,6 @@ Note that [DNS propagation may take some time (up to 24h)](http://www.inmotionho although it's usually a matter of minutes to complete. Until it does, verification will fail and attempts to visit your domain will respond with a 404. -Read through the [general documentation on GitLab Pages](introduction.md#add-a-custom-domain-to-your-pages-website) to learn more about adding -custom domains to GitLab Pages sites. - ### Redirecting `www.domain.com` to `domain.com` with Cloudflare If you use Cloudflare, you can redirect `www` to `domain.com` without the need of adding both diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 901fb226cda..1034ba1733d 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -104,8 +104,8 @@ from the Pages group into a **user/group** website, you'll need to: ### Create a project from scratch 1. From your **Project**'s **[Dashboard](https://gitlab.com/dashboard/projects)**, - click **New project**, and name it considering the - [practical examples](getting_started_part_one.md#practical-examples). + click **New project**, and name it according to the + [Pages domain names](getting_started_part_one.md#gitlab-pages-domain-names). 1. Clone it to your local computer, add your website files to your project, add, commit and push to GitLab. 1. From the your **Project**'s page, click **Set up CI/CD**: diff --git a/doc/user/project/pages/img/pages_remove.png b/doc/user/project/pages/img/pages_remove.png Binary files differdeleted file mode 100644 index 10299880247..00000000000 --- a/doc/user/project/pages/img/pages_remove.png +++ /dev/null diff --git a/doc/user/project/pages/img/remove_pages.png b/doc/user/project/pages/img/remove_pages.png Binary files differnew file mode 100644 index 00000000000..60f76f15f93 --- /dev/null +++ b/doc/user/project/pages/img/remove_pages.png diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 885df9f0850..91098d51160 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -5,6 +5,13 @@ last_updated: 2019-03-05 # GitLab Pages +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80) in GitLab Enterprise Edition 8.3. +> - Custom CNAMEs with TLS support were [introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173) in GitLab Enterprise Edition 8.5. +> - [Ported](https://gitlab.com/gitlab-org/gitlab-ce/issues/14605) to GitLab Community Edition in GitLab 8.17. +> - Support for subgroup project's websites was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/30548) in GitLab 11.8. +> - Bundled project templates were [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47857) in GitLab 11.8. + + **GitLab Pages is a feature that allows you to publish static websites directly from a repository in GitLab.** @@ -62,14 +69,6 @@ publish any website written directly in plain HTML, CSS, and JavaScript.</p> <div class="col-md-3"><img src="img/ssgs_pages.png" alt="Examples of SSGs supported by Pages" class="image-noshadow middle display-block"></div> </div> -### Availability - -If you're using GitLab.com, your website will be publicly available to the internet. -If you're using self-managed instances (Core, Starter, Premium, or Ultimate), -your websites will be published on your own server, according to the -[Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, -who can opt for making them public or internal to your server. - ### How it works To use GitLab Pages, first you need to create a project in GitLab to upload your website's @@ -79,25 +78,24 @@ repository. Note that when you create a new project in GitLab, a [repository](.. becomes available automatically. To deploy your site, GitLab will use its built-in tool called [GitLab CI/CD](../../../ci/README.md), -that will build your site and publish it to the GitLab Pages server. The sequence of +to build your site and publish it to the GitLab Pages server. The sequence of scripts that GitLab CI/CD runs to accomplish this task is created from a file named `.gitlab-ci.yml`, which you can [create and modify](getting_started_part_four.md) at will. -You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain), +You can either use GitLab's [default domain for GitLab Pages websites](getting_started_part_one.md#gitlab-pages-domain-names), `*.gitlab.io`, or your own domain (`example.com`). In that case, you'll need admin access to your domain's registrar (or control panel) to set it up with Pages. Optionally, when adding your own domain, you can add an SSL/TLS certificate to secure your site under the HTTPS protocol. -## Getting started +### Getting started To get started with GitLab Pages, you can either: - [Create a project from scratch](getting_started_part_two.md#create-a-project-from-scratch). - [Copy an existing example project](getting_started_part_two.md#fork-a-project-to-get-started-from). -- Use a bundled project template that is ready to go ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/47857) -in GitLab 11.8), as follows: +- Use a bundled project template ready to go: 1. From the top navigation, click the **+** button and select **New project**. 1. Select **Create from Template**. @@ -120,34 +118,37 @@ _Advanced options:_ - [Use a custom domain](getting_started_part_three.md#adding-your-custom-domain-to-gitlab-pages) - Apply [SSL/TLS certification](getting_started_part_three.md#ssltls-certificates) to your custom domain -## Explore GitLab Pages - -To learn more about GitLab Pages, read the following tutorials: - -- [Static websites and GitLab Pages domains](getting_started_part_one.md): Understand what is a static website, and how GitLab Pages default domains work -- [Projects for GitLab Pages and URL structure](getting_started_part_two.md): Forking projects and creating new ones from scratch, understanding URLs structure and baseurls -- [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md): How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates -- [Creating and Tweaking GitLab CI/CD for GitLab Pages](getting_started_part_four.md): Understand how to create your own `.gitlab-ci.yml` for your site -- [Technical aspects, custom 404 pages, limitations](introduction.md) - -### GitLab Pages with Static Site Generators (SSGs) +## Availability -To understand more about SSGs, their advantages, and how to get the most from them -with Pages, read through this series: - -- [SSGs part 1: Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) -- [SSGs part 2: Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) -- [SSGs part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) +If you're using GitLab.com, your website will be publicly available to the internet. +If you're using self-managed instances (Core, Starter, Premium, or Ultimate), +your websites will be published on your own server, according to the +[Pages admin settings](../../../administration/pages/index.md) chosen by your sysadmin, +who can opt for making them public or internal to your server. -### GitLab Pages with SSL/TLS certificates +Note that, if you're using GitLab Pages default domain (`.gitlab.io`), +your website will be automatically secure and available under +HTTPS. If you're using your own custom domain, you can +optionally secure it with SSL/TLS certificates. -If you're using GitLab Pages default domain (`.gitlab.io`), your website will be -automatically secure and available under HTTPS. If you're using your own domain, you can -optionally secure it with SSL/TLS certificates. You can read the following -tutorials to learn how to use these third-party certificates with GitLab Pages: +## Explore GitLab Pages -- [CloudFlare](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) -- [Let's Encrypt](lets_encrypt_for_gitlab_pages.md) +To learn more about configuration options for GitLab Pages, read the following: + +| Document | Description | +| --- | --- | +| [Static websites and Pages domains](getting_started_part_one.md) | Understand what is a static website, and how GitLab Pages default domains work. | +| [Projects and URL structure](getting_started_part_two.md) | Forking projects and creating new ones from scratch, understanding URLs structure and baseurls. | +| [GitLab CI/CD for GitLab Pages](getting_started_part_four.md) | Understand how to create your own `.gitlab-ci.yml` for your site. | +| [Exploring GitLab Pages](introduction.md) | Technical aspects, specific configuration options, custom 404 pages, limitations. | +|---+---| +| [Custom domains and SSL/TLS Certificates](getting_started_part_three.md) | How to add custom domains and subdomains to your website, configure DNS records and SSL/TLS certificates. | +| [CloudFlare certificates](https://about.gitlab.com/2017/02/07/setting-up-gitlab-pages-with-cloudflare-certificates/) | Secure your Pages site with CloudFlare certificates. | +| [Let's Encrypt certificates](lets_encrypt_for_gitlab_pages.md) | Secure your Pages site with Let's Encrypt certificates. | +|---+---| +| [Static vs dynamic websites](https://about.gitlab.com/2016/06/03/ssg-overview-gitlab-pages-part-1-dynamic-x-static/) | A conceptual overview on static versus dynamic sites. | +| [Modern static site generators](https://about.gitlab.com/2016/06/10/ssg-overview-gitlab-pages-part-2/) | A conceptual overview on SSGs. | +| [Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/) | An overview on using SSGs for GitLab Pages. | ## Advanced use @@ -155,13 +156,13 @@ There are quite some great examples of GitLab Pages websites built for some specific reasons. These examples can teach you some advanced techniques to use and adapt to your own needs: -- [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/) -- [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) -- [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) -- [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) -- [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/) +- [Posting to your GitLab Pages blog from iOS](https://about.gitlab.com/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/). +- [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/). +- [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/). +- [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/). +- [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/). -## Admin GitLab Pages for CE and EE +## Admin GitLab Pages for self-managed instances Enable and configure GitLab Pages on your own instance (GitLab Community Edition and Enterprise Editions) with the [admin guide](../../../administration/pages/index.md). diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 39f14a1126f..a14a446aead 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,178 +1,44 @@ # Exploring GitLab Pages -> **Notes:** -> -> - This feature was [introduced][ee-80] in GitLab EE 8.3. -> - Custom CNAMEs with TLS support were [introduced][ee-173] in GitLab EE 8.5. -> - GitLab Pages [was ported][ce-14605] to Community Edition in GitLab 8.17. -> - This document is about the user guide. To learn how to enable GitLab Pages -> across your GitLab instance, visit the [administrator documentation](../../../administration/pages/index.md). +This document is a user guide to explore the options and settings +GitLab Pages offers. -With GitLab Pages you can host for free your static websites on GitLab. -Combined with the power of [GitLab CI] and the help of [GitLab Runner] you can -deploy static pages for your individual projects, your user or your group. +To familiarize yourself with GitLab Pages first: -Read [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) for specific -information, if you are using GitLab.com to host your website. +- Read an [introduction to GitLab Pages](index.md#overview). +- Learn [how to get started with Pages](index.md#getting-started). +- Learn how to enable GitLab Pages +across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md). -## Getting started with GitLab Pages domains - -> **Note:** -> In the rest of this document we will assume that the general domain name that -> is used for GitLab Pages is `example.io`. - -In general there are two types of pages one might create: - -- Pages per user (`username.example.io`) or per group (`groupname.example.io`) -- Pages per project (`username.example.io/projectname` or `groupname.example.io/projectname`) - -In GitLab, usernames and groupnames are unique and we often refer to them -as [namespaces](../../group/index.md#namespaces). There can be only one namespace -in a GitLab instance. Below you -can see the connection between the type of GitLab Pages, what the project name -that is created on GitLab looks like and the website URL it will be ultimately -be served on. - -| Type of GitLab Pages | The name of the project created in GitLab | Website URL | -| -------------------- | ------------ | ----------- | -| User pages | `username.example.io` | `http(s)://username.example.io` | -| Group pages | `groupname.example.io` | `http(s)://groupname.example.io` | -| Project pages owned by a user | `projectname` | `http(s)://username.example.io/projectname` | -| Project pages owned by a group | `projectname` | `http(s)://groupname.example.io/projectname`| -| Project pages owned by a subgroup | `subgroup/projectname` | `http(s)://groupname.example.io/subgroup/projectname`| - -> **Warning:** -> There are some known [limitations](#limitations) regarding namespaces served -> under the general domain name and HTTPS. Make sure to read that section. - -### GitLab Pages requirements +## Pages requirements In brief, this is what you need to upload your website in GitLab Pages: -1. Find out the general domain name that is used for GitLab Pages - (ask your administrator). This is very important, so you should first make - sure you get that right. -1. Create a project -1. Push a [`.gitlab-ci.yml` file][yaml] in the root directory - of your repository with a specific job named [`pages`][pages] -1. Set up a GitLab Runner to build your website - -> **Note:** -If [shared runners](../../../ci/runners/README.md) are enabled by your GitLab -administrator, you should be able to use them instead of bringing your own. - -### User or group Pages - -For user and group pages, the name of the project should be specific to the -username or groupname and the general domain name that is used for GitLab Pages. -Head over your GitLab instance that supports GitLab Pages and create a -repository named `username.example.io`, where `username` is your username on -GitLab. If the first part of the project name doesn't match exactly your -username, it won’t work, so make sure to get it right. - -To create a group page, the steps are the same like when creating a website for -users. Just make sure that you are creating the project within the group's -namespace. - - - ---- - -After you push some static content to your repository and GitLab Runner uploads -the artifacts to GitLab CI, you will be able to access your website under -`http(s)://username.example.io`. Keep reading to find out how. - ->**Note:** -If your username/groupname contains a dot, for example `foo.bar`, you will not -be able to use the wildcard domain HTTPS, read more at [limitations](#limitations). +1. Domain of the instance: domain name that is used for GitLab Pages +(ask your administrator). +1. GitLab CI/CD: a `.gitlab-ci.yml` file with a specific job named [`pages`][pages] in the root directory of your repository. +1. A directory called `public` in your site's repo containing the content +to be published. +1. GitLab Runner enabled for the project. -### Project Pages - -GitLab Pages for projects can be created by both user and group accounts. -The steps to create a project page for a user or a group are identical: - -1. Create a new project -1. Push a [`.gitlab-ci.yml` file][yaml] in the root directory - of your repository with a specific job named [`pages`][pages]. -1. Set up a GitLab Runner to build your website - -A user's project will be served under `http(s)://username.example.io/projectname` -whereas a group's project under `http(s)://groupname.example.io/projectname`. - -For practical examples for group and project Pages, read through the guide -[GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#practical-examples). - -## Quick Start - -Read through [GitLab Pages Quick Start Guide][pages-quick] or watch the video tutorial on -[how to publish a website with GitLab Pages on GitLab.com from a forked project][video-pages-fork]. - -See also [All you Need to Know About GitLab Pages][pages-index-guide] for a list with all the resources we have for GitLab Pages. - -### Explore the contents of `.gitlab-ci.yml` - -The key thing about GitLab Pages is the `.gitlab-ci.yml` file, something that -gives you absolute control over the build process. You can actually watch your -website being built live by following the CI job traces. - -For a simplified user guide on setting up GitLab CI/CD for Pages, read through -the article [GitLab Pages from A to Z: Part 4 - Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md) - -> **Note:** -> Before reading this section, make sure you familiarize yourself with GitLab CI -> and the specific syntax of[`.gitlab-ci.yml`][yaml] by -> following our [quick start guide]. - -To make use of GitLab Pages, the contents of `.gitlab-ci.yml` must follow the -rules below: - -1. A special job named [`pages`][pages] must be defined -1. Any static content which will be served by GitLab Pages must be placed under - a `public/` directory -1. `artifacts` with a path to the `public/` directory must be defined +## GitLab Pages on GitLab.com -In its simplest form, `.gitlab-ci.yml` looks like: +If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to host your website, then: -```yaml -pages: - script: - - my_commands - artifacts: - paths: - - public -``` +- The domain name for GitLab Pages on GitLab.com is `gitlab.io`. +- Custom domains and TLS support are enabled. +- Shared runners are enabled by default, provided for free and can be used to + build your website. If you want you can still bring your own Runner. -When the Runner reaches to build the `pages` job, it executes whatever is -defined in the `script` parameter and if the job completes with a non-zero -exit status, it then uploads the `public/` directory to GitLab Pages. +## Example projects -The `public/` directory should contain all the static content of your website. -Depending on how you plan to publish your website, the steps defined in the -[`script` parameter](../../../ci/yaml/README.md#script) may differ. +Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete list of example projects. Contributions are very welcome. -Be aware that Pages are by default branch/tag agnostic and their deployment -relies solely on what you specify in `.gitlab-ci.yml`. If you don't limit the -`pages` job with the [`only` parameter](../../../ci/yaml/README.md#onlyexcept-basic), -whenever a new commit is pushed to whatever branch or tag, the Pages will be -overwritten. In the example below, we limit the Pages to be deployed whenever -a commit is pushed only on the `master` branch: +## Specific configuration options for Pages -```yaml -pages: - script: - - my_commands - artifacts: - paths: - - public - only: - - master -``` - -We then tell the Runner to treat the `public/` directory as `artifacts` and -upload it to GitLab. And since all these parameters were all under a `pages` -job, the contents of the `public` directory will be served by GitLab Pages. +Learn how to set up GitLab CI/CD for specific use cases. -#### How `.gitlab-ci.yml` looks like when the static content is in your repository +### `.gitlab-ci.yml` for plain HTML websites Supposed your repository contained the following files: @@ -201,55 +67,11 @@ pages: - master ``` -#### How `.gitlab-ci.yml` looks like when using a static generator - -In general, GitLab Pages support any kind of [static site generator][staticgen], -since `.gitlab-ci.yml` can be configured to run any possible command. - -In the root directory of your Git repository, place the source files of your -favorite static generator. Then provide a `.gitlab-ci.yml` file which is -specific to your static generator. +### `.gitlab-ci.yml` for a static site generator -The example below, uses [Jekyll] to build the static site: +See this document for a [step-by-step guide](getting_started_part_four.md). -```yaml -image: ruby:2.1 # the script will run in Ruby 2.1 using the Docker image ruby:2.1 - -pages: # the build job must be named pages - script: - - gem install jekyll # we install jekyll - - jekyll build -d public/ # we tell jekyll to build the site for us - artifacts: - paths: - - public # this is where the site will live and the Runner uploads it in GitLab - only: - - master # this script is only affecting the master branch -``` - -Here, we used the Docker executor and in the first line we specified the base -image against which our jobs will run. - -You have to make sure that the generated static files are ultimately placed -under the `public` directory, that's why in the `script` section we run the -`jekyll` command that jobs the website and puts all content in the `public/` -directory. Depending on the static generator of your choice, this command will -differ. Search in the documentation of the static generator you will use if -there is an option to explicitly set the output directory. If there is not -such an option, you can always add one more line under `script` to rename the -resulting directory in `public/`. - -We then tell the Runner to treat the `public/` directory as `artifacts` and -upload it to GitLab. - ---- - -See the [jekyll example project][pages-jekyll] to better understand how this -works. - -For a list of Pages projects, see the [example projects](#example-projects) to -get you started. - -#### How to set up GitLab Pages in a repository where there's also actual code +### `.gitlab-ci.yml` for a repository where there's also actual code Remember that GitLab Pages are by default branch/tag agnostic and their deployment relies solely on what you specify in `.gitlab-ci.yml`. You can limit @@ -294,28 +116,6 @@ also includes `.gitlab-ci.yml`. [jekyll-master]: https://gitlab.com/pages/jekyll-branched/tree/master [jekyll-pages]: https://gitlab.com/pages/jekyll-branched/tree/pages -## Next steps - -So you have successfully deployed your website, congratulations! Let's check -what more you can do with GitLab Pages. - -### Example projects - -Below is a list of example projects for GitLab Pages with a plain HTML website -or various static site generators. Contributions are very welcome. - -- [Plain HTML](https://gitlab.com/pages/plain-html) -- [Jekyll](https://gitlab.com/pages/jekyll) -- [Hugo](https://gitlab.com/pages/hugo) -- [Middleman](https://gitlab.com/pages/middleman) -- [Hexo](https://gitlab.com/pages/hexo) -- [Brunch](https://gitlab.com/pages/brunch) -- [Metalsmith](https://gitlab.com/pages/metalsmith) -- [Harp](https://gitlab.com/pages/harp) - -Visit the GitLab Pages group for a full list of example projects: -<https://gitlab.com/groups/pages>. - ### Serving compressed assets Most modern browsers support downloading files in a compressed format. This @@ -408,52 +208,6 @@ NOTE: **Note:** When `public/data/index.html` exists, it takes priority over the `public/data.html` file for both the `/data` and `/data/` URL paths. -### Add a custom domain to your Pages website - -For a complete guide on Pages domains, read through the article -[GitLab Pages from A to Z: Part 3 - GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) - -If this setting is enabled by your GitLab administrator, you should be able to -see the **New Domain** button when visiting your project's settings through the -gear icon in the top right and then navigating to **Pages**. - - - ---- - -You can add multiple domains pointing to your website hosted under GitLab. -Once the domain is added, you can see it listed under the **Domains** section. - - - ---- - -As a last step, you need to configure your DNS and add a CNAME pointing to your -user/group page. Click on the **Details** button of a domain for further -instructions. - - - ---- - ->**Note:** -Currently there is support only for custom domains on per-project basis. That -means that if you add a custom domain (`example.com`) for your user website -(`username.example.io`), a project that is served under `username.example.io/foo`, -will not be accessible under `example.com/foo`. - -### Secure your custom domain website with TLS - -When you add a new custom domain, you also have the chance to add a TLS -certificate. If this setting is enabled by your GitLab administrator, you -should be able to see the option to upload the public certificate and the -private key when adding a new domain. - - - -For a complete guide on Pages domains, read through the article -[GitLab Pages from A to Z: Part 3 - GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) - ### Custom error codes pages You can provide your own 403 and 404 error pages by creating the `403.html` and @@ -472,29 +226,17 @@ If the case of `404.html`, there are different scenarios. For example: - If you use a custom domain and try to access `/non/existing_file`, GitLab Pages will try to serve only `/404.html`. -### Remove the contents of your pages - -If you ever feel the need to purge your Pages content, you can do so by going -to your project's settings through the gear icon in the top right, and then -navigating to **Pages**. Hit the **Remove pages** button and your Pages website -will be deleted. Simple as that. - - - -## GitLab Pages on GitLab.com - -If you are using GitLab.com to host your website, then: - -- The general domain name for GitLab Pages on GitLab.com is `gitlab.io`. -- Custom domains and TLS support are enabled. -- Shared runners are enabled by default, provided for free and can be used to - build your website. If you want you can still bring your own Runner. +### Redirects in GitLab Pages -The rest of the guide still applies. +Since you cannot use any custom server configuration files, like `.htaccess` or +any `.conf` file, if you want to redirect a page to another +location, you can use the [HTTP meta refresh tag][metarefresh]. -See also: [GitLab Pages from A to Z: Part 1 - Static sites and GitLab Pages domains](getting_started_part_one.md#gitlab-pages-domain). +Some static site generators provide plugins for that functionality so that you +don't have to create and edit HTML files manually. For example, Jekyll has the +[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from). -## GitLab Pages access control **[CORE ONLY]** +### GitLab Pages Access Control **[CORE ONLY]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. @@ -536,6 +278,15 @@ The next time someone tries to access your website and the access control is enabled, they will be presented with a page to sign into GitLab and verify they can access the website. +## Unpublishing your Pages + +If you ever feel the need to purge your Pages content, you can do so by going +to your project's settings through the gear icon in the top right, and then +navigating to **Pages**. Hit the **Remove pages** button and your Pages website +will be deleted. + + + ## Limitations When using Pages under the general domain of a GitLab instance (`*.example.io`), @@ -550,16 +301,6 @@ don't redirect HTTP to HTTPS. GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). You can only create the highest-level group website. -## Redirects in GitLab Pages - -Since you cannot use any custom server configuration files, like `.htaccess` or -any `.conf` file, if you want to redirect a page to another -location, you can use the [HTTP meta refresh tag][metarefresh]. - -Some static site generators provide plugins for that functionality so that you -don't have to create and edit HTML files manually. For example, Jekyll has the -[redirect-from plugin](https://github.com/jekyll/jekyll-redirect-from). - ## Frequently Asked Questions ### Can I download my generated pages? @@ -581,8 +322,6 @@ No, you don't. You can create your project first and it will be accessed under For a list of known issues, visit GitLab's [public issue tracker]. [jekyll]: http://jekyllrb.com/ -[ee-80]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/80 -[ee-173]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/173 [pages-daemon]: https://gitlab.com/gitlab-org/gitlab-pages [gitlab ci]: https://about.gitlab.com/gitlab-ci [gitlab runner]: https://docs.gitlab.com/runner/ @@ -592,7 +331,6 @@ For a list of known issues, visit GitLab's [public issue tracker]. [pages-jekyll]: https://gitlab.com/pages/jekyll [metarefresh]: https://en.wikipedia.org/wiki/Meta_refresh [public issue tracker]: https://gitlab.com/gitlab-org/gitlab-ce/issues?label_name=pages -[ce-14605]: https://gitlab.com/gitlab-org/gitlab-ce/issues/14605 [quick start guide]: ../../../ci/quick_start/README.md [pages-index-guide]: index.md [pages-quick]: getting_started_part_one.md 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 5ad500c4d20..ea22f3e905b 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -141,7 +141,7 @@ Now that your certificate has been issued, let's add it to your Pages site: ``` 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/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index a3f40c20192..629b5e1fde4 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -55,7 +55,8 @@ For more examples on artifacts, follow the [artifacts reference in > **Note:** > With [GitLab 10.1][ce-14399], HTML files in a public project can be previewed > directly in a new tab without the need to download them when -> [GitLab Pages](../../../administration/pages/index.md) is enabled +> [GitLab Pages](../../../administration/pages/index.md) is enabled. +> The same holds for textual formats (currently supported extensions: `.txt`, `.json`, and `.log`). After a job finishes, if you visit the job's specific page, there are three buttons. You can download the artifacts archive or browse its contents, whereas diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 718566a539f..97ecc4c0d65 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -97,7 +97,7 @@ Some things to note about precedence: > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2508) in GitLab 9.1 -[Jupyter][jupyter] Notebook (previously IPython Notebook) files are used for +[Jupyter](https://jupyter.org) Notebook (previously IPython Notebook) files are used for interactive computing in many fields and contain a complete record of the user's sessions and include code, narrative text, equations and rich output. @@ -220,14 +220,10 @@ Select branches to compare using the [branch filter search box](branches/index.m Find it under your project's **Repository > Compare**. -## Locked files +## Locked files **[PREMIUM]** -> Available in [GitLab Premium](https://about.gitlab.com/pricing/). - -Lock your files to prevent any conflicting changes. - -[File Locking](https://docs.gitlab.com/ee/user/project/file_lock.html) is available only in -[GitLab Premium](https://about.gitlab.com/pricing/). +Use [File Locking](https://docs.gitlab.com/ee/user/project/file_lock.html) to +lock your files to prevent any conflicting changes. ## Repository's API @@ -243,22 +239,19 @@ used for cloning your project. The button is only shown on macOS. ## Download Source Code -Source code stored in the repository can be downloaded. +> Support for directory download was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24704) in GitLab 11.11. +The source code stored in a repository can be downloaded from the UI. By clicking the download icon, a dropdown will open with links to download the following:  -- **Source Code:** - This allows users to download the source code on branch they're currently - viewing. Available zip, tar, tar.gz and tar.bz2. +- **Source code:** + allows users to download the source code on branch they're currently + viewing. Available extensions: `zip`, `tar`, `tar.gz`, and `tar.bz2`. - **Directory:** - > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/24704) in GitLab 11.10 - - Only shows up when viewing a sub-directory. This allows users to download - the specific directory they're currently viewing. Also available in zip, tar, - tar.gz and tar.bz2. + only shows up when viewing a sub-directory. This allows users to download + the specific directory they're currently viewing. Also available in `zip`, + `tar`, `tar.gz`, and `tar.bz2`. - **Artifacts:** - This allows users to download the artifacts of the latest CI build. - -[jupyter]: https://jupyter.org + allows users to download the artifacts of the latest CI build. diff --git a/doc/workflow/repository_mirroring.md b/doc/workflow/repository_mirroring.md index ae1624b7dc0..9fcadbf3bee 100644 --- a/doc/workflow/repository_mirroring.md +++ b/doc/workflow/repository_mirroring.md @@ -84,7 +84,7 @@ To set up a mirror from GitLab to GitHub, you need to follow these steps: 1. Fill in **Password** field with your GitHub personal access token. 1. Click the **Mirror repository** button. -The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. +The mirrored repository will be listed. For example, `https://*****:*****@github.com/<your_github_group>/<your_github_project>.git`. The repository will push soon. To force a push, click the appropriate button. @@ -138,13 +138,18 @@ upstream and GitLab will no longer automatically update this branch to prevent a ### How it works -Once you activate the pull mirroring feature, the mirror will be inserted into a queue. A scheduler -will start every minute and schedule a fixed number of mirrors for update, based on the configured maximum capacity. +Once the pull mirroring feature has been enabled for a repository, the repository is added to a queue. -If the mirror updates successfully, it will be enqueued once again with a small backoff period. +Once per minute, a Sidekiq cron job schedules repository mirrors to update, based on: -If the mirror fails (for example, a branch diverged from upstream), the project's backoff period is -increased each time it fails, up to a maximum amount of time. +- The capacity available. This is determined by Sidekiq settings. For GitLab.com, see [GitLab.com Sidekiq settings](../user/gitlab_com/index.md#sidekiq). +- The number of repository mirrors already in the queue that are due to be updated. Being due depends on when the repository mirror was last updated and how many times it's been retried. + +Repository mirrors are updated as Sidekiq becomes available to process them. If the process of updating the repository mirror: + +- Succeeds, an update will be enqueued again with at least a 30 minute wait. +- Fails (for example, a branch diverged from upstream), it will be attempted again later. Mirrors can fail + up to 14 times before they will not be enqueued for update again. ### SSH authentication diff --git a/doc/workflow/time_tracking.md b/doc/workflow/time_tracking.md index e60b6819bf1..c03dffa967d 100644 --- a/doc/workflow/time_tracking.md +++ b/doc/workflow/time_tracking.md @@ -75,6 +75,6 @@ Default conversion rates are 1mo = 4w, 1w = 5d and 1d = 8h. Other interesting links: -- [Time Tracking landing page on about.gitlab.com](https://about.gitlab.com/features/time-tracking) +- [Time Tracking landing page on about.gitlab.com](https://about.gitlab.com/solutions/time-tracking/) [quick actions]: ../user/project/quick_actions.md |
