diff options
Diffstat (limited to 'doc')
128 files changed, 2492 insertions, 935 deletions
diff --git a/doc/administration/auth/oidc.md b/doc/administration/auth/oidc.md index e55f7dbb4df..00422ec347c 100644 --- a/doc/administration/auth/oidc.md +++ b/doc/administration/auth/oidc.md @@ -31,6 +31,7 @@ The OpenID Connect will provide you with a client details and secret for you to { 'name' => 'openid_connect', 'label' => '<your_oidc_label>', 'args' => { + "name' => 'openid_connect', 'scope' => ['openid','profile'], 'response_type' => 'code', 'issuer' => '<your_oidc_url>', @@ -53,6 +54,7 @@ The OpenID Connect will provide you with a client details and secret for you to - { name: 'openid_connect', label: '<your_oidc_label>', args: { + name: 'openid_connect', scope: ['openid','profile'], response_type: 'code', issuer: '<your_oidc_url>', @@ -103,3 +105,59 @@ On the sign in page, there should now be an OpenID Connect icon below the regula Click the icon to begin the authentication process. The OpenID Connect provider will ask the user to sign in and authorize the GitLab application (if confirmation required by the client). If everything goes well, the user will be redirected to GitLab and will be signed in. + +## Example configurations + +The following configurations illustrate how to set up OpenID with +different providers with Omnibus GitLab. + +### Google + +See the [Google +documentation](https://developers.google.com/identity/protocols/OpenIDConnect) +for more details: + +```ruby + gitlab_rails['omniauth_providers'] = [ + { + 'name' => 'openid_connect', + 'label' => 'Google OpenID', + 'args' => { + 'name' => 'openid_connect', + 'scope' => ['openid', 'profile', 'email'], + 'response_type' => 'code', + 'issuer' => 'https://accounts.google.com', + 'client_auth_method' => 'query', + 'discovery' => true, + 'uid_field' => 'preferred_username', + 'client_options' => { + 'identifier' => '<YOUR PROJECT CLIENT ID>', + 'secret' => '<YOUR PROJECT CLIENT SECRET>', + 'redirect_uri' => 'https://example.com/users/auth/openid_connect/callback', + } + } + } +``` + +### Troubleshooting + +If you're having trouble, here are some tips: + +1. Ensure `discovery` is set to `true`. Setting it to `false` requires +specifying all the URLs and keys required to make OpenID work. + +1. Check your system clock to ensure the time is synchronized properly. + +1. As mentioned in [the +documentation](https://github.com/m0n9oose/omniauth_openid_connect), +make sure `issuer` corresponds to the base URL of the Discovery URL. For +example, `https://accounts.google.com` is used for the URL +`https://accounts.google.com/.well-known/openid-configuration`. + +1. The OpenID Connect client uses HTTP Basic Authentication to send the +OAuth2 access token. For example, if you are seeing 401 errors upon +retrieving the `userinfo` endpoint, you may want to check your OpenID +Web server configuration. For example, for +[oauth2-server-php](https://github.com/bshaffer/oauth2-server-php), you +may need to [add a configuration parameter to +Apache](https://github.com/bshaffer/oauth2-server-php/issues/926#issuecomment-387502778). diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md index c0cdea216cb..1e5a56c3f4e 100644 --- a/doc/administration/geo/replication/database.md +++ b/doc/administration/geo/replication/database.md @@ -445,8 +445,7 @@ The replication process is now complete. PostgreSQL connections. We recommend using PGBouncer if you use GitLab in a high-availability configuration with a cluster of nodes supporting a Geo **primary** node and another cluster of nodes supporting a Geo **secondary** node. For more -information, see the [Omnibus HA](../../high_availability/database.md#configure-using-omnibus) -documentation. +information, see [High Availability with GitLab Omnibus](../../high_availability/database.md#high-availability-with-gitlab-omnibus-premium-only). For a Geo **secondary** node to work properly with PGBouncer in front of the database, it will need a separate read-only user to make [PostgreSQL FDW queries][FDW] diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index dce3819a7c1..3b874e5d312 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -23,10 +23,10 @@ environments including [Basic Scaling](README.md#basic-scaling) and ### Provide your own PostgreSQL instance **[CORE ONLY]** -If you want to use your own deployed PostgreSQL instance(s), +If you want to use your own deployed PostgreSQL instance(s), see [Provide your own PostgreSQL instance](#provide-your-own-postgresql-instance-core-only) -for more details. However, you can use the GitLab Omnibus package to easily -deploy the bundled PostgreSQL. +for more details. However, you can use the GitLab Omnibus package to easily +deploy the bundled PostgreSQL. ### Standalone PostgreSQL using GitLab Omnibus **[CORE ONLY]** @@ -36,19 +36,19 @@ deploy the bundled PostgreSQL. - Do not complete any other steps on the download page. 1. Generate a password hash for PostgreSQL. This assumes you will use the default username of `gitlab` (recommended). The command will request a password - and confirmation. Use the value that is output by this command in the next + and confirmation. Use the value that is output by this command in the next step as the value of `POSTGRESQL_PASSWORD_HASH`. ```sh sudo gitlab-ctl pg-password-md5 gitlab ``` - + 1. Edit `/etc/gitlab/gitlab.rb` and add the contents below, updating placeholder - values appropriately. - + values appropriately. + - `POSTGRESQL_PASSWORD_HASH` - The value output from the previous step - `APPLICATION_SERVER_IP_BLOCKS` - A space delimited list of IP subnets or IP - addresses of the GitLab application servers that will connect to the + addresses of the GitLab application servers that will connect to the database. Example: `%w(123.123.123.123/32 123.123.123.234/32)` ```ruby @@ -65,11 +65,11 @@ deploy the bundled PostgreSQL. postgresql['listen_address'] = '0.0.0.0' postgresql['port'] = 5432 - # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value + # Replace POSTGRESQL_PASSWORD_HASH with a generated md5 value postgresql['sql_user_password'] = 'POSTGRESQL_PASSWORD_HASH' # Replace XXX.XXX.XXX.XXX/YY with Network Address - # ???? + # ???? postgresql['trust_auth_cidr_addresses'] = %w(APPLICATION_SERVER_IP_BLOCKS) # Disable automatic database migrations @@ -77,12 +77,12 @@ deploy the bundled PostgreSQL. ``` NOTE: **Note:** The role `postgres_role` was introduced with GitLab 10.3 - + 1. [Reconfigure GitLab] for the changes to take effect. 1. Note the PostgreSQL node's IP address or hostname, port, and plain text password. These will be necessary when configuring the GitLab application servers later. - + Advanced configuration options are supported and can be added if needed. @@ -101,18 +101,19 @@ environments including [Horizontal](README.md#horizontal), If you want to use your own deployed PostgreSQL instance(s), see [Provide your own PostgreSQL instance](#provide-your-own-postgresql-instance-core-only) for more details. However, you can use the GitLab Omnibus package to easily -deploy the bundled PostgreSQL. +deploy the bundled PostgreSQL. ### High Availability with GitLab Omnibus **[PREMIUM ONLY]** > Important notes: +> > - This document will focus only on configuration supported with [GitLab Premium](https://about.gitlab.com/pricing/), using the Omnibus GitLab package. > - If you are a Community Edition or Starter user, consider using a cloud hosted solution. > - This document will not cover installations from source. > > - If HA setup is not what you were looking for, see the [database configuration document](http://docs.gitlab.com/omnibus/settings/database.html) > for the Omnibus GitLab packages. - +> > Please read this document fully before attempting to configure PostgreSQL HA > for GitLab. > @@ -122,9 +123,9 @@ The recommended configuration for a PostgreSQL HA requires: - A minimum of three database nodes - Each node will run the following services: - - `PostgreSQL` - The database itself - - `repmgrd` - A service to monitor, and handle failover in case of a failure - - `Consul` agent - Used for service discovery, to alert other nodes when failover occurs + - `PostgreSQL` - The database itself + - `repmgrd` - A service to monitor, and handle failover in case of a failure + - `Consul` agent - Used for service discovery, to alert other nodes when failover occurs - A minimum of three `Consul` server nodes - A minimum of one `pgbouncer` service node @@ -142,7 +143,7 @@ Database nodes run two services with PostgreSQL: - Selecting a new master for the cluster. - Promoting the new node to master. - Instructing remaining servers to follow the new master node. - + On failure, the old master node is automatically evicted from the cluster, and should be rejoined manually once recovered. - Consul. Monitors the status of each node in the database cluster and tracks its health in a service definition on the consul cluster. @@ -171,13 +172,10 @@ Similarly, PostgreSQL access is controlled based on the network source. This is why you will need: -> IP address of each nodes network interface -> - This can be set to `0.0.0.0` to listen on all interfaces. It cannot -> be set to the loopack address `127.0.0.1` -> -> Network Address -> - This can be in subnet (i.e. `192.168.0.0/255.255.255.0`) or CIDR (i.e. -> `192.168.0.0/24`) form. +- IP address of each nodes network interface. This can be set to `0.0.0.0` to + listen on all interfaces. It cannot be set to the loopack address `127.0.0.1`. +- Network Address. This can be in subnet (i.e. `192.168.0.0/255.255.255.0`) + or CIDR (i.e. `192.168.0.0/24`) form. ##### User information @@ -199,7 +197,7 @@ When using default setup, minimum configuration requires: sudo gitlab-ctl pg-password-md5 CONSUL_USERNAME ``` -- `CONSUL_SERVER_NODES`. The IP addresses or DNS records of the Consul server nodes. +- `CONSUL_SERVER_NODES`. The IP addresses or DNS records of the Consul server nodes. Few notes on the service itself: @@ -220,8 +218,7 @@ the number of database nodes in the cluster. This is used to prevent replication from using up all of the available database connections. -> Note: -> - In this document we are assuming 3 database nodes, which makes this configuration: +In this document we are assuming 3 database nodes, which makes this configuration: ``` postgresql['max_wal_senders'] = 4 @@ -277,7 +274,7 @@ be allowed to authenticate with the service. Few notes on the service itself: - The service runs under the same system account as the database - - In the package, this is by default `gitlab-psql` + - In the package, this is by default `gitlab-psql` - The service will have a superuser database user account generated for it - This defaults to `gitlab_repmgr` @@ -327,7 +324,7 @@ On each Consul node perform the following: Before moving on, make sure Consul is configured correctly. Run the following command to verify all server nodes are communicating: -``` +```sh /opt/gitlab/embedded/bin/consul members ``` @@ -401,14 +398,15 @@ check the [Troubleshooting section](#troubleshooting) before proceeding. repmgr['master_on_initialization'] = false ``` -1. [Reconfigure GitLab] for te changes to take effect. +1. [Reconfigure GitLab] for the changes to take effect. > Please note: +> > - If you want your database to listen on a specific interface, change the config: -> `postgresql['listen_address'] = '0.0.0.0'` +> `postgresql['listen_address'] = '0.0.0.0'`. > - If your Pgbouncer service runs under a different user account, > you also need to specify: `postgresql['pgbouncer_user'] = PGBOUNCER_USERNAME` in -> your configuration +> your configuration. ##### Database nodes post-configuration @@ -449,7 +447,6 @@ Select one node as a primary node. is not an IP address, it will need to be a resolvable name (via DNS or `/etc/hosts`) - ###### Secondary nodes 1. Set up the repmgr standby: @@ -500,7 +497,7 @@ Before moving on, make sure the databases are configured correctly. Run the following command on the **primary** node to verify that replication is working properly: -``` +```sh gitlab-ctl repmgr cluster show ``` @@ -518,7 +515,7 @@ If the 'Role' column for any node says "FAILED", check the Also, check that the check master command works successfully on each node: -``` +```sh su - gitlab-consul gitlab-ctl repmgr-check-master || echo 'This node is a standby repmgr node' ``` @@ -649,7 +646,7 @@ in the Troubleshooting section before proceeding. ##### Ensure GitLab is running At this point, your GitLab instance should be up and running. Verify you are -able to login, and create issues and merge requests. If you have troubles check +able to login, and create issues and merge requests. If you have troubles check the [Troubleshooting section](#troubleshooting). #### Example configuration @@ -665,13 +662,13 @@ can connect to each freely other on those addresses. Here is a list and description of each machine and the assigned IP: -* `10.6.0.11`: Consul 1 -* `10.6.0.12`: Consul 2 -* `10.6.0.13`: Consul 3 -* `10.6.0.21`: PostgreSQL master -* `10.6.0.22`: PostgreSQL secondary -* `10.6.0.23`: PostgreSQL secondary -* `10.6.0.31`: GitLab application +- `10.6.0.11`: Consul 1 +- `10.6.0.12`: Consul 2 +- `10.6.0.13`: Consul 3 +- `10.6.0.21`: PostgreSQL master +- `10.6.0.22`: PostgreSQL secondary +- `10.6.0.23`: PostgreSQL secondary +- `10.6.0.31`: GitLab application All passwords are set to `toomanysecrets`, please do not use this password or derived hashes. @@ -735,7 +732,7 @@ consul['configuration'] = { On secondary nodes, edit `/etc/gitlab/gitlab.rb` and add all the configuration added to primary node, noted above. In addition, append the following -configuration +configuration: ``` # HA setting to specify if a node should attempt to be master on initialization @@ -839,10 +836,10 @@ In this example we start with all servers on the same 10.6.0.0/16 private networ Here is a list and description of each machine and the assigned IP: -* `10.6.0.21`: PostgreSQL master -* `10.6.0.22`: PostgreSQL secondary -* `10.6.0.23`: PostgreSQL secondary -* `10.6.0.31`: GitLab application +- `10.6.0.21`: PostgreSQL master +- `10.6.0.22`: PostgreSQL secondary +- `10.6.0.23`: PostgreSQL secondary +- `10.6.0.31`: GitLab application All passwords are set to `toomanysecrets`, please do not use this password or derived hashes. @@ -853,6 +850,7 @@ Please note that after the initial configuration, if a failover occurs, the Post ##### Example minimal configuration for database servers ##### Primary node + On primary database node edit `/etc/gitlab/gitlab.rb`: ```ruby @@ -1047,7 +1045,6 @@ For example: repmgr['trust_auth_cidr_addresses'] = %w(192.168.1.44/32 db2.example.com) ``` - ##### MD5 Authentication If you are running on an untrusted network, repmgr can use md5 authentication @@ -1114,7 +1111,7 @@ steps to fix the problem: 1. Change to the `gitlab-consul` user - `su - gitlab-consul` 1. Try the check command again - `gitlab-ctl repmgr-check-master`. -Now there should not be errors. If errors still occur then there is another problem. +Now there should not be errors. If errors still occur then there is another problem. #### PGBouncer error `ERROR: pgbouncer cannot connect to server` @@ -1157,8 +1154,6 @@ If you're running into an issue with a component not outlined here, be sure to c **Note**: We recommend that you follow the instructions here for a full [PostgreSQL cluster](#high-availability-with-gitlab-omnibus-premium-only). If you are reading this section due to an old bookmark, you can find that old documentation [in the repository](https://gitlab.com/gitlab-org/gitlab-ce/blob/v10.1.4/doc/administration/high_availability/database.md#configure-using-omnibus). ---- - Read more on high-availability configuration: 1. [Configure Redis](redis.md) diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index ef370573a98..05e15fc303b 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -7,9 +7,9 @@ > - Starting with GitLab 8.17, builds are renamed to jobs. > - This is the administration documentation. For the user guide see [pipelines/job_artifacts](../user/project/pipelines/job_artifacts.md). -Artifacts is a list of files and directories which are attached to a job -after it completes successfully. This feature is enabled by default in all -GitLab installations. Keep reading if you want to know how to disable it. +Artifacts is a list of files and directories which are attached to a job after it +finishes. This feature is enabled by default in all GitLab installations. Keep reading +if you want to know how to disable it. ## Disabling job artifacts @@ -42,8 +42,9 @@ To disable artifacts site-wide, follow the steps below. ## Storing job artifacts -After a successful job, GitLab Runner uploads an archive containing the job -artifacts to GitLab. +GitLab Runner can upload an archive containing the job artifacts to GitLab. By default, +this is done when the job succeeds, but can also be done on failure, or always, via the +[`artifacts:when`](../ci/yaml/README.md#artifactswhen) parameter. ### Using local storage diff --git a/doc/administration/logs.md b/doc/administration/logs.md index ac41f9177dd..c5cfb8d5016 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -129,7 +129,7 @@ It contains information about [integrations](../user/project/integrations/projec ``` json {"severity":"ERROR","time":"2018-09-06T14:56:20.439Z","service_class":"JiraService","project_id":8,"project_path":"h5bp/html5-boilerplate","message":"Error sending message","client_url":"http://jira.gitlap.com:8080","error":"execution expired"} -{"severity":"INFO","time":"2018-09-06T17:15:16.365Z","service_class":"JiraService","project_id":3,"project_path":"namespace2/project2","message":"Successfully posted","client_url":"http://jira.example.net"} +{"severity":"INFO","time":"2018-09-06T17:15:16.365Z","service_class":"JiraService","project_id":3,"project_path":"namespace2/project2","message":"Successfully posted","client_url":"http://jira.example.com"} ``` ## `kubernetes.log` diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 3dcd1593099..84b71ae6f1c 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -125,6 +125,7 @@ When Puma is used instead of Unicorn, following metrics are available: | puma_max_threads | Gauge | 12.0 | Maximum number of worker threads | | puma_idle_threads | Gauge | 12.0 | Number of spawned threads which are not processing a request | | rack_state_total | Gauge | 12.0 | Number of requests in a given rack state | +| puma_killer_terminations_total | Gauge | 12.0 | Number of workers terminated by PumaWorkerKiller | ## Metrics shared directory diff --git a/doc/api/README.md b/doc/api/README.md index 439f58c1253..3a1064b787e 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -21,72 +21,83 @@ See also: The following API resources are available in the project context: -| Resource | Available endpoints | -|:------------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | -| [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | -| [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | -| [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | -| [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` | -| [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) | -| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | -| [Deployments](deployments.md) | `/projects/:id/deployments` | -| [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` | -| [Environments](environments.md) | `/projects/:id/environments` | -| [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | -| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | -| [Issue boards](boards.md) | `/projects/:id/boards` | -| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | -| [Labels](labels.md) | `/projects/:id/labels` | -| [Members](members.md) | `/projects/:id/members` (also available for groups) | -| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | -| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` | -| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | -| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | -| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | -| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | -| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | -| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | -| [Project badges](project_badges.md) | `/projects/:id/badges` | -| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | -| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | -| [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` | -| [Project milestones](milestones.md) | `/projects/:id/milestones` | -| [Project snippets](project_snippets.md) | `/projects/:id/snippets` | -| [Project templates](project_templates.md) | `/projects/:id/templates` | -| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | -| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | -| [Releases](releases/index.md) | `/projects/:id/releases` | -| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | -| [Repositories](repositories.md) | `/projects/:id/repository` | -| [Repository files](repository_files.md) | `/projects/:id/repository/files` | -| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | -| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` | -| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | -| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | -| [Services](services.md) | `/projects/:id/services` | -| [Tags](tags.md) | `/projects/:id/repository/tags` | -| [Wikis](wikis.md) | `/projects/:id/wikis` | +| Resource | Available endpoints | +|:--------------------------------------------------------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Access requests](access_requests.md) | `/projects/:id/access_requests` (also available for groups) | +| [Award emoji](award_emoji.md) | `/projects/:id/issues/.../award_emoji`, `/projects/:id/merge_requests/.../award_emoji`, `/projects/:id/snippets/.../award_emoji` | +| [Branches](branches.md) | `/projects/:id/repository/branches/`, `/projects/:id/repository/merged_branches` | +| [Commits](commits.md) | `/projects/:id/repository/commits`, `/projects/:id/statuses` | +| [Container Registry](container_registry.md) | `/projects/:id/registry/repositories` | +| [Custom attributes](custom_attributes.md) | `/projects/:id/custom_attributes` (also available for groups and users) | +| [Deploy keys](deploy_keys.md) | `/projects/:id/deploy_keys` (also available standalone) | +| [Deployments](deployments.md) | `/projects/:id/deployments` | +| [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) | +| [Environments](environments.md) | `/projects/:id/environments` | +| [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | +| [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | +| [Issue boards](boards.md) | `/projects/:id/boards` | +| [Issue links](issue_links.md) **[STARTER]** | `/projects/:id/issues/.../links` | +| [Jobs](jobs.md) | `/projects/:id/jobs`, `/projects/:id/pipelines/.../jobs` | +| [Labels](labels.md) | `/projects/:id/labels` | +| [Managed licenses](managed_licenses.md) **[ULTIMATE]** | `/projects/:id/managed_licenses` | +| [Members](members.md) | `/projects/:id/members` (also available for groups) | +| [Merge request approvals](merge_request_approvals.md) **[STARTER]** | `/projects/:id/approvals`, `/projects/:id/merge_requests/.../approvals` | +| [Merge requests](merge_requests.md) | `/projects/:id/merge_requests` (also available for groups and standalone) | +| [Notes](notes.md) (comments) | `/projects/:id/issues/.../notes`, `/projects/:id/snippets/.../notes`, `/projects/:id/merge_requests/.../notes` (also available for groups) | +| [Notification settings](notification_settings.md) | `/projects/:id/notification_settings` (also available for groups and standalone) | +| [Packages](packages.md) **[PREMIUM]** | `/projects/:id/packages` | +| [Pages domains](pages_domains.md) | `/projects/:id/pages` (also available standalone) | +| [Pipelines](pipelines.md) | `/projects/:id/pipelines` | +| [Pipeline schedules](pipeline_schedules.md) | `/projects/:id/pipeline_schedules` | +| [Pipeline triggers](pipeline_triggers.md) | `/projects/:id/triggers` | +| [Projects](projects.md) including setting Webhooks | `/projects`, `/projects/:id/hooks` (also available for users) | +| [Project badges](project_badges.md) | `/projects/:id/badges` | +| [Project clusters](project_clusters.md) | `/projects/:id/clusters` | +| [Project-level variables](project_level_variables.md) | `/projects/:id/variables` | +| [Project import/export](project_import_export.md) | `/projects/:id/export`, `/projects/import`, `/projects/:id/import` | +| [Project milestones](milestones.md) | `/projects/:id/milestones` | +| [Project snippets](project_snippets.md) | `/projects/:id/snippets` | +| [Project templates](project_templates.md) | `/projects/:id/templates` | +| [Protected branches](protected_branches.md) | `/projects/:id/protected_branches` | +| [Protected tags](protected_tags.md) | `/projects/:id/protected_tags` | +| [Releases](releases/index.md) | `/projects/:id/releases` | +| [Release links](releases/links.md) | `/projects/:id/releases/.../assets/links` | +| [Repositories](repositories.md) | `/projects/:id/repository` | +| [Repository files](repository_files.md) | `/projects/:id/repository/files` | +| [Repository submodules](repository_submodules.md) | `/projects/:id/repository/submodules` | +| [Resource label events](resource_label_events.md) | `/projects/:id/issues/.../resource_label_events`, `/projects/:id/merge_requests/.../resource_label_events` (also available for groups) | +| [Runners](runners.md) | `/projects/:id/runners` (also available standalone) | +| [Search](search.md) | `/projects/:id/search` (also available for groups and standalone) | +| [Services](services.md) | `/projects/:id/services` | +| [Tags](tags.md) | `/projects/:id/repository/tags` | +| [Vulnerabilities](vulnerabilities.md) **[ULTIMATE]** | `/projects/:id/vulnerabilities` (also available for groups) | +| [Wikis](wikis.md) | `/projects/:id/wikis` | ### Group resources The following API resources are available in the group context: -| Resource | Available endpoints | -|:--------------------------------------------------|:---------------------------------------------------------------------------------| -| [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | -| [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | -| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | -| [Group badges](group_badges.md) | `/groups/:id/badges` | -| [Group issue boards](group_boards.md) | `/groups/:id/boards` | -| [Group labels](group_labels.md) | `/groups/:id/labels` | -| [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | -| [Group milestones](group_milestones.md) | `/groups/:id/milestones` | -| [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | -| [Members](members.md) | `/groups/:id/members` (also available for projects) | -| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | -| [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) | -| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | +| Resource | Available endpoints | +|:-----------------------------------------------------------------|:---------------------------------------------------------------------------------| +| [Access requests](access_requests.md) | `/groups/:id/access_requests/` (also available for projects) | +| [Custom attributes](custom_attributes.md) | `/groups/:id/custom_attributes` (also available for projects and users) | +| [Discussions](discussions.md) (threaded comments) **[ULTIMATE]** | `/groups/:id/epics/.../discussions` (also available for projects) | +| [Epic issues](epic_issues.md) **[ULTIMATE]** | `/groups/:id/epics/.../issues` | +| [Epic links](epic_links.md) **[ULTIMATE]** | `/groups/:id/epics/.../epics` | +| [Epics](epics.md) **[ULTIMATE]** | `/groups/:id/epics` | +| [Groups](groups.md) | `/groups`, `/groups/.../subgroups` | +| [Group badges](group_badges.md) | `/groups/:id/badges` | +| [Group issue boards](group_boards.md) | `/groups/:id/boards` | +| [Group labels](group_labels.md) | `/groups/:id/labels` | +| [Group-level variables](group_level_variables.md) | `/groups/:id/variables` | +| [Group milestones](group_milestones.md) | `/groups/:id/milestones` | +| [Issues](issues.md) | `/groups/:id/issues` (also available for projects and standalone) | +| [Members](members.md) | `/groups/:id/members` (also available for projects) | +| [Merge requests](merge_requests.md) | `/groups/:id/merge_requests` (also available for projects and standalone) | +| [Notes](notes.md) (comments) | `/groups/:id/epics/.../notes` (also available for projects) | +| [Notification settings](notification_settings.md) | `/groups/:id/notification_settings` (also available for projects and standalone) | +| [Resource label events](resource_label_events.md) | `/groups/:id/epics/.../resource_label_events` (also available for projects) | +| [Search](search.md) | `/groups/:id/search` (also available for projects and standalone) | ### Standalone resources @@ -102,9 +113,11 @@ The following API resources are available outside of project and group contexts | [Deploy keys](deploy_keys.md) | `/deploy_keys` (also available for projects) | | [Events](events.md) | `/events`, `/users/:id/events` (also available for projects) | | [Feature flags](features.md) | `/features` | +| [Geo Nodes](geo_nodes.md) **[PREMIUM ONLY]** | `/geo_nodes` | | [Import repository from GitHub](import.md) | `/import/github` | | [Issues](issues.md) | `/issues` (also available for groups and projects) | | [Keys](keys.md) | `/keys` | +| [License](license.md) **[CORE ONLY]** | `/license` | | [Markdown](markdown.md) | `/markdown` | | [Merge requests](merge_requests.md) | `/merge_requests` (also available for groups and projects) | | [Namespaces](namespaces.md) | `/namespaces` | @@ -131,6 +144,11 @@ Endpoints are available for: - [GitLab CI YAML templates](templates/gitlab_ci_ymls.md). - [Open source license templates](templates/licenses.md). +## SCIM **[SILVER ONLY]** + +[GitLab.com Silver and above](https://about.gitlab.com/pricing/) provides an [SCIM API](scim.md) that implements [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644) and provides +the `/Users` endpoint. The base URL is: `/api/scim/v2/groups/:group_path/Users/`. + ## Road to GraphQL Going forward, we will start on moving to @@ -186,8 +204,6 @@ curl "https://gitlab.example.com/api/v4/projects" The API uses JSON to serialize data. You don't need to specify `.json` at the end of an API URL. -All of the API endpoints that use the `POST`, `PUT` or `PATCH` method support params in the request body, with `Content-Type` `application/x-www-form-urlencoded`, `multipart/form-data` or `application/json`. - ## Authentication Most API requests require authentication, or will only return public data when diff --git a/doc/api/issues.md b/doc/api/issues.md index 4fb3626f637..0d96cfa1b21 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -135,7 +135,11 @@ Example response: "award_emoji":"http://example.com/api/v4/projects/1/issues/76/award_emoji", "project":"http://example.com/api/v4/projects/1" }, - "subscribed": false + "subscribed": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ] ``` @@ -265,7 +269,11 @@ Example response: "award_emoji":"http://example.com/api/v4/projects/4/issues/41/award_emoji", "project":"http://example.com/api/v4/projects/4" }, - "subscribed": false + "subscribed": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ] ``` @@ -403,7 +411,11 @@ Example response: "award_emoji":"http://example.com/api/v4/projects/4/issues/41/award_emoji", "project":"http://example.com/api/v4/projects/4" }, - "subscribed": false + "subscribed": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ] ``` @@ -500,6 +512,10 @@ Example response: "notes": "http://example.com/api/v4/projects/1/issues/2/notes", "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", "project": "http://example.com/api/v4/projects/1" + }, + "task_completion_status":{ + "count":0, + "completed_count":0 } } ``` @@ -583,6 +599,10 @@ Example response: "notes": "http://example.com/api/v4/projects/1/issues/2/notes", "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", "project": "http://example.com/api/v4/projects/1" + }, + "task_completion_status":{ + "count":0, + "completed_count":0 } } ``` @@ -674,6 +694,10 @@ Example response: "notes": "http://example.com/api/v4/projects/1/issues/2/notes", "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", "project": "http://example.com/api/v4/projects/1" + }, + "task_completion_status":{ + "count":0, + "completed_count":0 } } ``` @@ -780,6 +804,10 @@ Example response: "notes": "http://example.com/api/v4/projects/1/issues/2/notes", "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", "project": "http://example.com/api/v4/projects/1" + }, + "task_completion_status":{ + "count":0, + "completed_count":0 } } ``` @@ -865,6 +893,10 @@ Example response: "notes": "http://example.com/api/v4/projects/1/issues/2/notes", "award_emoji": "http://example.com/api/v4/projects/1/issues/2/award_emoji", "project": "http://example.com/api/v4/projects/1" + }, + "task_completion_status":{ + "count":0, + "completed_count":0 } } ``` @@ -931,7 +963,11 @@ Example response: "due_date": null, "web_url": "http://example.com/example/example/issues/12", "confidential": false, - "discussion_locked": false + "discussion_locked": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` @@ -1029,7 +1065,11 @@ Example response: "due_date": null, "web_url": "http://example.com/example/example/issues/110", "confidential": false, - "discussion_locked": false + "discussion_locked": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } }, "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/issues/10", "body": "Vel voluptas atque dicta mollitia adipisci qui at.", diff --git a/doc/api/jobs.md b/doc/api/jobs.md index d51451b9c83..72973b69117 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -346,30 +346,58 @@ Example of response > **Notes**: > > - [Introduced][ce-2893] in GitLab 8.5. +> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346] +> in [GitLab Premium][ee] 9.5. -Get job artifacts of a project. +Get the job's artifacts zipped archive of a project. ``` GET /projects/:id/jobs/:job_id/artifacts ``` -| Attribute | Type | Required | Description | -|-----------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `job_id` | integer | yes | ID of a job. | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `job_id` | integer | yes | ID of a job. | +| `job_token` **[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | -Example requests: +Example request using the `PRIVATE-TOKEN` header: ```sh -curl --location --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/8/artifacts" +curl --output artifacts.zip --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts" ``` +To use this in a [`script` definition](../ci/yaml/README.md#script) inside +`.gitlab-ci.yml` **[PREMIUM]**, you can use either: + +- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. + For example, the following job will download the artifacts of the job with ID + `42`. Note that the command is wrapped into single quotes since it contains a + colon (`:`): + + ```yaml + artifact_download: + stage: test + script: + - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts"' + ``` + +- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. + For example, the following job will download the artifacts of the job with ID `42`: + + ```yaml + artifact_download: + stage: test + script: + - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/1/jobs/42/artifacts?job_token=$CI_JOB_TOKEN"' + ``` + Possible response status codes: | Status | Description | |-----------|---------------------------------| -| 200 | Serves the artifacts file | -| 404 | Build not found or no artifacts | +| 200 | Serves the artifacts file. | +| 404 | Build not found or no artifacts.| [ce-2893]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2893 @@ -378,9 +406,13 @@ Possible response status codes: > **Notes**: > > - [Introduced][ce-5347] in GitLab 8.10. +> - The use of `CI_JOB_TOKEN` in the artifacts download API was [introduced][ee-2346] +> in [GitLab Premium][ee] 9.5. -Download the artifacts archive from the given reference name and job provided the -job finished successfully. +Download the artifacts zipped archive from the given reference name and job, +provided the job finished successfully. This is the same as +[getting the job's artifacts](#get-job-artifacts), but by defining the job's +name instead of its ID. ``` GET /projects/:id/jobs/artifacts/:ref_name/download?job=name @@ -388,24 +420,51 @@ GET /projects/:id/jobs/artifacts/:ref_name/download?job=name Parameters -| Attribute | Type | Required | Description | -|------------|----------------|----------|------------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | -| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | -| `job` | string | yes | The name of the job. | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `ref_name` | string | yes | Branch or tag name in repository. HEAD or SHA references are not supported. | +| `job` | string | yes | The name of the job. | +| `job_token` **[PREMIUM]** | string | no | To be used with [triggers] for multi-project pipelines. It should be invoked only inside `.gitlab-ci.yml`. Its value is always `$CI_JOB_TOKEN`. | -Example requests: +Example request using the `PRIVATE-TOKEN` header: ```sh curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/jobs/artifacts/master/download?job=test" ``` +To use this in a [`script` definition](../ci/yaml/README.md#script) inside +`.gitlab-ci.yml` **[PREMIUM]**, you can use either: + +- The `JOB-TOKEN` header with the GitLab-provided `CI_JOB_TOKEN` variable. + For example, the following job will download the artifacts of the `test` job + of the `master` branch. Note that the command is wrapped into single quotes + since it contains a colon (`:`): + + ```yaml + artifact_download: + stage: test + script: + - 'curl --location --output artifacts.zip --header "JOB-TOKEN: $CI_JOB_TOKEN" "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test"' + ``` + +- Or the `job_token` attribute with the GitLab-provided `CI_JOB_TOKEN` variable. + For example, the following job will download the artifacts of the `test` job + of the `master` branch: + + ```yaml + artifact_download: + stage: test + script: + - 'curl --location --output artifacts.zip "https://gitlab.example.com/api/v4/projects/$CI_PROJECT_ID/jobs/artifacts/master/download?job=test&job_token=$CI_JOB_TOKEN"' + ``` + Possible response status codes: | Status | Description | |-----------|---------------------------------| -| 200 | Serves the artifacts file | -| 404 | Build not found or no artifacts | +| 200 | Serves the artifacts file. | +| 404 | Build not found or no artifacts.| [ce-5347]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5347 @@ -414,7 +473,7 @@ Possible response status codes: > Introduced in GitLab 10.0 Download a single artifact file from a job with a specified ID from within -the job's artifacts archive. The file is extracted from the archive and +the job's artifacts zipped archive. The file is extracted from the archive and streamed to the client. ``` @@ -783,3 +842,7 @@ Example of response "user": null } ``` + +[ee]: https://about.gitlab.com/pricing/ +[ee-2346]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/2346 +[triggers]: ../ci/triggers/README.md#when-a-pipeline-depends-on-the-artifacts-of-another-pipeline-premium diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 9529a9ec1f5..96a956ad03a 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -138,7 +138,11 @@ Parameters: "human_time_estimate": null, "human_total_time_spent": null }, - "squash": false + "squash": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ] ``` @@ -280,7 +284,11 @@ Parameters: "human_time_estimate": null, "human_total_time_spent": null }, - "squash": false + "squash": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ] ``` @@ -410,7 +418,11 @@ Parameters: "human_time_estimate": null, "human_total_time_spent": null }, - "squash": false + "squash": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ] ``` @@ -545,7 +557,11 @@ Parameters: "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, "diverged_commits_count": 2, - "rebase_in_progress": false + "rebase_in_progress": false, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` @@ -579,7 +595,7 @@ Parameters: "state": "active", "avatar_url": "http://www.gravatar.com/avatar/10fc7f102be8de7657fb4d80898bbfe3?s=80&d=identicon", "web_url": "http://localhost/user2" - }, + } ] ``` @@ -702,7 +718,11 @@ Parameters: "total_time_spent": 0, "human_time_estimate": null, "human_total_time_spent": null - } + }, + "task_completion_status":{ + "count":0, + "completed_count":0 + }, "changes": [ { "old_path": "VERSION", @@ -865,7 +885,11 @@ POST /projects/:id/merge_requests "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` @@ -1002,7 +1026,11 @@ Must include at least one non-required attribute from above. "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` @@ -1155,13 +1183,17 @@ Parameters: "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` ## Returns the up to date merge-ref HEAD commit -Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` +Merge the changes between the merge request source and target branches into `refs/merge-requests/:iid/merge` ref, of the target project repository, if possible. This ref will have the state the target branch would have if a regular merge action was taken. @@ -1309,7 +1341,11 @@ Parameters: "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` @@ -1345,7 +1381,7 @@ If the rebase operation is ongoing, the response will include the following: ```json { - "rebase_in_progress": true + "rebase_in_progress": true, "merge_error": null } ``` @@ -1356,7 +1392,7 @@ the following: ```json { "rebase_in_progress": false, - "merge_error": null, + "merge_error": null } ``` @@ -1365,7 +1401,7 @@ If the rebase operation fails, the response will include the following: ```json { "rebase_in_progress": false, - "merge_error": "Rebase failed. Please rebase locally", + "merge_error": "Rebase failed. Please rebase locally" } ``` @@ -1572,7 +1608,11 @@ Example response: "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` @@ -1701,7 +1741,11 @@ Example response: "head_sha": "2be7ddb704c7b6b83732fdd5b9f09d5a397b5f8f", "start_sha": "c380d3acebd181f13629a25d2e2acca46ffe1e00" }, - "diverged_commits_count": 2 + "diverged_commits_count": 2, + "task_completion_status":{ + "count":0, + "completed_count":0 + } } ``` diff --git a/doc/api/project_clusters.md b/doc/api/project_clusters.md index c831cc52a93..327781f6c93 100644 --- a/doc/api/project_clusters.md +++ b/doc/api/project_clusters.md @@ -167,6 +167,7 @@ Parameters: | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | | `platform_kubernetes_attributes[authorization_type]` | String | no | The cluster authorization type: `rbac`, `abac` or `unknown_authorization`. Defaults to `rbac`. | +| `environment_scope` | String | no | The associated environment to the cluster. Defaults to `*` **[PREMIUM]** | Example request: @@ -256,6 +257,7 @@ Parameters: | `platform_kubernetes_attributes[token]` | String | no | The token to authenticate against Kubernetes | | `platform_kubernetes_attributes[ca_cert]` | String | no | TLS certificate (needed if API is using a self-signed TLS certificate | | `platform_kubernetes_attributes[namespace]` | String | no | The unique namespace related to the project | +| `environment_scope` | String | no | The associated environment to the cluster **[PREMIUM]** | NOTE: **Note:** `name`, `api_url`, `ca_cert` and `token` can only be updated if the cluster was added diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 3b00f6f140e..66a749e4811 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -1,4 +1,4 @@ -# Project-level Variables API +# Project-level Variables API ## List project variables @@ -66,14 +66,15 @@ Create a new variable. POST /projects/:id/variables ``` -| Attribute | Type | required | Description | -|-----------------|---------|----------|-----------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | -| `value` | string | yes | The `value` of a variable | -| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | -| `protected` | boolean | no | Whether the variable is protected | -| `masked` | boolean | no | Whether the variable is masked | +| Attribute | Type | required | Description | +|---------------------|---------|----------|-----------------------| +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | +| `value` | string | yes | The `value` of a variable | +| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | +| `protected` | boolean | no | Whether the variable is protected | +| `masked` | boolean | no | Whether the variable is masked | +| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** | ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables" --form "key=NEW_VARIABLE" --form "value=new value" @@ -83,9 +84,11 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla { "key": "NEW_VARIABLE", "value": "new value", + "protected": false, "variable_type": "env_var", "protected": false, - "masked": false + "masked": false, + "environment_scope": "*" } ``` @@ -97,14 +100,15 @@ Update a project's variable. PUT /projects/:id/variables/:key ``` -| Attribute | Type | required | Description | -|-----------------|---------|----------|-------------------------| -| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `key` | string | yes | The `key` of a variable | -| `value` | string | yes | The `value` of a variable | -| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | -| `protected` | boolean | no | Whether the variable is protected | -| `masked` | boolean | no | Whether the variable is masked | +| Attribute | Type | required | Description | +|---------------------|---------|----------|-------------------------| +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `key` | string | yes | The `key` of a variable | +| `value` | string | yes | The `value` of a variable | +| `variable_type` | string | no | The type of a variable. Available types are: `env_var` (default) and `file` | +| `protected` | boolean | no | Whether the variable is protected | +| `masked` | boolean | no | Whether the variable is masked | +| `environment_scope` | string | no | The `environment_scope` of the variable **[PREMIUM]** | ``` curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/variables/NEW_VARIABLE" --form "value=updated value" @@ -116,7 +120,8 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab "value": "updated value", "variable_type": "env_var", "protected": true, - "masked": false + "masked": false, + "environment_scope": "*" } ``` diff --git a/doc/api/search.md b/doc/api/search.md index c2dd72479c1..da81c8321c9 100644 --- a/doc/api/search.md +++ b/doc/api/search.md @@ -19,6 +19,8 @@ GET /search Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, snippet_titles, snippet_blobs, users. +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]** + The response depends on the requested scope. ### Scope: projects @@ -281,6 +283,98 @@ Example response: ] ``` +### Scope: wiki_blobs **[STARTER]** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +```bash +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=wiki_blobs&search=bye +``` + +Example response: + +```json + +[ + { + "basename": "home", + "data": "hello\n\nand bye\n\nend", + "filename": "home.md", + "id": null, + "ref": "master", + "startline": 5, + "project_id": 6 + } +] +``` + +### Scope: commits **[STARTER]** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +```bash +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=commits&search=bye +``` + +Example response: + +```json + +[ + { + "id": "4109c2d872d5fdb1ed057400d103766aaea97f98", + "short_id": "4109c2d8", + "title": "goodbye $.browser", + "created_at": "2013-02-18T22:02:54.000Z", + "parent_ids": [ + "59d05353ab575bcc2aa958fe1782e93297de64c9" + ], + "message": "goodbye $.browser\n", + "author_name": "angus croll", + "author_email": "anguscroll@gmail.com", + "authored_date": "2013-02-18T22:02:54.000Z", + "committer_name": "angus croll", + "committer_email": "anguscroll@gmail.com", + "committed_date": "2013-02-18T22:02:54.000Z", + "project_id": 6 + } +] +``` + +### Scope: blobs **[STARTER]** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +Filters are available for this scope: +- filename +- path +- extension + +to use a filter simply include it in your query like so: `a query filename:some_name*`. + +You may use wildcards (`*`) to use glob matching. + +```bash +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/search?scope=blobs&search=installation +``` + +Example response: + +```json + +[ + { + "basename": "README", + "data": "```\n\n## Installation\n\nQuick start using the [pre-built", + "filename": "README.md", + "id": null, + "ref": "master", + "startline": 46, + "project_id": 6 + } +] +``` + ### Scope: users ```bash @@ -320,6 +414,8 @@ GET /groups/:id/search Search the expression within the specified scope. Currently these scopes are supported: projects, issues, merge_requests, milestones, users. +If Elasticsearch is enabled additional scopes available are blobs, wiki_blobs and commits. Find more about [the feature](../integration/elasticsearch.md). **[STARTER]** + The response depends on the requested scope. ### Scope: projects @@ -520,6 +616,98 @@ Example response: ] ``` +### Scope: wiki_blobs **[STARTER]** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +```bash +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=wiki_blobs&search=bye +``` + +Example response: + +```json + +[ + { + "basename": "home", + "data": "hello\n\nand bye\n\nend", + "filename": "home.md", + "id": null, + "ref": "master", + "startline": 5, + "project_id": 6 + } +] +``` + +### Scope: commits **[STARTER]** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +```bash +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=commits&search=bye +``` + +Example response: + +```json + +[ + { + "id": "4109c2d872d5fdb1ed057400d103766aaea97f98", + "short_id": "4109c2d8", + "title": "goodbye $.browser", + "created_at": "2013-02-18T22:02:54.000Z", + "parent_ids": [ + "59d05353ab575bcc2aa958fe1782e93297de64c9" + ], + "message": "goodbye $.browser\n", + "author_name": "angus croll", + "author_email": "anguscroll@gmail.com", + "authored_date": "2013-02-18T22:02:54.000Z", + "committer_name": "angus croll", + "committer_email": "anguscroll@gmail.com", + "committed_date": "2013-02-18T22:02:54.000Z", + "project_id": 6 + } +] +``` + +### Scope: blobs **[STARTER]** + +This scope is available only if [Elasticsearch](../integration/elasticsearch.md) is enabled. + +Filters are available for this scope: +- filename +- path +- extension + +to use a filter simply include it in your query like so: `a query filename:some_name*`. + +You may use wildcards (`*`) to use glob matching. + +```bash +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/6/search?scope=blobs&search=installation +``` + +Example response: + +```json + +[ + { + "basename": "README", + "data": "```\n\n## Installation\n\nQuick start using the [pre-built", + "filename": "README.md", + "id": null, + "ref": "master", + "startline": 46, + "project_id": 6 + } +] +``` + ### Scope: users ```bash @@ -556,7 +744,6 @@ GET /projects/:id/search | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `scope` | string | yes | The scope to search in | | `search` | string | yes | The search query | -| `ref` | string | no | The name of a repository branch or tag to search on. The project's default branch is used by default. This is only applicable for scopes: commits, blobs, and wiki_blobs. | Search the expression within the specified scope. Currently these scopes are supported: issues, merge_requests, milestones, notes, wiki_blobs, commits, blobs, users. @@ -851,7 +1038,7 @@ Blobs searches are performed on both filenames and contents. Search results: times in the content. ```bash -curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation&ref=feature +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/6/search?scope=blobs&search=installation ``` Example response: @@ -864,7 +1051,7 @@ Example response: "data": "```\n\n## Installation\n\nQuick start using the [pre-built", "filename": "README.md", "id": null, - "ref": "feature", + "ref": "master", "startline": 46, "project_id": 6 } diff --git a/doc/ci/README.md b/doc/ci/README.md index 93b82a065b3..49d62faeccf 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -29,8 +29,11 @@ the development cycle, ensuring that all the code deployed to production complies with the code standards you established for your app. -For a complete overview of these methodologies and GitLab CI/CD, -read the [Introduction to CI/CD with GitLab](introduction/index.md). +For a: + +- Complete overview of these methodologies and GitLab CI/CD, + read the [Introduction to CI/CD with GitLab](introduction/index.md). +- Video demonstration of GitLab CI/CD, see [Demo: CI/CD with GitLab](https://www.youtube.com/watch?v=1iXFbchozdY). ## Getting started @@ -161,6 +164,33 @@ See also the [Why CI/CD?](https://docs.google.com/presentation/d/1OGgk2Tcxbpl7DJ As GitLab CI/CD has evolved, certain breaking changes have been necessary. These are: +#### 12.0 + +- [Use refspec to clone/fetch git + repository](https://gitlab.com/gitlab-org/gitlab-runner/issues/4069). +- [Old cache + configuration](https://gitlab.com/gitlab-org/gitlab-runner/issues/4070). +- [Old metrics server + configuration](https://gitlab.com/gitlab-org/gitlab-runner/issues/4072). +- [Remove + `FF_K8S_USE_ENTRYPOINT_OVER_COMMAND`](https://gitlab.com/gitlab-org/gitlab-runner/issues/4073). +- [Remove Linux distributions that reach + EOL](https://gitlab.com/gitlab-org/gitlab-runner/merge_requests/1130). +- [Update command line API for helper + images](https://gitlab.com/gitlab-org/gitlab-runner/issues/4013). +- [Remove old `git clean` + flow](https://gitlab.com/gitlab-org/gitlab-runner/issues/4175). + +#### 11.0 + +- No breaking changes. + +#### 10.0 + +- No breaking changes. + +#### 9.0 + - [CI variables renaming for GitLab 9.0](variables/deprecated_variables.md#gitlab-90-renamed-variables). Read about the deprecated CI variables and what you should use for GitLab 9.0+. - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md). diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index d703e106e76..9a5a3624c73 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -1,3 +1,7 @@ +--- +type: index, concepts, howto +--- + # Cache dependencies in GitLab CI/CD GitLab CI/CD provides a caching mechanism that can be used to save time @@ -60,7 +64,7 @@ In summary: - Caches are disabled if not defined globally or per job (using `cache:`). - Caches are available for all jobs in your `.gitlab-ci.yml` if enabled globally. -- Caches can be used by subsequent pipelines of that very same job (a script in +- Caches can be used by subsequent pipelines of that same job (a script in a stage) in which the cache was created (if not defined globally). - Caches are stored where the Runner is installed **and** uploaded to S3 if [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). @@ -87,7 +91,7 @@ cache, when declaring `cache` in your jobs, use one or a mix of the following: that share their cache. - [Use sticky Runners](../runners/README.md#locking-a-specific-runner-from-being-enabled-for-other-projects) that will be only available to a particular project. -- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (e.g., +- [Use a `key`](../yaml/README.md#cachekey) that fits your workflow (for example, different caches on each branch). For that, you can take advantage of the [CI/CD predefined variables](../variables/README.md#predefined-environment-variables). @@ -420,7 +424,7 @@ mismatch and a few ideas how to fix it. Let's explore some examples. ---- +#### Examples Let's assume you have only one Runner assigned to your project, so the cache will be stored in the Runner's machine by default. If two jobs, A and B, @@ -462,8 +466,6 @@ job B: To fix that, use different `keys` for each job. ---- - In another case, let's assume you have more than one Runners assigned to your project, but the distributed cache is not enabled. We want the second time the pipeline is run, `job A` and `job B` to re-use their cache (which in this case @@ -526,3 +528,15 @@ Behind the scenes, this works by increasing a counter in the database, and the value of that counter is used to create the key for the cache by appending an integer to it: `-1`, `-2`, etc. After a push, a new key is generated and the old cache is not valid anymore. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index 5ecdf0f8c54..241134783da 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -1,3 +1,7 @@ +--- +type: index, concepts, howto +--- + # GitLab ChatOps > **Notes:** @@ -10,7 +14,10 @@ GitLab ChatOps provides a method to interact with CI/CD jobs through chat servic ## How it works -GitLab ChatOps is built upon two existing features, [GitLab CI/CD](../README.md) and [Slack Slash Commmands](../../user/project/integrations/slack_slash_commands.md). +GitLab ChatOps is built upon two existing features: + +- [GitLab CI/CD](../README.md). +- [Slack Slash Commands](../../user/project/integrations/slack_slash_commands.md). A new `run` action has been added to the [slash commands](../../integration/slash_commands.md), which takes two arguments: a `<job name>` to execute and the `<job arguments>`. When executed, ChatOps will look up the specified job name and attempt to match it to a corresponding job in [.gitlab-ci.yml](../yaml/README.md). If a matching job is found on `master`, a pipeline containing just that job is scheduled. Two additional [CI/CD variables](../variables/README.md#predefined-environment-variables) are passed to the job: `CHAT_INPUT` contains any additional arguments, and `CHAT_CHANNEL` is set to the name of channel the action was triggered in. @@ -22,9 +29,9 @@ After the job has finished, its output is sent back to Slack provided it has com Since ChatOps is built upon GitLab CI/CD, the job has all the same features and functions available. There a few best practices to consider however when creating ChatOps jobs: -* It is strongly recommended to set `only: [chat]` so the job does not run as part of the standard CI pipeline. -* If the job is set to `when: manual`, the pipeline will be created however the job will wait to be started. -* It is important to keep in mind that there is very limited support for access control. If the user who triggered the slash command is a developer in the project, the job will run. The job itself can utilize existing [CI/CD variables](../variables/README.html#predefined-environment-variables) like `GITLAB_USER_ID` to perform additional rights validation, however these variables can be [overridden](../variables/README.html#priority-of-environment-variables). +- It is strongly recommended to set `only: [chat]` so the job does not run as part of the standard CI pipeline. +- If the job is set to `when: manual`, the pipeline will be created however the job will wait to be started. +- It is important to keep in mind that there is limited support for access control. If the user who triggered the slash command is a developer in the project, the job will run. The job itself can utilize existing [CI/CD variables](../variables/README.html#predefined-environment-variables) like `GITLAB_USER_ID` to perform additional rights validation, however these variables can be [overridden](../variables/README.html#priority-of-environment-variables). ### Controlling the ChatOps reply @@ -59,3 +66,15 @@ You can find and download the official GitLab ChatOps icon here.  [Download bigger image](img/gitlab-chatops-icon.png) + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md index 1c8e12d229c..9126eb65f07 100644 --- a/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md +++ b/doc/ci/ci_cd_for_external_repos/bitbucket_integration.md @@ -1,8 +1,15 @@ +--- +type: howto +--- + # Using GitLab CI/CD with a Bitbucket Cloud repository **[PREMIUM]** -GitLab CI/CD can be used with Bitbucket Cloud by creating a -[CI/CD project](https://docs.gitlab.com/ee/user/project/ci_cd_for_external_repo.html) and connecting -your Git repository via URL. +GitLab CI/CD can be used with Bitbucket Cloud by: + +1. Creating a [CI/CD project](https://docs.gitlab.com/ee/user/project/ci_cd_for_external_repo.html). +1. Connecting your Git repository via URL. + +To use GitLab CI/CD with a Bitbucket Cloud repository: 1. In GitLab create a **CI/CD for external repo**, select **Repo by URL** and create the project. @@ -16,13 +23,13 @@ your Git repository via URL. with `api` scope. This will be used to authenticate requests from the web hook that will be created in Bitbucket to notify GitLab of new commits. -1. In Bitbucket from **Settings > Webhooks** create a new web hook to notify +1. In Bitbucket, from **Settings > Webhooks**, create a new web hook to notify GitLab of new commits. The web hook URL should be set to the GitLab API to trigger pull mirroring, using the Personal Access Token we just generated for authentication. - ``` + ```text https://gitlab.com/api/v4/projects/<NAMESPACE>%2F<PROJECT>/mirror/pull?private_token=<PERSONAL_ACCESS_TOKEN> ``` @@ -33,27 +40,27 @@ your Git repository via URL. After saving, test the web hook by pushing a change to your Bitbucket repository. -1. In Bitbucket create an **App Password** from **Bitbucket Settings > App +1. In Bitbucket, create an **App Password** from **Bitbucket Settings > App Passwords** to authenticate the build status script setting commit build statuses in Bitbucket. Repository write permissions are required.  -1. In GitLab from **Settings > CI/CD > Environment variables** add variables to allow - communication with Bitbucket via the Bitbucket API. +1. In GitLab, from **Settings > CI/CD > Environment variables**, add variables to allow + communication with Bitbucket via the Bitbucket API: - `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above + `BITBUCKET_ACCESS_TOKEN`: the Bitbucket app password created above. - `BITBUCKET_USERNAME`: the username of the Bitbucket account + `BITBUCKET_USERNAME`: the username of the Bitbucket account. - `BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ + `BITBUCKET_NAMESPACE`: set this if your GitLab and Bitbucket namespaces differ. - `BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ + `BITBUCKET_REPOSITORY`: set this if your GitLab and Bitbucket project names differ. -1. In Bitbucket add a script to push the pipeline status to Bitbucket. +1. In Bitbucket, add a script to push the pipeline status to Bitbucket. > Note: changes made in GitLab will be overwritten by any changes made - upstream in Bitbucket. + > upstream in Bitbucket. Create a file `build_status` and insert the script below and run `chmod +x build_status` in your terminal to make the script executable. @@ -111,7 +118,7 @@ your Git repository via URL. 1. Still in Bitbucket, create a `.gitlab-ci.yml` file to use the script to push pipeline success and failures to Bitbucket. - ``` + ```yaml stages: - test - ci_status @@ -145,3 +152,15 @@ GitLab is now configured to mirror changes from Bitbucket, run CI/CD pipelines configured in `.gitlab-ci.yml` and push the status to Bitbucket. [pull-mirroring]: ../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/ci_cd_for_external_repos/github_integration.md b/doc/ci/ci_cd_for_external_repos/github_integration.md index 0e2acf957e0..612dcc93bc1 100644 --- a/doc/ci/ci_cd_for_external_repos/github_integration.md +++ b/doc/ci/ci_cd_for_external_repos/github_integration.md @@ -1,3 +1,7 @@ +--- +type: howto +--- + # Using GitLab CI/CD with a GitHub repository **[PREMIUM]** GitLab CI/CD can be used with **GitHub.com** and **GitHub Enterprise** by @@ -15,7 +19,7 @@ administrator: NOTE: **Note:** Due to a 10-token limitation on the [GitHub OAuth Implementation](https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/#creating-multiple-tokens-for-oauth-apps), -if you import more than 10 times, your oldest imported project's token will be +if you import more than 10 times, your oldest imported project's token will be revoked. See issue [#9147](https://gitlab.com/gitlab-org/gitlab-ee/issues/9147) for more information. @@ -31,23 +35,27 @@ for more information. 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will import the project, enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter), enable -[GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html), and create a web hook -on GitHub to notify GitLab of new commits. +GitLab will: + +1. Import the project. +1. Enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter). +1. Enable [GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html). +1. Create a web hook on GitHub to notify GitLab of new commits. ## Connect with Personal Access Token -NOTE: **Note:** Personal access tokens can only be used to connect GitHub.com +NOTE: **Note:** +Personal access tokens can only be used to connect GitHub.com repositories to GitLab. If you are not using the [GitHub integration](../../integration/github.md), you can still perform a one-off authorization with GitHub to grant GitLab access your repositories: -1. Open https://github.com/settings/tokens/new to create a **Personal Access +1. Open <https://github.com/settings/tokens/new> to create a **Personal Access Token**. This token with be used to access your repository and push commit statuses to GitHub. - + The `repo` and `admin:repo_hook` should be enable to allow GitLab access to your project, update commit statuses, and create a web hook to notify GitLab of new commits. @@ -62,20 +70,23 @@ repositories: 1. In GitHub, add a `.gitlab-ci.yml` to [configure GitLab CI/CD](../quick_start/README.md). -GitLab will import the project, enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter), enable -[GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html), and create a web hook -on GitHub to notify GitLab of new commits. +GitLab will: + +1. Import the project. +1. Enable [Pull Mirroring](../../workflow/repository_mirroring.md#pulling-from-a-remote-repository-starter). +1. Enable [GitHub project integration](https://docs.gitlab.com/ee/user/project/integrations/github.html). +1. Create a web hook on GitHub to notify GitLab of new commits. ## Connect manually If the [GitHub integration](../../integration/github.md) is not enabled, or is enabled for a different GitHub instance, you GitLab CI/CD can be manually enabled for -your repository. +your repository: -1. In GitHub open https://github.com/settings/tokens/new create a **Personal +1. In GitHub open <https://github.com/settings/tokens/new> create a **Personal Access Token.** GitLab will use this token to access your repository and push commit statuses. - + Enter a **Token description** and update the scope to allow: `repo` so that GitLab can access your project and update commit statuses @@ -109,3 +120,15 @@ your repository.  1. In GitHub add a `.gitlab-ci.yml` to configure GitLab CI/CD. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/ci_cd_for_external_repos/index.md b/doc/ci/ci_cd_for_external_repos/index.md index 450ffe512dc..5de88412121 100644 --- a/doc/ci/ci_cd_for_external_repos/index.md +++ b/doc/ci/ci_cd_for_external_repos/index.md @@ -1,3 +1,7 @@ +--- +type: index, howto +--- + # GitLab CI/CD for external repositories **[PREMIUM]** NOTE: **Note:** @@ -6,22 +10,26 @@ GitLab.com users until September 22nd, 2019. >[Introduced][ee-4642] in [GitLab Premium][eep] 10.6. -GitLab CI/CD can be used with GitHub or any other Git server. +GitLab CI/CD can be used with: + +- [GitHub](github_integration.md). +- [Bitbucket Cloud](bitbucket_integration.md). +- Any other Git server. + Instead of moving your entire project to GitLab, you can connect your external repository to get the benefits of GitLab CI/CD. -- [GitHub](github_integration.md) -- [Bitbucket Cloud](bitbucket_integration.md) - Connecting an external repository will set up [repository mirroring][mirroring] and create a lightweight project where issues, merge requests, wiki, and snippets disabled. These features [can be re-enabled later][settings]. -1. From your GitLab dashboard click **New project** -1. Switch to the **CI/CD for external repo** tab -1. Choose **GitHub** or **Repo by URL** -1. The next steps are similar to the [import flow](../../user/project/import/index.md) +To connect to an external repository: + +1. From your GitLab dashboard, click **New project**. +1. Switch to the **CI/CD for external repo** tab. +1. Choose **GitHub** or **Repo by URL**. +1. The next steps are similar to the [import flow](../../user/project/import/index.md).  diff --git a/doc/ci/docker/README.md b/doc/ci/docker/README.md index 446f5b54f0c..f76471b50f2 100644 --- a/doc/ci/docker/README.md +++ b/doc/ci/docker/README.md @@ -1,9 +1,13 @@ --- comments: false +type: index --- # Docker integration +GitLab CI/CD can be combined with [Docker](https://www.docker.com) to enable +integration between the two. + The following documentation is available for using GitLab CI/CD with Docker: - [Using Docker images](using_docker_images.md). diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index dd112dadc40..d8068bbb7f0 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -1,16 +1,18 @@ +--- +type: concepts, howto +--- + # Building Docker images with GitLab CI/CD GitLab CI/CD allows you to use Docker Engine to build and test docker-based projects. -TIP: **Tip:** -This also allows to you to use `docker-compose` and other docker-enabled tools. One of the new trends in Continuous Integration/Deployment is to: -1. Create an application image -1. Run tests against the created image -1. Push image to a remote registry -1. Deploy to a server from the pushed image +1. Create an application image. +1. Run tests against the created image. +1. Push image to a remote registry. +1. Deploy to a server from the pushed image. It's also useful when your application already has the `Dockerfile` that can be used to create and test an image: @@ -75,7 +77,7 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. - docker run my-docker-image /script/to/run/tests ``` -1. You can now use `docker` command and install `docker-compose` if needed. +1. You can now use `docker` command (and **install** `docker-compose` if needed). NOTE: **Note:** By adding `gitlab-runner` to the `docker` group you are effectively granting `gitlab-runner` full root permissions. @@ -85,8 +87,10 @@ For more information please read [On Docker security: `docker` group considered The second approach is to use the special docker-in-docker (dind) [Docker image](https://hub.docker.com/_/docker/) with all tools installed -(`docker` and `docker-compose`) and run the job script in context of that -image in privileged mode. +(`docker`) and run the job script in context of that +image in privileged mode. + +NOTE: **Note:** `docker-compose` is not part of docker-in-docker (dind). In case you'd like to use `docker-compose` in your CI builds, please follow the (installation instructions for docker-compose)[https://docs.docker.com/compose/install/] provided by docker. In order to do that, follow the steps: @@ -113,7 +117,7 @@ In order to do that, follow the steps: The above command will create a `config.toml` entry similar to this: - ``` + ```toml [[runners]] url = "https://gitlab.com/" token = TOKEN @@ -227,7 +231,7 @@ In order to do that, follow the steps: The above command will create a `config.toml` entry similar to this: - ``` + ```toml [[runners]] url = "https://gitlab.com/" token = REGISTRATION_TOKEN @@ -270,9 +274,9 @@ aware of the following implications: create containers with specific names, they may conflict with each other. - Sharing files and directories from the source repo into containers may not work as expected since volume mounting is done in the context of the host - machine, not the build container, e.g.: + machine, not the build container. For example: - ``` + ```sh docker run --rm -t -i -v $(pwd)/src:/home/app/src test-image:latest run_app_tests ``` @@ -337,7 +341,7 @@ NOTE: **Note:** The shared Runners on GitLab.com use the `overlay2` driver by default. By default, when using `docker:dind`, Docker uses the `vfs` storage driver which -copies the filesystem on every run. This is a very disk-intensive operation +copies the filesystem on every run. This is a disk-intensive operation which can be avoided if a different driver is used, for example `overlay2`. ### Requirements @@ -345,13 +349,13 @@ which can be avoided if a different driver is used, for example `overlay2`. 1. Make sure a recent kernel is used, preferably `>= 4.2`. 1. Check whether the `overlay` module is loaded: - ``` + ```sh sudo lsmod | grep overlay ``` If you see no result, then it isn't loaded. To load it use: - ``` + ```sh sudo modprobe overlay ``` @@ -359,7 +363,7 @@ which can be avoided if a different driver is used, for example `overlay2`. On Ubuntu systems, this is done by editing `/etc/modules`. Just add the following line into it: - ``` + ```text overlay ``` @@ -367,7 +371,7 @@ which can be avoided if a different driver is used, for example `overlay2`. You can enable the driver for each project individually by editing the project's `.gitlab-ci.yml`: -``` +```yaml variables: DOCKER_DRIVER: overlay2 ``` @@ -571,3 +575,15 @@ deploy: [docker-cap]: https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities [2fa]: ../../user/profile/account/two_factor_authentication.md [pat]: ../../user/profile/personal_access_tokens.md + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index 13c26bc5f47..d09efce7cc1 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -1,3 +1,7 @@ +--- +type: concepts, howto +--- + # Using Docker images GitLab CI in conjunction with [GitLab Runner](../runners/README.md) can use @@ -45,10 +49,10 @@ The `image` keyword is the name of the Docker image the Docker executor will run to perform the CI tasks. By default, the executor will only pull images from [Docker Hub][hub], -but this can be configured in the `gitlab-runner/config.toml` by setting +however this can be configured in the `gitlab-runner/config.toml` by setting the [Docker pull policy][] to allow using local images. -For more information about images and Docker Hub please read +For more information about images and Docker Hub, please read the [Docker Fundamentals][] documentation. ## What is a service @@ -95,8 +99,8 @@ required for the CI/CD job to proceed and is accessed by network. To make sure this works, the Runner: -1. checks which ports are exposed from the container by default -1. starts a special container that waits for these ports to be accessible +1. Checks which ports are exposed from the container by default. +1. Starts a special container that waits for these ports to be accessible. When the second stage of the check fails, either because there is no opened port in the service, or the service was not started properly before the timeout and the port is not @@ -106,7 +110,7 @@ In most cases it will affect the job, but there may be situations when the job will still succeed even if that warning was printed. For example: - The service was started a little after the warning was raised, and the job is - not using the linked service from the very beginning. In that case, when the + not using the linked service from the beginning. In that case, when the job needed to access the service, it may have been already there waiting for connections. - The service container is not providing any networking service, but it's doing @@ -143,9 +147,9 @@ job: If you need to have `php`, `node` and `go` available for your script, you should either: -- choose an existing Docker image that contains all required tools, or -- create your own Docker image, which will have all the required tools included - and use that in your job +- Choose an existing Docker image that contains all required tools. +- Create your own Docker image, which will have all the required tools included + and use that in your job. ### Accessing the services @@ -167,18 +171,18 @@ access to it from your build container under two hostnames to choose from: - `tutum-wordpress` - `tutum__wordpress` ->**Note:** +NOTE: **Note:** Hostnames with underscores are not RFC valid and may cause problems in 3rd party applications. The default aliases for the service's hostname are created from its image name following these rules: -- Everything after the colon (`:`) is stripped +- Everything after the colon (`:`) is stripped. - Slash (`/`) is replaced with double underscores (`__`) and the primary alias - is created + is created. - Slash (`/`) is replaced with a single dash (`-`) and the secondary alias is - created (requires GitLab Runner v1.1.0 or higher) + created (requires GitLab Runner v1.1.0 or higher). To override the default behavior, you can [specify a service alias](#available-settings-for-services). @@ -333,7 +337,7 @@ services: ``` The Runner will still start two containers using the `mysql:latest` image, -but now each of them will also be accessible with the alias configured +however now each of them will also be accessible with the alias configured in `.gitlab-ci.yml` file. ### Setting a command for the service @@ -408,8 +412,6 @@ you should check which one your Runner is using. Specifically: The syntax of `image:entrypoint` is similar to [Dockerfile's `ENTRYPOINT`][entrypoint]. ----- - Let's assume you have a `super/sql:experimental` image with some SQL database inside it and you would like to use it as a base image for your job because you want to execute some tests with this database binary. Let's also assume that @@ -443,7 +445,7 @@ image: Look for the `[runners.docker]` section: -``` +```toml [runners.docker] image = "ruby:2.1" services = ["mysql:latest", "postgres:latest"] @@ -469,11 +471,11 @@ image which is private and requires you to login into a private container regist Let's also assume that these are the login credentials: -| Key | Value | -|----------|---------------------------| -| registry | registry.example.com:5000 | -| username | my_username | -| password | my_password | +| Key | Value | +|:---------|:----------------------------| +| registry | `registry.example.com:5000` | +| username | `my_username` | +| password | `my_password` | To configure access for `registry.example.com:5000`, follow these steps: @@ -534,7 +536,8 @@ To configure access for `registry.example.com:5000`, follow these steps: You can add configuration for as many registries as you want, adding more registries to the `"auths"` hash as described above. -NOTE: **Note:** The full `hostname:port` combination is required everywhere +NOTE: **Note:** +The full `hostname:port` combination is required everywhere for the Runner to match the `DOCKER_AUTH_CONFIG`. For example, if `registry.example.com:5000/namespace/image:tag` is specified in `.gitlab-ci.yml`, then the `DOCKER_AUTH_CONFIG` must also specify `registry.example.com:5000`. @@ -551,8 +554,9 @@ service containers. For all possible configuration variables check the documentation of each image provided in their corresponding Docker hub page. -*Note: All variables will be passed to all services containers. It's not -designed to distinguish which variable should go where.* +NOTE: **Note:** +All variables will be passed to all services containers. It's not +designed to distinguish which variable should go where. ### PostgreSQL service example @@ -582,8 +586,9 @@ time. ## How to debug a job locally -*Note: The following commands are run without root privileges. You should be -able to run Docker with your regular user account.* +NOTE: **Note:** +The following commands are run without root privileges. You should be +able to run Docker with your regular user account. First start with creating a file named `build_script`: @@ -602,7 +607,7 @@ is specific to your project. Then create some service containers: -``` +```sh docker run -d --name service-mysql mysql:latest docker run -d --name service-postgres postgres:latest ``` @@ -614,7 +619,7 @@ respectively. They will both run in the background (`-d`). Finally, create a build container by executing the `build_script` file we created earlier: -``` +```sh docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.1 /bin/bash < build_script ``` @@ -626,7 +631,7 @@ piped using STDIN to the bash interpreter which in turn executes the When you finish testing and no longer need the containers, you can remove them with: -``` +```sh docker rm -f -v build service-mysql service-postgres ``` diff --git a/doc/ci/docker/using_kaniko.md b/doc/ci/docker/using_kaniko.md index f354cdb398e..50f1ac3d54a 100644 --- a/doc/ci/docker/using_kaniko.md +++ b/doc/ci/docker/using_kaniko.md @@ -1,3 +1,7 @@ +--- +type: howto +--- + # Building images with kaniko and GitLab CI/CD > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45512) in GitLab 11.2. @@ -9,17 +13,18 @@ container images from a Dockerfile, inside a container or Kubernetes cluster. kaniko solves two problems with using the [docker-in-docker build](using_docker_build.md#use-docker-in-docker-executor) method: -1. Docker-in-docker requires [privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) - in order to function, which is a significant security concern. -1. Docker-in-docker generally incurs a performance penalty and can be quite slow. +- Docker-in-docker requires [privileged mode](https://docs.docker.com/engine/reference/run/#runtime-privilege-and-linux-capabilities) + in order to function, which is a significant security concern. +- Docker-in-docker generally incurs a performance penalty and can be quite slow. ## Requirements In order to utilize kaniko with GitLab, a [GitLab Runner](https://docs.gitlab.com/runner/) -using either the [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html), -[Docker](https://docs.gitlab.com/runner/executors/docker.html), or -[Docker Machine](https://docs.gitlab.com/runner/executors/docker_machine.html) -executors is required. +using one of the following executors is required: + +- [Kubernetes](https://docs.gitlab.com/runner/executors/kubernetes.html). +- [Docker](https://docs.gitlab.com/runner/executors/docker.html). +- [Docker Machine](https://docs.gitlab.com/runner/executors/docker_machine.html). ## Building a Docker image with kaniko @@ -34,14 +39,17 @@ few important details: - A Docker `config.json` file needs to be created with the authentication information for the desired container registry. ---- +In the following example, kaniko is used to: + +1. Build a Docker image. +1. Then push it to [GitLab Container Registry](../../user/project/container_registry.md). -In the following example, kaniko is used to build a Docker image and then push -it to [GitLab Container Registry](../../user/project/container_registry.md). The job will run only when a tag is pushed. A `config.json` file is created under `/kaniko/.docker` with the needed GitLab Container Registry credentials taken from the [environment variables](../variables/README.md#predefined-environment-variables) -GitLab CI/CD provides. In the last step, kaniko uses the `Dockerfile` under the +GitLab CI/CD provides. + +In the last step, kaniko uses the `Dockerfile` under the root directory of the project, builds the Docker image and pushes it to the project's Container Registry while tagging it with the Git tag: @@ -80,3 +88,15 @@ store: ... -----END CERTIFICATE-----" >> /kaniko/ssl/certs/ca-certificates.crt ``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index 9934d543991..56200142055 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -1,29 +1,32 @@ --- -type: reference +type: howto --- # How to enable or disable GitLab CI/CD -To effectively use GitLab CI/CD, you need a valid [`.gitlab-ci.yml`](yaml/README.md) -file present at the root directory of your project and a -[runner](runners/README.md) properly set up. You can read our -[quick start guide](quick_start/README.md) to get you started. +To effectively use GitLab CI/CD, you need: + +- A valid [`.gitlab-ci.yml`](yaml/README.md) file present at the root directory + of your project. +- A [runner](runners/README.md) properly set up. + +You can read our [quick start guide](quick_start/README.md) to get you started. If you are using an external CI/CD server like Jenkins or Drone CI, it is advised to disable GitLab CI/CD in order to not have any conflicts with the commits status API. ---- - GitLab CI/CD is exposed via the `/pipelines` and `/jobs` pages of a project. Disabling GitLab CI/CD in a project does not delete any previous jobs. In fact, the `/pipelines` and `/jobs` pages can still be accessed, although it's hidden from the left sidebar menu. -GitLab CI/CD is enabled by default on new installations and can be disabled either -individually under each project's settings, or site-wide by modifying the -settings in `gitlab.yml` and `gitlab.rb` for source and Omnibus installations -respectively. +GitLab CI/CD is enabled by default on new installations and can be disabled +either: + +- Individually under each project's settings. +- Site-wide by modifying the settings in `gitlab.yml` and `gitlab.rb` for source + and Omnibus installations respectively. ## Per-project user setting @@ -40,10 +43,10 @@ and `gitlab.rb` for source and Omnibus installations respectively. Two things to note: -1. Disabling GitLab CI/CD, will affect only newly-created projects. Projects that - had it enabled prior to this modification, will work as before. -1. Even if you disable GitLab CI/CD, users will still be able to enable it in the - project's settings. +- Disabling GitLab CI/CD, will affect only newly-created projects. Projects that + had it enabled prior to this modification, will work as before. +- Even if you disable GitLab CI/CD, users will still be able to enable it in the + project's settings. For installations from source, open `gitlab.yml` with your editor and set `builds` to `false`: @@ -58,12 +61,32 @@ default_projects_features: builds: false ``` -Save the file and restart GitLab: `sudo service gitlab restart`. +Save the file and restart GitLab: + +```sh +sudo service gitlab restart +``` For Omnibus installations, edit `/etc/gitlab/gitlab.rb` and add the line: -``` +```ruby gitlab_rails['gitlab_default_projects_features_builds'] = false ``` -Save the file and reconfigure GitLab: `sudo gitlab-ctl reconfigure`. +Save the file and reconfigure GitLab: + +```sh +sudo gitlab-ctl reconfigure +``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 9f930833093..bd419965a9c 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -92,7 +92,7 @@ deploy_staging: - master ``` -We have defined 3 [stages](yaml/README.md#stages): +We have defined three [stages](yaml/README.md#stages): - `test` - `build` @@ -135,7 +135,7 @@ In summary, with the above `.gitlab-ci.yml` we have achieved the following: > the name given in `.gitlab-ci.yml` (with any variables expanded), while the > second is a "cleaned-up" version of the name, suitable for use in URLs, DNS, > etc. - +> > Starting with GitLab 9.3, the environment URL is exposed to the Runner via > `$CI_ENVIRONMENT_URL`. The URL is expanded from `.gitlab-ci.yml`, or if > the URL was not defined there, the external URL from the environment is used. @@ -617,6 +617,10 @@ versions of the app, all without leaving GitLab.  +#### Linking to external dashboard + +Add a [button to the Monitoring dashboard](../user/project/operations/linking_to_an_external_dashboard.md) linking directly to your existing external dashboards. + ### Web terminals > Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners. diff --git a/doc/ci/environments/protected_environments.md b/doc/ci/environments/protected_environments.md index ab5c0e2dbad..b72ebe838b8 100644 --- a/doc/ci/environments/protected_environments.md +++ b/doc/ci/environments/protected_environments.md @@ -1,3 +1,7 @@ +--- +type: concepts, howto +--- + # Protected Environments **[PREMIUM]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6303) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.3. @@ -47,3 +51,15 @@ Maintainers can: - Update existing protected environments at any time by changing the access in the **Allowed to Deploy** dropdown menu. - Unprotect a protected environment by clicking the **Unprotect** button for that environment. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index 40638d151c4..50c8d82602b 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -26,6 +26,10 @@ and when hovering or tapping (on touchscreen devices) they will expand and be sh Multi-project pipelines are useful for larger products that require cross-project inter-dependencies, such as those adopting a [microservices architecture](https://about.gitlab.com/2016/08/16/trends-in-version-control-land-microservices/). +For a demonstration of how cross-functional development teams can use cross-pipeline +triggering to trigger multiple pipelines for different microservices projects, see +[Cross-project Pipeline Triggering and Visualization](https://about.gitlab.com/handbook/marketing/product-marketing/demo/#cross-project-pipeline-triggering-and-visualization-may-2019---1110). + ## Use cases Let's assume you deploy your web app from different projects in GitLab: diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index 8b0634ed268..1ad3d516df9 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -270,9 +270,6 @@ Clicking on an individual job will show you its job trace, and allow you to: - Retry the job. - Erase the job trace. -NOTE: **Note:** -To prevent jobs from being bypassed or run out of order, canceled jobs can only be retried when the whole pipeline they belong to is retried. - ### Seeing the failure reason for jobs > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17782) in GitLab 10.7. diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index c851931e85c..df455857dee 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -92,7 +92,7 @@ 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 contain only letters, numbers, or underscores. +- The value must only consist of characters from the Base64 alphabet, defined in [RFC4648](https://tools.ietf.org/html/rfc4648). - The value must be at least 8 characters long. - The value must not use variables. @@ -479,6 +479,7 @@ 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 `==` or `!=` to compare a variable content to a @@ -489,6 +490,7 @@ 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 @@ -499,6 +501,7 @@ Below you can find supported syntax reference: 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 @@ -508,6 +511,7 @@ Below you can find supported syntax reference: 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 @@ -527,6 +531,7 @@ 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 @@ -536,6 +541,19 @@ Below you can find supported syntax reference: Pattern matching is case-sensitive by default. Use `i` flag modifier, like `/pattern/i` to make a pattern case-insensitive. +1. Conjunction / Disjunction + + > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 == "something"` + + > Example: `$VARIABLE1 =~ /^content.*/ && $VARIABLE2 =~ /thing$/ && $VARIABLE3` + + > Example: `$VARIABLE1 =~ /^content.*/ || $VARIABLE2 =~ /thing$/ && $VARIABLE3` + + It is possible to join multiple conditions using `&&` or `||`. Any of the otherwise + supported syntax may be used in a conjunctive or disjunctive statement. + Precedence of operators follows standard Ruby 2.5 operation + [precedence](https://ruby-doc.org/core-2.5.0/doc/syntax/precedence_rdoc.html). + ## Debug tracing > Introduced in GitLab Runner 1.7. diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 716363a8d6d..fa4b0378f61 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -1189,9 +1189,9 @@ skip the download step. > - Job artifacts are only collected for successful jobs by default. `artifacts` is used to specify a list of files and directories which should be -attached to the job after success. +attached to the job when it [succeeds, fails, or always](#artifactswhen). -The artifacts will be sent to GitLab after the job finishes successfully and will +The artifacts will be sent to GitLab after the job finishes and will be available for download in the GitLab UI. [Read more about artifacts](../../user/project/pipelines/job_artifacts.md). diff --git a/doc/development/README.md b/doc/development/README.md index 624665a42d1..d2f09fc01de 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -20,6 +20,7 @@ description: 'Learn how to contribute to GitLab.' - [Automatic CE->EE merge](automatic_ce_ee_merge.md) - [Guidelines for implementing Enterprise Edition features](ee_features.md) - [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) +- [Requesting access to Chatops on GitLab.com](chatops_on_gitlabcom.md#requesting-access) (for GitLabbers) ## UX and frontend guides diff --git a/doc/development/architecture.md b/doc/development/architecture.md index a0e4020da09..650325121b2 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -676,7 +676,7 @@ We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/ha [runner-gdk]: https://gitlab.com/gitlab-org/gitlab-development-kit/blob/master/doc/howto/runner.md [database-migrations-omnibus]: https://docs.gitlab.com/omnibus/settings/database.html#disabling-automatic-database-migration [database-migrations-charts]: https://docs.gitlab.com/charts/charts/gitlab/migrations/ -[database-migrations-source]: ../update/upgrading_from_source.md#13-install-libs-migrations-etc +[database-migrations-source]: ../update/upgrading_from_source.md#14-install-libs-migrations-etc [certificate-management-omnibus]: https://docs.gitlab.com/omnibus/settings/ssl.html [certificate-management-charts]: https://docs.gitlab.com/charts/installation/tls.html [certificate-management-source]: ../install/installation.md#using-https diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md new file mode 100644 index 00000000000..c63ec53414c --- /dev/null +++ b/doc/development/chatops_on_gitlabcom.md @@ -0,0 +1,21 @@ +# Chatops on GitLab.com + +Chatops on GitLab.com allows GitLabbers to run various automation tasks on GitLab.com using Slack. + +## Requesting access + +GitLabbers may need access to Chatops on GitLab.com for administration tasks such as: + +- Configuring feature flags on staging. +- Running `EXPLAIN` queries against the GitLab.com production replica. + +To request access to Chatops on GitLab.com: + +1. Log into <https://ops.gitlab.net/users/sign_in> using the same username as for GitLab.com. +1. Ask [anyone in the `chatops` project](https://gitlab.com/gitlab-com/chatops/project_members) to add you by running `/chatops run member add <username> gitlab-com/chatops --ops`. + +## See also + + - [Chatops Usage](https://docs.gitlab.com/ee/ci/chatops/README.html) + - [Understanding EXPLAIN plans](understanding_explain_plans.md) + - [Feature Groups](feature_flags.md#feature-groups) diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index 77f064a21a9..e4225f2bc39 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -25,3 +25,17 @@ 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). + +### `modal_copy_button` vs `clipboard_button` + +The `clipboard_button` uses the `copy_to_clipboard.js` behaviour, which is +initialized on page load, so if there are vue-based clipboard buttons that +don't exist at page load (such as ones in a `GlModal`), they do not have the +click handlers associated with the clipboard package. + +`modal_copy_button` was added that manages an instance of the +[`clipboard` plugin](https://www.npmjs.com/package/clipboard) specific to +the instance of that component, which means that clipboard events are +bound on mounting and destroyed when the button is, mitigating the above +issue. It also has bindings to a particular container or modal ID +available, to work with the focus trap created by our GlModal. diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md index c871015aaf6..13f0c5cc33e 100644 --- a/doc/development/feature_flags.md +++ b/doc/development/feature_flags.md @@ -20,7 +20,7 @@ dynamic (querying the DB etc.). Once defined in `lib/feature.rb`, you will be able to activate a feature for a given feature group via the [`feature_group` param of the features API](../api/features.md#set-or-create-a-feature) -For GitLab.com, team members have access to feature flags through chatops. Only +For GitLab.com, [team members have access to feature flags through Chatops](chatops_on_gitlabcom.md). Only percentage gates are supported at this time. Setting a feature to be used 50% of the time, you should execute `/chatops run feature set my_feature_flag 50`. diff --git a/doc/development/i18n/externalization.md b/doc/development/i18n/externalization.md index 8f23ad4732a..9fb8ea542d9 100644 --- a/doc/development/i18n/externalization.md +++ b/doc/development/i18n/externalization.md @@ -174,7 +174,7 @@ For example use `%{created_at}` in Ruby but `%{createdAt}` in JavaScript. # => When size == 2: 'There are 2 mice.' ``` - Avoid using `%d` or count variables in sigular strings. This allows more natural translation in some languages. + Avoid using `%d` or count variables in singular strings. This allows more natural translation in some languages. - In JavaScript: @@ -332,7 +332,7 @@ Errors in `locale/zh_HK/gitlab.po`: Syntax error in msgstr Syntax error in message_line There should be only whitespace until the end of line after the double quote character of a message text. - Parseing result before error: '{:msgid=>["", "You are going to remove %{project_name_with_namespace}.\\n", "Removed project CANNOT be restored!\\n", "Are you ABSOLUTELY sure?"]}' + Parsing result before error: '{:msgid=>["", "You are going to remove %{project_name_with_namespace}.\\n", "Removed project CANNOT be restored!\\n", "Are you ABSOLUTELY sure?"]}' SimplePoParser filtered backtrace: SimplePoParser::ParserError Errors in `locale/zh_TW/gitlab.po`: 1 pipeline diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index fb5cfb6c157..35c5b155594 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -130,7 +130,7 @@ are very appreciative of the work done by translators and proofreaders! your previous translations by [GitLab team members](https://about.gitlab.com/team/) or [Core team members](https://about.gitlab.com/core-team/) who are fluent in the language or current proofreaders. - - When a request is made for the first proofreader for a lanuguage and there are no [GitLab team members](https://about.gitlab.com/team/) + - When a request is made for the first proofreader for a language and there are no [GitLab team members](https://about.gitlab.com/team/) or [Core team members](https://about.gitlab.com/core-team/) who speak the language, we will request links to previous translation work in other communities or projects. diff --git a/doc/development/licensing.md b/doc/development/licensing.md index 0e71cd47481..0db90d2872f 100644 --- a/doc/development/licensing.md +++ b/doc/development/licensing.md @@ -88,9 +88,11 @@ Definitions GitLab means GitLab Inc. and its affiliates and subsidiaries. -## Requesting Approval for Licenses +## Requesting Approval for Licenses or any other Intellectual Property -Libraries that are not listed in the [Acceptable Licenses][Acceptable-Licenses] or [Unacceptable Licenses][Unacceptable-Licenses] list can be submitted to the legal team for review. Please email `legal@gitlab.com` with the details. After a decision has been made, the original requestor is responsible for updating this document. +Libraries that are not already approved and listed on the [Acceptable Licenses][Acceptable-Licenses] list or that may be listed on the [Unacceptable Licenses][Unacceptable-Licenses] list may be submitted to the legal team for review and use on a case-by-case basis. Please email `legal@gitlab.com` with the details of how the software will be used, whether or not it will be modified, and how it will be distributed (if at all). After a decision has been made, the original requestor is responsible for updating this document, if applicable. Not all approvals will be approved for universal use and may continue to remain on the Unacceptable License list. + +All inquiries relating to patents should be directed to the Legal team. ## Notes diff --git a/doc/development/testing_guide/end_to_end/dynamic_element_validation.md b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md new file mode 100644 index 00000000000..f7b3ca8bc89 --- /dev/null +++ b/doc/development/testing_guide/end_to_end/dynamic_element_validation.md @@ -0,0 +1,113 @@ +# Dynamic Element Validation + +We devised a solution to solve common test automation problems such as the dreaded `NoSuchElementException`. + +Other problems that dynamic element validations solve are... + +- When we perform an action with the mouse, we expect something to occur. +- When our test is navigating to (or from) a page, we ensure that we are on the page we expect before +test continuation. + +## How it works + +We interpret user actions on the page to have some sort of effect. These actions are + +- [Navigation](#navigation) +- [Clicks](#clicks) + +### Navigation + +When a page is navigated to, there are elements that will always appear on the page unconditionally. + +Dynamic element validation is instituted when using + +```ruby +Runtime::Browser.visit(:gitlab, Some::Page) +``` + +### Clicks + +When we perform a click within our tests, we expect something to occur. That something could be a component to now +appear on the webpage, or the test to navigate away from the page entirely. + +Dynamic element validation is instituted when using + +```ruby +click_element :my_element, Some::Page +``` + +### Required Elements + +#### Definition + +First it is important to define what a "required element" is. + +Simply put, a required element is a visible HTML element that appears on a UI component without any user input. + +"Visible" can be defined as + +- Not having any CSS preventing its display. E.g.: `display: none` or `width: 0px; height: 0px;` +- Being able to be interacted with by the user + +"UI component" can be defined as + +- Anything the user sees +- A button, a text field +- A layer that sits atop the page + +#### Application + +Requiring elements is very easy. By adding `required: true` as a parameter to an `element`, you've now made it +a requirement that the element appear on the page upon navigation. + +## Examples + +Given ... + +```ruby +class MyPage < Page::Base + view 'app/views/view.html.haml' do + element :my_element, required: true + element :another_element, required: true + element :conditional_element + end + + def open_layer + click_element :my_element, Layer::MyLayer + end +end + +class Layer < Page::Component + view 'app/views/mylayer/layer.html.haml' do + element :message_content, required: true + end +end +``` + +### Navigating + +Given the [source](#examples) ... + +```ruby +Runtime::Browser.visit(:gitlab, Page::MyPage) + +execute_stuff +``` + +will invoke GitLab QA to scan `MyPage` for `my_element` and `another_element` to be on the page before continuing to +`execute_stuff` + +### Clicking + +Given the [source](#examples) ... + +```ruby +def open_layer + click_element :my_element, Layer::MyLayer +end +``` + +will invoke GitLab QA to ensure that `message_content` appears on +the Layer upon clicking `my_element`. + +This will imply that the Layer is indeed rendered before we continue our test. diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index d0de33892c4..73e1fd862c1 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -82,15 +82,17 @@ module Page end # ... + end end end ``` -The `view` DSL method declares the filename of the view where an -`element` is implemented. +### Defining Elements + +The `view` DSL method will correspond to the rails View, partial, or vue component that renders the elements. The `element` DSL method in turn declares an element for which a corresponding -`qa-element-name-dasherized` CSS class need to be added to the view file. +`qa-element-name-dasherized` CSS class will need to be added to the view file. You can also define a value (String or Regexp) to match to the actual view code but **this is deprecated** in favor of the above method for two reasons: @@ -115,6 +117,37 @@ view 'app/views/my/view.html.haml' do end ``` +### Adding Elements to a View + +Given the following elements... + +```ruby +view 'app/views/my/view.html.haml' do + element :login_field + element :password_field + element :sign_in_button +end +``` + +To add these elements to the view, you must change the rails View, partial, or vue component by adding a `qa-element-descriptor` class +for each element defined. + +In our case, `qa-login-field`, `qa-password-field` and `qa-sign-in-button` + +**app/views/my/view.html.haml** + +```haml += f.text_field :login, class: "form-control top qa-login-field", autofocus: "autofocus", autocapitalize: "off", autocorrect: "off", required: true, title: "This field is required." += f.password_field :password, class: "form-control bottom qa-password-field", required: true, title: "This field is required." += f.submit "Sign in", class: "btn btn-success qa-sign-in-button" +``` + +Things to note: + +- The CSS class must be `kebab-cased` (separated with hyphens "`-`") +- If the element appears on the page unconditionally, add `required: true` to the element. See +[Dynamic element validation](dynamic_element_validation.md) + ## Running the test locally During development, you can run the `qa:selectors` test by running diff --git a/doc/development/understanding_explain_plans.md b/doc/development/understanding_explain_plans.md index 2ef8b3148e4..bfbb7be70e3 100644 --- a/doc/development/understanding_explain_plans.md +++ b/doc/development/understanding_explain_plans.md @@ -654,6 +654,7 @@ and related tools such as: - <https://explain.depesz.com/> - <http://tatiyants.com/postgres-query-plan-visualization/> + ## Producing query plans There are a few ways to get the output of a query plan. Of course you @@ -683,9 +684,9 @@ Execution time: 0.113 ms ### Chatops -GitLab employees can also use our chatops solution, available in Slack using the -`/chatops` slash command. You can use chatops to get a query plan by running the -following: +[GitLab employees can also use our chatops solution, available in Slack using the +`/chatops` slash command](chatops_on_gitlabcom.md). +You can use chatops to get a query plan by running the following: ``` /chatops run explain SELECT COUNT(*) FROM projects WHERE visibility_level IN (0, 20) diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 107d48fb90c..ee3d17704a2 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -168,14 +168,14 @@ CREATE EXTENSION postgres_fdw; ## Unicorn Workers -It's possible to increase the amount of unicorn workers and this will usually help to reduce the response time of the applications and increase the ability to handle parallel requests. - For most instances we recommend using: CPU cores + 1 = unicorn workers. So for a machine with 2 cores, 3 unicorn workers is ideal. For all machines that have 2GB and up we recommend a minimum of three unicorn workers. If you have a 1GB machine we recommend to configure only two Unicorn workers to prevent excessive swapping. +As long as you have enough available CPU and memory capacity, it's okay to increase the number of unicorn workers and this will usually help to reduce the response time of the applications and increase the ability to handle parallel requests. + To change the Unicorn workers when you have the Omnibus package (which defaults to the recommendation above) please see [the Unicorn settings in the Omnibus GitLab documentation](https://docs.gitlab.com/omnibus/settings/unicorn.html). ## Redis and Sidekiq diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 0a037b3876b..57a5a42fbed 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -192,9 +192,6 @@ Performing asynchronous indexing, as this will describe, will generate a lot of Make sure to prepare for this task by either [Horizontally Scaling](../administration/high_availability/README.md#basic-scaling) or creating [extra sidekiq processes](../administration/operations/extra_sidekiq_processes.md) -NOTE: **Note**: -After indexing the repositories asynchronously, you **MUST** index the database to be able to search. - Configure Elasticsearch's host and port in **Admin > Settings > Integrations**. Then create empty indexes using one of the following commands: ```sh @@ -217,78 +214,49 @@ curl --request PUT localhost:9200/gitlab-production/_settings --data '{ } }' ``` -Then enable Elasticsearch indexing and run repository indexing tasks: +Then enable Elasticsearch indexing and run project indexing tasks: ```sh # Omnibus installations -sudo gitlab-rake gitlab:elastic:index_repositories_async +sudo gitlab-rake gitlab:elastic:index_projects # Installations from source -bundle exec rake gitlab:elastic:index_repositories_async RAILS_ENV=production +bundle exec rake gitlab:elastic:index_projects RAILS_ENV=production ``` -This enqueues a number of Sidekiq jobs to index your existing repositories. -You can view the jobs in the admin panel (they are placed in the `elastic_batch_project_indexer`) +This enqueues a Sidekiq job for each project that needs to be indexed. +You can view the jobs in the admin panel (they are placed in the `elastic_indexer` queue), or you can query indexing status using a rake task: ```sh # Omnibus installations -sudo gitlab-rake gitlab:elastic:index_repositories_status +sudo gitlab-rake gitlab:elastic:index_projects_status # Installations from source -bundle exec rake gitlab:elastic:index_repositories_status RAILS_ENV=production +bundle exec rake gitlab:elastic:index_projects_status RAILS_ENV=production Indexing is 65.55% complete (6555/10000 projects) ``` -By default, one job is created for every 300 projects. For large numbers of -projects, you may wish to increase the batch size, by setting the `BATCH` -environment variable. - -You can also run the initial indexing synchronously - this is most useful if -you have a small number of projects or need finer-grained control over indexing -than Sidekiq permits: +If you want to limit the index to a range of projects you can provide the +`ID_FROM` and `ID_TO` parameters: ```sh # Omnibus installations -sudo gitlab-rake gitlab:elastic:index_repositories +sudo gitlab-rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 # Installations from source -bundle exec rake gitlab:elastic:index_repositories RAILS_ENV=production -``` - -It might take a while depending on how big your Git repositories are. - -If you want to run several tasks in parallel (probably in separate terminal -windows) you can provide the `ID_FROM` and `ID_TO` parameters: - -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_repositories ID_FROM=1001 ID_TO=2000 - -# Installations from source -bundle exec rake gitlab:elastic:index_repositories ID_FROM=1001 ID_TO=2000 RAILS_ENV=production +bundle exec rake gitlab:elastic:index_projects ID_FROM=1001 ID_TO=2000 RAILS_ENV=production ``` Where `ID_FROM` and `ID_TO` are project IDs. Both parameters are optional. -As an example, if you have 3,000 repositories and you want to run three separate indexing tasks, you might run: +The above examples will index all projects starting with ID `1001` up to (and including) ID `2000`. -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_repositories ID_TO=1000 -sudo gitlab-rake gitlab:elastic:index_repositories ID_FROM=1001 ID_TO=2000 -sudo gitlab-rake gitlab:elastic:index_repositories ID_FROM=2001 - -# Installations from source -bundle exec rake gitlab:elastic:index_repositories RAILS_ENV=production ID_TO=1000 -bundle exec rake gitlab:elastic:index_repositories RAILS_ENV=production ID_FROM=1001 ID_TO=2000 -bundle exec rake gitlab:elastic:index_repositories RAILS_ENV=production ID_FROM=2001 -``` - -Sometimes your repository index process `gitlab:elastic:index_repositories` or -`gitlab:elastic:index_repositories_async` can get interrupted. This may happen -for many reasons, but it's always safe to run the indexing job again - it will -skip those repositories that have already been indexed. +TIP: **Troubleshooting:** +Sometimes the project indexing jobs queued by `gitlab:elastic:index_projects` +can get interrupted. This may happen for many reasons, but it's always safe +to run the indexing task again - it will skip those repositories that have +already been indexed. As the indexer stores the last commit SHA of every indexed repository in the database, you can run the indexer with the special parameter `UPDATE_INDEX` and @@ -297,10 +265,10 @@ that repository is indexed, it can be useful in case if your index is outdated: ```sh # Omnibus installations -sudo gitlab-rake gitlab:elastic:index_repositories UPDATE_INDEX=true ID_TO=1000 +sudo gitlab-rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 # Installations from source -bundle exec rake gitlab:elastic:index_repositories UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production +bundle exec rake gitlab:elastic:index_projects UPDATE_INDEX=true ID_TO=1000 RAILS_ENV=production ``` You can also use the `gitlab:elastic:clear_index_status` Rake task to force the @@ -320,16 +288,6 @@ bundle exec rake gitlab:elastic:index_wikis RAILS_ENV=production The wiki indexer also supports the `ID_FROM` and `ID_TO` parameters if you want to limit a project set. -Index all database entities (Keep in mind it can take a while, so consider using `screen` or `tmux`): - -```sh -# Omnibus installations -sudo gitlab-rake gitlab:elastic:index_database - -# Installations from source -bundle exec rake gitlab:elastic:index_database RAILS_ENV=production -``` - Enable replication and refreshing again after indexing (only if you previously disabled it): ```bash @@ -376,25 +334,15 @@ There are several rake tasks available to you via the command line: - This is a wrapper task. It does the following: - `sudo gitlab-rake gitlab:elastic:create_empty_index` - `sudo gitlab-rake gitlab:elastic:clear_index_status` + - `sudo gitlab-rake gitlab:elastic:index_projects` - `sudo gitlab-rake gitlab:elastic:index_wikis` - - `sudo gitlab-rake gitlab:elastic:index_database` - - `sudo gitlab-rake gitlab:elastic:index_repositories` -- [sudo gitlab-rake gitlab:elastic:index_repositories_async](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This iterates over all projects and places them in batches. It then sends these batches to the background via sidekiq jobs to be indexed. -- [sudo gitlab-rake gitlab:elastic:index_repositories_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) + - `sudo gitlab-rake gitlab:elastic:index_snippets` +- [sudo gitlab-rake gitlab:elastic:index_projects](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) + - This iterates over all projects and queues sidekiq jobs to index them in the background. +- [sudo gitlab-rake gitlab:elastic:index_projects_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This determines the overall status of the indexing. It is done by counting the total number of indexed projects, dividing by a count of the total number of projects, then multiplying by 100. -- [sudo gitlab-rake gitlab:elastic:index_repositories](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This iterates over all projects and places them in batches. It then performs indexing on said batches synchronously. - [sudo gitlab-rake gitlab:elastic:index_wikis](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - Iterates over every project, determines if said project contains wiki data, and then indexes the blobs (content) of said wiki data. -- [sudo gitlab-rake gitlab:elastic:index_database](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - This is a [rake multitask](https://www.rubydoc.info/github/ruby/rake/Rake/MultiTask). It does the following: - - `sudo gitlab-rake gitlab:elastic:index_projects` - - `sudo gitlab-rake gitlab:elastic:index_issues` - - `sudo gitlab-rake gitlab:elastic:index_merge_requests` - - `sudo gitlab-rake gitlab:elastic:index_snippets` - - `sudo gitlab-rake gitlab:elastic:index_notes` - - `sudo gitlab-rake gitlab:elastic:index_milestones` - [sudo gitlab-rake gitlab:elastic:create_empty_index](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - This generates an empty index on the Elasticsearch side. - [sudo gitlab-rake gitlab:elastic:clear_index_status](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) @@ -405,18 +353,8 @@ There are several rake tasks available to you via the command line: - Does the same thing as `sudo gitlab-rake gitlab:elastic:create_empty_index` - [sudo gitlab-rake gitlab:elastic:add_feature_visibility_levels_to_project](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - Adds visibility information to the indices for projects. -- [sudo gitlab-rake gitlab:elastic:index_projects](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Performs an Elasticsearch import that indexes projects data. -- [sudo gitlab-rake gitlab:elastic:index_issues](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Performs an Elasticsearch import that indexes issues data. -- [sudo gitlab-rake gitlab:elastic:index_merge_requests](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Performs an Elasticsearch import that indexes merge requests data. - [sudo gitlab-rake gitlab:elastic:index_snippets](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - Performs an Elasticsearch import that indexes the snippets data. -- [sudo gitlab-rake gitlab:elastic:index_notes](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Performs an Elasticsearch import that indexes the notes data. -- [sudo gitlab-rake gitlab:elastic:index_milestones](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/ee/lib/tasks/gitlab/elastic.rake) - - Performs an Elasticsearch import that indexes the milestones data. ### Environment Variables @@ -424,40 +362,16 @@ In addition to the rake tasks, there are some environment variables that can be | Environment Variable | Data Type | What it does | | -------------------- |:---------:| ---------------------------------------------------------------------------- | -| `BATCH` | Integer | Modifies the size of the indexing batch (default 300 projects). | | `UPDATE_INDEX` | Boolean | Tells the indexer to overwrite any existing index data (true/false). | | `ID_TO` | Integer | Tells the indexer to only index projects less than or equal to the value. | | `ID_FROM` | Integer | Tells the indexer to only index projects greater than or equal to the value. | -### Batching - -The ability to apply batching makes the indexer run more efficiently. The default -size of a batch is 300 projects, which may or may not be ideal for your setup. -Depending on the resources available to your GitLab instance (sidekiq) and your -Elasticsearch instance (RAM, CPU), you may be able to increase or decrease the -batch size for more efficiency. - -- The larger the batch size is, the less sidekiq jobs and indexing requests get created. -- The larger the batch size is, the more time and RAM it takes to process. -- The smaller the batch size, the more sidekiq jobs, and indexing requests get created. -- The smaller the batch size, the more CPU gets utilized. - -Finding the ideal size can be tricky, and will vary from GitLab instance to GitLab instance. -Generally speaking, if the default is not ideal for you, try reducing it to somewhere in -the 50-150 range (for bigger sized repos) or 450-600 range (for many small-sized repos). - -Example use: - -```sh -sudo gitlab-rake gitlab:elastic:index_repositories_async BATCH=50 -``` - ### Indexing a specific project Because the `ID_TO` and `ID_FROM` environment variables use the `or equal to` comparison, you can index only one project by using both these variables with the same project ID number: ```sh -root@git:~# sudo gitlab-rake gitlab:elastic:index_repositories ID_TO=5 ID_FROM=5 +root@git:~# sudo gitlab-rake gitlab:elastic:index_projects ID_TO=5 ID_FROM=5 Indexing project repositories...I, [2019-03-04T21:27:03.083410 #3384] INFO -- : Indexing GitLab User / test (ID=33)... I, [2019-03-04T21:27:05.215266 #3384] INFO -- : Indexing GitLab User / test (ID=33) is done! ``` @@ -554,7 +468,7 @@ Here are some common pitfalls and how to overcome them: - **The indexing process is taking a very long time** - The more data present in your GitLab instance, the longer the indexing process takes. You might want to try adjusting the BATCH sizes for asynchronous indexing to help speed up the process. + The more data present in your GitLab instance, the longer the indexing process takes. - **No new data is added to the Elasticsearch index when I push code** diff --git a/doc/integration/github.md b/doc/integration/github.md index e145afbdd5e..5b01dd9feb7 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -21,10 +21,10 @@ To get the credentials (a pair of Client ID and Client Secret), you must registe - Application name: This can be anything. Consider something like `<Organization>'s GitLab` or `<Your Name>'s GitLab` or something else descriptive. - Homepage URL: The URL of your GitLab installation. For example, `https://gitlab.example.com`. - Application description: Fill this in if you wish. - - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth/github/callback`. Please make sure the port is included if your GitLab instance is not configured on default port. + - Authorization callback URL: `http(s)://${YOUR_DOMAIN}/users/auth`. Please make sure the port is included if your GitLab instance is not configured on default port.  - NOTE: Be sure to append `/users/auth/github/callback` to the end of the callback URL + NOTE: Be sure to append `/users/auth` to the end of the callback URL to prevent a [OAuth2 convert redirect](http://tetraph.com/covert_redirect/) vulnerability. diff --git a/doc/security/README.md b/doc/security/README.md index a90127e0356..c48d5bc2065 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -1,5 +1,6 @@ --- comments: false +type: index --- # Security diff --git a/doc/security/crime_vulnerability.md b/doc/security/crime_vulnerability.md index d61a205d954..9665cc0337f 100644 --- a/doc/security/crime_vulnerability.md +++ b/doc/security/crime_vulnerability.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # How we manage the TLS protocol CRIME vulnerability > CRIME ("Compression Ratio Info-leak Made Easy") is a security exploit against @@ -7,15 +11,15 @@ authentication cookies, it allows an attacker to perform session hijacking on an authenticated web session, allowing the launching of further attacks. ([CRIME](https://en.wikipedia.org/w/index.php?title=CRIME&oldid=692423806)) -### Description +## Description -The TLS Protocol CRIME Vulnerability affects compression over HTTPS, therefore -it warns against using SSL Compression (for example gzip) or SPDY which -optionally uses compression as well. +The TLS Protocol CRIME Vulnerability affects systems that use data compression +over HTTPS. Your system might be vulnerable to the CRIME vulnerability if you use +SSL Compression (for example, gzip) or SPDY (which optionally uses compression). GitLab supports both gzip and [SPDY][ngx-spdy] and mitigates the CRIME -vulnerability by deactivating gzip when HTTPS is enabled. You can see the -sources of the files in question: +vulnerability by deactivating gzip when HTTPS is enabled. The sources of the +files are here: - [Source installation NGINX file][source-nginx] - [Omnibus installation NGINX file][omnibus-nginx] @@ -24,7 +28,7 @@ Although SPDY is enabled in Omnibus installations, CRIME relies on compression (the 'C') and the default compression level in NGINX's SPDY module is 0 (no compression). -### Nessus +## Nessus The Nessus scanner, [reports a possible CRIME vulnerability][nessus] in GitLab similar to the following format: @@ -45,12 +49,12 @@ SPDY support earlier than version 4 is advertised. ``` From the report above it is important to note that Nessus is only checking if -TLS advertises the SPDY protocol earlier than version 4, it does not perform an -attack nor does it check if compression is enabled. With just this approach, it +TLS advertises the SPDY protocol earlier than version 4. It does not perform an +attack nor does it check if compression is enabled. The Nessus scanner alone cannot tell that SPDY's compression is disabled and not subject to the CRIME vulnerability. -### References +## References - Nginx ["Module ngx_http_spdy_module"][ngx-spdy] - Tenable Network Security, Inc. ["Transport Layer Security (TLS) Protocol CRIME Vulnerability"][nessus] @@ -61,3 +65,15 @@ vulnerability. [ngx-spdy]: http://nginx.org/en/docs/http/ngx_http_spdy_module.html [nessus]: https://www.tenable.com/plugins/index.php?view=single&id=62565 [wiki-crime]: https://en.wikipedia.org/wiki/CRIME + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/information_exclusivity.md b/doc/security/information_exclusivity.md index 22756232025..62a20d3f257 100644 --- a/doc/security/information_exclusivity.md +++ b/doc/security/information_exclusivity.md @@ -1,9 +1,36 @@ +--- +type: concepts +--- # Information exclusivity -Git is a distributed version control system (DVCS). -This means that everyone that works with the source code has a local copy of the complete repository. -In GitLab every project member that is not a guest (so reporters, developers and maintainers) can clone the repository to get a local copy. -After obtaining this local copy the user can upload the full repository anywhere, including another project under their control or another server. -The consequence is that you can't build access controls that prevent the intentional sharing of source code by users that have access to the source code. -This is an inherent feature of a DVCS and all git management systems have this limitation. -Obviously you can take steps to prevent unintentional sharing and information destruction, this is why only some people are allowed to invite others and nobody can force push a protected branch. +Git is a distributed version control system (DVCS). This means that everyone +who works with the source code has a local copy of the complete repository. + +In GitLab every project member that is not a guest (reporters, developers, and +maintainers) can clone the repository to create a local copy. After obtaining +a local copy, the user can upload the full repository anywhere, including to +another project that is under their control, or onto another server. + +Therefore, it is impossible to build access controls that prevent the +intentional sharing of source code by users that have access to the source code. + +This is an inherent feature of a DVCS. All git management systems have this +limitation. + +You can take steps to prevent unintentional sharing and information +destruction. This limitation is the reason why only certain people are allowed +to [add users to a project](../user/project/members/index.md) +and why only a GitLab admin can [force push a protected +branch](../user/project/protected_branches.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index d21b26a43e8..d78293c75c6 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -1,11 +1,28 @@ +--- +type: reference, howto +--- # Custom password length limits -If you want to enforce longer user passwords you can create an extra Devise initializer with the steps below. +If you want to enforce longer user passwords you can create an extra Devise +initializer with the steps below. -If you do not use the `devise_password_length.rb` initializer the password length is set to a minimum of 8 characters in `config/initializers/devise.rb`. +If you do not use the `devise_password_length.rb` initializer the password +length is set to a minimum of 8 characters in `config/initializers/devise.rb`. ```bash cd /home/git/gitlab sudo -u git -H cp config/initializers/devise_password_length.rb.example config/initializers/devise_password_length.rb sudo -u git -H editor config/initializers/devise_password_length.rb # inspect and edit the new password length limits ``` + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/rack_attack.md b/doc/security/rack_attack.md index 66081d7e376..fa4b0d1fb09 100644 --- a/doc/security/rack_attack.md +++ b/doc/security/rack_attack.md @@ -1,24 +1,28 @@ +--- +type: reference, howto +--- # Rack Attack -Rack Attack, also known as Rack::Attack, is [a rubygem](https://github.com/kickstarter/rack-attack) +[Rack Attack](https://github.com/kickstarter/rack-attack), also known as Rack::Attack, is a Ruby gem that is meant to protect GitLab with the ability to customize throttling and -blocking user IPs. +to block user IP addresses. + You can prevent brute-force passwords attacks, scrapers, or any other offenders -by throttling requests from IP addresses making large volumes of requests. -In case you find throttling is not enough to protect you against abusive clients, -Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering and +by throttling requests from IP addresses that are making large volumes of requests. +If you find throttling is not enough to protect you against abusive clients, +Rack Attack offers IP whitelisting, blacklisting, Fail2ban style filtering, and tracking. **Note:** Starting with 11.2, Rack Attack is disabled by default. To continue -using this feature, please enable it by [configuring `gitlab.rb` as described in Settings](#settings). +using Rack Attack, please enable it by [configuring `gitlab.rb` as described in Settings](#settings). By default, user sign-in, user sign-up (if enabled), and user password reset is limited to 6 requests per minute. After trying for 6 times, the client will have to wait for the next minute to be able to try again. -If you installed or upgraded GitLab by following the [official guides](../install/README.md) -this should be disabled by default. If your instance is not exposed to any incoming -connections, it is recommended to leave Rack Attack disabled. +If you installed or upgraded GitLab by following the [official guides](../install/README.md), +Rack Attack should be disabled by default. If your instance is not exposed to any incoming +connections, it is recommended that you leave Rack Attack disabled. For more information on how to use these options check out [rack-attack README](https://github.com/kickstarter/rack-attack/blob/master/README.md). @@ -27,7 +31,7 @@ For more information on how to use these options check out **Omnibus GitLab** -1. Open `/etc/gitlab/gitlab.rb` with you editor +1. Open `/etc/gitlab/gitlab.rb` with your editor 1. Add the following: ```ruby @@ -53,7 +57,7 @@ The following settings can be configured: For example, `["127.0.0.1", "127.0.0.2", "127.0.0.3"]`. - `maxretry`: The maximum amount of times a request can be made in the specified time. -- `findtime`: The maximum amount of time failed requests can count against an IP +- `findtime`: The maximum amount of time that failed requests can count against an IP before it's blacklisted (in seconds). - `bantime`: The total amount of time that a blacklisted IP will be blocked (in seconds). diff --git a/doc/security/reset_root_password.md b/doc/security/reset_root_password.md index 6a882ed6fe5..a58d70f0ff2 100644 --- a/doc/security/reset_root_password.md +++ b/doc/security/reset_root_password.md @@ -1,8 +1,11 @@ +--- +type: howto +--- # How to reset your root password -Log into your server with root privileges. Then start a Ruby on Rails console. +To reset your root password, first log into your server with root privileges. -Start the console with this command: +Start a Ruby on Rails console with this command: ```bash gitlab-rails console production @@ -38,3 +41,15 @@ user.save! ``` Exit the console and try to login with your new password. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 6b6a8a06cc9..ae4cc44519e 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -1,3 +1,6 @@ +--- +type: reference, howto +--- # Restrict allowed SSH key technologies and minimum length `ssh-keygen` allows users to create RSA keys with as few as 768 bits, which @@ -25,3 +28,15 @@ An icon will be visible to the user of a restricted key in the SSH keys section  Hovering over this icon will tell you why the key is restricted. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index 2ece4ed3fc9..ad5daef805a 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -1,3 +1,6 @@ +--- +type: howto +--- # Enforce Two-factor Authentication (2FA) Two-factor Authentication (2FA) provides an additional level of security to your @@ -55,3 +58,15 @@ sudo -u git -H bundle exec rake gitlab:two_factor:disable_for_all_users RAILS_EN CAUTION: **Caution:** This is a permanent and irreversible action. Users will have to reactivate 2FA from scratch if they want to use it again. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/unlock_user.md b/doc/security/unlock_user.md index d5ecef7f605..75cf754e197 100644 --- a/doc/security/unlock_user.md +++ b/doc/security/unlock_user.md @@ -1,8 +1,12 @@ +--- +type: howto +--- # How to unlock a locked user -Log into your server with root privileges. Then start a Ruby on Rails console. +To unlock a locked user, first log into your server with root privileges. + +Start a Ruby on Rails console with this command: -Start the console with this command: ```bash gitlab-rails console production @@ -29,3 +33,15 @@ user.unlock_access! ``` Exit the console, the user should now be able to log in again. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 8c07e11dcb1..f0af0a7ac6a 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -1,7 +1,23 @@ +--- +type: howto +--- # User email confirmation at sign-up -GitLab admin can enable email confirmation on sign-up, if you want to confirm all -user emails before they are able to sign-in. +GitLab can be configured to require confirmation of a user's email address when +the user signs up. When this setting is enabled, the user is unable to sign in until +they confirm their email address. In the Admin area under **Settings** (`/admin/application_settings`), go to section -**Sign-up Restrictions** and look for **Send confirmation email on sign-up** option. +**Sign-up Restrictions** and look for the **Send confirmation email on sign-up** option. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/user_file_uploads.md b/doc/security/user_file_uploads.md index 98493d33b00..00a2607b607 100644 --- a/doc/security/user_file_uploads.md +++ b/doc/security/user_file_uploads.md @@ -1,11 +1,30 @@ +--- +type: reference +--- # User File Uploads -Images attached to issues, merge requests or comments do not require authentication -to be viewed if someone knows the direct URL. This direct URL contains a random -32-character ID that prevents unauthorized people from guessing the URL to an -image containing sensitive information. We don't enable authentication because -these images need to be visible in the body of notification emails, which are -often read from email clients that are not authenticated with GitLab, like -Outlook, Apple Mail, or the Mail app on your mobile device. +Images that are attached to issues, merge requests, or comments +do not require authentication to be viewed if they are accessed directly by URL. +This direct URL contains a random 32-character ID that prevents unauthorized +people from guessing the URL for an image, thus there is some protection if an +image contains sensitive information. -Note that non-image attachments do require authentication to be viewed. +Authentication is not enabled because images must be visible in the body of +notification emails, which are often read from email clients that are not +authenticated with GitLab, such as Outlook, Apple Mail, or the Mail app on your +mobile device. + +>**Note:** +Non-image attachments do require authentication to be viewed. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index 8c26bbac6a7..d4fa088cb15 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -1,20 +1,56 @@ +--- +type: concepts, reference, howto +--- # Webhooks and insecure internal web services -If you have non-GitLab web services running on your GitLab server or within its local network, these may be vulnerable to exploitation via Webhooks. +If you have non-GitLab web services running on your GitLab server or within its +local network, these may be vulnerable to exploitation via Webhooks. -With [Webhooks](../user/project/integrations/webhooks.md), you and your project maintainers and owners can set up URLs to be triggered when specific things happen to projects. Normally, these requests are sent to external web services specifically set up for this purpose, that process the request and its attached data in some appropriate way. +With [Webhooks](../user/project/integrations/webhooks.md), you and your project +maintainers and owners can set up URLs to be triggered when specific changes +occur in your projects. Normally, these requests are sent to external web services +specifically set up for this purpose, that process the request and its attached +data in some appropriate way. -Things get hairy, however, when a Webhook is set up with a URL that doesn't point to an external, but to an internal service, that may do something completely unintended when the webhook is triggered and the POST request is sent. +Things get hairy, however, when a Webhook is set up with a URL that doesn't +point to an external, but to an internal service, that may do something +completely unintended when the webhook is triggered and the POST request is +sent. -Because Webhook requests are made by the GitLab server itself, these have complete access to everything running on the server (`http://localhost:123`) or within the server's local network (`http://192.168.1.12:345`), even if these services are otherwise protected and inaccessible from the outside world. +Because Webhook requests are made by the GitLab server itself, these have +complete access to everything running on the server (`http://localhost:123`) or +within the server's local network (`http://192.168.1.12:345`), even if these +services are otherwise protected and inaccessible from the outside world. -If a web service does not require authentication, Webhooks can be used to trigger destructive commands by getting the GitLab server to make POST requests to endpoints like `http://localhost:123/some-resource/delete`. +If a web service does not require authentication, Webhooks can be used to +trigger destructive commands by getting the GitLab server to make POST requests +to endpoints like `http://localhost:123/some-resource/delete`. -To prevent this type of exploitation from happening, starting with GitLab 10.6, all Webhook requests to the current GitLab instance server address and/or in a private network will be forbidden by default. That means that all requests made to 127.0.0.1, ::1 and 0.0.0.0, as well as IPv4 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 and IPv6 site-local (ffc0::/10) addresses won't be allowed. +To prevent this type of exploitation from happening, starting with GitLab 10.6, +all Webhook requests to the current GitLab instance server address and/or in a +private network will be forbidden by default. That means that all requests made +to 127.0.0.1, ::1 and 0.0.0.0, as well as IPv4 10.0.0.0/8, 172.16.0.0/12, +192.168.0.0/16 and IPv6 site-local (ffc0::/10) addresses won't be allowed. -This behavior can be overridden by enabling the option *"Allow requests to the local network from hooks and services"* in the *"Outbound requests"* section inside the Admin area under **Settings** (`/admin/application_settings/network`): +This behavior can be overridden by enabling the option *"Allow requests to the +local network from hooks and services"* in the *"Outbound requests"* section +inside the Admin area under **Settings** +(`/admin/application_settings/network`):  >**Note:** -*System hooks* are exempt from this protection because they are set up by admins. +*System hooks* are exempt from this protection because they are set up by +admins. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/topics/git/how_to_install_git/index.md b/doc/topics/git/how_to_install_git/index.md index d7e1979217e..c7bede2d269 100644 --- a/doc/topics/git/how_to_install_git/index.md +++ b/doc/topics/git/how_to_install_git/index.md @@ -5,14 +5,20 @@ level: beginner article_type: user guide date: 2017-05-15 description: 'This article describes how to install Git on macOS, Ubuntu Linux and Windows.' +type: howto +last_updated: 2019-05-31 --- # Installing Git -To begin contributing to GitLab projects +To begin contributing to GitLab projects, you will need to install the Git client on your computer. + This article will show you how to install Git on macOS, Ubuntu Linux and Windows. +Information on [installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) +is also available at the official Git website. + ## Install Git on macOS using the Homebrew package manager Although it is easy to use the version of Git shipped with macOS @@ -21,7 +27,7 @@ we recommend installing it via Homebrew to get access to an extensive selection of dependency managed libraries and applications. If you are sure you don't need access to any additional development libraries -or don't have approximately 15gb of available disk space for Xcode and Homebrew +or don't have approximately 15gb of available disk space for Xcode and Homebrew, use one of the aforementioned methods. ### Installing Xcode @@ -40,11 +46,12 @@ for the official Homebrew installation instructions. With Homebrew installed you are now ready to install Git. Open a Terminal and enter in the following command: -```bash +```sh brew install git ``` Congratulations you should now have Git installed via Homebrew. + Next read our article on [adding an SSH key to GitLab](../../../ssh/README.md). ## Install Git on Ubuntu Linux @@ -55,16 +62,30 @@ it is recommended to use the built in package manager to install Git. Open a Terminal and enter in the following commands to install the latest Git from the official Git maintained package archives: -```bash +```sh sudo apt-add-repository ppa:git-core/ppa sudo apt-get update sudo apt-get install git ``` Congratulations you should now have Git installed via the Ubuntu package manager. + Next read our article on [adding an SSH key to GitLab](../../../ssh/README.md). ## Installing Git on Windows from the Git website Browse to the [Git website](https://git-scm.com/) and download and install Git for Windows. + Next read our article on [adding an SSH key to GitLab](../../../ssh/README.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md index db6d1a62f59..cdcd8215b23 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -1,8 +1,12 @@ -# Git documentation +--- +type: index +--- + +# Git Git is a [free and open source](https://git-scm.com/about/free-and-open-source) distributed version control system designed to handle everything from small to -very large projects with speed and efficiency. +large projects with speed and efficiency. [GitLab](https://about.gitlab.com) is a Git-based fully integrated platform for software development. Besides Git's functionalities, GitLab has a lot of @@ -11,64 +15,73 @@ powerful [features](https://about.gitlab.com/features/) to enhance your We've gathered some resources to help you to get the best from Git with GitLab. +More information is also available on the [Git website](https://git-scm.com). + ## Getting started -- [Git concepts](../../university/training/user_training.md#git-concepts) +The following resources will help you get started with Git: + +- [Git-ing started with Git](https://www.youtube.com/watch?v=Ce5nz5n41z4), + a video introduction to Git. +- [Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics) +- [Git on the Server - GitLab](https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab) - [How to install Git](how_to_install_git/index.md) - [Start using Git on the command line](../../gitlab-basics/start-using-git.md) - [Command Line basic commands](../../gitlab-basics/command-line-commands.md) - [GitLab Git Cheat Sheet (download)](https://about.gitlab.com/images/press/git-cheat-sheet.pdf) -- Commits - - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) +- Commits: + - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) - [Squashing commits](../../workflow/gitlab_flow.md#squashing-commits-with-rebase) -**Third-party references:** +### Concepts -- [Getting Started - Git website](https://git-scm.com) -- [Getting Started - Version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) -- [Getting Started - Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics) -- [Getting Started - Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -- [Git on the Server - GitLab](https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab) +The following are resources about version control concepts: -### Concepts +- [Git concepts](../../university/training/user_training.md#git-concepts) +- [Why Git is Worth the Learning Curve](https://about.gitlab.com/2017/05/17/learning-curve-is-the-biggest-challenge-developers-face-with-git/) +- [The future of SaaS hosted Git repository pricing](https://about.gitlab.com/2016/05/11/git-repository-pricing/) +- [Git website topic about version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) +- [GitLab University presentation about Version Control](https://docs.google.com/presentation/d/16sX7hUrCZyOFbpvnrAFrg6tVO5_yT98IgdAqOmXwBho/edit?usp=sharing) -- Article (2017-05-17): [Why Git is Worth the Learning Curve](https://about.gitlab.com/2017/05/17/learning-curve-is-the-biggest-challenge-developers-face-with-git/) -- Article (2016-05-11): [The future of SaaS hosted Git repository pricing](https://about.gitlab.com/2016/05/11/git-repository-pricing/) -- GLU Course (Presentation): [About Version Control](https://docs.google.com/presentation/d/16sX7hUrCZyOFbpvnrAFrg6tVO5_yT98IgdAqOmXwBho/edit?usp=sharing) +## Git tips -## Exploring Git +The following resources may help you become more efficient at using Git: - [Git Tips & Tricks](https://about.gitlab.com/2016/12/08/git-tips-and-tricks/) - [Eight Tips to help you work better with Git](https://about.gitlab.com/2015/02/19/8-tips-to-help-you-work-better-with-git/) ## Troubleshooting Git +If you have problems with Git, the following may help: + - [Numerous _undo_ possibilities in Git](numerous_undo_possibilities_in_git/index.md) -- Learn a few [Git troubleshooting](troubleshooting_git.md) techniques to help you out. +- Learn a few [Git troubleshooting](troubleshooting_git.md) techniques ## Branching strategies -- [GitLab Flow](https://about.gitlab.com/2014/09/29/gitlab-flow/) - -**Third-party references:** - - [Git Branching - Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) - [Git Branching - Branching Workflows](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows) +- [GitLab Flow](https://about.gitlab.com/2014/09/29/gitlab-flow/) ## Advanced use +The following are advanced topics for those who want to get the most out of Git: + - [Custom Git Hooks](../../administration/custom_hooks.md) - [Git Attributes](../../user/project/git_attributes.md) - Git Submodules: [Using Git submodules with GitLab CI](../../ci/git_submodules.md#using-git-submodules-with-gitlab-ci) ## API -- [Gitignore templates](../../api/templates/gitignores.md) +[Gitignore templates](../../api/templates/gitignores.md) API allow for +Git-related queries from GitLab. ## Git LFS +The following relate to Git Large File Storage: + - [Getting Started with Git LFS](https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/) - [GitLab Git LFS documentation](../../workflow/lfs/manage_large_binaries_with_git_lfs.md) - [Git-Annex to Git-LFS migration guide](../../workflow/lfs/migrate_from_git_annex_to_git_lfs.md) -- Article (2015-08-13): [Towards a production quality open source Git LFS server](https://about.gitlab.com/2015/08/13/towards-a-production-quality-open-source-git-lfs-server/) +- [Towards a production quality open source Git LFS server](https://about.gitlab.com/2015/08/13/towards-a-production-quality-open-source-git-lfs-server/) diff --git a/doc/topics/git/numerous_undo_possibilities_in_git/index.md b/doc/topics/git/numerous_undo_possibilities_in_git/index.md index 8a8021dc36d..84201e11831 100644 --- a/doc/topics/git/numerous_undo_possibilities_in_git/index.md +++ b/doc/topics/git/numerous_undo_possibilities_in_git/index.md @@ -4,25 +4,30 @@ author_gitlab: Letme level: intermediary article_type: tutorial date: 2017-05-15 +type: howto +last_updated: 2019-05-31 --- # Numerous undo possibilities in Git -## Introduction - In this tutorial, we will show you different ways of undoing your work in Git, for which we will assume you have a basic working knowledge of. Check GitLab's -[Git documentation](../index.md#git-documentation) for reference. +[Git documentation](../index.md) for reference. + Also, we will only provide some general info of the commands, which is enough -to get you started for the easy cases/examples, but for anything more advanced please refer to the [Git book](https://git-scm.com/book/en/v2). +to get you started for the easy cases/examples, but for anything more advanced +please refer to the [Git book](https://git-scm.com/book/en/v2). We will explain a few different techniques to undo your changes based on the stage of the change in your current development. Also, keep in mind that [nothing in -Git is really deleted.][git-autoclean-ref] +Git is really deleted][git-autoclean-ref]. + This means that until Git automatically cleans detached commits (which cannot be accessed by branch or tag) it will be possible to view them with `git reflog` command and access them with direct commit-id. Read more about _[redoing the undo](#redoing-the-undo)_ on the section below. +## Introduction + This guide is organized depending on the [stage of development][git-basics] where you want to undo your changes from and if they were shared with other developers or not. Because Git is tracking changes a created or edited file is in the unstaged state @@ -31,35 +36,41 @@ a file into the **staged** state, which is then committed (`git commit`) to your local repository. After that, file can be shared with other developers (`git push`). Here's what we'll cover in this tutorial: - - [Undo local changes](#undo-local-changes) which were not pushed to remote repository +- [Undo local changes](#undo-local-changes) which were not pushed to remote repository: - - Before you commit, in both unstaged and staged state - - After you committed + - Before you commit, in both unstaged and staged state. + - After you committed. - - Undo changes after they are pushed to remote repository +- Undo changes after they are pushed to remote repository: - - [Without history modification](#undo-remote-changes-without-changing-history) (preferred way) - - [With history modification](#undo-remote-changes-with-modifying-history) (requires - coordination with team and force pushes). - - [Usecases when modifying history is generally acceptable](#where-modifying-history-is-generally-acceptable) - - [How to modify history](#how-modifying-history-is-done) - - [How to remove sensitive information from repository](#deleting-sensitive-information-from-commits) + - [Without history modification](#undo-remote-changes-without-changing-history) (preferred way). + - [With history modification](#undo-remote-changes-with-modifying-history) (requires + coordination with team and force pushes). + - [Use cases when modifying history is generally acceptable](#where-modifying-history-is-generally-acceptable). + - [How to modify history](#how-modifying-history-is-done). + - [How to remove sensitive information from repository](#deleting-sensitive-information-from-commits). ### Branching strategy [Git][git-official] is a de-centralized version control system, which means that beside regular versioning of the whole repository, it has possibilities to exchange changes -with other repositories. To avoid chaos with +with other repositories. + +To avoid chaos with [multiple sources of truth][git-distributed], various development workflows have to be followed, and it depends on your internal workflow how certain changes or commits can be undone or changed. + [GitLab Flow][gitlab-flow] provides a good balance between developers clashing with each other while developing the same feature and cooperating seamlessly, but it does not enable joined development of the same feature by multiple developers by default. + When multiple developers develop the same feature on the same branch, clashing with every synchronization is unavoidable, but a proper or chosen Git Workflow will -prevent that anything is lost or out of sync when feature is complete. You can also +prevent that anything is lost or out of sync when feature is complete. + +You can also read through this blog post on [Git Tips & Tricks][gitlab-git-tips-n-tricks] to learn how to easily **do** things in Git. @@ -97,19 +108,19 @@ no changes added to commit (use "git add" and/or "git commit -a") At this point there are 3 options to undo the local changes you have: -- Discard all local changes, but save them for possible re-use [later](#quickly-save-local-changes) +- Discard all local changes, but save them for possible re-use [later](#quickly-save-local-changes): ```shell git stash ``` -- Discarding local changes (permanently) to a file +- Discarding local changes (permanently) to a file: ```shell git checkout -- <file> ``` -- Discard all local changes to all files permanently +- Discard all local changes to all files permanently: ```shell git reset --hard @@ -150,7 +161,7 @@ of the staging tree. You also have an option to discard all changes with Lets start the example by editing a file, with your favorite editor, to change the content and add it to staging -``` +```sh vim <file> git add <file> ``` @@ -164,30 +175,30 @@ Your branch is up-to-date with 'origin/master'. Changes to be committed: (use "git reset HEAD <file>..." to unstage) - new file: <file> + new file: <file> ``` Now you have 4 options to undo your changes: -- Unstage the file to current commit (HEAD) +- Unstage the file to current commit (HEAD): ```shell git reset HEAD <file> ``` -- Unstage everything - retain changes +- Unstage everything - retain changes: ```shell git reset ``` -- Discard all local changes, but save them for [later](#quickly-save-local-changes) +- Discard all local changes, but save them for [later](#quickly-save-local-changes): ```shell git stash ``` -- Discard everything permanently +- Discard everything permanently: ```shell git reset --hard @@ -206,7 +217,9 @@ your code, you'll have less options to troubleshoot your work. Through the development process some of the previously committed changes do not fit anymore in the end solution, or are source of the bugs. Once you find the commit which triggered bug, or once you have a faulty commit, you can simply -revert it with `git revert commit-id`. This command inverts (swaps) the additions and +revert it with `git revert commit-id`. + +This command inverts (swaps) the additions and deletions in that commit, so that it does not modify history. Retaining history can be helpful in future to notice that some changes have been tried unsuccessfully in the past. @@ -225,19 +238,19 @@ through simple bisection process. You can read more about it [in official Git To In our example we will end up with commit `B`, that introduced bug/error. We have 4 options on how to remove it (or part of it) from our repository. -- Undo (swap additions and deletions) changes introduced by commit `B`. +- Undo (swap additions and deletions) changes introduced by commit `B`: ```shell git revert commit-B-id ``` -- Undo changes on a single file or directory from commit `B`, but retain them in the staged state +- Undo changes on a single file or directory from commit `B`, but retain them in the staged state: ```shell git checkout commit-B-id <file> ``` -- Undo changes on a single file or directory from commit `B`, but retain them in the unstaged state +- Undo changes on a single file or directory from commit `B`, but retain them in the unstaged state: ```shell git reset commit-B-id <file> @@ -246,7 +259,9 @@ In our example we will end up with commit `B`, that introduced bug/error. We hav - There is one command we also must not forget: **creating a new branch** from the point where changes are not applicable or where the development has hit a dead end. For example you have done commits `A-B-C-D` on your feature-branch - and then you figure `C` and `D` are wrong. At this point you either reset to `B` + and then you figure `C` and `D` are wrong. + + At this point you either reset to `B` and do commit `F` (which will cause problems with pushing and if forced pushed also with other developers) since branch now looks `A-B-F`, which clashes with what other developers have locally (you will [change history](#with-history-modification)), or you simply checkout commit `B` create @@ -269,13 +284,13 @@ In our example we will end up with commit `B`, that introduced bug/error. We hav There is one command for history modification and that is `git rebase`. Command provides interactive mode (`-i` flag) which enables you to: - - **reword** commit messages (there is also `git commit --amend` for editing - last commit message) - - **edit** the commit content (changes introduced by commit) and message - - **squash** multiple commits into a single one, and have a custom or aggregated - commit message - - **drop** commits - simply delete them - - and few more options +- **reword** commit messages (there is also `git commit --amend` for editing + last commit message). +- **edit** the commit content (changes introduced by commit) and message. +- **squash** multiple commits into a single one, and have a custom or aggregated + commit message. +- **drop** commits - simply delete them. +- and few more options. Let us check few examples. Again there are commits `A-B-C-D` where you want to delete commit `B`. @@ -301,7 +316,7 @@ In case you want to modify something introduced in commit `B`. - Command opens your favorite text editor where you write `edit` in front of commit `B`, but leave default `pick` with all other commits. Save and exit the editor to - perform a rebase + perform a rebase. - Now do your edits and commit changes: @@ -348,7 +363,9 @@ and then on end description of that action. This topic is roughly same as modifying committed local changes without modifying history. **It should be the preferred way of undoing changes on any remote repository or public branch.** Keep in mind that branching is the best solution when you want -to retain the history of faulty development, yet start anew from certain point. Branching +to retain the history of faulty development, yet start anew from certain point. + +Branching enables you to include the existing changes in new development (by merging) and it also provides a clear timeline and development structure. @@ -386,12 +403,14 @@ the cleanup of detached commits (happens automatically). Modified history breaks the development chain of other developers, as changed history does not have matching commits'ids. For that reason it should not be used on any public branch or on branch that *might* be used by other -developers. When contributing to big open source repositories (e.g. [GitLab CE][gitlab-ce]), +developers. When contributing to big open source repositories (for example, [GitLab CE][gitlab-ce]), it is acceptable to *squash* commits into a single one, to present a nicer history of your contribution. + Keep in mind that this also removes the comments attached to certain commits in merge requests, so if you need to retain traceability in GitLab, then modifying history is not acceptable. + A feature-branch of a merge request is a public branch and might be used by other developers, but project process and rules might allow or require you to use `git rebase` (command that changes history) to reduce number of @@ -400,8 +419,8 @@ GitLab). There is a `git merge --squash` command which does exactly that (squashes commits on feature-branch to a single commit on target branch at merge). ->**Note:** -Never modify the commit history of `master` or shared branch +NOTE: **Note:** +Never modify the commit history of `master` or shared branch. ### How modifying history is done @@ -436,7 +455,7 @@ pick <commit3-id> <commit3-commit-message> # Note that empty commits are commented out ``` ->**Note:** +NOTE: **Note:** It is important to notice that comment from the output clearly states that, if you decide to abort, then do not just close your editor (as that will in-fact modify history), but remove all uncommented lines and save. @@ -470,7 +489,7 @@ tools that can use some of Git specifics to enable faster execution of common tasks (which is exactly what removing sensitive information file is about). An alternative is [BFG Repo-cleaner][bfg-repo-cleaner]. Keep in mind that these tools are faster because they do not provide a same fully feature set as `git filter-branch` -does, but focus on specific usecases. +does, but focus on specific use cases. ## Conclusion @@ -480,6 +499,18 @@ depending on the stage of your process. Git also enables rewriting history, but should be avoided as it might cause problems when multiple developers are contributing to the same codebase. +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> + <!-- Identifiers, in alphabetical order --> [bfg-repo-cleaner]: https://rtyley.github.io/bfg-repo-cleaner/ diff --git a/doc/topics/git/troubleshooting_git.md b/doc/topics/git/troubleshooting_git.md index 71651fcf421..417d91bf834 100644 --- a/doc/topics/git/troubleshooting_git.md +++ b/doc/topics/git/troubleshooting_git.md @@ -1,3 +1,7 @@ +--- +type: howto +--- + # Troubleshooting Git Sometimes things don't work the way they should or as you might expect when @@ -9,7 +13,7 @@ with Git. 'Broken pipe' errors can occur when attempting to push to a remote repository. When pushing you will usually see: -``` +```text Write failed: Broken pipe fatal: The remote end hung up unexpectedly ``` @@ -39,14 +43,15 @@ There's another option where you can prevent session timeouts by configuring SSH 'keep alive' either on the client or on the server (if you are a GitLab admin and have access to the server). -NOTE: **Note:** configuring *both* the client and the server is unnecessary. +NOTE: **Note:** +Configuring *both* the client and the server is unnecessary. **To configure SSH on the client side**: -- On UNIX, edit `~/.ssh/config` (create the file if it doesn’t exist) and - add or edit: +- On UNIX, edit `~/.ssh/config` (create the file if it doesn’t exist) and + add or edit: - ``` + ```text Host your-gitlab-instance-url.com ServerAliveInterval 60 ServerAliveCountMax 5 @@ -58,7 +63,7 @@ NOTE: **Note:** configuring *both* the client and the server is unnecessary. **To configure SSH on the server side**, edit `/etc/ssh/sshd_config` and add: -``` +```text ClientAliveInterval 60 ClientAliveCountMax 5 ``` @@ -83,35 +88,35 @@ to >= 2.9 (see [Broken pipe when pushing to Git repository][Broken-Pipe]). Users may experience the following error when attempting to push or pull using Git over SSH: -``` -Please make sure you have the correct access rights -and the repository exists. +```text +Please make sure you have the correct access rights +and the repository exists. ... -ssh_exchange_identification: read: Connection reset by peer -fatal: Could not read from remote repository. +ssh_exchange_identification: read: Connection reset by peer +fatal: Could not read from remote repository. ``` This error usually indicates that SSH daemon's `MaxStartups` value is throttling -SSH connections. This setting specifies the maximum number of unauthenticated +SSH connections. This setting specifies the maximum number of unauthenticated connections to the SSH daemon. This affects users with proper authentication credentials (SSH keys) because every connection is 'unauthenticated' in the -beginning. The default value is `10`. +beginning. The default value is `10`. Increase `MaxStartups` by adding or modifying the value in `/etc/ssh/sshd_config`: -``` +```text MaxStartups 100 ``` -Restart SSHD for the change to take effect. +Restart SSHD for the change to take effect. ## Timeout during git push/pull If pulling/pushing from/to your repository ends up taking more than 50 seconds, -a timeout will be issued with a log of the number of operations performed +a timeout will be issued with a log of the number of operations performed and their respective timings, like the example below: -``` +```text remote: Running checks for branch: master remote: Scanning for LFS objects... (153ms) remote: Calculating new repository size... (cancelled after 729ms) diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 82a86f3f343..f82d666c7be 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -114,7 +114,47 @@ sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ rm go1.10.5.linux-amd64.tar.gz ``` -### 6. Get latest code +### 6. Update git + +NOTE: **Note:** +GitLab 11.11 and higher only supports Git 2.21.x and newer, and +[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-ce/issues/54255). +Be sure to upgrade your installation if necessary. + +```bash +# Make sure Git is version 2.21.0 or higher +git --version + +# Remove packaged Git +sudo apt-get remove git-core + +# Install dependencies +sudo apt-get install -y libcurl4-openssl-dev libexpat1-dev gettext libz-dev libssl-dev build-essential + +# Download and compile pcre2 from source +curl --silent --show-error --location https://ftp.pcre.org/pub/pcre/pcre2-10.33.tar.gz --output pcre2.tar.gz +tar -xzf pcre2.tar.gz +cd pcre2-10.33 +chmod +x configure +./configure --prefix=/usr --enable-jit +make +make install + +# Download and compile from source +cd /tmp +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 --with-libpcre +make prefix=/usr/local all + +# Install into /usr/local/bin +sudo make prefix=/usr/local install + +# You should edit config/gitlab.yml, change the git -> bin_path to /usr/local/bin/git +``` + +### 7. Get latest code ```bash cd /home/git/gitlab @@ -142,7 +182,7 @@ cd /home/git/gitlab sudo -u git -H git checkout BRANCH-ee ``` -### 7. Update gitlab-shell +### 8. Update gitlab-shell ```bash cd /home/git/gitlab-shell @@ -152,7 +192,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) sudo -u git -H bin/compile ``` -### 8. Update gitlab-workhorse +### 9. Update gitlab-workhorse Install and compile gitlab-workhorse. GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). @@ -167,7 +207,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) sudo -u git -H make ``` -### 9. Update Gitaly +### 10. Update Gitaly #### Compile Gitaly @@ -178,7 +218,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) sudo -u git -H make ``` -### 10. Update gitlab-pages +### 11. Update gitlab-pages #### Only needed if you use GitLab Pages @@ -195,7 +235,7 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` -### 11. Update MySQL permissions +### 12. Update MySQL permissions If you are using MySQL you need to grant the GitLab user the necessary permissions on the database: @@ -217,7 +257,7 @@ You can make this setting permanent by adding it to your `my.cnf`: log_bin_trust_function_creators=1 ``` -### 12. Update configuration files +### 13. Update configuration files #### New configuration options for `gitlab.yml` @@ -291,7 +331,7 @@ For Ubuntu 16.04.1 LTS: sudo systemctl daemon-reload ``` -### 13. Install libs, migrations, etc. +### 14. Install libs, migrations, etc. ```bash cd /home/git/gitlab @@ -323,14 +363,14 @@ sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production **MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). -### 14. Start application +### 15. Start application ```bash sudo service gitlab start sudo service nginx restart ``` -### 15. Check application status +### 16. Check application status Check if GitLab and its environment are configured correctly: diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index ff056490653..f80d4e9d2aa 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -6,7 +6,7 @@ type: concepts, howto > - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1. > - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and was -> be deprecated in GitLab 9.1. +> deprecated in GitLab 9.1. > - [Access token](#access-token-deprecated) has been deprecated in GitLab 9.4 > in favor of [IP whitelist](#ip-whitelist). diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 1d355824760..001e4b6bf48 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -40,11 +40,9 @@ These settings can be found within: - **Admin Area > Settings > General**. - The path `/admin/application_settings`. -The very first push of a new project cannot be checked for size as of now, so -the first push will allow you to upload more than the limit dictates, but every -subsequent push will be denied. LFS objects, however, can be checked on first -push and **will** be rejected if the sum of their sizes exceeds the maximum -allowed repository size. +The first push of a new project, including LFS objects, will be checked for size +and **will** be rejected if the sum of their sizes exceeds the maximum allowed +repository size. For details on manually purging files, see [reducing the repository size using Git](../../project/repository/reducing_the_repo_size_using_git.md). diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 0e697b9e445..eed087ae52b 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -1,9 +1,13 @@ -# Admin area settings **[CORE ONLY]** +--- +type: index +--- -In the admin area settings, you can find various options for your GitLab +# Admin Area settings **[CORE ONLY]** + +In the Admin Area **Settings** page, you can find various options for your GitLab instance like sign-up restrictions, account limits and quota, metrics, etc. -Navigate to it by going to **Admin area > Settings**. Some of the settings +Navigate to it by going to **Admin Area > Settings**. Some of the settings include: - [Account and limit settings](account_and_limit_settings.md) **[STARTER]** @@ -22,7 +26,7 @@ in the **Localization** section of **Admin area > Settings > Preferences**. ## GitLab.com admin area settings -Most of the settings under the admin area change the behavior of the whole +Most of the settings under the Admin Area change the behavior of the whole GitLab instance. For GitLab.com, the admin settings are available only for the GitLab.com administrators, and the parameters can be found on the [GitLab.com settings](../../gitlab_com/index.md) documentation. diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 4d1b7d0f252..a1229484388 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -1,8 +1,25 @@ +--- +type: reference +--- + # Visibility and access controls +GitLab allows admins to: + +- Control access and visibility to GitLab resources including branches and projects. +- Select from which hosting sites code can be imported into GitLab. +- Select the protocols permitted to access GitLab. +- Enable or disable repository mirroring. + +To access the visibility and access control options: + +1. Log in to GitLab as an admin. +1. Go to **Admin Area > Settings > General**. +1. Expand the **Visibility and access controls** section. + ## Import sources -Choose from which hosting sites the users can +Choose from which hosting sites users can [import their projects](../../project/import/index.md).  @@ -11,12 +28,10 @@ Choose from which hosting sites the users can > [Introduced][ce-4696] in GitLab 8.10. -With GitLab's Access restrictions you can choose which Git access protocols you -want your users to use to communicate with GitLab. This feature can be enabled -via the `Application Settings` in the Admin interface. +With GitLab's access restrictions, you can select with which protocols users can communicate with +GitLab. -The setting is called `Enabled Git access protocols`, and it gives you the option -to choose between: +From the **Enabled Git access protocols** dropdown, select one of the following: - Both SSH and HTTP(S) - Only SSH @@ -24,10 +39,9 @@ to choose between:  -When both SSH and HTTP(S) are enabled, GitLab will behave as usual, it will give -your users the option to choose which protocol they would like to use. +When both SSH and HTTP(S) are enabled, your users can choose either protocol. -When you choose to allow only one of the protocols, a couple of things will happen: +When only one protocol is enabled: - The project page will only show the allowed protocol's URL, with no option to change it. @@ -54,10 +68,22 @@ application level. > [Introduced][ee-3586] in GitLab 10.3. This option is enabled by default. By disabling it, both pull and push mirroring will no longer -work in every repository and can only be re-enabled on a per-project basis by an admin. +work in every repository and can only be re-enabled by an admin on a per-project basis.  +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> + [ce-4696]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4696 [ce-18021]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18021 [ee-3586]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3586 diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index abc6e771b0f..028ff72a160 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -39,6 +39,8 @@ However, DAST can be [configured](#full-scan) to also perform a so-called "active scan". That is, attack your application and produce a more extensive security report. It can be very useful combined with [Review Apps](../../../ci/review_apps/index.md). +The [`dast`](https://gitlab.com/gitlab-org/security-products/dast/container_registry) Docker image in GitLab container registry is updated on a weekly basis to have all [`owasp2docker-weekly`](https://hub.docker.com/r/owasp/zap2docker-weekly/) updates in it. + ## Use cases It helps you automatically find security vulnerabilities in your running web diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 658d493ba39..d78cf778110 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -225,6 +225,17 @@ vulnerabilities in your groups and projects. Read more about the Once a vulnerability is found, you can interact with it. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +## Dependency List + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/10075) +in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.0. + +An additional benefit of Dependency Scanning is the ability to get a list of your project's dependencies with their versions. + +This list can be generated only for [supported languages and package managers](#supported-languages-and-package-managers). + +To see the generated dependency list, navigate to the Dependency List page under your project's left sidebar menu **Project > Dependency List**. + ## Contributing to the vulnerability database You can search the [gemnasium-db](https://gitlab.com/gitlab-org/security-products/gemnasium-db) project diff --git a/doc/user/application_security/img/dismissed_info.png b/doc/user/application_security/img/dismissed_info.png Binary files differnew file mode 100644 index 00000000000..64d5cf26ed2 --- /dev/null +++ b/doc/user/application_security/img/dismissed_info.png diff --git a/doc/user/application_security/img/interactive_reports.png b/doc/user/application_security/img/interactive_reports.png Binary files differindex 9f9812dc69d..373b39104db 100644 --- a/doc/user/application_security/img/interactive_reports.png +++ b/doc/user/application_security/img/interactive_reports.png diff --git a/doc/user/application_security/index.md b/doc/user/application_security/index.md index 64e72fab198..679847b76d7 100644 --- a/doc/user/application_security/index.md +++ b/doc/user/application_security/index.md @@ -47,6 +47,16 @@ You can dismiss vulnerabilities by clicking the **Dismiss vulnerability** button This will dismiss the vulnerability and re-render it to reflect its dismissed state. If you wish to undo this dismissal, you can click the **Undo dismiss** button. +#### Adding a dismissal reason + +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 12.0. + +When dismissing a vulnerability, it's often helpful to provide a reason for doing so. +If you press the comment button next to **Dismiss vulnerability** in the modal, a text box will appear, allowing you to add a comment with your dismissal. +This comment can not currently be edited or removed, but [future versions](https://gitlab.com/gitlab-org/gitlab-ee/issues/11721) will add this functionality. + + + ### Creating an issue for a vulnerability You can create an issue for a vulnerability by selecting the **Create issue** diff --git a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png Binary files differindex 3294e59e943..f0dad6c54d0 100644 --- a/doc/user/application_security/security_dashboard/img/project_security_dashboard.png +++ b/doc/user/application_security/security_dashboard/img/project_security_dashboard.png diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 97abe99fe62..b520c4fb579 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -140,8 +140,8 @@ that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/amit1rrr/rubix). More information on -creating executable runbooks can be found in [our Nurtch -documentation](../project/clusters/runbooks/index.md#nurtch-executable-runbooks). Note that +creating executable runbooks can be found in [our Runbooks +documentation](../project/clusters/runbooks/index.md#executable-runbooks). Note that Ingress must be installed and have an IP address assigned before JupyterHub can be installed. @@ -152,6 +152,33 @@ chart is used to install this application with a [`values.yaml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/vendor/jupyter/values.yaml) file. +#### Jupyter Git Integration + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28783) in GitLab 12 for project-level clusters. + +When installing JupyterHub onto your Kubernetes cluster, [JupyterLab's Git extension](https://github.com/jupyterlab/jupyterlab-git) +is automatically provisioned and configured using the authenticated user's: + +- Name +- Email +- Newly created access token + +JupyterLab's Git extension enables full version control of your notebooks as well as issuance of Git commands within Jupyter. +Git commands can be issued via the **Git** tab on the left panel or via Jupyter's command line prompt. + +NOTE: **Note:** +JupyterLab's Git extension stores the user token in the JupyterHub DB in encrypted format +and in the single user Jupyter instance as plain text. This is because [Git requires storing +credentials as plain text](https://git-scm.com/docs/git-credential-store). Potentially, if +a nefarious user finds a way to read from the file system in the single user Jupyter instance +they could retrieve the token. + + + +You can clone repositories from the files tab in Jupyter: + + + ### Knative > Available for project-level clusters since GitLab 11.5. diff --git a/doc/user/clusters/img/jupyter-git-extension.gif b/doc/user/clusters/img/jupyter-git-extension.gif Binary files differnew file mode 100644 index 00000000000..13a88d97425 --- /dev/null +++ b/doc/user/clusters/img/jupyter-git-extension.gif diff --git a/doc/user/clusters/img/jupyter-gitclone.png b/doc/user/clusters/img/jupyter-gitclone.png Binary files differnew file mode 100644 index 00000000000..41d467f806a --- /dev/null +++ b/doc/user/clusters/img/jupyter-gitclone.png diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index e0e89051be4..3c5e820c1ca 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -52,7 +52,7 @@ Add another cluster similar to the first one and make sure to [set an environment scope](#environment-scopes-premium) that will differentiate the new cluster from the rest. -## Gitlab-managed clusters +## GitLab-managed clusters > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5. > Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11. @@ -149,3 +149,15 @@ The following features are not currently available for group-level clusters: 1. Terminals (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55487)). 1. Pod logs (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55488)). 1. Deployment boards (see [related issue](https://gitlab.com/gitlab-org/gitlab-ce/issues/55489)). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/contribution_analytics/index.md b/doc/user/group/contribution_analytics/index.md index bc88eff9ed2..7e6cb24a51e 100644 --- a/doc/user/group/contribution_analytics/index.md +++ b/doc/user/group/contribution_analytics/index.md @@ -1,46 +1,58 @@ -# Contribution Analytics **[STARTER]** +--- +type: reference +--- ->**Note:** -Introduced in [GitLab Starter][ee] 8.3. +# Contribution Analytics **[STARTER]** -Track your team members' activity across your organization. +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.3. ## Overview -With Contribution Analytics you can get an overview of the activity of -issues, merge requests, and push events of your organization and its members. +With Contribution Analytics you can get an overview of the following activity in your +group: -The analytics page is located at **Group > Contribution Analytics** -under the URL `/groups/<groupname>/analytics`. +- Issues +- Merge requests +- Push events + +To view the Contribution Analytics, go to your group's **Overview > Contribution Analytics** +page. ## Use cases -- Analyze your team's contributions over a period of time and offer a bonus for the top contributors -- Identify opportunities for improvement with group members who may benefit from additional support +- Analyze your team's contributions over a period of time, and offer a bonus for the top +contributors. +- Identify opportunities for improvement with group members who may benefit from additional +support. ## Using Contribution Analytics -There are three main bar graphs that are deducted from the number of -contributions per group member. These contributions include push events, merge -requests and closed issues. Hovering on each bar you can see the number of -events for a specific member. +There are three main bar graphs that illustrate the number of contributions per group +member for the following: + +- Push events +- Merge requests +- Closed issues + +Hover over each bar to display the number of events for a specific group member.  ## Changing the period time -There are three periods you can choose from, 'Last week', 'Last month' and -'Last three months'. The default is 'Last week'. +You can choose from the following three periods: + +- Last week (default) +- Last month +- Last three months -You can choose which period to display by using the dropdown calendar menu in -the upper right corner. +Select the desired period from the calendar dropdown.  ## Sorting by different factors -Apart from the bar graphs you can also see the contributions per group member -which are depicted in a table that can be sorted by: +Contributions per group member are also presented in tabular format. Click a column header to sort the table by that column: * Member name * Number of pushed events @@ -52,4 +64,14 @@ which are depicted in a table that can be sorted by:  -[ee]: https://about.gitlab.com/pricing/ +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/custom_project_templates.md b/doc/user/group/custom_project_templates.md index f67325272a6..aa088d2fcdb 100644 --- a/doc/user/group/custom_project_templates.md +++ b/doc/user/group/custom_project_templates.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Custom group-level project templates **[PREMIUM]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6861) in [GitLab Premium](https://about.gitlab.com/pricing) 11.6. @@ -24,3 +28,15 @@ Projects of nested subgroups of a selected template source cannot be used. Repository and database information that are copied over to each new project are identical to the data exported with [GitLab's Project Import/Export](../project/settings/import_export.md). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 6035f0c7326..2e4106f55e5 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Epics **[ULTIMATE]** > Introduced in [GitLab Ultimate][ee] 10.2. @@ -215,3 +219,15 @@ Once you wrote your comment, you can either: ## Notifications - [Receive notifications](../../../workflow/notifications.md) for epic events. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/index.md b/doc/user/group/index.md index eb0c7bc998f..8335e532d0b 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -9,6 +9,8 @@ With GitLab Groups, you can: - Assemble related projects together. - Grant members access to several projects at once. +For a video introduction to GitLab Groups, see [GitLab University: Repositories, Projects and Groups](https://www.youtube.com/watch?v=4TWfh1aKHHw). + Groups can also be nested in [subgroups](subgroups/index.md). Find your groups by clicking **Groups > Your Groups** in the top navigation. diff --git a/doc/user/group/insights/index.md b/doc/user/group/insights/index.md index 83c284dce7a..a4ea71074ec 100644 --- a/doc/user/group/insights/index.md +++ b/doc/user/group/insights/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Insights **[ULTIMATE]** > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.9 behind the `insights` feature flag. @@ -44,3 +48,15 @@ access to the project they belong to, or because they are confidential) are filtered out of the Insights charts. You may also consult the [group permissions table](../../permissions.md#group-members-permissions). + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/issues_analytics/index.md b/doc/user/group/issues_analytics/index.md index cf53d7423a6..46d5c1e2e09 100644 --- a/doc/user/group/issues_analytics/index.md +++ b/doc/user/group/issues_analytics/index.md @@ -1,16 +1,43 @@ +--- +type: reference +--- + # Issues Analytics **[PREMIUM]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7478) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.5. -GitLab by default displays a bar chart of the number of issues created each month, for the -current month, and 12 months prior, for a total of 13 months. +Issues Analytics is a bar graph which illustrates the number of issues created each month. +The default timespan is 13 months, which includes the current month, and the 12 months +prior. -You can change the total number of months displayed by setting a URL parameter. -For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` -would show a total of 15 months for the chart in the GitLab.org group. +To access the chart, navigate to a group's sidebar and select **Issues > Analytics**. -The **Search or filter results...** field can be used for filtering the issues by any attribute. For example, labels, assignee, milestone, and author. +Hover over each bar to see the total number of issues. -To access the chart, navigate to a group's sidebar and select **Issues > Analytics**. +To narrow the scope of issues included in the graph, enter your criteria in the +**Search or filter results...** field. Criteria from the following list can be typed in or selected from a menu: + +- Author +- Assignee +- Milestone +- Label +- My reaction +- Weight + +You can change the total number of months displayed by setting a URL parameter. +For example, `https://gitlab.com/groups/gitlab-org/-/issues_analytics?months_back=15` +shows a total of 15 months for the chart in the GitLab.org group.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/roadmap/index.md b/doc/user/group/roadmap/index.md index 310c4bb88d0..683c715c8d5 100644 --- a/doc/user/group/roadmap/index.md +++ b/doc/user/group/roadmap/index.md @@ -1,3 +1,7 @@ +--- +type: reference +--- + # Roadmap **[ULTIMATE]** > Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 10.5. @@ -19,13 +23,20 @@ Epics in the view can be sorted by: - **Start date** - **Due date** -Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [epics list view](../epics/index.md). +Each option contains a button that toggles the sort order between **ascending** and **descending**. The sort option and order will be persisted when browsing Epics, +including the [epics list view](../epics/index.md). Roadmaps can also be [visualized inside an epic](../epics/index.md#roadmap-in-epics). ## Timeline duration -Starting with [GitLab Ultimate][ee] 11.0, Roadmap supports three different date ranges; Quarters, Months (Default) and Weeks. +> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing) 11.0. + +Roadmap supports the following date ranges: + +- Quarters +- Months (Default) +- Weeks ### Quarters @@ -62,3 +73,15 @@ and due date. If an epic doesn't have a due date, the timeline bar fades away towards the future. Similarly, if an epic doesn't have a start date, the timeline bar becomes more visible as it approaches the epic's due date on the timeline. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/saml_sso/index.md b/doc/user/group/saml_sso/index.md index 62a3ef52c34..fcfd638f185 100644 --- a/doc/user/group/saml_sso/index.md +++ b/doc/user/group/saml_sso/index.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # SAML SSO for GitLab.com Groups **[SILVER ONLY]** > Introduced in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.0. @@ -15,7 +19,7 @@ SAML SSO for GitLab.com groups does not sync users between providers without usi ## Configuring your Identity Provider 1. Navigate to the group and click **Settings > SAML SSO**. -1. Configure your SAML server using the **Assertion consumer service URL** and **Issuer**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [your identity provider's documentation](#providers) for more details. +1. Configure your SAML server using the **Assertion consumer service URL** and **Identifier**. Alternatively GitLab provides [metadata XML configuration](#metadata-configuration). See [your identity provider's documentation](#providers) for more details. 1. Configure the SAML response to include a NameID that uniquely identifies each user. 1. Configure required assertions using the [table below](#assertions). 1. Once the identity provider is set up, move on to [configuring GitLab](#configuring-gitlab). @@ -43,12 +47,12 @@ GitLab.com uses the SAML NameID to identify users. The NameID element: ### Assertions -| Field | Supported keys | Notes | -|-|----------------|-------------| -| Email | `email`, `mail` | (required) | -| Full Name | `name` | | -| First Name | `first_name`, `firstname`, `firstName` | | -| Last Name | `last_name`, `lastname`, `lastName` | | +| Field | Supported keys | +|-------|----------------| +| Email (required)| `email`, `mail` | +| Full Name | `name` | +| First Name | `first_name`, `firstname`, `firstName` | +| Last Name | `last_name`, `lastname`, `lastName` | ## Metadata configuration @@ -122,3 +126,15 @@ For example, to unlink the `MyOrg` account, the following **Disconnect** button | Assertion consumer service URL | The callback on GitLab where users will be redirected after successfully authenticating with the identity provider. | | Issuer | How GitLab identifies itself to the identity provider. Also known as a "Relying party trust identifier". | | Certificate fingerprint | Used to confirm that communications over SAML are secure by checking that the server is signing communications with the correct certificate. Also known as a certificate thumbprint. | + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/saml_sso/scim_setup.md b/doc/user/group/saml_sso/scim_setup.md index c00628bf909..96cc523f4ec 100644 --- a/doc/user/group/saml_sso/scim_setup.md +++ b/doc/user/group/saml_sso/scim_setup.md @@ -1,7 +1,15 @@ +--- +type: howto, reference +--- + # SCIM provisioning using SAML SSO for Groups **[SILVER ONLY]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/9388) in [GitLab.com Silver](https://about.gitlab.com/pricing/) 11.10. +System for Cross-domain Identity Management (SCIM), is an open standard that enables the +automation of user provisioning. When SCIM is provisioned for a GitLab group, membership of +that group is synchronized between GitLab and the identity provider. + GitLab's [SCIM API](../../../api/scim.md) implements part of [the RFC7644 protocol](https://tools.ietf.org/html/rfc7644). Currently, the following actions are available: @@ -100,3 +108,15 @@ the `Provisioning Status` to `ON`. Once enabled, the synchronization details and any errors will appear on the bottom of the **Provisioning** screen, together with a link to the audit logs. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index 4e81e28a45a..79ae94dd9ef 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -1,11 +1,17 @@ +--- +type: reference, howto, concepts +--- + # Subgroups NOTE: **Note:** [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/2772) in GitLab 9.0. Not available when using MySQL as external database (support removed in GitLab 9.3 [due to performance reasons](https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600)). -With subgroups (aka nested groups or hierarchical groups) you can have -up to 20 levels of nested groups, which among other things can help you to: +Subgroups, also known as nested groups or hierarchical groups, allow you to have up to 20 +levels of groups. + +By using subgroups you can do the following: - **Separate internal / external organizations.** Since every group can have its own visibility level, you are able to host groups for different @@ -17,8 +23,9 @@ up to 20 levels of nested groups, which among other things can help you to: ## Database Requirements -Nested groups are only supported when you use PostgreSQL. Supporting nested -groups on MySQL in an efficient way is not possible due to MySQL's limitations. +Subgroups are only supported when you use PostgreSQL. Supporting subgroups on MySQL in an +efficient way is not possible due to MySQL's limitations. + See the following links for more information: - <https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> @@ -37,7 +44,7 @@ only 1 parent group. It resembles a directory behavior or a nested items list: - Group 1.2.2.1 In a real world example, imagine maintaining a GNU/Linux distribution with the -first group being the name of the distro and subsequent groups split like: +first group being the name of the distribution, and subsequent groups split as follows: - Organization Group - GNU/Linux distro - Category Subgroup - Packages @@ -69,22 +76,22 @@ Another example of GitLab as a company would be the following: --- -The maximum nested groups a group can have, including the first one in the +The maximum subgroups a group can have, including the first one in the hierarchy, is 21. -Things like transferring or importing a project inside nested groups, work like +Actions such as transferring or importing a project inside subgroups, work like when performing these actions the traditional way with the `group/project` structure. ## Creating a subgroup NOTE: **Note:** -You need to be an Owner of a group in order to be able to create a subgroup. For +You must be an Owner of a group to create a subgroup. For more information check the [permissions table](../../permissions.md#group-members-permissions). For a list of words that are not allowed to be used as group names see the [reserved names](../../reserved_names.md). Users can always create subgroups if they are explicitly added as an Owner to -a parent group even if group creation is disabled by an administrator in their +a parent group, even if group creation is disabled by an administrator in their settings. To create a subgroup: @@ -111,7 +118,7 @@ When you add a member to a subgroup, they inherit the membership and permission level from the parent group. This model allows access to nested groups if you have membership in one of its parents. -The group permissions for a member can be changed only by Owners and only on +The group permissions for a member can be changed only by Owners, and only on the **Members** page of the group the member was added. You can tell if a member has inherited the permissions from a parent group by @@ -119,24 +126,24 @@ looking at the group's **Members** page.  -From the image above, we can deduct the following things: +From the image above, we can deduce the following things: -- There are 5 members that have access to the group `four` +- There are 5 members that have access to the group `four`. - User0 is a Reporter and has inherited their permissions from group `one` - which is above the hierarchy of group `four` + which is above the hierarchy of group `four`. - User1 is a Developer and has inherited their permissions from group - `one/two` which is above the hierarchy of group `four` + `one/two` which is above the hierarchy of group `four`. - User2 is a Developer and has inherited their permissions from group - `one/two/three` which is above the hierarchy of group `four` + `one/two/three` which is above the hierarchy of group `four`. - For User3 there is no indication of a parent group, therefore they belong to - group `four`, the one we're inspecting + group `four`, the one we're inspecting. - Administrator is the Owner and member of **all** subgroups and for that reason, - same as User3, there is no indication of an ancestor group + as with User3, there is no indication of an ancestor group. ### Overriding the ancestor group membership NOTE: **Note:** -You need to be an Owner of a group in order to be able to add members to it. +You must be an Owner of a group to be able to add members to it. NOTE: **Note:** A user's permissions in a subgroup cannot be lower than in any of its ancestor groups. @@ -154,7 +161,7 @@ the permissions will fallback to those of the ancestor group. ## Mentioning subgroups Mentioning groups (`@group`) in issues, commits and merge requests, would -notify all members of that group. Now with subgroups, there is a more granular +notify all members of that group. Now with subgroups, there is more granular support if you want to split your group's structure. Mentioning works as before and you can choose the group of people to be notified. @@ -179,3 +186,15 @@ Here's a list of what you can't do with subgroups: [permissions]: ../../permissions.md#group-members-permissions [reserved]: ../../reserved_names.md [issue]: https://gitlab.com/gitlab-org/gitlab-ce/issues/30472#note_27747600 + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 0d7bbb0af79..304a7984191 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -23,7 +23,7 @@ Here's a list of things that will **not** be deleted: - Award emoji that the user created Instead of being deleted, these records will be moved to a system-wide -"Ghost User", whose sole purpose is to act as a container for such records. +user with the username "Ghost User", whose sole purpose is to act as a container for such records. Any commits made by a deleted user will still display the username of the original user. When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) or spam log, these associated records are not ghosted and will be removed, along with any groups the user diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 6360a01a0ad..c67b12fb91a 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -17,13 +17,15 @@ Modern implementations have introduced the concept of an "executable runbooks", where, along with a well-defined process, operators can execute pre-written code blocks or database queries against a given environment. -## Nurtch Executable Runbooks +## Executable Runbooks > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. The JupyterHub app offered via GitLab’s Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps -runbooks. A sample runbook is provided, showcasing common operations. +runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it +simple to create common Kubernetes and AWS workflows, you can also create them manually without +Rubix. **<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index dfbed0ec95f..2cda850f24e 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -216,7 +216,7 @@ The sample function can now be triggered from any HTTP client using a simple `PO --header "Content-Type: application/json" \ --request POST \ --data '{"GitLab":"FaaS"}' \ - http://functions-echo.functions-1.functions.example.com + http://functions-echo.functions-1.functions.example.com/ ``` 2. Using a web-based tool (ie. postman, restlet, etc) diff --git a/doc/user/project/insights/index.md b/doc/user/project/insights/index.md index 5154ff38154..3344e560870 100644 --- a/doc/user/project/insights/index.md +++ b/doc/user/project/insights/index.md @@ -179,7 +179,7 @@ Supported values are: Filter by the state of the queried "issuable". -If you omit it, no state filter will be applied. +If you omit it, the `opened` state filter will be applied. Supported values are: @@ -187,6 +187,7 @@ Supported values are: - `closed`: Closed Open issues / merge requests. - `locked`: Issues / merge requests that have their discussion locked. - `merged`: Merged merge requests. +- `all`: Issues / merge requests in all states #### `query.filter_labels` diff --git a/doc/user/project/integrations/img/jira_add_user_to_group.png b/doc/user/project/integrations/img/jira_add_user_to_group.png Binary files differindex 27dac49260c..d8cf541a81e 100644 --- a/doc/user/project/integrations/img/jira_add_user_to_group.png +++ b/doc/user/project/integrations/img/jira_add_user_to_group.png diff --git a/doc/user/project/integrations/img/jira_added_user_to_group.png b/doc/user/project/integrations/img/jira_added_user_to_group.png Binary files differnew file mode 100644 index 00000000000..b3e29a65d6e --- /dev/null +++ b/doc/user/project/integrations/img/jira_added_user_to_group.png diff --git a/doc/user/project/integrations/img/jira_create_new_group.png b/doc/user/project/integrations/img/jira_create_new_group.png Binary files differindex 06c4e84fc61..84be3a94a45 100644 --- a/doc/user/project/integrations/img/jira_create_new_group.png +++ b/doc/user/project/integrations/img/jira_create_new_group.png diff --git a/doc/user/project/integrations/img/jira_create_new_user.png b/doc/user/project/integrations/img/jira_create_new_user.png Binary files differindex e9c03ed770d..8460dc98ef9 100644 --- a/doc/user/project/integrations/img/jira_create_new_user.png +++ b/doc/user/project/integrations/img/jira_create_new_user.png diff --git a/doc/user/project/integrations/img/jira_group_access.png b/doc/user/project/integrations/img/jira_group_access.png Binary files differindex 448cc55504d..58cf114bd55 100644 --- a/doc/user/project/integrations/img/jira_group_access.png +++ b/doc/user/project/integrations/img/jira_group_access.png diff --git a/doc/user/project/integrations/img/jira_user_management_link.png b/doc/user/project/integrations/img/jira_user_management_link.png Binary files differindex 5eb9d031c3e..43ef18da6c8 100644 --- a/doc/user/project/integrations/img/jira_user_management_link.png +++ b/doc/user/project/integrations/img/jira_user_management_link.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index a90167b9767..c652149052e 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -47,11 +47,11 @@ project in Jira and then enter the correct values in GitLab. When connecting to **JIRA Server**, which supports basic authentication, a **username and password** are required. Check the link below and proceed to the next step: -- [Setting up an user in JIRA server](jira_server_configuration.md) +- [Setting up a user in JIRA server](jira_server_configuration.md) When connecting to **JIRA Cloud**, which supports authentication via API token, an **email and API token**, are required. Check the link below and proceed to the next step: -- [Setting up an user in JIRA cloud](jira_cloud_configuration.md) +- [Setting up a user in JIRA cloud](jira_cloud_configuration.md) ### Configuring GitLab diff --git a/doc/user/project/integrations/jira_server_configuration.md b/doc/user/project/integrations/jira_server_configuration.md index 20036183187..13d65c4d8e4 100644 --- a/doc/user/project/integrations/jira_server_configuration.md +++ b/doc/user/project/integrations/jira_server_configuration.md @@ -1,18 +1,16 @@ # Creating a username and password for JIRA server We need to create a user in Jira which will have access to all projects that -need to integrate with GitLab. Login to your Jira instance as admin and under -*Administration*, go to *User Management* and create a new user. +need to integrate with GitLab. As an example, we'll create a user named `gitlab` and add it to the `Jira-developers` group. NOTE: **Note** -It is important that the user `gitlab` has 'write' access to projects in Jira. +It is important that the Jira user created for the integration is given 'write' +access to your Jira projects. This is covered in the process below. -We have split this stage in steps so it is easier to follow. - -1. Log in to your Jira instance as an administrator and under **Administration** +1. Log in to your Jira instance as an administrator and under **Jira Administration** go to **User Management** to create a new user.  @@ -27,27 +25,34 @@ We have split this stage in steps so it is easier to follow.  -1. Create a `gitlab-developers` group which will have write access - to projects in Jira. Go to the **Groups** tab and select **Create group**. +1. Create a `gitlab-developers` group. (We will give this group write access to Jira + projects in a later step). Go to the **Groups** tab on the left, and select **Add group**.  - Give it an optional description and click **Create group**. + Give it a name and click **Add group**. -  +1. Add the `gitlab` user to the `gitlab-developers` group by clicking **Edit members**. + The `gitlab-developers` group should be listed in the leftmost box as a selected group. + Under **Add members to selected group(s)**, enter `gitlab`. -1. To give the newly-created group 'write' access, go to - **Application access > View configuration** and add the `gitlab-developers` - group to Jira Core. +  + + Click **Add selected users** and `gitlab` should appear in the **Group member(s)** box. + This membership is saved automatically. + +  + +1. To give the newly-created group 'write' access, you need to create a **Permission Scheme**. + To do this, click the gear icon and select **Issues**. Then click **Permission Schemes**. + Click **Add Permission Scheme** and enter a **Name** and, optionally, a **Description**. + +1. Once your permission scheme is created, you'll be taken back to the permissions scheme list. + Locate your new permissions scheme and click **Permissions**. Next to **Administer Projects**, + click **Edit**. In the resulting dialog box, select **Group** and select `gitlab-developers` + from the dropdown.  -1. Add the `gitlab` user to the `gitlab-developers` group by going to - **Users > GitLab user > Add group** and selecting the `gitlab-developers` - group from the dropdown menu. Notice that the group says _Access_, which is - intended as part of this process. - -  - The Jira configuration is complete. Write down the new Jira username and its password as they will be needed when [configuring GitLab in the next section](jira.md#configuring-gitlab). diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index a0f500a939f..d5f28ddabc1 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -653,7 +653,33 @@ X-Gitlab-Event: Note Hook "description": "test", "milestone_id": null, "state": "closed", - "iid": 17 + "iid": 17, + "labels": [ + { + "id": 25, + "title": "Afterpod", + "color": "#3e8068", + "project_id": null, + "created_at": "2019-06-05T14:32:20.211Z", + "updated_at": "2019-06-05T14:32:20.211Z", + "template": false, + "description": null, + "type": "GroupLabel", + "group_id": 4 + }, + { + "id": 86, + "title": "Element", + "color": "#231afe", + "project_id": 4, + "created_at": "2019-06-05T14:32:20.637Z", + "updated_at": "2019-06-05T14:32:20.637Z", + "template": false, + "description": null, + "type": "ProjectLabel", + "group_id": null + } + ], } } ``` diff --git a/doc/user/project/integrations/youtrack.md b/doc/user/project/integrations/youtrack.md index a2a468b6fe4..81c148e41fd 100644 --- a/doc/user/project/integrations/youtrack.md +++ b/doc/user/project/integrations/youtrack.md @@ -31,8 +31,8 @@ To disable the internal issue tracker in a project: ## Referencing YouTrack issues in GitLab Issues in YouTrack can be referenced as `<PROJECT>-<ID>`. `<PROJECT>` -must start with a capital letter and can then be followed by capital or lower case -letters, numbers or underscores. `<ID>` is a number. An example reference is `YT-101` or `Api_32-143`. +must start with a letter and is followed by letters, numbers, or underscores. +`<ID>` is a number. An example reference is `YT-101`, `Api_32-143` or `gl-030`. References to `<PROJECT>-<ID>` in merge requests, commits, or comments are automatically linked to the YouTrack issue URL. For more information, see the [External Issue Tracker](../../../integration/external-issue-tracker.md) documentation. diff --git a/doc/user/project/labels.md b/doc/user/project/labels.md index 8e9e9aa79cf..e5f62a3bb8d 100644 --- a/doc/user/project/labels.md +++ b/doc/user/project/labels.md @@ -32,6 +32,14 @@ An issue, epic, or merge request cannot have two scoped labels with the same key For example, if an issue is already labeled `priority::3` and you apply the label `priority::2` to it, `priority::3` is automatically removed. +### Labels with multiple colon pairs + +If labels have multiple instances of `::`, the longest path from left to right, until the last `::`, is considered the "key" or the "scope". + +For example, `nested::key1::value1` and `nested::key1::value2` cannot both exist on the same issue. Adding the latter label will automatically remove the former due to the shared scope of `nested::key1`. + +`nested::key1::value1` and `nested::key2::value1` can both exist on the same issue, as these are considered to use two different label scopes, `nested::key1` and `nested::key2`. + ### Workflows with scoped labels **[PREMIUM]** Suppose you wanted a custom field in issues to track the platform operating system diff --git a/doc/user/project/merge_requests/allow_collaboration.md b/doc/user/project/merge_requests/allow_collaboration.md index da6e6b5fd3a..e94125e658d 100644 --- a/doc/user/project/merge_requests/allow_collaboration.md +++ b/doc/user/project/merge_requests/allow_collaboration.md @@ -1,3 +1,7 @@ +--- +type: reference, howto +--- + # Allow collaboration on merge requests across forks > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17395) @@ -70,3 +74,15 @@ Here's how the process would look like: Note the colon (`:`) between the two branches. The above command will push the local branch `thedude-awesome-project-update-docs` to the `update-docs` branch of the `git@gitlab.com:thedude/awesome-project.git` repository. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/authorization_for_merge_requests.md b/doc/user/project/merge_requests/authorization_for_merge_requests.md index 79444ee5682..0579e3568da 100644 --- a/doc/user/project/merge_requests/authorization_for_merge_requests.md +++ b/doc/user/project/merge_requests/authorization_for_merge_requests.md @@ -1,8 +1,12 @@ +--- +type: concepts +--- + # Authorization for Merge requests There are two main ways to have a merge request flow with GitLab: -1. Working with [protected branches] in a single repository. +1. Working with [protected branches](../protected_branches.md) in a single repository. 1. Working with forks of an authoritative project. ## Protected branch flow @@ -53,4 +57,14 @@ forks. - The project need to keep their forks up to date, which requires more advanced Git skills (managing multiple remotes). -[protected branches]: ../protected_branches.md +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/browser_performance_testing.md b/doc/user/project/merge_requests/browser_performance_testing.md index 65ee2e128ae..f6c4f767e3c 100644 --- a/doc/user/project/merge_requests/browser_performance_testing.md +++ b/doc/user/project/merge_requests/browser_performance_testing.md @@ -1,14 +1,18 @@ +--- +type: reference, howto +--- + # Browser Performance Testing **[PREMIUM]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3507) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.3. -## Overview - If your application offers a web interface and you are using [GitLab CI/CD](../../../ci/README.md), you can quickly determine the performance impact of pending code changes. +## Overview + GitLab uses [Sitespeed.io](https://www.sitespeed.io), a free and open source tool for measuring the performance of web sites, and has built a simple [Sitespeed plugin](https://gitlab.com/gitlab-org/gl-performance) @@ -52,3 +56,15 @@ Consecutive merge requests will have something to compare to and the Performance report will be shown properly.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/cherry_pick_changes.md b/doc/user/project/merge_requests/cherry_pick_changes.md index 06b3779668b..a5c191c150f 100644 --- a/doc/user/project/merge_requests/cherry_pick_changes.md +++ b/doc/user/project/merge_requests/cherry_pick_changes.md @@ -1,8 +1,11 @@ -# Cherry-pick changes +--- +type: reference, concepts +--- -> [Introduced][ce-3514] in GitLab 8.7. +# Cherry-pick changes -GitLab implements Git's powerful feature to [cherry-pick any commit][git-cherry-pick] +GitLab implements Git's powerful feature to +[cherry-pick any commit](https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation") with introducing a **Cherry-pick** button in merge requests and commit details. ## Cherry-picking a merge request @@ -18,9 +21,9 @@ where you can choose to either: - Cherry-pick the changes directly into the selected branch. - Create a new merge request with the cherry-picked changes. -## Cherry-picking a Commit +## Cherry-picking a commit -You can cherry-pick a Commit from the Commit details page: +You can cherry-pick a commit from the commit details page:  @@ -39,5 +42,14 @@ mainline: git cherry-pick -m 2 7a39eb0 ``` -[ce-3514]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3514 "Cherry-pick button Merge Request" -[git-cherry-pick]: https://git-scm.com/docs/git-cherry-pick "Git cherry-pick documentation" +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 705ff333579..c3c2bdd94b3 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -1,14 +1,16 @@ +--- +type: reference, howto +--- + # Code Quality **[STARTER]** > [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1984) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.3. -## Overview - -If you are using [GitLab CI/CD](../../../ci/README.md), you can analyze your +With the help of [GitLab CI/CD](../../../ci/README.md), you can analyze your source code quality using GitLab Code Quality. Code Quality uses [Code Climate Engines](https://codeclimate.com), which are -free and open source. Code Quality doesn’t require a Code Climate subscription. +free and open source. Code Quality doesn't require a Code Climate subscription. Going a step further, GitLab can show the Code Quality report right in the merge request widget area: @@ -69,14 +71,24 @@ example on [analyzing a project's code quality](../../../ci/examples/code_qualit GitLab then checks this report, compares the metrics between the source and target branches, and shows the information right on the merge request. -CAUTION: **Caution:** If multiple jobs in a pipeline generate a code quality artifact, only the artifact from the last created job (the job with the largest job ID) is used. To avoid confusion, configure only one job to generate a code quality artifact. -NOTE: **Note:** If the Code Quality report doesn't have anything to compare to, no information will be displayed in the merge request area. That is the case when you add the Code Quality job in your `.gitlab-ci.yml` for the very first time. Consecutive merge requests will have something to compare to and the Code Quality report will be shown properly. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/fast_forward_merge.md b/doc/user/project/merge_requests/fast_forward_merge.md index 3cd91a185e3..4f3c68090e4 100644 --- a/doc/user/project/merge_requests/fast_forward_merge.md +++ b/doc/user/project/merge_requests/fast_forward_merge.md @@ -1,21 +1,24 @@ +--- +type: reference, concepts +--- + # Fast-forward merge requests -Retain a linear Git history and a way to accept merge requests without -creating merge commits. +Sometimes, a workflow policy might mandate a clean commit history without +merge commits. In such cases, the fast-forward merge is the perfect candidate. + +With fast-forward merge requests, you can retain a linear Git history and a way +to accept merge requests without creating merge commits. ## Overview -When the fast-forward merge ([`--ff-only`][ffonly]) setting is enabled, no merge -commits will be created and all merges are fast-forwarded, which means that -merging is only allowed if the branch could be fast-forwarded. +When the fast-forward merge +([`--ff-only`](https://git-scm.com/docs/git-merge#git-merge---ff-only)) setting +is enabled, no merge commits will be created and all merges are fast-forwarded, +which means that merging is only allowed if the branch could be fast-forwarded. When a fast-forward merge is not possible, the user is given the option to rebase. -## Use cases - -Sometimes, a workflow policy might mandate a clean commit history without -merge commits. In such cases, the fast-forward merge is the perfect candidate. - ## Enabling fast-forward merges 1. Navigate to your project's **Settings** and search for the 'Merge method' @@ -32,4 +35,14 @@ source branch locally before you will be able to do a fast-forward merge.  -[ffonly]: https://git-scm.com/docs/git-merge#git-merge---ff-only +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 4cfe59b808a..447b338928c 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -1,7 +1,11 @@ +--- +type: index, reference, concepts +--- + # Merge requests -Merge requests allow you to exchange changes you made to source code and -collaborate with other people on the same project. +Merge requests allow you to visualize and collaborate on the proposed changes +to source code that exist as commits on a given Git branch.  @@ -511,7 +515,7 @@ seconds and the status will update automatically. Merge Request pipeline statuses can't be retrieved when the following occurs: -1. A Merge Requst is created +1. A Merge Request is created 1. The Merge Request is closed 1. Changes are made in the project 1. The Merge Request is reopened @@ -606,6 +610,9 @@ And to check out a particular merge request: git checkout origin/merge-requests/1 ``` +all the above can be done with [git-mr] script. + +[git-mr]: https://gitlab.com/glensc/git-mr [products]: https://about.gitlab.com/products/ "GitLab products page" [protected branches]: ../protected_branches.md [ci]: ../../../ci/README.md diff --git a/doc/user/project/merge_requests/merge_request_approvals.md b/doc/user/project/merge_requests/merge_request_approvals.md index 2e9db949890..fd151a6df45 100644 --- a/doc/user/project/merge_requests/merge_request_approvals.md +++ b/doc/user/project/merge_requests/merge_request_approvals.md @@ -1,7 +1,23 @@ +--- +type: reference, concepts +--- + # Merge request approvals **[STARTER]** > Introduced in [GitLab Enterprise Edition 7.12](https://about.gitlab.com/2015/06/22/gitlab-7-12-released/#merge-request-approvers-ee-only). +Merge request approvals enable enforced code review by requiring specified people +to approve a merge request before it can be unblocked for merging. + +## Use cases + +1. Enforcing review of all code that gets merged into a repository. +2. Specifying code maintainers for an entire repository. +3. Specifying reviewers for a given proposed code change. +4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes. + +## Enabling the new approvals interface + NOTE: **Note:** Prior to 12.0, if you are running a self-managed instance, the new interface shown on this page will not be available unless the feature flag @@ -21,20 +37,6 @@ sudo -u git -H bin/rails console RAILS_ENV=production Then run `Feature.enable(:approval_rules)` to enable the feature flag. -The documentation for the older interface can be accessed -[here](/11.7/ee/user/project/merge_requests/merge_request_approvals.html). - -## Overview - -Merge request approvals enable enforced code review by requiring specified people to approve a merge request before it can be unblocked for merging. - -## Use cases - -1. Enforcing review of all code that gets merged into a repository. -2. Specifying code maintainers for an entire repository. -3. Specifying reviewers for a given proposed code change. -4. Specifying categories of reviewers, such as BE, FE, QA, DB, etc., for all proposed code changes. - ## Editing approvals To edit the merge request approvals: @@ -328,3 +330,15 @@ To filter merge requests by an individual approver, you can type (or select from the dropdown) `approver` and select the user.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md index 1477e35dca8..c93c7a5fe08 100644 --- a/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md +++ b/doc/user/project/merge_requests/merge_when_pipeline_succeeds.md @@ -1,3 +1,7 @@ +--- +type: reference, concepts +--- + # Merge when pipeline succeeds When reviewing a merge request that looks ready to merge but still has one or @@ -7,6 +11,8 @@ finish and remember to merge the request manually.  +## How it works + When you hit the "Merge When Pipeline Succeeds" button, the status of the merge request will be updated to represent the impending merge. If you cannot wait for the pipeline to succeed and want to merge immediately, this option is @@ -29,9 +35,6 @@ changes to be reviewed. ## Only allow merge requests to be merged if the pipeline succeeds -> **Note:** -You need to have jobs configured to enable this feature. - You can prevent merge requests from being merged if their pipeline did not succeed or if there are discussions to be resolved. @@ -39,9 +42,21 @@ Navigate to your project's settings page and expand the **Merge requests** secti In the **Merge checks** subsection, select the **Pipelines must succeed** check box and hit **Save** for the changes to take effect. -  + From now on, every time the pipeline fails you will not be able to merge the merge request from the UI, until you make all relevant jobs pass.  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/resolve_conflicts.md b/doc/user/project/merge_requests/resolve_conflicts.md index ccef2853e3f..6a0f2d18629 100644 --- a/doc/user/project/merge_requests/resolve_conflicts.md +++ b/doc/user/project/merge_requests/resolve_conflicts.md @@ -1,3 +1,7 @@ +--- +type: reference, concepts +--- + # Merge request conflict resolution Merge conflicts occur when two branches have different changes that cannot be @@ -66,3 +70,15 @@ Additionally, GitLab does not detect conflicts in renames away from a path. For example, this will not create a conflict: on branch `a`, doing `git mv file1 file2`; on branch `b`, doing `git mv file1 file3`. Instead, both files will be present in the branch after the merge request is merged. + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/revert_changes.md b/doc/user/project/merge_requests/revert_changes.md index b9102798a49..1cbbcf45400 100644 --- a/doc/user/project/merge_requests/revert_changes.md +++ b/doc/user/project/merge_requests/revert_changes.md @@ -1,11 +1,13 @@ -# Reverting changes +--- +type: reference, concepts +--- -> [Introduced][ce-1990] in GitLab 8.5. +# Reverting changes -GitLab implements Git's powerful feature to [revert any commit][git-revert] -with introducing a **Revert** button in merge requests and commit details. +You can use Git's powerful feature to [revert any commit](https://git-scm.com/docs/git-revert "Git revert documentation") +by clicking the **Revert** button in merge requests and commit details. -## Reverting a Merge Request +## Reverting a merge request NOTE: **Note:** The **Revert** button will only be available for merge requests @@ -30,9 +32,9 @@ create a new merge request with the revert changes. After the merge request has been reverted, the **Revert** button will not be available anymore. -## Reverting a Commit +## Reverting a commit -You can revert a Commit from the Commit details page: +You can revert a commit from the commit details page:  @@ -54,5 +56,14 @@ mainline: git revert -m 2 7a39eb0 ``` -[ce-1990]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1990 "Revert button Merge Request" -[git-revert]: https://git-scm.com/docs/git-revert "Git revert documentation" +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 4ff8ec3a7e6..39fd2588811 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -1,8 +1,14 @@ +--- +type: reference, concepts +--- + # Squash and merge -> [Introduced][ee-1024] in [GitLab Starter][ee] 8.17, and in [GitLab Core][ce] [11.0][ce-18956]. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1024) in [GitLab Starter](https://about.gitlab.com/pricing/) 8.17. +> - [Ported](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18956) to GitLab Core 11.0. -Combine all commits of your merge request into one and retain a clean history. +With squash and merge you can combine all your merge request's commits into one +and retain a clean history. ## Overview @@ -12,11 +18,11 @@ and then merges that commit using the merge method set for the project. In other words, squashing a merge request turns a long list of commits: -![List of commits from a merge request][mr-commits] + Into a single commit on merge: -![A squashed commit followed by a merge commit][squashed-commit] + The squashed commit's commit message will be either: @@ -44,20 +50,18 @@ all you have to do is enable squashing before you press merge to join the commits in the merge request into a single commit. This way, the history of your base branch remains clean with -meaningful commit messages and is simpler to [revert] if necessary. +meaningful commit messages and is simpler to [revert](revert_changes.md) if necessary. ## Enabling squash for a merge request Anyone who can create or edit a merge request can choose for it to be squashed on the merge request form: -![Squash commits checkbox on edit form][squash-edit-form] - ---- + This can then be overridden at the time of accepting the merge request: -![Squash commits checkbox on accept merge request form][squash-mr-widget] + ## Commit metadata for squashed commits @@ -69,19 +73,20 @@ The squashed commit has the following metadata: ## Squash and fast-forward merge -When a project has the [fast-forward merge setting enabled][ff-merge], the merge +When a project has the [fast-forward merge setting enabled](fast_forward_merge.md#enabling-fast-forward-merges), the merge request must be able to be fast-forwarded without squashing in order to squash it. This is because squashing is only available when accepting a merge request, so a merge request may need to be rebased before squashing, even though squashing can itself be considered equivalent to rebasing. -[ee-1024]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1024 -[ce-18956]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18956 -[mr-commits]: img/squash_mr_commits.png -[squashed-commit]: img/squash_squashed_commit.png -[squash-edit-form]: img/squash_edit_form.png -[squash-mr-widget]: img/squash_mr_widget.png -[ff-merge]: fast_forward_merge.md#enabling-fast-forward-merges -[ce]: https://about.gitlab.com/pricing/ -[ee]: https://about.gitlab.com/pricing/ -[revert]: revert_changes.md +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/versions.md b/doc/user/project/merge_requests/versions.md index 70bd1e60594..fbe216c3aed 100644 --- a/doc/user/project/merge_requests/versions.md +++ b/doc/user/project/merge_requests/versions.md @@ -1,13 +1,8 @@ -# Merge requests versions +--- +type: reference, concepts +--- -> **Notes:** -> -> - [Introduced][ce-5467] in GitLab 8.12. -> - Comments are disabled while viewing outdated merge versions or comparing to -> versions other than base. -> - Merge request versions are based on push not on commit. So, if you pushed 5 -> commits in a single push, it will be a single option in the dropdown. If you -> pushed 5 times, that will count for 5 options. +# Merge requests versions Every time you push to a branch that is tied to a merge request, a new version of merge request diff is created. When you visit a merge request that contains @@ -16,25 +11,38 @@ request diffs.  ---- +## Selecting a version By default, the latest version of changes is shown. However, you can select an older one from version dropdown.  ---- +Merge request versions are based on push not on commit. So, if you pushed 5 +commits in a single push, it will be a single option in the dropdown. If you +pushed 5 times, that will count for 5 options. You can also compare the merge request version with an older one to see what has changed since then.  ---- +Comments are disabled while viewing outdated merge versions or comparing to +versions other than base. Every time you push new changes to the branch, a link to compare the last changes appears as a system note.  -[ce-5467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5467 +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/merge_requests/work_in_progress_merge_requests.md b/doc/user/project/merge_requests/work_in_progress_merge_requests.md index 6f33eb9a482..9cd868067bc 100644 --- a/doc/user/project/merge_requests/work_in_progress_merge_requests.md +++ b/doc/user/project/merge_requests/work_in_progress_merge_requests.md @@ -1,4 +1,8 @@ -# "Work In Progress" Merge Requests +--- +type: reference, concepts +--- + +# "Work In Progress" merge requests If a merge request is not yet ready to be merged, perhaps due to continued development or open discussions, you can prevent it from being accepted before it's ready by flagging @@ -7,7 +11,7 @@ being merged, and it will stay disabled until the "WIP" flag has been removed.  -## Adding the "Work In Progress" flag to a Merge Request +## Adding the "Work In Progress" flag to a merge request There are several ways to flag a merge request as a Work In Progress: @@ -21,7 +25,7 @@ There are several ways to flag a merge request as a Work In Progress: source branch. This is not a toggle, and doing it again in another commit will have no effect. -## Removing the "Work In Progress" flag from a Merge Request +## Removing the "Work In Progress" flag from a merge request Similar to above, when a Merge Request is ready to be merged, you can remove the "Work in Progress" flag in several ways: @@ -37,10 +41,22 @@ Similar to above, when a Merge Request is ready to be merged, you can remove the Must have at least Developer level permissions on the project for the button to be visible. -## Including/Excluding WIP Merge Requests when searching +## Including/excluding WIP merge requests when searching When viewing/searching the merge requests list, you can choose to include or exclude WIP merge requests by adding a "WIP" filter in the search box, and choosing "Yes" (to include) or "No" (to exclude).  + +<!-- ## Troubleshooting + +Include any troubleshooting steps that you can foresee. If you know beforehand what issues +one might have when setting this up, or when something is changed, or on upgrading, it's +important to describe those, too. Think of things that may go wrong and include them here. +This is important to minimize requests for support, and to avoid doc comments with +questions that you know someone might ask. + +Each scenario can be a third-level heading, e.g. `### Getting error message X`. +If you have none to add when creating a doc, leave this section in place +but commented out to help encourage others to add to it in the future. --> diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index d36312c9b8d..c07c4099f22 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -28,10 +28,10 @@ The reasons to do it like that are: and maximizing security. With the new behavior, any job that is triggered by the user, is also marked -with their permissions. When a user does a `git push` or changes files through +with their read permissions. When a user does a `git push` or changes files through the web UI, a new pipeline will be usually created. This pipeline will be marked as created be the pusher (local push or via the UI) and any job created in this -pipeline will have the permissions of the pusher. +pipeline will have the read permissions of the pusher but not write permissions. This allows us to make it really easy to evaluate the access for all projects that have [Git submodules][gitsub] or are using container images that the pusher @@ -67,9 +67,10 @@ Let's consider the following scenario: ## Job token -A unique job token is generated for each job and it allows the user to +A unique job token is generated for each job and provides the user read access all projects that would be normally accessible to the user creating that -job. +job. The unique job token does not have any write permissions, but there +is a [proposal to add support](https://gitlab.com/gitlab-org/gitlab-ce/issues/18106). We try to make sure that this token doesn't leak by: diff --git a/doc/user/project/operations/img/external_dashboard_link.png b/doc/user/project/operations/img/external_dashboard_link.png Binary files differnew file mode 100644 index 00000000000..4fb8bce7cd0 --- /dev/null +++ b/doc/user/project/operations/img/external_dashboard_link.png diff --git a/doc/user/project/operations/img/external_dashboard_settings.png b/doc/user/project/operations/img/external_dashboard_settings.png Binary files differnew file mode 100644 index 00000000000..8dc380f01e2 --- /dev/null +++ b/doc/user/project/operations/img/external_dashboard_settings.png diff --git a/doc/user/project/operations/index.md b/doc/user/project/operations/index.md index 0086c15c98a..84711d1146f 100644 --- a/doc/user/project/operations/index.md +++ b/doc/user/project/operations/index.md @@ -9,3 +9,4 @@ your applications: - Discover and view errors generated by your applications with [Error Tracking](error_tracking.md). - Create, toggle, and remove [Feature Flags](feature_flags.md). **[PREMIUM]** - [Trace](tracing.md) the performance and health of a deployed application. **[ULTIMATE]** +- Add a [button to the Monitoring dashboard](linking_to_an_external_dashboard.md) linking directly to your existing external dashboards. diff --git a/doc/user/project/operations/linking_to_an_external_dashboard.md b/doc/user/project/operations/linking_to_an_external_dashboard.md new file mode 100644 index 00000000000..0371a40a217 --- /dev/null +++ b/doc/user/project/operations/linking_to_an_external_dashboard.md @@ -0,0 +1,19 @@ +# Linking to an external dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/57171) in GitLab 12.0. + +You can add a button to the Monitoring dashboard linking directly to your existing external dashboards. + +## Enabling the external dashboard link + +1. Go to **Settings > Operations** and scroll to the section titled **External dashboard**. + +1. Fill in the URL to your external dashboard and click **Save changes**. + +  + +1. There should now be a button on your + [Monitoring dashboard](../../../ci/environments.md#monitoring-environments) which + will open the URL you entered in the above step. + +  diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 87cd4941ae6..8baf41dba78 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -1,10 +1,6 @@ --- -last_updated: 2018-02-16 -author: Marcia Ramos -author_gitlab: marcia -level: intermediate -article_type: user guide -date: 2017-02-22 +last_updated: 2019-06-04 +type: reference, howto --- # Creating and Tweaking GitLab CI/CD for GitLab Pages diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index 7dbf58b5715..6d538ca2455 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,5 +1,6 @@ --- -last_updated: 2018-02-16 +last_updated: 2018-06-04 +type: concepts, reference --- # Static sites and GitLab Pages domains diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 769adbf780e..d585c19fc5c 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,10 +1,6 @@ --- -last_updated: 2018-11-19 -author: Marcia Ramos -author_gitlab: marcia -level: beginner -article_type: user guide -date: 2017-02-22 +last_updated: 2019-06-04 +type: concepts, reference, howto --- # GitLab Pages custom domains and SSL/TLS Certificates diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index b74520e6556..3e50cd4887c 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,10 +1,6 @@ --- -last_updated: 2019-03-05 -author: Marcia Ramos -author_gitlab: marcia -level: beginner -article_type: user guide -date: 2017-02-22 +last_updated: 2019-06-04 +type: reference, howto --- # Projects for GitLab Pages and URL structure @@ -13,11 +9,11 @@ date: 2017-02-22 To get started with GitLab Pages, you need: -1. A project -1. A configuration file (`.gitlab-ci.yml`) to deploy your site +1. A project, thus a repository to hold your website's codebase. +1. A configuration file (`.gitlab-ci.yml`) to deploy your site. 1. A specific `job` called `pages` in the configuration file - that will make GitLab aware that you are deploying a GitLab Pages website -1. A `public` directory with the content of the website + that will make GitLab aware that you are deploying a GitLab Pages website. +1. A `public` directory with the static content of the website. Optional Features: @@ -140,7 +136,7 @@ where you'll find its default URL. repository to you local computer and moving your site files into it, you can run `git init` in your local website directory, add the remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, - then add, commit, and push. + then add, commit, and push to GitLab. ## URLs and Baseurls @@ -173,4 +169,4 @@ baseurl: "" ## Custom Domains GitLab Pages supports custom domains and subdomains, served under HTTP or HTTPS. -Please check the [next part](getting_started_part_three.md) of this series for an overview. +See [GitLab Pages custom domains and SSL/TLS Certificates](getting_started_part_three.md) for more information. diff --git a/doc/user/project/pages/index.md b/doc/user/project/pages/index.md index 91098d51160..04bda212128 100644 --- a/doc/user/project/pages/index.md +++ b/doc/user/project/pages/index.md @@ -1,6 +1,7 @@ --- description: 'Learn how to use GitLab Pages to deploy a static website at no additional cost.' -last_updated: 2019-03-05 +last_updated: 2019-06-04 +type: index, reference --- # GitLab Pages @@ -140,7 +141,7 @@ To learn more about configuration options for GitLab Pages, read the following: | [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. | +| [Exploring GitLab Pages](introduction.md) | Requirements, technical aspects, specific GitLab CI's configuration options, custom 404 pages, limitations, FAQ. | |---+---| | [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. | diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index a14a446aead..4fab7f79e0c 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,3 +1,8 @@ +--- +type: reference +last_updated: 2018-06-04 +--- + # Exploring GitLab Pages This document is a user guide to explore the options and settings @@ -10,7 +15,7 @@ To familiarize yourself with GitLab Pages first: - Learn how to enable GitLab Pages across your GitLab instance on the [administrator documentation](../../../administration/pages/index.md). -## Pages requirements +## GitLab Pages requirements In brief, this is what you need to upload your website in GitLab Pages: @@ -34,6 +39,99 @@ If you are using [GitLab Pages on GitLab.com](#gitlab-pages-on-gitlabcom) to hos Visit the [GitLab Pages group](https://gitlab.com/groups/pages) for a complete list of example projects. Contributions are very welcome. +## Custom error codes Pages + +You can provide your own 403 and 404 error pages by creating the `403.html` and +`404.html` files respectively in the root directory of the `public/` directory +that will be included in the artifacts. Usually this is the root directory of +your project, but that may differ depending on your static generator +configuration. + +If the case of `404.html`, there are different scenarios. For example: + +- If you use project Pages (served under `/projectname/`) and try to access + `/projectname/non/existing_file`, GitLab Pages will try to serve first + `/projectname/404.html`, and then `/404.html`. +- If you use user/group Pages (served under `/`) and try to access + `/non/existing_file` GitLab Pages will try to serve `/404.html`. +- If you use a custom domain and try to access `/non/existing_file`, GitLab + Pages will try to serve only `/404.html`. + +## 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). + +## GitLab Pages Access Control **[CORE ONLY]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. + +NOTE: **Note:** +GitLab Pages access control is not activated on GitLab.com. You can check its +progress on the +[infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5576). + +You can enable Pages access control on your project, so that only +[members of your project](../../permissions.md#project-members-permissions) +(at least Guest) can access your website: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Toggle the **Pages** button to enable the access control. + + NOTE: **Note:** + If you don't see the toggle button, that means that it's not enabled. + Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). + +1. The Pages access control dropdown allows you to set who can view pages hosted + with GitLab Pages, depending on your project's visibility: + + - If your project is private: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is internal: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. + - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + - If your project is public: + - **Only project members**: Only project members will be able to browse the website. + - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. + +1. Click **Save changes**. + +--- + +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`), +you _cannot_ use HTTPS with sub-subdomains. That means that if your +username/groupname contains a dot, for example `foo.bar`, the domain +`https://foo.bar.example.io` will _not_ work. This is a limitation of the +[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you +don't redirect HTTP to HTTPS. + +[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC" + +GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). +You can only create the highest-level group website. + ## Specific configuration options for Pages Learn how to set up GitLab CI/CD for specific use cases. @@ -208,99 +306,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. -### Custom error codes pages - -You can provide your own 403 and 404 error pages by creating the `403.html` and -`404.html` files respectively in the root directory of the `public/` directory -that will be included in the artifacts. Usually this is the root directory of -your project, but that may differ depending on your static generator -configuration. - -If the case of `404.html`, there are different scenarios. For example: - -- If you use project Pages (served under `/projectname/`) and try to access - `/projectname/non/existing_file`, GitLab Pages will try to serve first - `/projectname/404.html`, and then `/404.html`. -- If you use user/group Pages (served under `/`) and try to access - `/non/existing_file` GitLab Pages will try to serve `/404.html`. -- If you use a custom domain and try to access `/non/existing_file`, GitLab - Pages will try to serve only `/404.html`. - -### 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). - -### GitLab Pages Access Control **[CORE ONLY]** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/33422) in GitLab 11.5. - -NOTE: **Note:** -GitLab Pages access control is not activated on GitLab.com. You can check its -progress on the -[infrastructure issue tracker](https://gitlab.com/gitlab-com/gl-infra/infrastructure/issues/5576). - -You can enable Pages access control on your project, so that only -[members of your project](../../permissions.md#project-members-permissions) -(at least Guest) can access your website: - -1. Navigate to your project's **Settings > General > Permissions**. -1. Toggle the **Pages** button to enable the access control. - - NOTE: **Note:** - If you don't see the toggle button, that means that it's not enabled. - Ask your administrator to [enable it](../../../administration/pages/index.md#access-control). - -1. The Pages access control dropdown allows you to set who can view pages hosted - with GitLab Pages, depending on your project's visibility: - - - If your project is private: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. - - If your project is internal: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone logged into GitLab will be able to browse the website, no matter their project membership. - - **Everyone**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. - - If your project is public: - - **Only project members**: Only project members will be able to browse the website. - - **Everyone with access**: Everyone, both logged into and logged out of GitLab, will be able to browse the website, no matter their project membership. - -1. Click **Save changes**. - ---- - -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`), -you _cannot_ use HTTPS with sub-subdomains. That means that if your -username/groupname contains a dot, for example `foo.bar`, the domain -`https://foo.bar.example.io` will _not_ work. This is a limitation of the -[HTTP Over TLS protocol][rfc]. HTTP pages will continue to work provided you -don't redirect HTTP to HTTPS. - -[rfc]: https://tools.ietf.org/html/rfc2818#section-3.1 "HTTP Over TLS RFC" - -GitLab Pages [does **not** support group websites for subgroups](../../group/subgroups/index.md#limitations). -You can only create the highest-level group website. - ## Frequently Asked Questions ### Can I download my generated pages? 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 da1b7c59c8e..91a660c0f7a 100644 --- a/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md +++ b/doc/user/project/pages/lets_encrypt_for_gitlab_pages.md @@ -1,5 +1,7 @@ --- description: "How to secure GitLab Pages websites with Let's Encrypt." +type: howto +last_updated: 2019-06-04 --- # Let's Encrypt for GitLab Pages diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 629b5e1fde4..002addfc043 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -16,7 +16,7 @@ > [administration/job_artifacts](../../../administration/job_artifacts.md). Artifacts is a list of files and directories which are attached to a job -after it completes successfully. This feature is enabled by default in all +after it finishes. This feature is enabled by default in all GitLab installations. ## Defining artifacts in `.gitlab-ci.yml` @@ -36,12 +36,14 @@ pdf: A job named `pdf` calls the `xelatex` command in order to build a pdf file from the latex source file `mycv.tex`. We then define the `artifacts` paths which in turn are defined with the `paths` keyword. All paths to files and directories -are relative to the repository that was cloned during the build. These uploaded -artifacts will be kept in GitLab for 1 week as defined by the `expire_in` -definition. You have the option to keep the artifacts from expiring via the -[web interface](#browsing-artifacts). If the expiry time is not defined, -it defaults to the [instance wide -setting](../../admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only). +are relative to the repository that was cloned during the build. + +The artifacts will be uploaded when the job succeeds by default, but can be set to upload +when the job fails, or always, if the [`artifacts:when`](../../../ci/yaml/README.md#artifactswhen) +parameter is used. These uploaded artifacts will be kept in GitLab for 1 week as defined +by the `expire_in` definition. You have the option to keep the artifacts from expiring +via the [web interface](#browsing-artifacts). If the expiry time is not defined, it defaults +to the [instance wide setting](../../admin_area/settings/continuous_integration.md#default-artifacts-expiration-core-only). For more examples on artifacts, follow the [artifacts reference in `.gitlab-ci.yml`](../../../ci/yaml/README.md#artifacts). diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 8b762307ac4..16f48c462eb 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -20,6 +20,22 @@ There are two options. Using: The default Git strategy can be overridden by the [GIT_STRATEGY variable](../../../ci/yaml/README.md#git-strategy) in `.gitlab-ci.yml`. +## Git shallow clone + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/28919) in GitLab 12.0. + +NOTE: **Note**: As of GitLab 12.0, newly created projects will automaticallyl have a default +`git depth` value of `50`. + +It is possible to limit the number of changes that GitLab CI/CD will fetch when cloning +a repository. Setting a limit to `git depth` can speed up Pipelines execution. Maximum +allowed value is `1000`. + +To disable shallow clone and make GitLab CI/CD fetch all branches and tags each time, +keep the value empty or set to `0`. + +This value can also be [overridden by `GIT_DEPTH`](../../../ci/large_repositories/index.md#shallow-cloning) variable in `.gitlab-ci.yml` file. + ## Timeout Timeout defines the maximum amount of time in minutes that a job is able run. |
