diff options
Diffstat (limited to 'doc')
95 files changed, 3235 insertions, 1983 deletions
diff --git a/doc/README.md b/doc/README.md index 489c8117b9d..5eaa998a7b8 100644 --- a/doc/README.md +++ b/doc/README.md @@ -111,7 +111,7 @@ The following documentation relates to the DevOps **Plan** stage: | [Discussions](user/discussions/index.md) | Threads, comments, and resolvable discussions in issues, commits, and merge requests. | | [Due Dates](user/project/issues/due_dates.md) | Keep track of issue deadlines. | | [Epics](user/group/epics/index.md) **[ULTIMATE]** | Tracking groups of issues that share a theme. | -| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/moving_issues.md) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. | +| [Issues](user/project/issues/index.md), including [confidential issues](user/project/issues/confidential_issues.md),<br/>[issue and merge request templates](user/project/description_templates.md),<br/>and [moving issues](user/project/issues/managing_issues.md#moving-issues) | Project issues, restricting access to issues, create templates for submitting new issues and merge requests, and moving issues between projects. | | [Labels](user/project/labels.md) | Categorize issues or merge requests with descriptive labels. | | [Milestones](user/project/milestones/index.md) | Set milestones for delivery of issues and merge requests, with optional due date. | | [Project Issue Board](user/project/issue_board.md) | Display issues on a Scrum or Kanban board. | diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index 1f2961ea39a..79ac7fe0352 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -1,6 +1,4 @@ -[//]: # (Do *NOT* modify this file in EE documentation. All changes in this) -[//]: # (file should happen in CE, too. If the change is EE-specific, put) -[//]: # (it in `ldap-ee.md`.) +<!-- If the change is EE-specific, put it in `ldap-ee.md`, NOT here. --> # LDAP diff --git a/doc/administration/geo/disaster_recovery/background_verification.md b/doc/administration/geo/disaster_recovery/background_verification.md index d4c8c2d3624..e19cd9bbfec 100644 --- a/doc/administration/geo/disaster_recovery/background_verification.md +++ b/doc/administration/geo/disaster_recovery/background_verification.md @@ -143,11 +143,13 @@ If the **primary** and **secondary** nodes have a checksum verification mismatch 1. On the project admin page get the **Gitaly storage name**, and **Gitaly relative path**:  -1. Navigate to the project's repository directory on both **primary** and **secondary** nodes (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs` is customized, check the directory layout on your server to be sure. +1. Navigate to the project's repository directory on both **primary** and **secondary** nodes + (the path is usually `/var/opt/gitlab/git-data/repositories`). Note that if `git_data_dirs` + is customized, check the directory layout on your server to be sure. - ```sh - cd /var/opt/gitlab/git-data/repositories - ``` + ```sh + cd /var/opt/gitlab/git-data/repositories + ``` 1. Run the following command on the **primary** node, redirecting the output to a file: diff --git a/doc/administration/geo/disaster_recovery/bring_primary_back.md b/doc/administration/geo/disaster_recovery/bring_primary_back.md index f4d31a98080..9a981b49349 100644 --- a/doc/administration/geo/disaster_recovery/bring_primary_back.md +++ b/doc/administration/geo/disaster_recovery/bring_primary_back.md @@ -21,20 +21,20 @@ To bring the former **primary** node up to date: 1. SSH into the former **primary** node that has fallen behind. 1. Make sure all the services are up: - ```sh - sudo gitlab-ctl start - ``` - - > **Note 1:** If you [disabled the **primary** node permanently][disaster-recovery-disable-primary], - > you need to undo those steps now. For Debian/Ubuntu you just need to run - > `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install - > the GitLab instance from scratch and set it up as a **secondary** node by - > following [Setup instructions][setup-geo]. In this case, you don't need to follow the next step. - > - > **Note 2:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record) - > for this node during disaster recovery procedure you may need to [block - > all the writes to this node](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/doc/gitlab-geo/planned-failover.md#block-primary-traffic) - > during this procedure. + ```sh + sudo gitlab-ctl start + ``` + + NOTE: **Note:** If you [disabled the **primary** node permanently][disaster-recovery-disable-primary], + you need to undo those steps now. For Debian/Ubuntu you just need to run + `sudo systemctl enable gitlab-runsvdir`. For CentOS 6, you need to install + the GitLab instance from scratch and set it up as a **secondary** node by + following [Setup instructions][setup-geo]. In this case, you don't need to follow the next step. + + NOTE: **Note:** If you [changed the DNS records](index.md#step-4-optional-updating-the-primary-domain-dns-record) + for this node during disaster recovery procedure you may need to [block + all the writes to this node](planned_failover.md#prevent-updates-to-the-primary-node) + during this procedure. 1. [Setup database replication][database-replication]. Note that in this case, **primary** node refers to the current **primary** node, and **secondary** node refers to the diff --git a/doc/administration/geo/disaster_recovery/index.md b/doc/administration/geo/disaster_recovery/index.md index 71dc797f281..86182b84062 100644 --- a/doc/administration/geo/disaster_recovery/index.md +++ b/doc/administration/geo/disaster_recovery/index.md @@ -39,48 +39,50 @@ must disable the **primary** node. 1. SSH into the **primary** node to stop and disable GitLab, if possible: - ```sh - sudo gitlab-ctl stop - ``` + ```sh + sudo gitlab-ctl stop + ``` - Prevent GitLab from starting up again if the server unexpectedly reboots: + Prevent GitLab from starting up again if the server unexpectedly reboots: - ```sh - sudo systemctl disable gitlab-runsvdir - ``` + ```sh + sudo systemctl disable gitlab-runsvdir + ``` - > **CentOS only**: In CentOS 6 or older, there is no easy way to prevent GitLab from being - > started if the machine reboots isn't available (see [gitlab-org/omnibus-gitlab#3058]). - > It may be safest to uninstall the GitLab package completely: + NOTE: **Note:** + (**CentOS only**) In CentOS 6 or older, there is no easy way to prevent GitLab from being + started if the machine reboots isn't available (see [gitlab-org/omnibus-gitlab#3058]). + It may be safest to uninstall the GitLab package completely: - ```sh - yum remove gitlab-ee - ``` + ```sh + yum remove gitlab-ee + ``` - > **Ubuntu 14.04 LTS**: If you are using an older version of Ubuntu - > or any other distro based on the Upstart init system, you can prevent GitLab - > from starting if the machine reboots by doing the following: + NOTE: **Note:** + (**Ubuntu 14.04 LTS**) If you are using an older version of Ubuntu + or any other distro based on the Upstart init system, you can prevent GitLab + from starting if the machine reboots by doing the following: - ```sh - initctl stop gitlab-runsvvdir - echo 'manual' > /etc/init/gitlab-runsvdir.override - initctl reload-configuration - ``` + ```sh + initctl stop gitlab-runsvvdir + echo 'manual' > /etc/init/gitlab-runsvdir.override + initctl reload-configuration + ``` 1. If you do not have SSH access to the **primary** node, take the machine offline and - prevent it from rebooting by any means at your disposal. - Since there are many ways you may prefer to accomplish this, we will avoid a - single recommendation. You may need to: - - Reconfigure the load balancers. - - Change DNS records (e.g., point the primary DNS record to the **secondary** - node in order to stop usage of the **primary** node). - - Stop the virtual servers. - - Block traffic through a firewall. - - Revoke object storage permissions from the **primary** node. - - Physically disconnect a machine. - -1. If you plan to - [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record), + prevent it from rebooting by any means at your disposal. + Since there are many ways you may prefer to accomplish this, we will avoid a + single recommendation. You may need to: + + - Reconfigure the load balancers. + - Change DNS records (e.g., point the primary DNS record to the **secondary** + node in order to stop usage of the **primary** node). + - Stop the virtual servers. + - Block traffic through a firewall. + - Revoke object storage permissions from the **primary** node. + - Physically disconnect a machine. + +1. If you plan to [update the primary domain DNS record](#step-4-optional-updating-the-primary-domain-dns-record), you may wish to lower the TTL now to speed up propagation. ### Step 3. Promoting a **secondary** node @@ -94,26 +96,26 @@ the **secondary** to the **primary**. 1. SSH in to your **secondary** node and login as root: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Edit `/etc/gitlab/gitlab.rb` to reflect its new status as **primary** by removing any lines that enabled the `geo_secondary_role`: - ```ruby - ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. - geo_secondary_role['enable'] = true + ```ruby + ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. + geo_secondary_role['enable'] = true - ## In 11.5+ documentation, the role was enabled as follows. Remove this line. - roles ['geo_secondary_role'] - ``` + ## In 11.5+ documentation, the role was enabled as follows. Remove this line. + roles ['geo_secondary_role'] + ``` 1. Promote the **secondary** node to the **primary** node. Execute: - ```sh - gitlab-ctl promote-to-primary-node - ``` + ```sh + gitlab-ctl promote-to-primary-node + ``` 1. Verify you can connect to the newly promoted **primary** node using the URL used previously for the **secondary** node. @@ -129,31 +131,31 @@ do this manually. 1. SSH in to the database node in the **secondary** and trigger PostgreSQL to promote to read-write: - ```bash - sudo gitlab-pg-ctl promote - ``` + ```bash + sudo gitlab-pg-ctl promote + ``` 1. Edit `/etc/gitlab/gitlab.rb` on every machine in the **secondary** to reflect its new status as **primary** by removing any lines that enabled the `geo_secondary_role`: - ```ruby - ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. - geo_secondary_role['enable'] = true + ```ruby + ## In pre-11.5 documentation, the role was enabled as follows. Remove this line. + geo_secondary_role['enable'] = true - ## In 11.5+ documentation, the role was enabled as follows. Remove this line. - roles ['geo_secondary_role'] - ``` + ## In 11.5+ documentation, the role was enabled as follows. Remove this line. + roles ['geo_secondary_role'] + ``` - After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) each - machine so the changes take effect. + After making these changes [Reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) each + machine so the changes take effect. 1. Promote the **secondary** to **primary**. SSH into a single application server and execute: - ```bash - sudo gitlab-rake geo:set_secondary_as_primary - ``` + ```bash + sudo gitlab-rake geo:set_secondary_as_primary + ``` 1. Verify you can connect to the newly promoted **primary** using the URL used previously for the **secondary**. @@ -167,37 +169,37 @@ secondary domain, like changing Git remotes and API URLs. 1. SSH into the **secondary** node and login as root: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Update the primary domain's DNS record. After updating the primary domain's DNS records to point to the **secondary** node, edit `/etc/gitlab/gitlab.rb` on the **secondary** node to reflect the new URL: - ```ruby - # Change the existing external_url configuration - external_url 'https://<new_external_url>' - ``` + ```ruby + # Change the existing external_url configuration + external_url 'https://<new_external_url>' + ``` - NOTE: **Note** - Changing `external_url` won't prevent access via the old secondary URL, as - long as the secondary DNS records are still intact. + NOTE: **Note** + Changing `external_url` won't prevent access via the old secondary URL, as + long as the secondary DNS records are still intact. 1. Reconfigure the **secondary** node for the change to take effect: - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` 1. Execute the command below to update the newly promoted **primary** node URL: - ```sh - gitlab-rake geo:update_primary_node_url - ``` + ```sh + gitlab-rake geo:update_primary_node_url + ``` - This command will use the changed `external_url` configuration defined - in `/etc/gitlab/gitlab.rb`. + This command will use the changed `external_url` configuration defined + in `/etc/gitlab/gitlab.rb`. 1. Verify you can connect to the newly promoted **primary** using its URL. If you updated the DNS records for the primary domain, these changes may @@ -231,62 +233,61 @@ and after that you also need two extra steps. 1. SSH into the new **primary** node and login as root: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Edit `/etc/gitlab/gitlab.rb` - ```ruby - ## Enable a Geo Primary role (if you haven't yet) - roles ['geo_primary_role'] + ```ruby + ## Enable a Geo Primary role (if you haven't yet) + roles ['geo_primary_role'] - ## - # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be - # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] - ## - postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32'] + ## + # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be + # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] + ## + postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32'] - # Every secondary server needs to have its own slot so specify the number of secondary nodes you're going to have - postgresql['max_replication_slots'] = 1 + # Every secondary server needs to have its own slot so specify the number of secondary nodes you're going to have + postgresql['max_replication_slots'] = 1 - ## - ## Disable automatic database migrations temporarily - ## (until PostgreSQL is restarted and listening on the private address). - ## - gitlab_rails['auto_migrate'] = false + ## + ## Disable automatic database migrations temporarily + ## (until PostgreSQL is restarted and listening on the private address). + ## + gitlab_rails['auto_migrate'] = false + ``` - ``` - - (For more details about these settings you can read [Configure the primary server][configure-the-primary-server]) + (For more details about these settings you can read [Configure the primary server][configure-the-primary-server]) 1. Save the file and reconfigure GitLab for the database listen changes and the replication slot changes to be applied. - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` - Restart PostgreSQL for its changes to take effect: + Restart PostgreSQL for its changes to take effect: - ```sh - gitlab-ctl restart postgresql - ``` + ```sh + gitlab-ctl restart postgresql + ``` 1. Re-enable migrations now that PostgreSQL is restarted and listening on the private address. - Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`: + Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`: - ```ruby - gitlab_rails['auto_migrate'] = true - ``` + ```ruby + gitlab_rails['auto_migrate'] = true + ``` - Save the file and reconfigure GitLab: + Save the file and reconfigure GitLab: - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` ### Step 2. Initiate the replication process diff --git a/doc/administration/geo/disaster_recovery/planned_failover.md b/doc/administration/geo/disaster_recovery/planned_failover.md index b8071b5993f..c1a95157f8d 100644 --- a/doc/administration/geo/disaster_recovery/planned_failover.md +++ b/doc/administration/geo/disaster_recovery/planned_failover.md @@ -143,26 +143,26 @@ access to the **primary** node during the maintenance window. all HTTP, HTTPS and SSH traffic to/from the **primary** node, **except** for your IP and the **secondary** node's IP. - For instance, you might run the following commands on the server(s) making up your **primary** node: + For instance, you might run the following commands on the server(s) making up your **primary** node: - ```sh - sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 22 -j ACCEPT - sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 22 -j ACCEPT - sudo iptables -A INPUT --destination-port 22 -j REJECT + ```sh + sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 22 -j ACCEPT + sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 22 -j ACCEPT + sudo iptables -A INPUT --destination-port 22 -j REJECT - sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 80 -j ACCEPT - sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 80 -j ACCEPT - sudo iptables -A INPUT --tcp-dport 80 -j REJECT + sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 80 -j ACCEPT + sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 80 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 80 -j REJECT - sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 443 -j ACCEPT - sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 443 -j ACCEPT - sudo iptables -A INPUT --tcp-dport 443 -j REJECT - ``` + sudo iptables -A INPUT -p tcp -s <secondary_node_ip> --destination-port 443 -j ACCEPT + sudo iptables -A INPUT -p tcp -s <your_ip> --destination-port 443 -j ACCEPT + sudo iptables -A INPUT --tcp-dport 443 -j REJECT + ``` - From this point, users will be unable to view their data or make changes on the - **primary** node. They will also be unable to log in to the **secondary** node. - However, existing sessions will work for the remainder of the maintenance period, and - public data will be accessible throughout. + From this point, users will be unable to view their data or make changes on the + **primary** node. They will also be unable to log in to the **secondary** node. + However, existing sessions will work for the remainder of the maintenance period, and + public data will be accessible throughout. 1. Verify the **primary** node is blocked to HTTP traffic by visiting it in browser via another IP. The server should refuse connection. @@ -187,10 +187,11 @@ access to the **primary** node during the maintenance window. before it is completed will cause the work to be lost. 1. On the **primary** node, navigate to **Admin Area > Geo** and wait for the following conditions to be true of the **secondary** node you are failing over to: - - All replication meters to each 100% replicated, 0% failures. - - All verification meters reach 100% verified, 0% failures. - - Database replication lag is 0ms. - - The Geo log cursor is up to date (0 events behind). + + - All replication meters to each 100% replicated, 0% failures. + - All verification meters reach 100% verified, 0% failures. + - Database replication lag is 0ms. + - The Geo log cursor is up to date (0 events behind). 1. On the **secondary** node, navigate to **Admin Area > Monitoring > Background Jobs > Queues** and wait for all the `geo` queues to drop to 0 queued and 0 running jobs. diff --git a/doc/administration/geo/replication/configuration.md b/doc/administration/geo/replication/configuration.md index 3d4f69d3abe..dd5e09c0dd7 100644 --- a/doc/administration/geo/replication/configuration.md +++ b/doc/administration/geo/replication/configuration.md @@ -16,11 +16,10 @@ The basic steps of configuring a **secondary** node are to: You are encouraged to first read through all the steps before executing them in your testing/production environment. -> **Notes:** -> - **Do not** setup any custom authentication for the **secondary** nodes. This will be - handled by the **primary** node. -> - Any change that requires access to the **Admin Area** needs to be done in the - **primary** node because the **secondary** node is a read-only replica. +NOTE: **Note:** +**Do not** set up any custom authentication for the **secondary** nodes. This will be handled by the **primary** node. +Any change that requires access to the **Admin Area** needs to be done in the +**primary** node because the **secondary** node is a read-only replica. ### Step 1. Manually replicate secret GitLab values @@ -31,47 +30,47 @@ they must be manually replicated to the **secondary** node. 1. SSH into the **primary** node, and execute the command below: - ```sh - sudo cat /etc/gitlab/gitlab-secrets.json - ``` + ```sh + sudo cat /etc/gitlab/gitlab-secrets.json + ``` - This will display the secrets that need to be replicated, in JSON format. + This will display the secrets that need to be replicated, in JSON format. 1. SSH into the **secondary** node and login as the `root` user: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Make a backup of any existing secrets: - ```sh - mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F` - ``` + ```sh + mv /etc/gitlab/gitlab-secrets.json /etc/gitlab/gitlab-secrets.json.`date +%F` + ``` 1. Copy `/etc/gitlab/gitlab-secrets.json` from the **primary** node to the **secondary** node, or copy-and-paste the file contents between nodes: - ```sh - sudo editor /etc/gitlab/gitlab-secrets.json + ```sh + sudo editor /etc/gitlab/gitlab-secrets.json - # paste the output of the `cat` command you ran on the primary - # save and exit - ``` + # paste the output of the `cat` command you ran on the primary + # save and exit + ``` 1. Ensure the file permissions are correct: - ```sh - chown root:root /etc/gitlab/gitlab-secrets.json - chmod 0600 /etc/gitlab/gitlab-secrets.json - ``` + ```sh + chown root:root /etc/gitlab/gitlab-secrets.json + chmod 0600 /etc/gitlab/gitlab-secrets.json + ``` 1. Reconfigure the **secondary** node for the change to take effect: - ```sh - gitlab-ctl reconfigure - gitlab-ctl restart - ``` + ```sh + gitlab-ctl reconfigure + gitlab-ctl restart + ``` ### Step 2. Manually replicate the **primary** node's SSH host keys @@ -89,80 +88,80 @@ keys must be manually replicated to the **secondary** node. 1. SSH into the **secondary** node and login as the `root` user: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Make a backup of any existing SSH host keys: - ```sh - find /etc/ssh -iname ssh_host_* -exec cp {} {}.backup.`date +%F` \; - ``` + ```sh + find /etc/ssh -iname ssh_host_* -exec cp {} {}.backup.`date +%F` \; + ``` 1. Copy OpenSSH host keys from the **primary** node: - If you can access your **primary** node using the **root** user: + If you can access your **primary** node using the **root** user: - ```sh - # Run this from the secondary node, change `<primary_node_fqdn>` for the IP or FQDN of the server - scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh - ``` + ```sh + # Run this from the secondary node, change `<primary_node_fqdn>` for the IP or FQDN of the server + scp root@<primary_node_fqdn>:/etc/ssh/ssh_host_*_key* /etc/ssh + ``` - If you only have access through a user with **sudo** privileges: + If you only have access through a user with **sudo** privileges: - ```sh - # Run this from your primary node: - sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key* + ```sh + # Run this from your primary node: + sudo tar --transform 's/.*\///g' -zcvf ~/geo-host-key.tar.gz /etc/ssh/ssh_host_*_key* - # Run this from your secondary node: - scp <user_with_sudo>@<primary_node_fqdn>:geo-host-key.tar.gz . - tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh - ``` + # Run this from your secondary node: + scp <user_with_sudo>@<primary_node_fqdn>:geo-host-key.tar.gz . + tar zxvf ~/geo-host-key.tar.gz -C /etc/ssh + ``` 1. On your **secondary** node, ensure the file permissions are correct: - ```sh - chown root:root /etc/ssh/ssh_host_*_key* - chmod 0600 /etc/ssh/ssh_host_*_key* - ``` + ```sh + chown root:root /etc/ssh/ssh_host_*_key* + chmod 0600 /etc/ssh/ssh_host_*_key* + ``` 1. To verify key fingerprint matches, execute the following command on both nodes: - ```sh - for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done - ``` + ```sh + for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done + ``` - You should get an output similar to this one and they should be identical on both nodes: + You should get an output similar to this one and they should be identical on both nodes: - ```sh - 1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA) - 256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA) - 256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519) - 2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA) - ``` + ```sh + 1024 SHA256:FEZX2jQa2bcsd/fn/uxBzxhKdx4Imc4raXrHwsbtP0M root@serverhostname (DSA) + 256 SHA256:uw98R35Uf+fYEQ/UnJD9Br4NXUFPv7JAUln5uHlgSeY root@serverhostname (ECDSA) + 256 SHA256:sqOUWcraZQKd89y/QQv/iynPTOGQxcOTIXU/LsoPmnM root@serverhostname (ED25519) + 2048 SHA256:qwa+rgir2Oy86QI+PZi/QVR+MSmrdrpsuH7YyKknC+s root@serverhostname (RSA) + ``` 1. Verify that you have the correct public keys for the existing private keys: - ```sh - # This will print the fingerprint for private keys: - for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done + ```sh + # This will print the fingerprint for private keys: + for file in /etc/ssh/ssh_host_*_key; do ssh-keygen -lf $file; done - # This will print the fingerprint for public keys: - for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done - ``` + # This will print the fingerprint for public keys: + for file in /etc/ssh/ssh_host_*_key.pub; do ssh-keygen -lf $file; done + ``` - NOTE: **Note**: - The output for private keys and public keys command should generate the same fingerprint. + NOTE: **Note:** + The output for private keys and public keys command should generate the same fingerprint. 1. Restart sshd on your **secondary** node: - ```sh - # Debian or Ubuntu installations - sudo service ssh reload + ```sh + # Debian or Ubuntu installations + sudo service ssh reload - # CentOS installations - sudo service sshd reload - ``` + # CentOS installations + sudo service sshd reload + ``` ### Step 3. Add the **secondary** node @@ -176,22 +175,22 @@ keys must be manually replicated to the **secondary** node. 1. Click the **Add node** button. 1. SSH into your GitLab **secondary** server and restart the services: - ```sh - gitlab-ctl restart - ``` + ```sh + gitlab-ctl restart + ``` - Check if there are any common issue with your Geo setup by running: + Check if there are any common issue with your Geo setup by running: - ```sh - gitlab-rake gitlab:geo:check - ``` + ```sh + gitlab-rake gitlab:geo:check + ``` 1. SSH into your **primary** server and login as root to verify the **secondary** node is reachable or there are any common issue with your Geo setup: - ```sh - gitlab-rake gitlab:geo:check - ``` + ```sh + gitlab-rake gitlab:geo:check + ``` Once added to the admin panel and restarted, the **secondary** node will automatically start replicating missing data from the **primary** node in a process known as **backfill**. @@ -250,9 +249,8 @@ The two most obvious issues that can become apparent in the dashboard are: 1. Database replication not working well. 1. Instance to instance notification not working. In that case, it can be something of the following: - - You are using a custom certificate or custom CA (see the - [troubleshooting document]). - - The instance is firewalled (check your firewall rules). + - You are using a custom certificate or custom CA (see the [troubleshooting document](troubleshooting.md)). + - The instance is firewalled (check your firewall rules). Please note that disabling a **secondary** node will stop the synchronization process. @@ -304,5 +302,4 @@ See the [troubleshooting document](troubleshooting.md). [gitlab-org/gitlab-ee#3789]: https://gitlab.com/gitlab-org/gitlab-ee/issues/3789 [gitlab-com/infrastructure#2821]: https://gitlab.com/gitlab-com/infrastructure/issues/2821 [omnibus-ssl]: https://docs.gitlab.com/omnibus/settings/ssl.html -[troubleshooting document]: troubleshooting.md [using-geo]: using_a_geo_server.md diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md index 6658c37752a..021ed2d9f3c 100644 --- a/doc/administration/geo/replication/database.md +++ b/doc/administration/geo/replication/database.md @@ -52,186 +52,188 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o 1. SSH into your GitLab **primary** server and login as root: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Execute the command below to define the node as **primary** node: - ```sh - gitlab-ctl set-geo-primary-node - ``` + ```sh + gitlab-ctl set-geo-primary-node + ``` - This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. + This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. 1. GitLab 10.4 and up only: Do the following to make sure the `gitlab` database user has a password defined: - Generate a MD5 hash of the desired password: + Generate a MD5 hash of the desired password: - ```sh - gitlab-ctl pg-password-md5 gitlab - # Enter password: <your_password_here> - # Confirm password: <your_password_here> - # fca0b89a972d69f00eb3ec98a5838484 - ``` + ```sh + gitlab-ctl pg-password-md5 gitlab + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # fca0b89a972d69f00eb3ec98a5838484 + ``` - Edit `/etc/gitlab/gitlab.rb`: + Edit `/etc/gitlab/gitlab.rb`: - ```ruby - # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - # Every node that runs Unicorn or Sidekiq needs to have the database - # password specified as below. If you have a high-availability setup, this - # must be present in all application nodes. - gitlab_rails['db_password'] = '<your_password_here>' - ``` + # Every node that runs Unicorn or Sidekiq needs to have the database + # password specified as below. If you have a high-availability setup, this + # must be present in all application nodes. + gitlab_rails['db_password'] = '<your_password_here>' + ``` 1. Omnibus GitLab already has a [replication user] called `gitlab_replicator`. You must set the password for this user manually. You will be prompted to enter a password: - ```sh - gitlab-ctl set-replication-password - ``` + ```sh + gitlab-ctl set-replication-password + ``` - This command will also read the `postgresql['sql_replication_user']` Omnibus - setting in case you have changed `gitlab_replicator` username to something - else. + This command will also read the `postgresql['sql_replication_user']` Omnibus + setting in case you have changed `gitlab_replicator` username to something + else. - If you are using an external database not managed by Omnibus GitLab, you need - to create the replicator user and define a password to it manually: + If you are using an external database not managed by Omnibus GitLab, you need + to create the replicator user and define a password to it manually: - ```sql - --- Create a new user 'replicator' - CREATE USER gitlab_replicator; + ```sql + --- Create a new user 'replicator' + CREATE USER gitlab_replicator; - --- Set/change a password and grants replication privilege - ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>'; - ``` + --- Set/change a password and grants replication privilege + ALTER USER gitlab_replicator WITH REPLICATION ENCRYPTED PASSWORD '<replication_password>'; + ``` 1. Configure PostgreSQL to listen on network interfaces: - For security reasons, PostgreSQL does not listen on any network interfaces - by default. However, Geo requires the **secondary** node to be able to - connect to the **primary** node's database. For this reason, we need the address of - each node. Note: For external PostgreSQL instances, see [additional instructions](external_database.md). - - If you are using a cloud provider, you can lookup the addresses for each - Geo node through your cloud provider's management console. - - To lookup the address of a Geo node, SSH in to the Geo node and execute: - - ```sh - ## - ## Private address - ## - ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}' - - ## - ## Public address - ## - echo "External address: $(curl --silent ipinfo.io/ip)" - ``` - - In most cases, the following addresses will be used to configure GitLab - Geo: - - | Configuration | Address | - |:----------------------------------------|:------------------------------------------------------| - | `postgresql['listen_address']` | **Primary** node's public or VPC private address. | - | `postgresql['md5_auth_cidr_addresses']` | **Secondary** node's public or VPC private addresses. | - - If you are using Google Cloud Platform, SoftLayer, or any other vendor that - provides a virtual private cloud (VPC) you can use the **secondary** node's private - address (corresponds to "internal address" for Google Cloud Platform) for - `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`. - - The `listen_address` option opens PostgreSQL up to network connections - with the interface corresponding to the given address. See [the PostgreSQL - documentation][pg-docs-runtime-conn] for more details. - - Depending on your network configuration, the suggested addresses may not - be correct. If your **primary** node and **secondary** nodes connect over a local - area network, or a virtual network connecting availability zones like - [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/) - you should use the **secondary** node's private address for `postgresql['md5_auth_cidr_addresses']`. - - Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP - addresses with addresses appropriate to your network configuration: - - ```ruby - ## - ## Geo Primary role - ## - configure dependent flags automatically to enable Geo - ## - roles ['geo_primary_role'] - - ## - ## Primary address - ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node - ## - postgresql['listen_address'] = '<primary_node_ip>' - - ## - # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be - # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] - ## - postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32'] - - ## - ## Replication settings - ## - set this to be the number of Geo secondary nodes you have - ## - postgresql['max_replication_slots'] = 1 - # postgresql['max_wal_senders'] = 10 - # postgresql['wal_keep_segments'] = 10 - - ## - ## Disable automatic database migrations temporarily - ## (until PostgreSQL is restarted and listening on the private address). - ## - gitlab_rails['auto_migrate'] = false - ``` + For security reasons, PostgreSQL does not listen on any network interfaces + by default. However, Geo requires the **secondary** node to be able to + connect to the **primary** node's database. For this reason, we need the address of + each node. + + NOTE: **Note:** For external PostgreSQL instances, see [additional instructions](external_database.md). + + If you are using a cloud provider, you can lookup the addresses for each + Geo node through your cloud provider's management console. + + To lookup the address of a Geo node, SSH in to the Geo node and execute: + + ```sh + ## + ## Private address + ## + ip route get 255.255.255.255 | awk '{print "Private address:", $NF; exit}' + + ## + ## Public address + ## + echo "External address: $(curl --silent ipinfo.io/ip)" + ``` + + In most cases, the following addresses will be used to configure GitLab + Geo: + + | Configuration | Address | + |:----------------------------------------|:------------------------------------------------------| + | `postgresql['listen_address']` | **Primary** node's public or VPC private address. | + | `postgresql['md5_auth_cidr_addresses']` | **Secondary** node's public or VPC private addresses. | + + If you are using Google Cloud Platform, SoftLayer, or any other vendor that + provides a virtual private cloud (VPC) you can use the **secondary** node's private + address (corresponds to "internal address" for Google Cloud Platform) for + `postgresql['md5_auth_cidr_addresses']` and `postgresql['listen_address']`. + + The `listen_address` option opens PostgreSQL up to network connections + with the interface corresponding to the given address. See [the PostgreSQL + documentation][pg-docs-runtime-conn] for more details. + + Depending on your network configuration, the suggested addresses may not + be correct. If your **primary** node and **secondary** nodes connect over a local + area network, or a virtual network connecting availability zones like + [Amazon's VPC](https://aws.amazon.com/vpc/) or [Google's VPC](https://cloud.google.com/vpc/) + you should use the **secondary** node's private address for `postgresql['md5_auth_cidr_addresses']`. + + Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP + addresses with addresses appropriate to your network configuration: + + ```ruby + ## + ## Geo Primary role + ## - configure dependent flags automatically to enable Geo + ## + roles ['geo_primary_role'] + + ## + ## Primary address + ## - replace '<primary_node_ip>' with the public or VPC address of your Geo primary node + ## + postgresql['listen_address'] = '<primary_node_ip>' + + ## + # Allow PostgreSQL client authentication from the primary and secondary IPs. These IPs may be + # public or VPC addresses in CIDR format, for example ['198.51.100.1/32', '198.51.100.2/32'] + ## + postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32'] + + ## + ## Replication settings + ## - set this to be the number of Geo secondary nodes you have + ## + postgresql['max_replication_slots'] = 1 + # postgresql['max_wal_senders'] = 10 + # postgresql['wal_keep_segments'] = 10 + + ## + ## Disable automatic database migrations temporarily + ## (until PostgreSQL is restarted and listening on the private address). + ## + gitlab_rails['auto_migrate'] = false + ``` 1. Optional: If you want to add another **secondary** node, the relevant setting would look like: - ```ruby - postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32', '<another_secondary_node_ip>/32'] - ``` + ```ruby + postgresql['md5_auth_cidr_addresses'] = ['<primary_node_ip>/32', '<secondary_node_ip>/32', '<another_secondary_node_ip>/32'] + ``` - You may also want to edit the `wal_keep_segments` and `max_wal_senders` to - match your database replication requirements. Consult the [PostgreSQL - - Replication documentation][pg-docs-runtime-replication] - for more information. + You may also want to edit the `wal_keep_segments` and `max_wal_senders` to + match your database replication requirements. Consult the [PostgreSQL - + Replication documentation][pg-docs-runtime-replication] + for more information. 1. Save the file and reconfigure GitLab for the database listen changes and the replication slot changes to be applied: - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` - Restart PostgreSQL for its changes to take effect: + Restart PostgreSQL for its changes to take effect: - ```sh - gitlab-ctl restart postgresql - ``` + ```sh + gitlab-ctl restart postgresql + ``` 1. Re-enable migrations now that PostgreSQL is restarted and listening on the private address. - Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`: + Edit `/etc/gitlab/gitlab.rb` and **change** the configuration to `true`: - ```ruby - gitlab_rails['auto_migrate'] = true - ``` + ```ruby + gitlab_rails['auto_migrate'] = true + ``` - Save the file and reconfigure GitLab: + Save the file and reconfigure GitLab: - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` 1. Now that the PostgreSQL server is set up to accept remote connections, run `netstat -plnt | grep 5432` to make sure that PostgreSQL is listening on port @@ -241,143 +243,143 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o will be used automatically to protect your PostgreSQL traffic from eavesdroppers, but to protect against active ("man-in-the-middle") attackers, the **secondary** node needs a copy of the certificate. Make a copy of the PostgreSQL - `server.crt` file on the **primary** node by running this command: + `server.crt` file on the **primary** node by running this command: - ```sh - cat ~gitlab-psql/data/server.crt - ``` + ```sh + cat ~gitlab-psql/data/server.crt + ``` - Copy the output into a clipboard or into a local file. You - will need it when setting up the **secondary** node! The certificate is not sensitive - data. + Copy the output into a clipboard or into a local file. You + will need it when setting up the **secondary** node! The certificate is not sensitive + data. ### Step 2. Configure the **secondary** server 1. SSH into your GitLab **secondary** server and login as root: - ``` - sudo -i - ``` + ``` + sudo -i + ``` 1. Stop application server and Sidekiq - ``` - gitlab-ctl stop unicorn - gitlab-ctl stop sidekiq - ``` + ``` + gitlab-ctl stop unicorn + gitlab-ctl stop sidekiq + ``` - NOTE: **Note**: - This step is important so we don't try to execute anything before the node is fully configured. + NOTE: **Note:** + This step is important so we don't try to execute anything before the node is fully configured. 1. [Check TCP connectivity][rake-maintenance] to the **primary** node's PostgreSQL server: - ```sh - gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432] - ``` + ```sh + gitlab-rake gitlab:tcp_check[<primary_node_ip>,5432] + ``` - NOTE: **Note**: - If this step fails, you may be using the wrong IP address, or a firewall may - be preventing access to the server. Check the IP address, paying close - attention to the difference between public and private addresses and ensure - that, if a firewall is present, the **secondary** node is permitted to connect to the - **primary** node on port 5432. + NOTE: **Note:** + If this step fails, you may be using the wrong IP address, or a firewall may + be preventing access to the server. Check the IP address, paying close + attention to the difference between public and private addresses and ensure + that, if a firewall is present, the **secondary** node is permitted to connect to the + **primary** node on port 5432. 1. Create a file `server.crt` in the **secondary** server, with the content you got on the last step of the **primary** node's setup: - ``` - editor server.crt - ``` + ``` + editor server.crt + ``` 1. Set up PostgreSQL TLS verification on the **secondary** node: - Install the `server.crt` file: + Install the `server.crt` file: - ```sh - install \ - -D \ - -o gitlab-psql \ - -g gitlab-psql \ - -m 0400 \ - -T server.crt ~gitlab-psql/.postgresql/root.crt - ``` + ```sh + install \ + -D \ + -o gitlab-psql \ + -g gitlab-psql \ + -m 0400 \ + -T server.crt ~gitlab-psql/.postgresql/root.crt + ``` - PostgreSQL will now only recognize that exact certificate when verifying TLS - connections. The certificate can only be replicated by someone with access - to the private key, which is **only** present on the **primary** node. + PostgreSQL will now only recognize that exact certificate when verifying TLS + connections. The certificate can only be replicated by someone with access + to the private key, which is **only** present on the **primary** node. 1. Test that the `gitlab-psql` user can connect to the **primary** node's database (the default Omnibus database name is gitlabhq_production): - ```sh - sudo \ - -u gitlab-psql /opt/gitlab/embedded/bin/psql \ - --list \ - -U gitlab_replicator \ - -d "dbname=gitlabhq_production sslmode=verify-ca" \ - -W \ - -h <primary_node_ip> - ``` + ```sh + sudo \ + -u gitlab-psql /opt/gitlab/embedded/bin/psql \ + --list \ + -U gitlab_replicator \ + -d "dbname=gitlabhq_production sslmode=verify-ca" \ + -W \ + -h <primary_node_ip> + ``` - When prompted enter the password you set in the first step for the - `gitlab_replicator` user. If all worked correctly, you should see - the list of **primary** node's databases. + When prompted enter the password you set in the first step for the + `gitlab_replicator` user. If all worked correctly, you should see + the list of **primary** node's databases. - A failure to connect here indicates that the TLS configuration is incorrect. - Ensure that the contents of `~gitlab-psql/data/server.crt` on the **primary** node - match the contents of `~gitlab-psql/.postgresql/root.crt` on the **secondary** node. + A failure to connect here indicates that the TLS configuration is incorrect. + Ensure that the contents of `~gitlab-psql/data/server.crt` on the **primary** node + match the contents of `~gitlab-psql/.postgresql/root.crt` on the **secondary** node. 1. Configure PostgreSQL to enable FDW support: - This step is similar to how we configured the **primary** instance. - We need to enable this, to enable FDW support, even if using a single node. - - Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP - addresses with addresses appropriate to your network configuration: - - ```ruby - ## - ## Geo Secondary role - ## - configure dependent flags automatically to enable Geo - ## - roles ['geo_secondary_role'] - - ## - ## Secondary address - ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node - ## - postgresql['listen_address'] = '<secondary_node_ip>' - postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] - - ## - ## Database credentials password (defined previously in primary node) - ## - replicate same values here as defined in primary node - ## - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - gitlab_rails['db_password'] = '<your_password_here>' - - ## - ## Enable FDW support for the Geo Tracking Database (improves performance) - ## - geo_secondary['db_fdw'] = true - ``` - - For external PostgreSQL instances, see [additional instructions](external_database.md). - If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`. + This step is similar to how we configured the **primary** instance. + We need to enable this, to enable FDW support, even if using a single node. + + Edit `/etc/gitlab/gitlab.rb` and add the following, replacing the IP + addresses with addresses appropriate to your network configuration: + + ```ruby + ## + ## Geo Secondary role + ## - configure dependent flags automatically to enable Geo + ## + roles ['geo_secondary_role'] + + ## + ## Secondary address + ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node + ## + postgresql['listen_address'] = '<secondary_node_ip>' + postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] + + ## + ## Database credentials password (defined previously in primary node) + ## - replicate same values here as defined in primary node + ## + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + gitlab_rails['db_password'] = '<your_password_here>' + + ## + ## Enable FDW support for the Geo Tracking Database (improves performance) + ## + geo_secondary['db_fdw'] = true + ``` + + For external PostgreSQL instances, see [additional instructions](external_database.md). + If you bring a former **primary** node back online to serve as a **secondary** node, then you also need to remove `roles ['geo_primary_role']` or `geo_primary_role['enable'] = true`. 1. Reconfigure GitLab for the changes to take effect: - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` 1. Restart PostgreSQL for the IP change to take effect and reconfigure again: - ```sh - gitlab-ctl restart postgresql - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl restart postgresql + gitlab-ctl reconfigure + ``` - This last reconfigure will provision the FDW configuration and enable it. + This last reconfigure will provision the FDW configuration and enable it. ### Step 3. Initiate the replication process @@ -394,9 +396,9 @@ data before running `pg_basebackup`. 1. SSH into your GitLab **secondary** server and login as root: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Choose a database-friendly name to use for your **secondary** node to use as the replication slot name. For example, if your domain is @@ -404,38 +406,40 @@ data before running `pg_basebackup`. name as shown in the commands below. 1. Execute the command below to start a backup/restore and begin the replication - CAUTION: **Warning:** Each Geo **secondary** node must have its own unique replication slot name. - Using the same slot name between two secondaries will break PostgreSQL replication. - - ```sh - gitlab-ctl replicate-geo-database \ - --slot-name=<secondary_node_name> \ - --host=<primary_node_ip> - ``` - - When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator` - user in the first step. - - This command also takes a number of additional options. You can use `--help` - to list them all, but here are a couple of tips: - - If PostgreSQL is listening on a non-standard port, add `--port=` as well. - - If your database is too large to be transferred in 30 minutes, you will need - to increase the timeout, e.g., `--backup-timeout=3600` if you expect the - initial replication to take under an hour. - - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether - (e.g., you know the network path is secure, or you are using a site-to-site - VPN). This is **not** safe over the public Internet! - - You can read more details about each `sslmode` in the - [PostgreSQL documentation][pg-docs-ssl]; - the instructions above are carefully written to ensure protection against - both passive eavesdroppers and active "man-in-the-middle" attackers. - - Change the `--slot-name` to the name of the replication slot - to be used on the **primary** database. The script will attempt to create the - replication slot automatically if it does not exist. - - If you're repurposing an old server into a Geo **secondary** node, you'll need to - add `--force` to the command line. - - When not in a production machine you can disable backup step if you - really sure this is what you want by adding `--skip-backup` + + CAUTION: **Warning:** Each Geo **secondary** node must have its own unique replication slot name. + Using the same slot name between two secondaries will break PostgreSQL replication. + + ```sh + gitlab-ctl replicate-geo-database \ + --slot-name=<secondary_node_name> \ + --host=<primary_node_ip> + ``` + + When prompted, enter the _plaintext_ password you set up for the `gitlab_replicator` + user in the first step. + + This command also takes a number of additional options. You can use `--help` + to list them all, but here are a couple of tips: + + - If PostgreSQL is listening on a non-standard port, add `--port=` as well. + - If your database is too large to be transferred in 30 minutes, you will need + to increase the timeout, e.g., `--backup-timeout=3600` if you expect the + initial replication to take under an hour. + - Pass `--sslmode=disable` to skip PostgreSQL TLS authentication altogether + (e.g., you know the network path is secure, or you are using a site-to-site + VPN). This is **not** safe over the public Internet! + - You can read more details about each `sslmode` in the + [PostgreSQL documentation][pg-docs-ssl]; + the instructions above are carefully written to ensure protection against + both passive eavesdroppers and active "man-in-the-middle" attackers. + - Change the `--slot-name` to the name of the replication slot + to be used on the **primary** database. The script will attempt to create the + replication slot automatically if it does not exist. + - If you're repurposing an old server into a Geo **secondary** node, you'll need to + add `--force` to the command line. + - When not in a production machine you can disable backup step if you + really sure this is what you want by adding `--skip-backup` The replication process is now complete. @@ -452,42 +456,42 @@ it will need a separate read-only user to make [PostgreSQL FDW queries][FDW] work: 1. On the **primary** Geo database, enter the PostgreSQL on the console as an - admin user. If you are using an Omnibus-managed database, log onto the **primary** - node that is running the PostgreSQL database (the default Omnibus database name is gitlabhq_production): + admin user. If you are using an Omnibus-managed database, log onto the **primary** + node that is running the PostgreSQL database (the default Omnibus database name is gitlabhq_production): - ```sh - sudo \ - -u gitlab-psql /opt/gitlab/embedded/bin/psql \ - -h /var/opt/gitlab/postgresql gitlabhq_production - ``` + ```sh + sudo \ + -u gitlab-psql /opt/gitlab/embedded/bin/psql \ + -h /var/opt/gitlab/postgresql gitlabhq_production + ``` 1. Then create the read-only user: - ```sql - -- NOTE: Use the password defined earlier - CREATE USER gitlab_geo_fdw WITH password 'mypassword'; - GRANT CONNECT ON DATABASE gitlabhq_production to gitlab_geo_fdw; - GRANT USAGE ON SCHEMA public TO gitlab_geo_fdw; - GRANT SELECT ON ALL TABLES IN SCHEMA public TO gitlab_geo_fdw; - GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO gitlab_geo_fdw; + ```sql + -- NOTE: Use the password defined earlier + CREATE USER gitlab_geo_fdw WITH password 'mypassword'; + GRANT CONNECT ON DATABASE gitlabhq_production to gitlab_geo_fdw; + GRANT USAGE ON SCHEMA public TO gitlab_geo_fdw; + GRANT SELECT ON ALL TABLES IN SCHEMA public TO gitlab_geo_fdw; + GRANT SELECT ON ALL SEQUENCES IN SCHEMA public TO gitlab_geo_fdw; - -- Tables created by "gitlab" should be made read-only for "gitlab_geo_fdw" - -- automatically. - ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON TABLES TO gitlab_geo_fdw; - ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON SEQUENCES TO gitlab_geo_fdw; - ``` + -- Tables created by "gitlab" should be made read-only for "gitlab_geo_fdw" + -- automatically. + ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON TABLES TO gitlab_geo_fdw; + ALTER DEFAULT PRIVILEGES FOR USER gitlab IN SCHEMA public GRANT SELECT ON SEQUENCES TO gitlab_geo_fdw; + ``` 1. On the **secondary** nodes, change `/etc/gitlab/gitlab.rb`: - ``` - geo_postgresql['fdw_external_user'] = 'gitlab_geo_fdw' - ``` + ``` + geo_postgresql['fdw_external_user'] = 'gitlab_geo_fdw' + ``` 1. Save the file and reconfigure GitLab for the changes to be applied: - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` ## Troubleshooting diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md index 177ca68613e..452e4f490a6 100644 --- a/doc/administration/geo/replication/external_database.md +++ b/doc/administration/geo/replication/external_database.md @@ -4,7 +4,7 @@ This document is relevant if you are using a PostgreSQL instance that is *not managed by Omnibus*. This includes cloud-managed instances like AWS RDS, or manually installed and configured PostgreSQL instances. -NOTE: **Note**: +NOTE: **Note:** We strongly recommend running Omnibus-managed instances as they are actively developed and tested. We aim to be compatible with most external (not managed by Omnibus) databases but we do not guarantee compatibility. @@ -13,17 +13,17 @@ developed and tested. We aim to be compatible with most external 1. SSH into a GitLab **primary** application server and login as root: - ```sh - sudo -i - ``` + ```sh + sudo -i + ``` 1. Execute the command below to define the node as **primary** node: - ```sh - gitlab-ctl set-geo-primary-node - ``` + ```sh + gitlab-ctl set-geo-primary-node + ``` - This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. + This command will use your defined `external_url` in `/etc/gitlab/gitlab.rb`. ### Configure the external database to be replicated @@ -101,26 +101,27 @@ To configure the connection to the external read-replica database and enable Log 1. SSH into a GitLab **secondary** application server and login as root: - ```bash - sudo -i - ``` + ```bash + sudo -i + ``` 1. Edit `/etc/gitlab/gitlab.rb` and add the following - ```ruby - ## - ## Geo Secondary role - ## - configure dependent flags automatically to enable Geo - ## - roles ['geo_secondary_role'] + ```ruby + ## + ## Geo Secondary role + ## - configure dependent flags automatically to enable Geo + ## + roles ['geo_secondary_role'] + + # note this is shared between both databases, + # make sure you define the same password in both + gitlab_rails['db_password'] = '<your_password_here>' - # note this is shared between both databases, - # make sure you define the same password in both - gitlab_rails['db_password'] = '<your_password_here>' + gitlab_rails['db_username'] = 'gitlab' + gitlab_rails['db_host'] = '<database_read_replica_host>' + ``` - gitlab_rails['db_username'] = 'gitlab' - gitlab_rails['db_host'] = '<database_read_replica_host>' - ``` 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) ### Configure the tracking database @@ -147,73 +148,72 @@ the tracking database on port 5432. 1. SSH into a GitLab **secondary** server and login as root: - ```bash - sudo -i - ``` + ```bash + sudo -i + ``` 1. Edit `/etc/gitlab/gitlab.rb` with the connection params and credentials for - the machine with the PostgreSQL instance: + the machine with the PostgreSQL instance: - ```ruby - geo_secondary['db_username'] = 'gitlab_geo' - geo_secondary['db_password'] = '<your_password_here>' + ```ruby + geo_secondary['db_username'] = 'gitlab_geo' + geo_secondary['db_password'] = '<your_password_here>' - geo_secondary['db_host'] = '<tracking_database_host>' - geo_secondary['db_port'] = <tracking_database_port> # change to the correct port - geo_secondary['db_fdw'] = true # enable FDW - geo_postgresql['enable'] = false # don't use internal managed instance - ``` + geo_secondary['db_host'] = '<tracking_database_host>' + geo_secondary['db_port'] = <tracking_database_port> # change to the correct port + geo_secondary['db_fdw'] = true # enable FDW + geo_postgresql['enable'] = false # don't use internal managed instance + ``` 1. Save the file and [reconfigure GitLab](../../restart_gitlab.md#omnibus-gitlab-reconfigure) 1. Run the tracking database migrations: - ```bash - gitlab-rake geo:db:create - gitlab-rake geo:db:migrate - ``` - -1. Configure the - [PostgreSQL FDW](https://www.postgresql.org/docs/9.6/static/postgres-fdw.html) - connection and credentials: - - Save the script below in a file, ex. `/tmp/geo_fdw.sh` and modify the connection - params to match your environment. Execute it to set up the FDW connection. - - ```bash - #!/bin/bash - - # Secondary Database connection params: - DB_HOST="<public_ip_or_vpc_private_ip>" - DB_NAME="gitlabhq_production" - DB_USER="gitlab" - DB_PASS="<your_password_here>" - DB_PORT="5432" - - # Tracking Database connection params: - GEO_DB_HOST="<public_ip_or_vpc_private_ip>" - GEO_DB_NAME="gitlabhq_geo_production" - GEO_DB_USER="gitlab_geo" - GEO_DB_PORT="5432" - - query_exec () { - gitlab-psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "${1}" - } - - query_exec "CREATE EXTENSION postgres_fdw;" - query_exec "CREATE SERVER gitlab_secondary FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host '${DB_HOST}', dbname '${DB_NAME}', port '${DB_PORT}');" - query_exec "CREATE USER MAPPING FOR ${GEO_DB_USER} SERVER gitlab_secondary OPTIONS (user '${DB_USER}', password '${DB_PASS}');" - query_exec "CREATE SCHEMA gitlab_secondary;" - query_exec "GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO ${GEO_DB_USER};" - ``` - - NOTE: **Note:** The script template above uses `gitlab-psql` as it's intended to be executed from the Geo machine, - but you can change it to `psql` and run it from any machine that has access to the database. We also recommend using - `psql` for AWS RDS. + ```bash + gitlab-rake geo:db:create + gitlab-rake geo:db:migrate + ``` + +1. Configure the [PostgreSQL FDW](https://www.postgresql.org/docs/9.6/static/postgres-fdw.html) + connection and credentials: + + Save the script below in a file, ex. `/tmp/geo_fdw.sh` and modify the connection + params to match your environment. Execute it to set up the FDW connection. + + ```bash + #!/bin/bash + + # Secondary Database connection params: + DB_HOST="<public_ip_or_vpc_private_ip>" + DB_NAME="gitlabhq_production" + DB_USER="gitlab" + DB_PASS="<your_password_here>" + DB_PORT="5432" + + # Tracking Database connection params: + GEO_DB_HOST="<public_ip_or_vpc_private_ip>" + GEO_DB_NAME="gitlabhq_geo_production" + GEO_DB_USER="gitlab_geo" + GEO_DB_PORT="5432" + + query_exec () { + gitlab-psql -h $GEO_DB_HOST -d $GEO_DB_NAME -p $GEO_DB_PORT -c "${1}" + } + + query_exec "CREATE EXTENSION postgres_fdw;" + query_exec "CREATE SERVER gitlab_secondary FOREIGN DATA WRAPPER postgres_fdw OPTIONS (host '${DB_HOST}', dbname '${DB_NAME}', port '${DB_PORT}');" + query_exec "CREATE USER MAPPING FOR ${GEO_DB_USER} SERVER gitlab_secondary OPTIONS (user '${DB_USER}', password '${DB_PASS}');" + query_exec "CREATE SCHEMA gitlab_secondary;" + query_exec "GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO ${GEO_DB_USER};" + ``` + + NOTE: **Note:** The script template above uses `gitlab-psql` as it's intended to be executed from the Geo machine, + but you can change it to `psql` and run it from any machine that has access to the database. We also recommend using + `psql` for AWS RDS. 1. Save the file and [restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) 1. Populate the FDW tables: - ```bash - gitlab-rake geo:db:refresh_foreign_tables - ``` + ```bash + gitlab-rake geo:db:refresh_foreign_tables + ``` diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md index 28ad89c4446..61e18df2480 100644 --- a/doc/administration/geo/replication/high_availability.md +++ b/doc/administration/geo/replication/high_availability.md @@ -50,17 +50,17 @@ The following steps enable a GitLab cluster to serve as the **primary** node. 1. Edit `/etc/gitlab/gitlab.rb` and add the following: - ```ruby - ## - ## Enable the Geo primary role - ## - roles ['geo_primary_role'] - - ## - ## Disable automatic migrations - ## - gitlab_rails['auto_migrate'] = false - ``` + ```ruby + ## + ## Enable the Geo primary role + ## + roles ['geo_primary_role'] + + ## + ## Disable automatic migrations + ## + gitlab_rails['auto_migrate'] = false + ``` After making these changes, [reconfigure GitLab][gitlab-reconfigure] so the changes take effect. @@ -107,36 +107,36 @@ Configure the [**secondary** database](database.md) as a read-only replica of the **primary** database. Use the following as a guide. 1. Edit `/etc/gitlab/gitlab.rb` in the replica database machine, and add the - following: - - ```ruby - ## - ## Configure the PostgreSQL role - ## - roles ['postgres_role'] - - ## - ## Secondary address - ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node - ## - replace '<tracking_database_ip>' with the public or VPC address of your Geo tracking database node - ## - postgresql['listen_address'] = '<secondary_node_ip>' - postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32', '<tracking_database_ip>/32'] - - ## - ## Database credentials password (defined previously in primary node) - ## - replicate same values here as defined in primary node - ## - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - gitlab_rails['db_password'] = '<your_password_here>' - - ## - ## When running the Geo tracking database on a separate machine, disable it - ## here and allow connections from the tracking database host. And ensure - ## the tracking database IP is in postgresql['md5_auth_cidr_addresses'] above. - ## - geo_postgresql['enable'] = false - ``` + following: + + ```ruby + ## + ## Configure the PostgreSQL role + ## + roles ['postgres_role'] + + ## + ## Secondary address + ## - replace '<secondary_node_ip>' with the public or VPC address of your Geo secondary node + ## - replace '<tracking_database_ip>' with the public or VPC address of your Geo tracking database node + ## + postgresql['listen_address'] = '<secondary_node_ip>' + postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32', '<tracking_database_ip>/32'] + + ## + ## Database credentials password (defined previously in primary node) + ## - replicate same values here as defined in primary node + ## + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + gitlab_rails['db_password'] = '<your_password_here>' + + ## + ## When running the Geo tracking database on a separate machine, disable it + ## here and allow connections from the tracking database host. And ensure + ## the tracking database IP is in postgresql['md5_auth_cidr_addresses'] above. + ## + geo_postgresql['enable'] = false + ``` After making these changes, [reconfigure GitLab][gitlab-reconfigure] so the changes take effect. @@ -151,47 +151,47 @@ only a single machine, rather than as a PostgreSQL cluster. Configure the tracking database. 1. Edit `/etc/gitlab/gitlab.rb` in the tracking database machine, and add the - following: - - ```ruby - ## - ## Enable the Geo secondary tracking database - ## - geo_postgresql['enable'] = true - geo_postgresql['listen_address'] = '<ip_address_of_this_host>' - geo_postgresql['sql_user_password'] = '<tracking_database_password_md5_hash>' - - ## - ## Configure FDW connection to the replica database - ## - geo_secondary['db_fdw'] = true - geo_postgresql['fdw_external_password'] = '<replica_database_password_plaintext>' - geo_postgresql['md5_auth_cidr_addresses'] = ['<replica_database_ip>/32'] - gitlab_rails['db_host'] = '<replica_database_ip>' - - # Prevent reconfigure from attempting to run migrations on the replica DB - gitlab_rails['auto_migrate'] = false - - ## - ## Disable all other services that aren't needed, since we don't have a role - ## that does this. - ## - alertmanager['enable'] = false - consul['enable'] = false - gitaly['enable'] = false - gitlab_monitor['enable'] = false - gitlab_workhorse['enable'] = false - nginx['enable'] = false - node_exporter['enable'] = false - pgbouncer_exporter['enable'] = false - postgresql['enable'] = false - prometheus['enable'] = false - redis['enable'] = false - redis_exporter['enable'] = false - repmgr['enable'] = false - sidekiq['enable'] = false - unicorn['enable'] = false - ``` + following: + + ```ruby + ## + ## Enable the Geo secondary tracking database + ## + geo_postgresql['enable'] = true + geo_postgresql['listen_address'] = '<ip_address_of_this_host>' + geo_postgresql['sql_user_password'] = '<tracking_database_password_md5_hash>' + + ## + ## Configure FDW connection to the replica database + ## + geo_secondary['db_fdw'] = true + geo_postgresql['fdw_external_password'] = '<replica_database_password_plaintext>' + geo_postgresql['md5_auth_cidr_addresses'] = ['<replica_database_ip>/32'] + gitlab_rails['db_host'] = '<replica_database_ip>' + + # Prevent reconfigure from attempting to run migrations on the replica DB + gitlab_rails['auto_migrate'] = false + + ## + ## Disable all other services that aren't needed, since we don't have a role + ## that does this. + ## + alertmanager['enable'] = false + consul['enable'] = false + gitaly['enable'] = false + gitlab_monitor['enable'] = false + gitlab_workhorse['enable'] = false + nginx['enable'] = false + node_exporter['enable'] = false + pgbouncer_exporter['enable'] = false + postgresql['enable'] = false + prometheus['enable'] = false + redis['enable'] = false + redis_exporter['enable'] = false + repmgr['enable'] = false + sidekiq['enable'] = false + unicorn['enable'] = false + ``` After making these changes, [reconfigure GitLab][gitlab-reconfigure] so the changes take effect. @@ -211,50 +211,50 @@ following modifications: 1. Edit `/etc/gitlab/gitlab.rb` on each application server in the **secondary** cluster, and add the following: - ```ruby - ## - ## Enable the Geo secondary role - ## - roles ['geo_secondary_role', 'application_role'] - - ## - ## Disable automatic migrations - ## - gitlab_rails['auto_migrate'] = false - - ## - ## Configure the connection to the tracking DB. And disable application - ## servers from running tracking databases. - ## - geo_secondary['db_host'] = '<geo_tracking_db_host>' - geo_secondary['db_password'] = '<geo_tracking_db_password>' - geo_postgresql['enable'] = false - - ## - ## Configure connection to the streaming replica database, if you haven't - ## already - ## - gitlab_rails['db_host'] = '<replica_database_host>' - gitlab_rails['db_password'] = '<replica_database_password>' - - ## - ## Configure connection to Redis, if you haven't already - ## - gitlab_rails['redis_host'] = '<redis_host>' - gitlab_rails['redis_password'] = '<redis_password>' - - ## - ## If you are using custom users not managed by Omnibus, you need to specify - ## UIDs and GIDs like below, and ensure they match between servers in a - ## cluster to avoid permissions issues - ## - user['uid'] = 9000 - user['gid'] = 9000 - web_server['uid'] = 9001 - web_server['gid'] = 9001 - registry['uid'] = 9002 - registry['gid'] = 9002 - ``` + ```ruby + ## + ## Enable the Geo secondary role + ## + roles ['geo_secondary_role', 'application_role'] + + ## + ## Disable automatic migrations + ## + gitlab_rails['auto_migrate'] = false + + ## + ## Configure the connection to the tracking DB. And disable application + ## servers from running tracking databases. + ## + geo_secondary['db_host'] = '<geo_tracking_db_host>' + geo_secondary['db_password'] = '<geo_tracking_db_password>' + geo_postgresql['enable'] = false + + ## + ## Configure connection to the streaming replica database, if you haven't + ## already + ## + gitlab_rails['db_host'] = '<replica_database_host>' + gitlab_rails['db_password'] = '<replica_database_password>' + + ## + ## Configure connection to Redis, if you haven't already + ## + gitlab_rails['redis_host'] = '<redis_host>' + gitlab_rails['redis_password'] = '<redis_password>' + + ## + ## If you are using custom users not managed by Omnibus, you need to specify + ## UIDs and GIDs like below, and ensure they match between servers in a + ## cluster to avoid permissions issues + ## + user['uid'] = 9000 + user['gid'] = 9000 + web_server['uid'] = 9001 + web_server['gid'] = 9001 + registry['uid'] = 9002 + registry['gid'] = 9002 + ``` NOTE: **Note:** If you had set up PostgreSQL cluster using the omnibus package and you had set diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index 54377f7ae4e..8e1d1cb46ba 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -80,8 +80,8 @@ In this diagram: - If present, the [LDAP server](#ldap) should be configured to replicate for [Disaster Recovery](../disaster_recovery/index.md) scenarios. - A **secondary** node performs different type of synchronizations against the **primary** node, using a special authorization protected by JWT: - - Repositories are cloned/updated via Git over HTTPS. - - Attachments, LFS objects, and other files are downloaded via HTTPS using a private API endpoint. + - Repositories are cloned/updated via Git over HTTPS. + - Attachments, LFS objects, and other files are downloaded via HTTPS using a private API endpoint. From the perspective of a user performing Git operations: @@ -107,8 +107,8 @@ The following are required to run Geo: - An operating system that supports OpenSSH 6.9+ (needed for [fast lookup of authorized SSH keys in the database](../../operations/fast_ssh_key_lookup.md)) The following operating systems are known to ship with a current version of OpenSSH: - - [CentOS](https://www.centos.org) 7.4+ - - [Ubuntu](https://www.ubuntu.com) 16.04+ + - [CentOS](https://www.centos.org) 7.4+ + - [Ubuntu](https://www.ubuntu.com) 16.04+ - PostgreSQL 9.6+ with [FDW](https://www.postgresql.org/docs/9.6/postgres-fdw.html) support and [Streaming Replication](https://wiki.postgresql.org/wiki/Streaming_Replication) - Git 2.9+ diff --git a/doc/administration/geo/replication/remove_geo_node.md b/doc/administration/geo/replication/remove_geo_node.md index b190fe7d42d..6bdaad8f783 100644 --- a/doc/administration/geo/replication/remove_geo_node.md +++ b/doc/administration/geo/replication/remove_geo_node.md @@ -10,41 +10,42 @@ Once removed from the Geo admin page, you must stop and uninstall the **secondar 1. On the **secondary** node, stop GitLab: - ```bash - sudo gitlab-ctl stop - ``` + ```bash + sudo gitlab-ctl stop + ``` + 1. On the **secondary** node, uninstall GitLab: - ```bash - # Stop gitlab and remove its supervision process - sudo gitlab-ctl uninstall + ```bash + # Stop gitlab and remove its supervision process + sudo gitlab-ctl uninstall - # Debian/Ubuntu - sudo dpkg --remove gitlab-ee + # Debian/Ubuntu + sudo dpkg --remove gitlab-ee - # Redhat/Centos - sudo rpm --erase gitlab-ee - ``` + # Redhat/Centos + sudo rpm --erase gitlab-ee + ``` Once GitLab has been uninstalled from the **secondary** node, the replication slot must be dropped from the **primary** node's database as follows: 1. On the **primary** node, start a PostgreSQL console session: - ```bash - sudo gitlab-psql - ``` + ```bash + sudo gitlab-psql + ``` - NOTE: **Note:** - Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. + NOTE: **Note:** + Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. 1. Find the name of the relevant replication slot. This is the slot that is specified with `--slot-name` when running the replicate command: `gitlab-ctl replicate-geo-database`. - ```sql - SELECT * FROM pg_replication_slots; - ``` + ```sql + SELECT * FROM pg_replication_slots; + ``` 1. Remove the replication slot for the **secondary** node: - ```sql - SELECT pg_drop_replication_slot('<name_of_slot>'); - ``` + ```sql + SELECT pg_drop_replication_slot('<name_of_slot>'); + ``` diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 5bd6cc81362..c7c78407084 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -184,17 +184,17 @@ log data to build up in `pg_xlog`. Removing the unused slots can reduce the amou 1. Start a PostgreSQL console session: - ```sh - sudo gitlab-psql gitlabhq_production - ``` + ```sh + sudo gitlab-psql gitlabhq_production + ``` - > Note that using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. + Note: **Note:** Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. 1. View your replication slots with: - ```sql - SELECT * FROM pg_replication_slots; - ``` + ```sql + SELECT * FROM pg_replication_slots; + ``` Slots where `active` is `f` are not active. @@ -204,9 +204,9 @@ Slots where `active` is `f` are not active. - If you are no longer using the slot (e.g. you no longer have Geo enabled), you can remove it with in the PostgreSQL console session: - ```sql - SELECT pg_drop_replication_slot('<name_of_extra_slot>'); - ``` + ```sql + SELECT pg_drop_replication_slot('<name_of_extra_slot>'); + ``` ### Very large repositories never successfully synchronize on the **secondary** node @@ -237,82 +237,82 @@ to start again from scratch, there are a few steps that can help you: 1. Stop Sidekiq and the Geo LogCursor - It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and - wait until the current jobs to finish processing. + It's possible to make Sidekiq stop gracefully, but making it stop getting new jobs and + wait until the current jobs to finish processing. - You need to send a **SIGTSTP** kill signal for the first phase and them a **SIGTERM** - when all jobs have finished. Otherwise just use the `gitlab-ctl stop` commands. + You need to send a **SIGTSTP** kill signal for the first phase and them a **SIGTERM** + when all jobs have finished. Otherwise just use the `gitlab-ctl stop` commands. - ```sh - gitlab-ctl status sidekiq - # run: sidekiq: (pid 10180) <- this is the PID you will use - kill -TSTP 10180 # change to the correct PID + ```sh + gitlab-ctl status sidekiq + # run: sidekiq: (pid 10180) <- this is the PID you will use + kill -TSTP 10180 # change to the correct PID - gitlab-ctl stop sidekiq - gitlab-ctl stop geo-logcursor - ``` + gitlab-ctl stop sidekiq + gitlab-ctl stop geo-logcursor + ``` - You can watch sidekiq logs to know when sidekiq jobs processing have finished: + You can watch sidekiq logs to know when sidekiq jobs processing have finished: - ```sh - gitlab-ctl tail sidekiq - ``` + ```sh + gitlab-ctl tail sidekiq + ``` 1. Rename repository storage folders and create new ones - ```sh - mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old - mkdir -p /var/opt/gitlab/git-data/repositories - chown git:git /var/opt/gitlab/git-data/repositories - ``` + ```sh + mv /var/opt/gitlab/git-data/repositories /var/opt/gitlab/git-data/repositories.old + mkdir -p /var/opt/gitlab/git-data/repositories + chown git:git /var/opt/gitlab/git-data/repositories + ``` - TIP: **Tip** - You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future - as soon as you confirmed that you don't need it anymore, to save disk space. + TIP: **Tip** + You may want to remove the `/var/opt/gitlab/git-data/repositories.old` in the future + as soon as you confirmed that you don't need it anymore, to save disk space. 1. _(Optional)_ Rename other data folders and create new ones - CAUTION: **Caution**: - You may still have files on the **secondary** node that have been removed from **primary** node but - removal have not been reflected. If you skip this step, they will never be removed - from this Geo node. + CAUTION: **Caution**: + You may still have files on the **secondary** node that have been removed from **primary** node but + removal have not been reflected. If you skip this step, they will never be removed + from this Geo node. - Any uploaded content like file attachments, avatars or LFS objects are stored in a - subfolder in one of the two paths below: + Any uploaded content like file attachments, avatars or LFS objects are stored in a + subfolder in one of the two paths below: - 1. /var/opt/gitlab/gitlab-rails/shared - 1. /var/opt/gitlab/gitlab-rails/uploads + - /var/opt/gitlab/gitlab-rails/shared + - /var/opt/gitlab/gitlab-rails/uploads - To rename all of them: + To rename all of them: - ```sh - gitlab-ctl stop + ```sh + gitlab-ctl stop - mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old - mkdir -p /var/opt/gitlab/gitlab-rails/shared + mv /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared.old + mkdir -p /var/opt/gitlab/gitlab-rails/shared - mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old - mkdir -p /var/opt/gitlab/gitlab-rails/uploads - ``` + mv /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads.old + mkdir -p /var/opt/gitlab/gitlab-rails/uploads + ``` - Reconfigure in order to recreate the folders and make sure permissions and ownership - are correctly + Reconfigure in order to recreate the folders and make sure permissions and ownership + are correctly - ```sh - gitlab-ctl reconfigure - ``` + ```sh + gitlab-ctl reconfigure + ``` 1. Reset the Tracking Database - ```sh - gitlab-rake geo:db:reset - ``` + ```sh + gitlab-rake geo:db:reset + ``` 1. Restart previously stopped services - ```sh - gitlab-ctl start - ``` + ```sh + gitlab-ctl start + ``` ## Fixing Foreign Data Wrapper errors @@ -345,108 +345,106 @@ To check the configuration: 1. Enter the database console: - ```sh - gitlab-geo-psql - ``` + ```sh + gitlab-geo-psql + ``` 1. Check whether any tables are present. If everything is working, you should see something like this: - ```sql - gitlabhq_geo_production=# SELECT * from information_schema.foreign_tables; - foreign_table_catalog | foreign_table_schema | foreign_table_name | foreign_server_catalog | foreign_server_n - ame - -------------------------+----------------------+-------------------------------------------------+-------------------------+----------------- - ---- - gitlabhq_geo_production | gitlab_secondary | abuse_reports | gitlabhq_geo_production | gitlab_secondary - gitlabhq_geo_production | gitlab_secondary | appearances | gitlabhq_geo_production | gitlab_secondary - gitlabhq_geo_production | gitlab_secondary | application_setting_terms | gitlabhq_geo_production | gitlab_secondary - gitlabhq_geo_production | gitlab_secondary | application_settings | gitlabhq_geo_production | gitlab_secondary - <snip> - ``` - - However, if the query returns with `0 rows`, then continue onto the next steps. + ```sql + gitlabhq_geo_production=# SELECT * from information_schema.foreign_tables; + foreign_table_catalog | foreign_table_schema | foreign_table_name | foreign_server_catalog | foreign_server_name + -------------------------+----------------------+-------------------------------------------------+-------------------------+--------------------- + gitlabhq_geo_production | gitlab_secondary | abuse_reports | gitlabhq_geo_production | gitlab_secondary + gitlabhq_geo_production | gitlab_secondary | appearances | gitlabhq_geo_production | gitlab_secondary + gitlabhq_geo_production | gitlab_secondary | application_setting_terms | gitlabhq_geo_production | gitlab_secondary + gitlabhq_geo_production | gitlab_secondary | application_settings | gitlabhq_geo_production | gitlab_secondary + <snip> + ``` + + However, if the query returns with `0 rows`, then continue onto the next steps. 1. Check that the foreign server mapping is correct via `\des+`. The results should look something like this: - ```sql - gitlabhq_geo_production=# \des+ - List of foreign servers - -[ RECORD 1 ]--------+------------------------------------------------------------ - Name | gitlab_secondary - Owner | gitlab-psql - Foreign-data wrapper | postgres_fdw - Access privileges | "gitlab-psql"=U/"gitlab-psql" + - | gitlab_geo=U/"gitlab-psql" - Type | - Version | - FDW Options | (host '0.0.0.0', port '5432', dbname 'gitlabhq_production') - Description | - ``` - - NOTE: **Note:** Pay particular attention to the host and port under - FDW options. That configuration should point to the Geo secondary - database. - - If you need to experiment with changing the host or password, the - following queries demonstrate how: - - ```sql - ALTER SERVER gitlab_secondary OPTIONS (SET host '<my_new_host>'); - ALTER SERVER gitlab_secondary OPTIONS (SET port 5432); - ``` - - If you change the host and/or port, you will also have to adjust the - following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl - reconfigure`: - - - `gitlab_rails['db_host']` - - `gitlab_rails['db_port']` + ```sql + gitlabhq_geo_production=# \des+ + List of foreign servers + -[ RECORD 1 ]--------+------------------------------------------------------------ + Name | gitlab_secondary + Owner | gitlab-psql + Foreign-data wrapper | postgres_fdw + Access privileges | "gitlab-psql"=U/"gitlab-psql" + + | gitlab_geo=U/"gitlab-psql" + Type | + Version | + FDW Options | (host '0.0.0.0', port '5432', dbname 'gitlabhq_production') + Description | + ``` + + NOTE: **Note:** Pay particular attention to the host and port under + FDW options. That configuration should point to the Geo secondary + database. + + If you need to experiment with changing the host or password, the + following queries demonstrate how: + + ```sql + ALTER SERVER gitlab_secondary OPTIONS (SET host '<my_new_host>'); + ALTER SERVER gitlab_secondary OPTIONS (SET port 5432); + ``` + + If you change the host and/or port, you will also have to adjust the + following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl + reconfigure`: + + - `gitlab_rails['db_host']` + - `gitlab_rails['db_port']` 1. Check that the user mapping is configured properly via `\deu+`: - ```sql - gitlabhq_geo_production=# \deu+ - List of user mappings - Server | User name | FDW Options - ------------------+------------+-------------------------------------------------------------------------------- - gitlab_secondary | gitlab_geo | ("user" 'gitlab', password 'YOUR-PASSWORD-HERE') - (1 row) - ``` + ```sql + gitlabhq_geo_production=# \deu+ + List of user mappings + Server | User name | FDW Options + ------------------+------------+-------------------------------------------------------------------------------- + gitlab_secondary | gitlab_geo | ("user" 'gitlab', password 'YOUR-PASSWORD-HERE') + (1 row) + ``` - Make sure the password is correct. You can test that logins work by running `psql`: + Make sure the password is correct. You can test that logins work by running `psql`: - ```sh - # Connect to the tracking database as the `gitlab_geo` user - sudo \ - -u git /opt/gitlab/embedded/bin/psql \ - -h /var/opt/gitlab/geo-postgresql \ - -p 5431 \ - -U gitlab_geo \ - -W \ - -d gitlabhq_geo_production - ``` + ```sh + # Connect to the tracking database as the `gitlab_geo` user + sudo \ + -u git /opt/gitlab/embedded/bin/psql \ + -h /var/opt/gitlab/geo-postgresql \ + -p 5431 \ + -U gitlab_geo \ + -W \ + -d gitlabhq_geo_production + ``` - If you need to correct the password, the following query shows how: + If you need to correct the password, the following query shows how: - ```sql - ALTER USER MAPPING FOR gitlab_geo SERVER gitlab_secondary OPTIONS (SET password '<my_new_password>'); - ``` + ```sql + ALTER USER MAPPING FOR gitlab_geo SERVER gitlab_secondary OPTIONS (SET password '<my_new_password>'); + ``` - If you change the user or password, you will also have to adjust the - following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl - reconfigure`: + If you change the user or password, you will also have to adjust the + following settings in `/etc/gitlab/gitlab.rb` and run `gitlab-ctl + reconfigure`: - - `gitlab_rails['db_username']` - - `gitlab_rails['db_password']` + - `gitlab_rails['db_username']` + - `gitlab_rails['db_password']` - If you are using [PgBouncer in front of the secondary - database](database.md#pgbouncer-support-optional), be sure to update - the following settings: + If you are using [PgBouncer in front of the secondary + database](database.md#pgbouncer-support-optional), be sure to update + the following settings: - - `geo_postgresql['fdw_external_user']` - - `geo_postgresql['fdw_external_password']` + - `geo_postgresql['fdw_external_user']` + - `geo_postgresql['fdw_external_password']` #### Manual reload of FDW schema @@ -456,34 +454,34 @@ reload of the FDW schema. To manually reload the FDW schema: 1. On the node running the Geo tracking database, enter the PostgreSQL console via the `gitlab_geo` user: - ```sh - sudo \ - -u git /opt/gitlab/embedded/bin/psql \ - -h /var/opt/gitlab/geo-postgresql \ - -p 5431 \ - -U gitlab_geo \ - -W \ - -d gitlabhq_geo_production - ``` + ```sh + sudo \ + -u git /opt/gitlab/embedded/bin/psql \ + -h /var/opt/gitlab/geo-postgresql \ + -p 5431 \ + -U gitlab_geo \ + -W \ + -d gitlabhq_geo_production + ``` - Be sure to adjust the port and hostname for your configuration. You - may be asked to enter a password. + Be sure to adjust the port and hostname for your configuration. You + may be asked to enter a password. 1. Reload the schema via: - ```sql - DROP SCHEMA IF EXISTS gitlab_secondary CASCADE; - CREATE SCHEMA gitlab_secondary; - GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO gitlab_geo; - IMPORT FOREIGN SCHEMA public FROM SERVER gitlab_secondary INTO gitlab_secondary; - ``` + ```sql + DROP SCHEMA IF EXISTS gitlab_secondary CASCADE; + CREATE SCHEMA gitlab_secondary; + GRANT USAGE ON FOREIGN SERVER gitlab_secondary TO gitlab_geo; + IMPORT FOREIGN SCHEMA public FROM SERVER gitlab_secondary INTO gitlab_secondary; + ``` 1. Test that queries work: - ```sql - SELECT * from information_schema.foreign_tables; - SELECT * FROM gitlab_secondary.projects limit 1; - ``` + ```sql + SELECT * from information_schema.foreign_tables; + SELECT * FROM gitlab_secondary.projects limit 1; + ``` [database-start-replication]: database.md#step-3-initiate-the-replication-process [database-pg-replication]: database.md#postgresql-replication diff --git a/doc/administration/geo/replication/updating_the_geo_nodes.md b/doc/administration/geo/replication/updating_the_geo_nodes.md index 933a75c47d8..d56a59f4967 100644 --- a/doc/administration/geo/replication/updating_the_geo_nodes.md +++ b/doc/administration/geo/replication/updating_the_geo_nodes.md @@ -30,70 +30,70 @@ We now require this change as we use this password to enable the Foreign Data Wr the Geo Tracking Database. We are also improving security by disabling the use of **trust** authentication method. -1. **[primary]** Login to your **primary** node and run: +1. **(primary)** Login to your **primary** node and run: - ```sh - gitlab-ctl pg-password-md5 gitlab - # Enter password: <your_password_here> - # Confirm password: <your_password_here> - # fca0b89a972d69f00eb3ec98a5838484 - ``` + ```sh + gitlab-ctl pg-password-md5 gitlab + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # fca0b89a972d69f00eb3ec98a5838484 + ``` - Copy the generated hash and edit `/etc/gitlab/gitlab.rb`: + Copy the generated hash and edit `/etc/gitlab/gitlab.rb`: - ```ruby - # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - # Every node that runs Unicorn or Sidekiq needs to have the database - # password specified as below. If you have a high-availability setup, this - # must be present in all application nodes. - gitlab_rails['db_password'] = '<your_password_here>' - ``` + # Every node that runs Unicorn or Sidekiq needs to have the database + # password specified as below. If you have a high-availability setup, this + # must be present in all application nodes. + gitlab_rails['db_password'] = '<your_password_here>' + ``` - Still in the configuration file, locate and remove the `trust_auth_cidr_address`: + Still in the configuration file, locate and remove the `trust_auth_cidr_address`: - ```ruby - postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','1.2.3.4/32'] # <- Remove this - ``` + ```ruby + postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','1.2.3.4/32'] # <- Remove this + ``` -1. **[primary]** Reconfigure and restart: +1. **(primary)** Reconfigure and restart: - ```sh - sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart - ``` + ```sh + sudo gitlab-ctl reconfigure + sudo gitlab-ctl restart + ``` -1. **[secondary]** Login to all **secondary** nodes and edit `/etc/gitlab/gitlab.rb`: +1. **(secondary)** Login to all **secondary** nodes and edit `/etc/gitlab/gitlab.rb`: - ```ruby - # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` - postgresql['sql_user_password'] = '<md5_hash_of_your_password>' + ```ruby + # Fill with the hash generated by `gitlab-ctl pg-password-md5 gitlab` + postgresql['sql_user_password'] = '<md5_hash_of_your_password>' - # Every node that runs Unicorn or Sidekiq needs to have the database - # password specified as below. If you have a high-availability setup, this - # must be present in all application nodes. - gitlab_rails['db_password'] = '<your_password_here>' + # Every node that runs Unicorn or Sidekiq needs to have the database + # password specified as below. If you have a high-availability setup, this + # must be present in all application nodes. + gitlab_rails['db_password'] = '<your_password_here>' - # Enable Foreign Data Wrapper - geo_secondary['db_fdw'] = true + # Enable Foreign Data Wrapper + geo_secondary['db_fdw'] = true - # Secondary address in CIDR format, for example '5.6.7.8/32' - postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] - ``` + # Secondary address in CIDR format, for example '5.6.7.8/32' + postgresql['md5_auth_cidr_addresses'] = ['<secondary_node_ip>/32'] + ``` - Still in the configuration file, locate and remove the `trust_auth_cidr_address`: + Still in the configuration file, locate and remove the `trust_auth_cidr_address`: - ```ruby - postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','5.6.7.8/32'] # <- Remove this - ``` + ```ruby + postgresql['trust_auth_cidr_addresses'] = ['127.0.0.1/32','5.6.7.8/32'] # <- Remove this + ``` -1. **[secondary]** Reconfigure and restart: +1. **(secondary)** Reconfigure and restart: - ```sh - sudo gitlab-ctl reconfigure - sudo gitlab-ctl restart - ``` + ```sh + sudo gitlab-ctl reconfigure + sudo gitlab-ctl restart + ``` ## Upgrading to GitLab 10.5 @@ -169,11 +169,11 @@ After you've verified that HTTP/HTTPS replication is working, you should remove the now-unused SSH keys from your secondaries, as they may cause problems if the **secondary** node if ever promoted to a **primary** node: -1. **[secondary]** Login to **all** your **secondary** nodes and run: +1. **(secondary)** Login to **all** your **secondary** nodes and run: - ```ruby - sudo -u git -H rm ~git/.ssh/id_rsa ~git/.ssh/id_rsa.pub - ``` + ```ruby + sudo -u git -H rm ~git/.ssh/id_rsa ~git/.ssh/id_rsa.pub + ``` ### Hashed Storage @@ -236,12 +236,12 @@ instructions below. When in doubt, it does not hurt to do a resync. The easiest way to do this in Omnibus is the following: - 1. Make sure you have Omnibus GitLab on the **primary** server. - 1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database. - 1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`. - 1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations. - 1. Install GitLab on the **secondary** server. - 1. Re-run the [database replication process][database-replication]. +1. Make sure you have Omnibus GitLab on the **primary** server. +1. Run `gitlab-ctl reconfigure` and `gitlab-ctl restart postgresql`. This will enable replication slots on the **primary** database. +1. Check the steps about defining `postgresql['sql_user_password']`, `gitlab_rails['db_password']`. +1. Make sure `postgresql['max_replication_slots']` matches the number of **secondary** Geo nodes locations. +1. Install GitLab on the **secondary** server. +1. Re-run the [database replication process][database-replication]. ## Special update notes for 9.0.x @@ -260,157 +260,154 @@ Make sure to follow the steps in the exact order as they appear below and pay extra attention in what node (either **primary** or **secondary**) you execute them! Each step is prepended with the relevant node for better clarity: -1. **[secondary]** Login to **all** your **secondary** nodes and stop all services: +1. **(secondary)** Login to **all** your **secondary** nodes and stop all services: - ```ruby - sudo gitlab-ctl stop - ``` + ```ruby + sudo gitlab-ctl stop + ``` -1. **[secondary]** Make a backup of the `recovery.conf` file on **all** +1. **(secondary)** Make a backup of the `recovery.conf` file on **all** **secondary** nodes to preserve PostgreSQL's credentials: - ```sh - sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab/ - ``` + ```sh + sudo cp /var/opt/gitlab/postgresql/data/recovery.conf /var/opt/gitlab/ + ``` -1. **[primary]** Update the **primary** node to GitLab 9.0 following the +1. **(primary)** Update the **primary** node to GitLab 9.0 following the [regular update docs][update]. At the end of the update, the **primary** node will be running with PostgreSQL 9.6. -1. **[primary]** To prevent a de-synchronization of the repository replication, +1. **(primary)** To prevent a de-synchronization of the repository replication, stop all services except `postgresql` as we will use it to re-initialize the **secondary** node's database: - ```sh - sudo gitlab-ctl stop - sudo gitlab-ctl start postgresql - ``` + ```sh + sudo gitlab-ctl stop + sudo gitlab-ctl start postgresql + ``` -1. **[secondary]** Run the following steps on each of the **secondary** nodes: +1. **(secondary)** Run the following steps on each of the **secondary** nodes: - 1. **[secondary]** Stop all services: + 1. **(secondary)** Stop all services: - ```sh - sudo gitlab-ctl stop - ``` + ```sh + sudo gitlab-ctl stop + ``` - 1. **[secondary]** Prevent running database migrations: + 1. **(secondary)** Prevent running database migrations: - ```sh - sudo touch /etc/gitlab/skip-auto-migrations - ``` + ```sh + sudo touch /etc/gitlab/skip-auto-migrations + ``` - 1. **[secondary]** Move the old database to another directory: + 1. **(secondary)** Move the old database to another directory: - ```sh - sudo mv /var/opt/gitlab/postgresql{,.bak} - ``` + ```sh + sudo mv /var/opt/gitlab/postgresql{,.bak} + ``` - 1. **[secondary]** Update to GitLab 9.0 following the [regular update docs][update]. - At the end of the update, the node will be running with PostgreSQL 9.6. + 1. **(secondary)** Update to GitLab 9.0 following the [regular update docs][update]. + At the end of the update, the node will be running with PostgreSQL 9.6. - 1. **[secondary]** Make sure all services are up: + 1. **(secondary)** Make sure all services are up: - ```sh - sudo gitlab-ctl start - ``` + ```sh + sudo gitlab-ctl start + ``` - 1. **[secondary]** Reconfigure GitLab: + 1. **(secondary)** Reconfigure GitLab: - ```sh - sudo gitlab-ctl reconfigure - ``` + ```sh + sudo gitlab-ctl reconfigure + ``` - 1. **[secondary]** Run the PostgreSQL upgrade command: + 1. **(secondary)** Run the PostgreSQL upgrade command: - ```sh - sudo gitlab-ctl pg-upgrade - ``` + ```sh + sudo gitlab-ctl pg-upgrade + ``` - 1. **[secondary]** See the stored credentials for the database that you will - need to re-initialize the replication: + 1. **(secondary)** See the stored credentials for the database that you will + need to re-initialize the replication: - ```sh - sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf - ``` + ```sh + sudo grep -s primary_conninfo /var/opt/gitlab/recovery.conf + ``` - 1. **[secondary]** Create the `replica.sh` script as described in the - [database configuration document][database-source-replication]. + 1. **(secondary)** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the + embedded paths if necessary: - 1. 1. **[secondary]** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the - embedded paths if necessary: + ``` + #!/bin/bash - ``` - #!/bin/bash + PORT="5432" + USER="gitlab_replicator" + echo --------------------------------------------------------------- + echo WARNING: Make sure this script is run from the secondary server + echo --------------------------------------------------------------- + echo + echo Enter the IP or FQDN of the primary PostgreSQL server + read HOST + echo Enter the password for $USER@$HOST + read -s PASSWORD + echo Enter the required sslmode + read SSLMODE - PORT="5432" - USER="gitlab_replicator" - echo --------------------------------------------------------------- - echo WARNING: Make sure this script is run from the secondary server - echo --------------------------------------------------------------- - echo - echo Enter the IP or FQDN of the primary PostgreSQL server - read HOST - echo Enter the password for $USER@$HOST - read -s PASSWORD - echo Enter the required sslmode - read SSLMODE + echo Stopping PostgreSQL and all GitLab services + sudo service gitlab stop + sudo service postgresql stop - echo Stopping PostgreSQL and all GitLab services - sudo service gitlab stop - sudo service postgresql stop + echo Backing up postgresql.conf + sudo -u postgres mv /var/opt/gitlab/postgresql/data/postgresql.conf /var/opt/gitlab/postgresql/ - echo Backing up postgresql.conf - sudo -u postgres mv /var/opt/gitlab/postgresql/data/postgresql.conf /var/opt/gitlab/postgresql/ + echo Cleaning up old cluster directory + sudo -u postgres rm -rf /var/opt/gitlab/postgresql/data - echo Cleaning up old cluster directory - sudo -u postgres rm -rf /var/opt/gitlab/postgresql/data + echo Starting base backup as the replicator user + echo Enter the password for $USER@$HOST + sudo -u postgres /opt/gitlab/embedded/bin/pg_basebackup -h $HOST -D /var/opt/gitlab/postgresql/data -U gitlab_replicator -v -x -P - echo Starting base backup as the replicator user - echo Enter the password for $USER@$HOST - sudo -u postgres /opt/gitlab/embedded/bin/pg_basebackup -h $HOST -D /var/opt/gitlab/postgresql/data -U gitlab_replicator -v -x -P + echo Writing recovery.conf file + sudo -u postgres bash -c "cat > /var/opt/gitlab/postgresql/data/recovery.conf <<- _EOF1_ + standby_mode = 'on' + primary_conninfo = 'host=$HOST port=$PORT user=$USER password=$PASSWORD sslmode=$SSLMODE' + _EOF1_ + " - echo Writing recovery.conf file - sudo -u postgres bash -c "cat > /var/opt/gitlab/postgresql/data/recovery.conf <<- _EOF1_ - standby_mode = 'on' - primary_conninfo = 'host=$HOST port=$PORT user=$USER password=$PASSWORD sslmode=$SSLMODE' - _EOF1_ - " + echo Restoring postgresql.conf + sudo -u postgres mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/ - echo Restoring postgresql.conf - sudo -u postgres mv /var/opt/gitlab/postgresql/postgresql.conf /var/opt/gitlab/postgresql/data/ + echo Starting PostgreSQL + sudo service postgresql start + ``` - echo Starting PostgreSQL - sudo service postgresql start - ``` + 1. **(secondary)** Run the recovery script using the credentials from the + previous step: - 1. **[secondary]** Run the recovery script using the credentials from the - previous step: + ```sh + sudo bash /tmp/replica.sh + ``` - ```sh - sudo bash /tmp/replica.sh - ``` + 1. **(secondary)** Reconfigure GitLab: - 1. **[secondary]** Reconfigure GitLab: + ```sh + sudo gitlab-ctl reconfigure + ``` - ```sh - sudo gitlab-ctl reconfigure - ``` + 1. **(secondary)** Start all services: - 1. **[secondary]** Start all services: + ```sh + sudo gitlab-ctl start + ``` - ```sh - sudo gitlab-ctl start - ``` + 1. **(secondary)** Repeat the steps for the remaining **secondary** nodes. - 1. **[secondary]** Repeat the steps for the remaining **secondary** nodes. - -1. **[primary]** After all **secondary** nodes are updated, start all services in +1. **(primary)** After all **secondary** nodes are updated, start all services in **primary** node: - ```sh - sudo gitlab-ctl start - ``` + ```sh + sudo gitlab-ctl start + ``` ## Check status after updating @@ -419,9 +416,9 @@ everything is working correctly: 1. Run the Geo raketask on all nodes, everything should be green: - ```sh - sudo gitlab-rake gitlab:geo:check - ``` + ```sh + sudo gitlab-rake gitlab:geo:check + ``` 1. Check the **primary** node's Geo dashboard for any errors. 1. Test the data replication by pushing code to the **primary** node and see if it @@ -435,9 +432,9 @@ and it is required since 10.0. 1. Run database migrations on tracking database: - ```sh - sudo gitlab-rake geo:db:migrate - ``` + ```sh + sudo gitlab-rake geo:db:migrate + ``` 1. Repeat this step for each **secondary** node. diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 0bffe2f7472..a3cbc4272f0 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -267,7 +267,7 @@ repository from your GitLab server over HTTP. Gitaly supports TLS encryption. To be able to communicate with a Gitaly instance that listens for secure connections you will need to use `tls://` url -scheme in the `gitaly_address` of the corresponding storage entry in the gitlab configuration. +scheme in the `gitaly_address` of the corresponding storage entry in the GitLab configuration. The admin needs to bring their own certificate as we do not provide that automatically. The certificate to be used needs to be installed on all Gitaly nodes and on all client nodes that communicate with it following procedures described in [GitLab custom certificate configuration](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates). diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index cc338725e1b..874525dd836 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -394,7 +394,7 @@ The prerequisites for a HA Redis setup are the following: 1. [Reconfigure Omnibus GitLab][reconfigure] for the changes to take effect. > Note: You can specify multiple roles like sentinel and redis as: -> roles ['redis_sentinel_role', 'redis_master_role']. Read more about high +> `roles ['redis_sentinel_role', 'redis_master_role']`. Read more about high > availability roles at <https://docs.gitlab.com/omnibus/roles/>. ### Step 2. Configuring the slave Redis instances @@ -443,7 +443,7 @@ The prerequisites for a HA Redis setup are the following: 1. Go through the steps again for all the other slave nodes. > Note: You can specify multiple roles like sentinel and redis as: -> roles ['redis_sentinel_role', 'redis_slave_role']. Read more about high +> `roles ['redis_sentinel_role', 'redis_slave_role']`. Read more about high > availability roles at <https://docs.gitlab.com/omnibus/roles/>. --- diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index 8271c579f5b..84a34ae7d6e 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -4,7 +4,7 @@ GitLab has several features based on receiving incoming emails: - [Reply by Email](reply_by_email.md): allow GitLab users to comment on issues and merge requests by replying to notification emails. -- [New issue by email](../user/project/issues/create_new_issue.md#new-issue-via-email): +- [New issue by email](../user/project/issues/managing_issues.md#new-issue-via-email): allow GitLab users to create a new issue by sending an email to a user-specific email address. - [New merge request by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email): diff --git a/doc/administration/index.md b/doc/administration/index.md index 602eecb9746..f480d18ea00 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -117,7 +117,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - Instances. **[PREMIUM ONLY]** - [Auditor users](auditor_users.md): Users with read-only access to all projects, groups, and other resources on the GitLab instance. **[PREMIUM ONLY]** - [Incoming email](incoming_email.md): Configure incoming emails to allow - users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/create_new_issue.md#new-issue-via-email) and + users to [reply by email](reply_by_email.md), create [issues by email](../user/project/issues/managing_issues.md#new-issue-via-email) and [merge requests by email](../user/project/merge_requests/index.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md). - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a basic Postfix mail server with IMAP authentication on Ubuntu for incoming diff --git a/doc/administration/issue_closing_pattern.md b/doc/administration/issue_closing_pattern.md index 160da47c780..9c352096ecc 100644 --- a/doc/administration/issue_closing_pattern.md +++ b/doc/administration/issue_closing_pattern.md @@ -1,4 +1,4 @@ -# Issue closing pattern +# Issue closing pattern **[CORE ONLY]** >**Note:** This is the administration documentation. @@ -46,4 +46,4 @@ Because Rubular doesn't understand `%{issue_ref}`, you can replace this by [gitlab.yml.example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example [reconfigure]: restart_gitlab.md#omnibus-gitlab-reconfigure [restart]: restart_gitlab.md#installations-from-source -[user documentation]: ../user/project/issues/automatic_issue_closing.md +[user documentation]: ../user/project/issues/managing_issues.md#closing-issues-automatically diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index 187fb2f73a1..51b0d78681d 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -103,6 +103,21 @@ repository for more information on this process. [grafana-dashboards]: https://gitlab.com/gitlab-org/grafana-dashboards +## Integration with GitLab UI + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/61005) in GitLab 12.1. + +If you have set up Grafana, you can enable a link to access it easily from the sidebar: + +1. Go to the admin area under **Settings > Metrics and profiling** + and expand "Metrics - Grafana". +1. Check the "Enable access to Grafana" checkbox. +1. If Grafana is enabled through Omnibus GitLab and on the same server, + leave "Grafana URL" unchanged. In any other case, enter the full URL + path of the Grafana instance. +1. Click **Save changes**. +1. The new link will be available in the admin area under **Monitoring > Metrics Dashboard**. + --- Read more on: diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 84b71ae6f1c..2d9e3f7f18b 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -108,7 +108,7 @@ Some basic Ruby runtime metrics are available: [GC.stat]: https://ruby-doc.org/core-2.3.0/GC.html#method-c-stat -## Puma Metrics **[EXPERIMENTAL]** +## Puma Metrics **(EXPERIMENTAL)** When Puma is used instead of Unicorn, following metrics are available: diff --git a/doc/api/group_boards.md b/doc/api/group_boards.md index 9b0ac23b41c..4157b25477f 100644 --- a/doc/api/group_boards.md +++ b/doc/api/group_boards.md @@ -5,7 +5,7 @@ Every API call to group boards must be authenticated. If a user is not a member of a group and the group is private, a `GET` request will result in `404` status code. -## Group Board +## List all group issue boards in a group Lists Issue Boards in the given group. @@ -27,7 +27,68 @@ Example response: [ { "id": 1, - "group_id": 5, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, + "lists" : [ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1 + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2 + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3 + } + ] + } +] +``` + +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see +different parameters, due to the ability to have multiple group boards. + +Example response: + +```json +[ + { + "id": 1, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, "lists" : [ { "id" : 1, @@ -61,9 +122,9 @@ Example response: ] ``` -## Single board +## Single group issue board -Gets a single board. +Gets a single group issue board. ``` GET /groups/:id/boards/:board_id @@ -83,7 +144,66 @@ Example response: ```json { "id": 1, - "group_id": 5, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, + "lists" : [ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1 + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2 + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3 + } + ] + } +``` + +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will see +different parameters, due to the ability to have multiple group issue boards.s + +Example response: + +```json + { + "id": 1, + "name:": "group issue board", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, "lists" : [ { "id" : 1, @@ -116,7 +236,156 @@ Example response: } ``` -## List board lists +## Create a group issue board **[PREMIUM]** + +Creates a Group Issue Board. + +``` +POST /groups/:id/boards +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the new board | + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards?name=newboard +``` + +Example response: + +```json + { + "id": 1, + "name": "newboard", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 12 + "title": "10.0" + }, + "lists" : [ + { + "id" : 1, + "label" : { + "name" : "Testing", + "color" : "#F0AD4E", + "description" : null + }, + "position" : 1 + }, + { + "id" : 2, + "label" : { + "name" : "Ready", + "color" : "#FF0000", + "description" : null + }, + "position" : 2 + }, + { + "id" : 3, + "label" : { + "name" : "Production", + "color" : "#FF5F00", + "description" : null + }, + "position" : 3 + } + ] + } +``` + +## Update a group issue board **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/5954) in GitLab 11.1. + +Updates a Group Issue Board. + +``` +PUT /groups/:id/boards/:board_id +``` + +| Attribute | Type | Required | Description | +| ------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `board_id` | integer | yes | The ID of a board | +| `name` | string | no | The new name of the board | +| `assignee_id` | integer | no | The assignee the board should be scoped to | +| `milestone_id` | integer | no | The milestone the board should be scoped to | +| `labels` | string | no | Comma-separated list of label names which the board should be scoped to | +| `weight` | integer | no | The weight range from 0 to 9, to which the board should be scoped to | + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1?name=new_name&milestone_id=44&assignee_id=1&labels=GroupLabel&weight=4 +``` + +Example response: + +```json + { + "id": 1, + "project": null, + "lists": [], + "name": "new_name", + "group": { + "id": 5, + "name": "Documentcloud", + "web_url": "http://example.com/groups/documentcloud" + }, + "milestone": { + "id": 44, + "iid": 1, + "group_id": 5, + "title": "Group Milestone", + "description": "Group Milestone Desc", + "state": "active", + "created_at": "2018-07-03T07:15:19.271Z", + "updated_at": "2018-07-03T07:15:19.271Z", + "due_date": null, + "start_date": null, + "web_url": "http://example.com/groups/documentcloud/-/milestones/1" + }, + "assignee": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://example.com/root" + }, + "labels": [{ + "id": 11, + "name": "GroupLabel", + "color": "#428BCA", + "description": "" + }], + "weight": 4 + } +``` + +## Delete a group issue board **[PREMIUM]** + +Deletes a Group Issue Board. + +``` +DELETE /groups/:id/boards/:board_id +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `board_id` | integer | yes | The ID of a board | + +```bash +curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/5/boards/1 +``` + +## List group issue board lists Get a list of the board's lists. Does not include `open` and `closed` lists @@ -168,7 +437,7 @@ Example response: ] ``` -## Single board list +## Single group issue board list Get a single board list. @@ -200,7 +469,7 @@ Example response: } ``` -## New board list +## New group issue board list Creates a new Issue Board list. @@ -232,7 +501,7 @@ Example response: } ``` -## Edit board list +## Edit group issue board list Updates an existing Issue Board list. This call is used to change list position. @@ -265,7 +534,7 @@ Example response: } ``` -## Delete a board list +## Delete a group issue board list Only for admins and group owners. Soft deletes the board list in question. diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 260eb09cc38..e780a60a416 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -136,3 +136,18 @@ Parameters: - `milestone_id` (required) - The ID of a group milestone [ce-12819]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/12819 + +## Get all burndown chart events for a single milestone **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1 + +Get all burndown chart events for a single milestone. + +``` +GET /groups/:id/milestones/:milestone_id/burndown_events +``` + +Parameters: + +- `id` (required) - The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user +- `milestone_id` (required) - The ID of a group milestone diff --git a/doc/api/groups.md b/doc/api/groups.md index 20789a1d4a4..e1bf296bc41 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -7,17 +7,17 @@ authentication, only public groups are returned. Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `skip_groups` | array of integers | no | Skip the group IDs passed | -| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence | -| `search` | string | no | Return the list of authorized groups matching the search criteria | -| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | -| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (admins only) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `owned` | boolean | no | Limit to groups explicitly owned by the current user | -| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) | +| Attribute | Type | Required | Description | +| ------------------------ | ----------------- | -------- | ---------- | +| `skip_groups` | array of integers | no | Skip the group IDs passed | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence | +| `search` | string | no | Return the list of authorized groups matching the search criteria | +| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | +| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | +| `statistics` | boolean | no | Include group statistics (admins only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `owned` | boolean | no | Limit to groups explicitly owned by the current user | +| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) | ``` GET /groups @@ -70,8 +70,8 @@ GET /groups?statistics=true "repository_size" : 33, "wiki_size" : 100, "lfs_objects_size" : 123, - "job_artifacts_size" : 57 - + "job_artifacts_size" : 57, + "packages_size": 0 } } ] @@ -94,18 +94,18 @@ When accessed without authentication, only public groups are returned. Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the parent group | -| `skip_groups` | array of integers | no | Skip the group IDs passed | -| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have precedence | -| `search` | string | no | Return the list of authorized groups matching the search criteria | -| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | -| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | -| `statistics` | boolean | no | Include group statistics (admins only) | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `owned` | boolean | no | Limit to groups explicitly owned by the current user | -| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) | +| Attribute | Type | Required | Description | +| ------------------------ | ----------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) of the parent group | +| `skip_groups` | array of integers | no | Skip the group IDs passed | +| `all_available` | boolean | no | Show all the groups you have access to (defaults to `false` for authenticated users, `true` for admin); Attributes `owned` and `min_access_level` have preceden | +| `search` | string | no | Return the list of authorized groups matching the search criteria | +| `order_by` | string | no | Order groups by `name`, `path` or `id`. Default is `name` | +| `sort` | string | no | Order groups in `asc` or `desc` order. Default is `asc` | +| `statistics` | boolean | no | Include group statistics (admins only) | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `owned` | boolean | no | Limit to groups explicitly owned by the current user | +| `min_access_level` | integer | no | Limit to groups where current user has at least this [access level](members.md) | ``` GET /groups/:id/subgroups @@ -142,22 +142,22 @@ GET /groups/:id/projects Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `archived` | boolean | no | Limit by archived status | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of authorized projects matching the search criteria | -| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | -| `owned` | boolean | no | Limit by projects owned by the current user | -| `starred` | boolean | no | Limit by projects starred by the current user | -| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | -| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | -| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | -| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| Attribute | Type | Required | Description | +| ----------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of authorized projects matching the search criteria | +| `simple` | boolean | no | Return only the ID, URL, name, and path of each project | +| `owned` | boolean | no | Limit by projects owned by the current user | +| `starred` | boolean | no | Limit by projects starred by the current user | +| `with_issues_enabled` | boolean | no | Limit by projects with issues feature enabled. Default is `false` | +| `with_merge_requests_enabled` | boolean | no | Limit by projects with merge requests feature enabled. Default is `false` | +| `with_shared` | boolean | no | Include projects shared to this group. Default is `true` | +| `include_subgroups` | boolean | no | Include projects in subgroups of this group. Default is `false` | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | Example response: @@ -214,11 +214,11 @@ GET /groups/:id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). | +| Attribute | Type | Required | Description | +| ------------------------ | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user. | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only). | +| `with_projects` | boolean | no | Include details from projects that belong to the specified group (defaults to `true`). | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/groups/4 @@ -375,6 +375,21 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters: + +Additional response parameters: + +```json +{ + "id": 4, + "description": "Aliquid qui quis dignissimos distinctio ut commodi voluptas est.", + "shared_runners_minutes_limit": 133, + "extra_shared_runners_minutes_limit": 133, + ... +} +``` + When adding the parameter `with_projects=false`, projects will not be returned. ```bash @@ -410,15 +425,17 @@ POST /groups Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `name` | string | yes | The name of the group | -| `path` | string | yes | The path of the group | -| `description` | string | no | The group's description | -| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | -| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group | -| `request_access_enabled` | boolean | no | Allow users to request member access. | -| `parent_id` | integer | no | The parent group id for creating nested group. | +| Attribute | Type | Required | Description | +| ------------------------------------ | ------- | -------- | ----------- | +| `name` | string | yes | The name of the group. | +| `path` | string | yes | The path of the group. | +| `description` | string | no | The group's description. | +| `visibility` | string | no | The group's visibility. Can be `private`, `internal`, or `public`. | +| `lfs_enabled` | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | +| `request_access_enabled` | boolean | no | Allow users to request member access. | +| `parent_id` | integer | no | The parent group ID for creating nested group. | +| `shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Pipeline minutes quota for this group. | +| `extra_shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Extra pipeline minutes quota for this group. | ## Transfer project to group @@ -430,10 +447,10 @@ POST /groups/:id/projects/:project_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | -| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| Attribute | Type | Required | Description | +| ------------ | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ## Update group @@ -443,16 +460,20 @@ Updates the project group. Only available to group owners and administrators. PUT /groups/:id ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the group | -| `name` | string | no | The name of the group | -| `path` | string | no | The path of the group | -| `description` | string | no | The description of the group | -| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | -| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group | -| `request_access_enabled` | boolean | no | Allow users to request member access. | -| `file_template_project_id` | integer | no | **(Premium)** The ID of a project to load custom file templates from | +| Attribute | Type | Required | Description | +| ------------------------------------ | ------- | -------- | ----------- | +| `id` | integer | yes | The ID of the group. | +| `name` | string | no | The name of the group. | +| `path` | string | no | The path of the group. | +| `description` | string | no | The description of the group. | +| `membership_lock` | boolean | no | **[STARTER]** Prevent adding new members to project membership within this group. | +| `share_with_group_lock` | boolean | no | Prevent sharing a project with another group within this group. | +| `visibility` | string | no | The visibility level of the group. Can be `private`, `internal`, or `public`. | +| `lfs_enabled` (optional) | boolean | no | Enable/disable Large File Storage (LFS) for the projects in this group. | +| `request_access_enabled` | boolean | no | Allow users to request member access. | +| `file_template_project_id` | integer | no | **[PREMIUM]** The ID of a project to load custom file templates from. | +| `shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Pipeline minutes quota for this group. | +| `extra_shared_runners_minutes_limit` | integer | no | **[STARTER ONLY]** Extra pipeline minutes quota for this group. | ```bash curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/5?name=Experimental" @@ -520,7 +541,7 @@ Example response: ## Remove group -Removes group with all projects inside. +Removes group with all projects inside. Only available to group owners and administrators. ``` DELETE /groups/:id @@ -552,10 +573,62 @@ GET /groups?search=foobar ] ``` +## Sync group with LDAP **[CORE ONLY]** + +Syncs the group with its linked LDAP group. Only available to group owners and administrators. + +``` +POST /groups/:id/ldap_sync +``` + +Parameters: + +- `id` (required) - The ID or path of a user group + ## Group members Please consult the [Group Members](members.md) documentation. +### Add LDAP group link **[CORE ONLY]** + +Adds an LDAP group link. + +``` +POST /groups/:id/ldap_group_links +``` + +Parameters: + +- `id` (required) - The ID of a group +- `cn` (required) - The CN of a LDAP group +- `group_access` (required) - Minimum access level for members of the LDAP group +- `provider` (required) - LDAP provider for the LDAP group + +### Delete LDAP group link **[CORE ONLY]** + +Deletes an LDAP group link. + +``` +DELETE /groups/:id/ldap_group_links/:cn +``` + +Parameters: + +- `id` (required) - The ID of a group +- `cn` (required) - The CN of a LDAP group + +Deletes a LDAP group link for a specific LDAP provider + +``` +DELETE /groups/:id/ldap_group_links/:provider/:cn +``` + +Parameters: + +- `id` (required) - The ID of a group +- `cn` (required) - The CN of a LDAP group +- `provider` (required) - Name of a LDAP provider + ## Namespaces in groups By default, groups only get 20 namespaces at a time because the API results are paginated. diff --git a/doc/api/issues.md b/doc/api/issues.md index 0d96cfa1b21..b29626525da 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -3,7 +3,7 @@ Every API call to issues must be authenticated. If a user is not a member of a project and the project is private, a `GET` -request on that project will result to a `404` status code. +request on that project will result in a `404` status code. ## Issues pagination @@ -39,7 +39,7 @@ GET /issues?confidential=true | ------------------- | ---------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | string | no | Return `all` issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `with_labels_details`| Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | @@ -47,6 +47,7 @@ GET /issues?confidential=true | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_username` | Array[String] | no | Return issues assigned to the given `username`. Simillar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `weight` **[STARTER]** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | @@ -144,6 +145,20 @@ Example response: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +[ + { + "state" : "opened", + "description" : "Ratione dolores corrupti mollitia soluta quia.", + "weight": null, + ... + } +] +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -174,7 +189,7 @@ GET /groups/:id/issues?confidential=true | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `with_labels_details`| Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. | | `iids[]` | Array[integer] | no | Return only the issues having the given `iid` | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | @@ -183,6 +198,7 @@ GET /groups/:id/issues?confidential=true | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_username` | Array[String] | no | Return issues assigned to the given `username`. Simillar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `weight` **[STARTER]** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search group issues against their `title` and `description` | @@ -278,6 +294,20 @@ Example response: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +[ + { + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "weight": null, + ... + } +] +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -309,7 +339,7 @@ GET /projects/:id/issues?confidential=true | `iids[]` | Array[integer] | no | Return only the milestone having the given `iid` | | `state` | string | no | Return all issues or just those that are `opened` or `closed` | | `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `None` lists all issues with no labels. `Any` lists all issues with at least one label. `No+Label` (Deprecated) lists all issues with no labels. Predefined names are case-insensitive. | -| `with_labels_details`| Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:text_color`. Default is `false`. | | `milestone` | string | no | The milestone title. `None` lists all issues with no milestone. `Any` lists all issues that have an assigned milestone. | | `scope` | string | no | Return issues for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13004] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Return issues created by the given user `id`. Mutually exclusive with `author_username`. Combine with `scope=all` or `scope=assigned_to_me`. _([Introduced][ce-13004] in GitLab 9.5)_ | @@ -317,6 +347,7 @@ GET /projects/:id/issues?confidential=true | `assignee_id` | integer | no | Return issues assigned to the given user `id`. Mutually exclusive with `assignee_username`. `None` returns unassigned issues. `Any` returns issues with an assignee. _([Introduced][ce-13004] in GitLab 9.5)_ | | `assignee_username` | Array[String] | no | Return issues assigned to the given `username`. Simillar to `assignee_id` and mutually exclusive with `assignee_id`. In CE version `assignee_username` array should only contain a single value or an invalid param error will be returned otherwise. | | `my_reaction_emoji` | string | no | Return issues reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `weight` **[STARTER]** | integer | no | Return issues with the specified `weight`. `None` returns issues with no weight assigned. `Any` returns issues with a weight assigned. | | `order_by` | string | no | Return issues ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return issues sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search project issues against their `title` and `description` | @@ -420,6 +451,20 @@ Example response: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +[ + { + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "weight": null, + ... + } +] +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -520,6 +565,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +{ + "project_id" : 4, + "description" : "Omnis vero earum sunt corporis dolor et placeat.", + "weight": null, + ... +} +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -536,16 +593,17 @@ POST /projects/:id/issues |-------------------------------------------|----------------|----------|--------------| | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iid` | integer/string | no | The internal ID of the project's issue (requires admin or project owner rights) | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_ids` | Array[integer] | no | The ID of the users to assign issue | -| `milestone_id` | integer | no | The global ID of a milestone to assign issue | -| `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project/group owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `assignee_ids` | Array[integer] | no | The ID of a user to assign issue | +| `milestone_id` | integer | no | The global ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project/group owner rights) | +| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| `weight` **[STARTER]** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -607,6 +665,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +{ + "project_id" : 4, + "description" : null, + "weight": null, + ... +} +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -622,17 +692,18 @@ PUT /projects/:id/issues/:issue_iid | Attribute | Type | Required | Description | |----------------|---------|----------|------------------------------------------------------------------------------------------------------------| -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `title` | string | no | The title of an issue | | `description` | string | no | The description of an issue | | `confidential` | boolean | no | Updates an issue to be confidential | -| `assignee_ids` | Array[integer] | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | +| `assignee_ids` | Array[integer] | no | The ID of the user(s) to assign the issue to. Set to `0` or provide an empty value to unassign all assignees. | | `milestone_id` | integer | no | The global ID of a milestone to assign the issue to. Set to `0` or provide an empty value to unassign a milestone.| | `labels` | string | no | Comma-separated label names for an issue. Set to an empty string to unassign all labels. | | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | | `updated_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | | `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `weight` **[STARTER]** | integer | no | The weight of the issue. Valid values are greater than or equal to 0. 0 | | `discussion_locked` | boolean | no | Flag indicating if the issue's discussion is locked. If the discussion is locked only project members can add or edit comments. | ```bash @@ -702,6 +773,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +{ + "project_id" : 4, + "description" : null, + "weight": null, + ... +} +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -812,6 +895,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +{ + "project_id": 5, + "description": "Repellat voluptas quibusdam voluptatem exercitationem.", + "weight": null, + ... +} +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. @@ -901,6 +996,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `weight` parameter: + +```json +{ + "project_id": 5, + "description": "Repellat voluptas quibusdam voluptatem exercitationem.", + "weight": null, + ... +} +``` + **Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. **Note**: The `closed_by` attribute was [introduced in GitLab 10.6][ce-17042]. This value will only be present for issues which were closed after GitLab 10.6 and when the user account that closed the issue still exists. diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 72973b69117..223bfed91a9 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -14,7 +14,7 @@ GET /projects/:id/jobs | `scope` | string **or** array of strings | no | Scope of jobs to show. Either one of or an array of the following: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, or `manual`. All jobs are returned if `scope` is not provided. | ```sh -curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running' +curl --globoff --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running' ``` Example of response diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 85a07589956..4a00ab66446 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -29,27 +29,28 @@ GET /merge_requests?search=foo&in=title Parameters: -| Attribute | Type | Required | Description | -| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | -| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | -| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | -| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | -| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | -| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | -| `created_after` | datetime | no | Return merge requests created on or after the given time | -| `created_before` | datetime | no | Return merge requests created on or before the given time | -| `updated_after` | datetime | no | Return merge requests updated on or after the given time | -| `updated_before` | datetime | no | Return merge requests updated on or before the given time | -| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | -| `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` | -| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | -| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | -| `source_branch` | string | no | Return merge requests with the given source branch | -| `target_branch` | string | no | Return merge requests with the given target branch | -| `search` | string | no | Search merge requests against their `title` and `description` | -| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | -| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | +| Attribute | Type | Required | Description | +| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------- | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, `locked`, or `merged` | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone. `None` returns merge requests with no milestone. `Any` returns merge requests that have an assigned milestone. | +| `view` | string | no | If `simple`, returns the `iid`, URL, title, description, and basic state of merge request | +| `labels` | string | no | Return merge requests matching a comma separated list of labels. `None` lists all merge requests with no labels. `Any` lists all merge requests with at least one label. `No+Label` (Deprecated) lists all merge requests with no labels. Predefined names are case-insensitive. | +| `created_after` | datetime | no | Return merge requests created on or after the given time | +| `created_before` | datetime | no | Return merge requests created on or before the given time | +| `updated_after` | datetime | no | Return merge requests updated on or after the given time | +| `updated_before` | datetime | no | Return merge requests updated on or before the given time | +| `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`. Defaults to `created_by_me`<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead. | +| `author_id` | integer | no | Returns merge requests created by the given user `id`. Combine with `scope=all` or `scope=assigned_to_me` | +| `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. | +| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | +| `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | +| `source_branch` | string | no | Return merge requests with the given source branch | +| `target_branch` | string | no | Return merge requests with the given target branch | +| `search` | string | no | Search merge requests against their `title` and `description` | +| `in` | string | no | Modify the scope of the `search` attribute. `title`, `description`, or a string joining them with comma. Default is `title,description` | +| `wip` | string | no | Filter merge requests against their `wip` status. `yes` to return *only* WIP merge requests, `no` to return *non* WIP merge requests | ```json [ @@ -147,6 +148,20 @@ Parameters: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +[ + { + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... + } +] +``` + ## List project merge requests Get all merge requests for this project. @@ -191,6 +206,7 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> For versions before 11.0, use the now deprecated `created-by-me` or `assigned-to-me` scopes instead.<br> _([Introduced][ce-13060] in GitLab 9.5. [Changed to snake_case][ce-18935] in GitLab 11.0)_ | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | +| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | @@ -293,6 +309,20 @@ Parameters: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +[ + { + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... + } +] +``` + ## List group merge requests Get all merge requests for this group and its subgroups. @@ -328,6 +358,7 @@ Parameters: | `scope` | string | no | Return merge requests for the given scope: `created_by_me`, `assigned_to_me` or `all`.<br> | | `author_id` | integer | no | Returns merge requests created by the given user `id` _([Introduced][ce-13060] in GitLab 9.5)_ | | `assignee_id` | integer | no | Returns merge requests assigned to the given user `id`. `None` returns unassigned merge requests. `Any` returns merge requests with an assignee. _([Introduced][ce-13060] in GitLab 9.5)_ | +| `approver_ids` **[STARTER]** | Array[integer] | no | Returns merge requests which have specified all the users with the given `id`s as individual approvers. `None` returns merge requests without approvers. `Any` returns merge requests with an approver. | | `my_reaction_emoji` | string | no | Return merge requests reacted by the authenticated user by the given `emoji`. `None` returns issues not given a reaction. `Any` returns issues given at least one reaction. _([Introduced][ce-14016] in GitLab 10.0)_ | | `source_branch` | string | no | Return merge requests with the given source branch | | `target_branch` | string | no | Return merge requests with the given target branch | @@ -427,6 +458,20 @@ Parameters: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +[ + { + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... + } +] +``` + ## Get single MR Shows information about a single merge request. @@ -565,6 +610,18 @@ Parameters: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + ## Get single MR participants Get a list of merge request participants. @@ -767,6 +824,7 @@ Parameters: ## Create MR Creates a new merge request. + ``` POST /projects/:id/merge_requests ``` @@ -788,6 +846,15 @@ POST /projects/:id/merge_requests | `allow_maintainer_to_push` | boolean | no | Deprecated, see allow_collaboration | | `squash` | boolean | no | Squash commits into a single commit when merging | +If `approvals_before_merge` **[STARTER]** is not provided, it inherits the value from the +target project. If it is provided, then the following conditions must hold in +order for it to take effect: + +1. The target project's `approvals_before_merge` must be greater than zero. A + value of zero disables approvals for that project. +1. The provided value of `approvals_before_merge` must be greater than the + target project's `approvals_before_merge`. + ```json { "id": 1, @@ -893,6 +960,18 @@ POST /projects/:id/merge_requests } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + ## Update MR Updates an existing merge request. You can change the target branch, title, or even close the MR. @@ -1034,6 +1113,18 @@ Must include at least one non-required attribute from above. } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + ## Delete a merge request Only for admins and project owners. Soft deletes the merge request in question. @@ -1191,9 +1282,21 @@ Parameters: } ``` -## Returns the up to date merge-ref HEAD commit +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + +## Merge to default merge ref path -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. @@ -1349,6 +1452,18 @@ Parameters: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + ## Rebase a merge request Automatically rebase the `source_branch` of the merge request against its @@ -1616,6 +1731,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + ## Unsubscribe from a merge request Unsubscribes the authenticated user from a merge request to not receive @@ -1749,6 +1876,18 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 1, + "title": "test1", + "approvals_before_merge": null + ... +} +``` + ## Create a todo Manually creates a todo for the current user on a merge request. @@ -1970,6 +2109,7 @@ Example response: }] } ``` + ## Set a time estimate for a merge request Sets an estimated time of work for this merge request. @@ -2114,3 +2254,7 @@ Example response: [ce-14016]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/14016 [ce-15454]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/15454 [ce-18935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/18935 + +## Approvals **[STARTER]** + +For approvals, please see [Merge Request Approvals](merge_request_approvals.md) diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 90d8c033cd6..e745d0c2e6c 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -147,3 +147,18 @@ Parameters: - `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone + +## Get all burndown chart events for a single milestone **[STARTER]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4737) in GitLab 12.1 + +Gets all burndown chart events for a single milestone. + +``` +GET /projects/:id/milestones/:milestone_id/burndown_events +``` + +Parameters: + +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `milestone_id` (required) - The ID of a project milestone diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index b66a3198ffb..5db7035fd90 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -54,7 +54,21 @@ Example response: ] ``` -**Note**: `members_count_with_descendants` are presented only for group maintainers/owners. +Users on GitLab.com [Bronze or higher](https://about.gitlab.com/pricing/#gitlab-com) may also see +the `plan` parameter associated with a namespace: + +```json +[ + { + "id": 1, + "name": "user1", + "plan": "bronze", + ... + } +] +``` + +NOTE: **Note:** Only group maintainers/owners are presented with `members_count_with_descendants`, as well as `plan` **[BRONZE ONLY]**. ## Search for namespace diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index e21e73c7dac..ccc1cccf7a4 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -1,8 +1,8 @@ # Notification settings API ->**Note:** This feature was [introduced][ce-5632] in GitLab 8.12. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632) in GitLab 8.12. -**Valid notification levels** +## Valid notification levels The notification levels are defined in the `NotificationSetting.level` model enumeration. Currently, these levels are recognized: @@ -17,22 +17,21 @@ custom If the `custom` level is used, specific email events can be controlled. Available events are returned by `NotificationSetting.email_events`. Currently, these events are recognized: -``` -new_note -new_issue -reopen_issue -close_issue -reassign_issue -issue_due -new_merge_request -push_to_merge_request -reopen_merge_request -close_merge_request -reassign_merge_request -merge_merge_request -failed_pipeline -success_pipeline -``` +- `new_note` +- `new_issue` +- `reopen_issue` +- `close_issue` +- `reassign_issue` +- `issue_due` +- `new_merge_request` +- `push_to_merge_request` +- `reopen_merge_request` +- `close_merge_request` +- `reassign_merge_request` +- `merge_merge_request` +- `failed_pipeline` +- `success_pipeline` +- `new_epic` **[ULTIMATE]** ## Global notification settings @@ -85,6 +84,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. | `merge_merge_request` | boolean | no | Enable/disable this notification | | `failed_pipeline` | boolean | no | Enable/disable this notification | | `success_pipeline` | boolean | no | Enable/disable this notification | +| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** | Example response: @@ -153,6 +153,7 @@ curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab. | `merge_merge_request` | boolean | no | Enable/disable this notification | | `failed_pipeline` | boolean | no | Enable/disable this notification | | `success_pipeline` | boolean | no | Enable/disable this notification | +| `new_epic` | boolean | no | Enable/disable this notification ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6626) in 11.3) **[ULTIMATE]** | Example responses: @@ -182,4 +183,17 @@ Example responses: } ``` -[ce-5632]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5632 +Users on GitLab [Ultimate or Gold](https://about.gitlab.com/pricing/) will also see +the `new_epic` parameter: + +```json +{ + "level": "custom", + "events": { + "new_note": true, + "new_issue": false, + "new_epic": false, + ... + } +} +``` diff --git a/doc/api/pipeline_schedules.md b/doc/api/pipeline_schedules.md index 470e55425f8..acf1ac90315 100644 --- a/doc/api/pipeline_schedules.md +++ b/doc/api/pipeline_schedules.md @@ -108,9 +108,9 @@ POST /projects/:id/pipeline_schedules | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | yes | The description of pipeline schedule | | `ref` | string | yes | The branch/tag name will be triggered | -| `cron ` | string | yes | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | -| `cron_timezone ` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`) | -| `active ` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) | +| `cron` | string | yes | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | +| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) (default: `'UTC'`) | +| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially (default: `true`) | ```sh curl --request POST --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form description="Build packages" --form ref="master" --form cron="0 1 * * 5" --form cron_timezone="UTC" --form active="true" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules" @@ -153,9 +153,9 @@ PUT /projects/:id/pipeline_schedules/:pipeline_schedule_id | `pipeline_schedule_id` | integer | yes | The pipeline schedule id | | `description` | string | no | The description of pipeline schedule | | `ref` | string | no | The branch/tag name will be triggered | -| `cron ` | string | no | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | -| `cron_timezone ` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`) | -| `active ` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. | +| `cron` | string | no | The cron (e.g. `0 1 * * *`) ([Cron syntax](https://en.wikipedia.org/wiki/Cron)) | +| `cron_timezone` | string | no | The timezone supported by `ActiveSupport::TimeZone` (e.g. `Pacific Time (US & Canada)`) or `TZInfo::Timezone` (e.g. `America/Los_Angeles`) | +| `active` | boolean | no | The activation of pipeline schedule. If false is set, the pipeline schedule will deactivated initially. | ```sh curl --request PUT --header "PRIVATE-TOKEN: k5ESFgWY2Qf5xEvDcFxZ" --form cron="0 2 * * *" "https://gitlab.example.com/api/v4/projects/29/pipeline_schedules/13" diff --git a/doc/api/project_aliases.md b/doc/api/project_aliases.md index 65845579409..76343b4cd82 100644 --- a/doc/api/project_aliases.md +++ b/doc/api/project_aliases.md @@ -68,13 +68,19 @@ Add a new alias for a project. Responds with a 201 when successful, POST /project_aliases ``` -| Attribute | Type | Required | Description | -|--------------|--------|----------|-----------------------------------------------| -| `project_id` | string | yes | The ID or URL-encoded path of the project. | -| `name` | string | yes | The name of the alias. Must be unique. | +| Attribute | Type | Required | Description | +|--------------|----------------|----------|----------------------------------------| +| `project_id` | integer/string | yes | The ID or path of the project. | +| `name` | string | yes | The name of the alias. Must be unique. | ``` -curl --request POST "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=gitlab-org%2Fgitlab-ee" --form "name=gitlab-ee" +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=1" --form "name=gitlab-ee" +``` + +or + +``` +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/project_aliases" --form "project_id=gitlab-org/gitlab-ee" --form "name=gitlab-ee" ``` Example response: diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 0ccb0517e08..2b2e40fb276 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -13,6 +13,12 @@ Constants for snippet visibility levels are: | `internal` | The snippet is visible for any logged in user | | `public` | The snippet can be accessed without any authentication | +NOTE: **Note:** +From July 2019, the `Internal` visibility setting is disabled for new projects, groups, +and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` +visibility setting keep this setting. You can read more about the change in the +[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388). + ## List snippets Get a list of project snippets. diff --git a/doc/api/projects.md b/doc/api/projects.md index 1d58e390d9e..e07d6ce9a42 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -14,7 +14,7 @@ Values for the project visibility level are: The project can be cloned by any logged in user. - `public`: - The project can be cloned without any authentication. + The project can be accessed without any authentication. ## Project merge method @@ -41,23 +41,23 @@ GET /projects | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `archived` | boolean | no | Limit by archived status | -| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | -| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | -| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | -| `search` | string | no | Return list of projects matching the search criteria | -| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | -| `owned` | boolean | no | Limit by projects explicitly owned by the current user | -| `membership` | boolean | no | Limit by projects that the current user is a member of | -| `starred` | boolean | no | Limit by projects starred by the current user | -| `statistics` | boolean | no | Include project statistics | -| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | -| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | +| `archived` | boolean | no | Limit by archived status | +| `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | +| `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | +| `sort` | string | no | Return projects sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Return list of projects matching the search criteria | +| `simple` | boolean | no | Return only limited fields for each project. This is a no-op without authentication as then _only_ simple fields are returned. | +| `owned` | boolean | no | Limit by projects explicitly owned by the current user | +| `membership` | boolean | no | Limit by projects that the current user is a member of | +| `starred` | boolean | no | Limit by projects starred by the current user | +| `statistics` | boolean | no | Include project statistics | +| `with_custom_attributes` | boolean | no | Include [custom attributes](custom_attributes.md) in response (admins only) | +| `with_issues_enabled` | boolean | no | Limit by enabled issues feature | | `with_merge_requests_enabled` | boolean | no | Limit by enabled merge requests feature | -| `with_programming_language` | string | no | Limit by projects which use the given programming language | -| `wiki_checksum_failed` | boolean | no | Limit projects where the wiki checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ | -| `repository_checksum_failed` | boolean | no | Limit projects where the repository checksum calculation has failed _([Introduced][ee-6137] in [GitLab Premium][eep] 11.2)_ | -| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) | +| `with_programming_language` | string | no | Limit by projects which use the given programming language | +| `wiki_checksum_failed` | boolean | no | **[PREMIUM]** Limit projects where the wiki checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | +| `repository_checksum_failed` | boolean | no | **[PREMIUM]** Limit projects where the repository checksum calculation has failed ([Introduced](https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.2) | +| `min_access_level` | integer | no | Limit by current user minimal [access level](members.md) | When `simple=true` or the user is unauthenticated this returns something like: @@ -156,7 +156,8 @@ When the user is authenticated and `simple` is not set this returns something li "repository_size": 1038090, "wiki_size" : 0, "lfs_objects_size": 0, - "job_artifacts_size": 0 + "job_artifacts_size": 0, + "packages_size": 0 }, "_links": { "self": "http://example.com/api/v4/projects", @@ -239,7 +240,8 @@ When the user is authenticated and `simple` is not set this returns something li "repository_size": 2066080, "wiki_size" : 0, "lfs_objects_size": 0, - "job_artifacts_size": 0 + "job_artifacts_size": 0, + "packages_size": 0 }, "_links": { "self": "http://example.com/api/v4/projects", @@ -254,6 +256,20 @@ When the user is authenticated and `simple` is not set this returns something li ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +[ + { + "id": 4, + "description": null, + "approvals_before_merge": 0, + ... + } +] +``` + You can filter by [custom attributes](custom_attributes.md) with: ``` @@ -349,7 +365,8 @@ GET /users/:user_id/projects "repository_size": 1038090, "wiki_size" : 0, "lfs_objects_size": 0, - "job_artifacts_size": 0 + "job_artifacts_size": 0, + "packages_size": 0 }, "_links": { "self": "http://example.com/api/v4/projects", @@ -432,7 +449,8 @@ GET /users/:user_id/projects "repository_size": 2066080, "wiki_size" : 0, "lfs_objects_size": 0, - "job_artifacts_size": 0 + "job_artifacts_size": 0, + "packages_size": 0 }, "_links": { "self": "http://example.com/api/v4/projects", @@ -548,6 +566,7 @@ GET /projects/:id "group_access_level": 10 } ], + "repository_storage": "default", "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, "printing_merge_requests_link_enabled": true, @@ -559,7 +578,8 @@ GET /projects/:id "repository_size": 1038090, "wiki_size" : 0, "lfs_objects_size": 0, - "job_artifacts_size": 0 + "job_artifacts_size": 0, + "packages_size": 0 }, "_links": { "self": "http://example.com/api/v4/projects", @@ -573,6 +593,18 @@ GET /projects/:id } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `approvals_before_merge` parameter: + +```json +{ + "id": 3, + "description": null, + "approvals_before_merge": 0, + ... +} +``` + **Note**: The `web_url` and `avatar_url` attributes on `namespace` were [introduced][ce-27427] in GitLab 11.11. If the project is a fork, and you provide a valid token to authenticate, the @@ -674,6 +706,7 @@ POST /projects | `name` | string | yes if path is not provided | The name of the new project. Equals path if not provided. | | `path` | string | yes if name is not provided | Repository name for new project. Generated based on name if not provided (generated lowercased with dashes). | | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | +| `default_branch` | string | no | `master` by default | | `description` | string | no | Short project description | | `issues_enabled` | boolean | no | Enable issues for this project | | `merge_requests_enabled` | boolean | no | Enable merge requests for this project | @@ -695,8 +728,16 @@ POST /projects | `avatar` | mixed | no | Image file for avatar of the project | | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | | `ci_config_path` | string | no | The path to CI config file | +| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | +| `approvals_before_merge` | integer | no | **[STARTER]** How many approvers should approve merge requests by default | +| `mirror` | boolean | no | **[STARTER]** Enables pull mirroring in a project | +| `mirror_trigger_builds` | boolean | no | **[STARTER]** Pull mirroring triggers builds | | `initialize_with_readme` | boolean | no | `false` by default | +NOTE: **Note:** If your HTTP repository is not publicly accessible, +add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` +where `password` is a public access key with the `api` scope enabled. + ## Create project for user Creates a new project owned by the specified user. Available only for admins. @@ -710,7 +751,6 @@ POST /projects/user/:user_id | `user_id` | integer | yes | The user ID of the project owner | | `name` | string | yes | The name of the new project | | `path` | string | no | Custom repository name for new project. By default generated based on name | -| `default_branch` | string | no | `master` by default | | `namespace_id` | integer | no | Namespace for the new project (defaults to the current user's namespace) | | `description` | string | no | Short project description | | `issues_enabled` | boolean | no | Enable issues for this project | @@ -733,6 +773,15 @@ POST /projects/user/:user_id | `avatar` | mixed | no | Image file for avatar of the project | | `printing_merge_request_link_enabled` | boolean | no | Show link to create/view merge request when pushing from the command line | | `ci_config_path` | string | no | The path to CI config file | +| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | +| `approvals_before_merge` | integer | no | **[STARTER]** How many approvers should approve merge requests by default | +| `external_authorization_classification_label` | string | no | **[CORE ONLY]** The classification label for the project | +| `mirror` | boolean | no | **[STARTER]** Enables pull mirroring in a project | +| `mirror_trigger_builds` | boolean | no | **[STARTER]** Pull mirroring triggers builds | + +NOTE: **Note:** If your HTTP repository is not publicly accessible, +add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` +where `password` is a public access key with the `api` scope enabled. ## Edit project @@ -769,6 +818,19 @@ PUT /projects/:id | `avatar` | mixed | no | Image file for avatar of the project | | `ci_config_path` | string | no | The path to CI config file | | `ci_default_git_depth` | integer | no | Default number of revisions for [shallow cloning](../user/project/pipelines/settings.md#git-shallow-clone) | +| `repository_storage` | string | no | Which storage shard the repository is on. Available only to admins | +| `approvals_before_merge` | integer | no | **[STARTER]** How many approvers should approve merge request by default | +| `external_authorization_classification_label` | string | no | **[CORE ONLY]** The classification label for the project | +| `mirror` | boolean | no | **[STARTER]** Enables pull mirroring in a project | +| `mirror_user_id` | integer | no | **[STARTER]** User responsible for all the activity surrounding a pull mirror event | +| `mirror_trigger_builds` | boolean | no | **[STARTER]** Pull mirroring triggers builds | +| `only_mirror_protected_branches` | boolean | no | **[STARTER]** Only mirror protected branches | +| `mirror_overwrites_diverged_branches` | boolean | no | **[STARTER]** Pull mirror overwrites diverged branches | +| `packages_enabled` | boolean | no | **[PREMIUM ONLY]** Enable or disable packages repository feature | + +NOTE: **Note:** If your HTTP repository is not publicly accessible, +add authentication information to the URL: `https://username:password@gitlab.company.com/group/project.git` +where `password` is a public access key with the `api` scope enabled. ## Fork project @@ -1292,7 +1354,7 @@ Example response: ## Remove project -Removes a project including all associated resources (issues, merge requests etc.) +Removes a project including all associated resources (issues, merge requests etc). ``` DELETE /projects/:id @@ -1548,9 +1610,111 @@ POST /projects/:id/housekeeping | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | + +## Push Rules **[STARTER]** + +### Get project push rules + +Get the push rules of a project. + +``` +GET /projects/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | + +```json +{ + "id": 1, + "project_id": 3, + "commit_message_regex": "Fixes \d+\..*", + "branch_name_regex": "", + "deny_delete_tag": false, + "created_at": "2012-10-12T17:04:47Z", + "member_check": false, + "prevent_secrets": false, + "author_email_regex": "", + "file_name_regex": "", + "max_file_size": 5, + "commit_committer_check": false +} +``` + +Users on GitLab [Premium, Silver, or higher](https://about.gitlab.com/pricing/) will also see +the `commit_committer_check` parameter: + +```json +{ + "id": 1, + "project_id": 3, + "commit_committer_check": false + ... +} +``` + +### Add project push rule + +Adds a push rule to a specified project. + +``` +POST /projects/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| -------------------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `deny_delete_tag` **[STARTER]** | boolean | no | Deny deleting a tag | +| `member_check` **[STARTER]** | boolean | no | Restrict commits by author (email) to existing GitLab users | +| `prevent_secrets` **[STARTER]** | boolean | no | GitLab will reject any files that are likely to contain secrets | +| `commit_message_regex` **[STARTER]** | string | no | All commit messages must match this, e.g. `Fixed \d+\..*` | +| `branch_name_regex` **[STARTER]** | string | no | All branch names must match this, e.g. `(feature|hotfix)\/*` | +| `author_email_regex` **[STARTER]** | string | no | All commit author emails must match this, e.g. `@my-company.com$` | +| `file_name_regex` **[STARTER]** | string | no | All commited filenames must **not** match this, e.g. `(jar|exe)$` | +| `max_file_size` **[STARTER]** | integer | no | Maximum file size (MB) | +| `commit_committer_check` **[PREMIUM]** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | + +### Edit project push rule + +Edits a push rule for a specified project. + +``` +PUT /projects/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| -------------------------------------- | -------------- | -------- | ----------- | +| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `deny_delete_tag` **[STARTER]** | boolean | no | Deny deleting a tag | +| `member_check` **[STARTER]** | boolean | no | Restrict commits by author (email) to existing GitLab users | +| `prevent_secrets` **[STARTER]** | boolean | no | GitLab will reject any files that are likely to contain secrets | +| `commit_message_regex` **[STARTER]** | string | no | All commit messages must match this, e.g. `Fixed \d+\..*` | +| `branch_name_regex` **[STARTER]** | string | no | All branch names must match this, e.g. `(feature|hotfix)\/*` | +| `author_email_regex` **[STARTER]** | string | no | All commit author emails must match this, e.g. `@my-company.com$` | +| `file_name_regex` **[STARTER]** | string | no | All commited filenames must **not** match this, e.g. `(jar|exe)$` | +| `max_file_size` **[STARTER]** | integer | no | Maximum file size (MB) | +| `commit_committer_check` **[PREMIUM]** | boolean | no | Users can only push commits to this repository that were committed with one of their own verified emails. | + +### Delete project push rule + +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0. + +Removes a push rule from a project. This is an idempotent method and can be called multiple times. +Either the push rule is available or not. + +``` +DELETE /projects/:id/push_rule +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | -### Transfer a project to a new namespace +## Transfer a project to a new namespace + +> Introduced in GitLab 11.1. ``` PUT /projects/:id/transfer @@ -1572,6 +1736,22 @@ Read more in the [Project import/export](project_import_export.md) documentation Read more in the [Project members](members.md) documentation. +## Start the pull mirroring process for a Project **[STARTER]** + +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing) 10.3. + +``` +POST /projects/:id/mirror/pull +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/:id/mirror/pull +``` + ## Project badges Read more in the [Project Badges](project_badges.md) documentation. @@ -1602,6 +1782,4 @@ GET /projects/:id/snapshot | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `wiki` | boolean | no | Whether to download the wiki, rather than project, repository | -[eep]: https://about.gitlab.com/pricing/ "Available only in GitLab Premium" -[ee-6137]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/6137 [ce-27427]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/27427 diff --git a/doc/api/protected_branches.md b/doc/api/protected_branches.md index a261bb75be5..6e41584afef 100644 --- a/doc/api/protected_branches.md +++ b/doc/api/protected_branches.md @@ -10,6 +10,7 @@ The access levels are defined in the `ProtectedRefAccess.allowed_access_levels` 0 => No access 30 => Developer access 40 => Maintainer access +60 => Admin access ``` ## List protected branches @@ -51,6 +52,36 @@ Example response: ] ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `user_id` and `group_id` parameters: + +Example response: + +```json +[ + { + "name": "master", + "push_access_levels": [ + { + "access_level": 40, + "user_id": null, + "group_id": null, + "access_level_description": "Maintainers" + } + ], + "merge_access_levels": [ + { + "access_level": null, + "user_id": null, + "group_id": 1234, + "access_level_description": "Example Merge Group" + } + ] + }, + ... +] +``` + ## Get a single protected branch or wildcard protected branch Gets a single protected branch or wildcard protected branch. @@ -88,6 +119,33 @@ Example response: } ``` +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `user_id` and `group_id` parameters: + +Example response: + +```json +{ + "name": "master", + "push_access_levels": [ + { + "access_level": 40, + "user_id": null, + "group_id": null, + "access_level_description": "Maintainers" + } + ], + "merge_access_levels": [ + { + "access_level": null, + "user_id": null, + "group_id": 1234, + "access_level_description": "Example Merge Group" + } + ] +} +``` + ## Protect repository branches Protects a single repository branch or several project repository @@ -98,15 +156,47 @@ POST /projects/:id/protected_branches ``` ```bash -curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30' +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&push_access_level=30&merge_access_level=30&unprotect_access_level=40' ``` | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | -| `name` | string | yes | The name of the branch or wildcard | -| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) | -| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `name` | string | yes | The name of the branch or wildcard | +| `push_access_level` | string | no | Access levels allowed to push (defaults: `40`, maintainer access level) | +| `merge_access_level` | string | no | Access levels allowed to merge (defaults: `40`, maintainer access level) | +| `unprotect_access_level` | string | no | Access levels allowed to unprotect (defaults: `40`, maintainer access level) | +| `allowed_to_push` | array | no | **[STARTER]** Array of access levels allowed to push, with each described by a hash | +| `allowed_to_merge` | array | no | **[STARTER]** Array of access levels allowed to merge, with each described by a hash | +| `allowed_to_unprotect` | array | no | **[STARTER]**Array of access levels allowed to unprotect, with each described by a hash | + +Example response: + +```json +{ + "name": "*-stable", + "push_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers" + } + ], + "merge_access_levels": [ + { + "access_level": 30, + "access_level_description": "Developers + Maintainers" + ], + "unprotect_access_levels": [ + { + "access_level": 40, + "access_level_description": "Maintainers" + } + ] +} +``` + +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `user_id` and `group_id` parameters: Example response: @@ -116,13 +206,65 @@ Example response: "push_access_levels": [ { "access_level": 30, + "user_id": null, + "group_id": null, "access_level_description": "Developers + Maintainers" } ], "merge_access_levels": [ { "access_level": 30, + "user_id": null, + "group_id": null, "access_level_description": "Developers + Maintainers" + ], + "unprotect_access_levels": [ + { + "access_level": 40, + "user_id": null, + "group_id": null, + "access_level_description": "Maintainers" + } + ] +} +``` + +### Example with user / group level access **[STARTER]** + +Elements in the `allowed_to_push` / `allowed_to_merge` / `allowed_to_unprotect` array should take the +form `{user_id: integer}`, `{group_id: integer}` or `{access_level: integer}`. Each user must have access to the project and each group must [have this project shared](../user/project/members/share_project_with_groups.md). These access levels allow [more granular control over protected branch access](../user/project/protected_branches.md#restricting-push-and-merge-access-to-certain-users-starter) and were [added to the API in ][ee-3516] in GitLab 10.3 EE. + +```bash +curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/projects/5/protected_branches?name=*-stable&allowed_to_push%5B%5D%5Buser_id%5D=1' +``` + +Example response: + +```json +{ + "name":"*-stable", + "push_access_levels": [ + { + "access_level":null, + "user_id":1, + "group_id":null, + "access_level_description":"Administrator" + } + ], + "merge_access_levels": [ + { + "access_level":40, + "user_id":null, + "group_id":null, + "access_level_description":"Maintainers" + } + ], + "unprotect_access_levels": [ + { + "access_level":40, + "user_id":null, + "group_id":null, + "access_level_description":"Maintainers" } ] } @@ -144,3 +286,5 @@ curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" 'https://git | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the branch | + +[ee-3516]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/3516 "ProtectedBranches API handles per user/group granularity" diff --git a/doc/api/settings.md b/doc/api/settings.md index b01cec64837..0f46662a8ae 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -67,6 +67,19 @@ Example response: } ``` +Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see +the `file_template_project_id` or the `geo_node_allowed_ips` parameters: + +```json +{ + "id" : 1, + "signup_enabled" : true, + "file_template_project_id": 1, + "geo_node_allowed_ips": "0.0.0.0/0, ::/0" + ... +} +``` + ## Change application settings Use an API call to modify GitLab instance @@ -121,10 +134,33 @@ Example response: "performance_bar_allowed_group_id": 42, "instance_statistics_visibility_private": false, "user_show_add_ssh_key_message": true, - "local_markdown_version": 0 + "file_template_project_id": 1, + "local_markdown_version": 0, + "geo_node_allowed_ips": "0.0.0.0/0, ::/0" } ``` +Users on GitLab [Premium or Ultimate](https://about.gitlab.com/pricing/) may also see +these parameters: + +- `external_authorization_service_enabled` +- `external_authorization_service_url` +- `external_authorization_service_default_label` +- `external_authorization_service_timeout` +- `file_template_project_id` +- `geo_node_allowed_ips` + +Example responses: **[PREMIUM ONLY]** + +```json + "external_authorization_service_enabled": true, + "external_authorization_service_url": "https://authorize.me", + "external_authorization_service_default_label": "default", + "external_authorization_service_timeout": 0.5, + "file_template_project_id": 1, + "geo_node_allowed_ips": "0.0.0.0/0, ::/0" +``` + ## List of settings that can be accessed via API calls In general, all settings are optional. Certain settings though, if enabled, will @@ -138,10 +174,14 @@ are listed in the descriptions of the relevant settings. | `after_sign_up_text` | string | no | Text shown to the user after signing up | | `akismet_api_key` | string | required by: `akismet_enabled` | API key for akismet spam protection. | | `akismet_enabled` | boolean | no | (**If enabled, requires:** `akismet_api_key`) Enable or disable akismet spam protection. | +| `allow_group_owners_to_manage_ldap` | boolean | no | **[PREMIUM]** Set to `true` to allow group owners to manage LDAP | | `allow_local_requests_from_hooks_and_services` | boolean | no | Allow requests to the local network from hooks and services. | | `authorized_keys_enabled` | boolean | no | By default, we write to the `authorized_keys` file to support Git over SSH without additional configuration. GitLab can be optimized to authenticate SSH keys via the database file. Only disable this if you have configured your OpenSSH server to use the AuthorizedKeysCommand. | | `auto_devops_domain` | string | no | Specify a domain to use by default for every project's Auto Review Apps and Auto Deploy stages. | | `auto_devops_enabled` | boolean | no | Enable Auto DevOps for projects by default. It will automatically build, test, and deploy applications based on a predefined CI/CD configuration. | +| `check_namespace_plan` | boolean | no | **[PREMIUM]** Enabling this will make only licensed EE features available to projects if the project namespace's plan includes the feature or if the project is public. | +| `clientside_sentry_dsn` | string | required by: `clientside_sentry_enabled` | Clientside Sentry Data Source Name. | +| `clientside_sentry_enabled` | boolean | no | (**If enabled, requires:** `clientside_sentry_dsn`) Enable Sentry error reporting for the client side. | | `container_registry_token_expire_delay` | integer | no | Container Registry token duration in minutes. | | `default_artifacts_expire_in` | string | no | Set the default expiration time for each job's artifacts. | | `default_branch_protection` | integer | no | Determine if developers can push to master. Can take: `0` _(not protected, both developers and maintainers can push new commits, force push, or delete the branch)_, `1` _(partially protected, developers and maintainers can push new commits, but cannot force push or delete the branch)_ or `2` _(fully protected, developers cannot push new commits, but maintainers can; no-one can force push or delete the branch)_ as a parameter. Default is `2`. | @@ -156,10 +196,31 @@ are listed in the descriptions of the relevant settings. | `dsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded DSA key. Default is `0` (no restriction). `-1` disables DSA keys. | | `ecdsa_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ECDSA key. Default is `0` (no restriction). `-1` disables ECDSA keys. | | `ed25519_key_restriction` | integer | no | The minimum allowed curve size (in bits) of an uploaded ED25519 key. Default is `0` (no restriction). `-1` disables ED25519 keys. | +| `elasticsearch_aws` | boolean | no | **[PREMIUM]** Enable the use of AWS hosted Elasticsearch | +| `elasticsearch_aws_access_key` | string | no | **[PREMIUM]** AWS IAM access key | +| `elasticsearch_aws_region` | string | no | **[PREMIUM]** The AWS region the elasticsearch domain is configured | +| `elasticsearch_aws_secret_access_key` | string | no | **[PREMIUM]** AWS IAM secret access key | +| `elasticsearch_experimental_indexer` | boolean | no | **[PREMIUM]** Use the experimental elasticsearch indexer. More info: <https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer> | +| `elasticsearch_indexing` | boolean | no | **[PREMIUM]** Enable Elasticsearch indexing | +| `elasticsearch_search` | boolean | no | **[PREMIUM]** Enable Elasticsearch search | +| `elasticsearch_url` | string | no | **[PREMIUM]** The url to use for connecting to Elasticsearch. Use a comma-separated list to support cluster (e.g., `http://localhost:9200, http://localhost:9201"`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | +| `elasticsearch_limit_indexing` | boolean | no | **[PREMIUM]** Limit Elasticsearch to index certain namespaces and projects | +| `elasticsearch_project_ids` | array of integers | no | **[PREMIUM]** The projects to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `elasticsearch_namespace_ids` | array of integers | no | **[PREMIUM]** The namespaces to index via Elasticsearch if `elasticsearch_limit_indexing` is enabled. | +| `email_additional_text` | string | no | **[PREMIUM]** Additional text added to the bottom of every email for legal/auditing/compliance reasons | | `email_author_in_body` | boolean | no | Some email servers do not support overriding the email sender name. Enable this option to include the name of the author of the issue, merge request or comment in the email body instead. | | `enabled_git_access_protocol` | string | no | Enabled protocols for Git access. Allowed values are: `ssh`, `http`, and `nil` to allow both protocols. | | `enforce_terms` | boolean | no | (**If enabled, requires:** `terms`) Enforce application ToS to all users. | -| `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | +| `external_auth_client_cert` | string | no | **[PREMIUM]** (**If enabled, requires:** `external_auth_client_key`) The certificate to use to authenticate with the external authorization service | +| `external_auth_client_key` | string | required by: `external_auth_client_cert` | **[PREMIUM]** Private key for the certificate when authentication is required for the external authorization service, this is encrypted when stored | +| `external_auth_client_key_pass` | string | no | **[PREMIUM]** Passphrase to use for the private key when authenticating with the external service this is encrypted when stored | +| `external_authorization_service_enabled` | boolean | no | **[PREMIUM]** (**If enabled, requires:** `external_authorization_service_default_label`, `external_authorization_service_timeout` and `external_authorization_service_url` ) Enable using an external authorization service for accessing projects | +| `external_authorization_service_default_label` | string | required by: `external_authorization_service_enabled` | **[PREMIUM]** The default classification label to use when requesting authorization and no classification label has been specified on the project | +| `external_authorization_service_timeout` | float | required by: `external_authorization_service_enabled` | **[PREMIUM]** The timeout after which an authorization request is aborted, in seconds. When a request times out, access is denied to the user. (min: 0.001, max: 10, step: 0.001) | +| `external_authorization_service_url` | string | required by: `external_authorization_service_enabled` | **[PREMIUM]** URL to which authorization requests will be directed | +| `file_template_project_id` | integer | no | **[PREMIUM]** The ID of a project to load custom file templates from | +| `first_day_of_week` | integer | no | Start day of the week for calendar views and date pickers. Valid values are `0` (default) for Sunday, `1` for Monday, and `6` for Saturday. | +| `geo_status_timeout` | integer | no | **[PREMIUM]** The amount of seconds after which a request to get a secondary node status will time out. | | `gitaly_timeout_default` | integer | no | Default Gitaly timeout, in seconds. This timeout is not enforced for git fetch/push operations or Sidekiq jobs. Set to `0` to disable timeouts. | | `gitaly_timeout_fast` | integer | no | Gitaly fast operation timeout, in seconds. Some Gitaly operations are expected to be fast. If they exceed this threshold, there may be a problem with a storage shard and 'failing fast' can help maintain the stability of the GitLab instance. Set to `0` to disable timeouts. | | `gitaly_timeout_medium` | integer | no | Medium Gitaly timeout, in seconds. This should be a value between the Fast and the Default timeout. Set to `0` to disable timeouts. | @@ -168,6 +229,7 @@ are listed in the descriptions of the relevant settings. | `help_page_hide_commercial_content` | boolean | no | Hide marketing-related entries from help. | | `help_page_support_url` | string | no | Alternate support URL for help page. | | `help_page_text` | string | no | Custom text displayed on the help page. | +| `help_text` | string | no | **[PREMIUM]** GitLab server administrator information | | `hide_third_party_offers` | boolean | no | Do not display offers from third parties within GitLab. | | `home_page_url` | string | no | Redirect to this URL when not logged in. | | `housekeeping_bitmaps_enabled` | boolean | required by: `housekeeping_enabled` | Enable Git pack file bitmap creation. | @@ -190,6 +252,9 @@ are listed in the descriptions of the relevant settings. | `metrics_sample_interval` | integer | required by: `metrics_enabled` | The sampling interval in seconds. | | `metrics_timeout` | integer | required by: `metrics_enabled` | The amount of seconds after which InfluxDB will time out. | | `mirror_available` | boolean | no | Allow mirrors to be set up for projects. If disabled, only admins will be able to set up mirrors in projects. | +| `mirror_capacity_threshold` | integer | no | **[PREMIUM]** Minimum capacity to be available before scheduling more mirrors preemptively | +| `mirror_max_capacity` | integer | no | **[PREMIUM]** Maximum number of mirrors that can be synchronizing at the same time. | +| `mirror_max_delay` | integer | no | **[PREMIUM]** Maximum time (in minutes) between updates that a mirror can have when scheduled to synchronize. | | `pages_domain_verification_enabled` | boolean | no | Require users to prove ownership of custom domains. Domain verification is an essential security measure for public GitLab sites. Users are required to demonstrate they control a domain before it is enabled. | | `password_authentication_enabled_for_git` | boolean | no | Enable authentication for Git over HTTP(S) via a GitLab account password. Default is `true`. | | `password_authentication_enabled_for_web` | boolean | no | Enable authentication for the web interface via a GitLab account password. Default is `true`. | @@ -201,21 +266,28 @@ are listed in the descriptions of the relevant settings. | `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to `0` to disable polling. | | `project_export_enabled` | boolean | no | Enable project export. | | `prometheus_metrics_enabled` | boolean | no | Enable prometheus metrics. | +| `pseudonymizer_enabled` | boolean | no | **[PREMIUM]** When enabled, GitLab will run a background job that will produce pseudonymized CSVs of the GitLab database that will be uploaded to your configured object storage directory. | `recaptcha_enabled` | boolean | no | (**If enabled, requires:** `recaptcha_private_key` and `recaptcha_site_key`) Enable recaptcha. | | `recaptcha_private_key` | string | required by: `recaptcha_enabled` | Private key for recaptcha. | | `recaptcha_site_key` | string | required by: `recaptcha_enabled` | Site key for recaptcha. | | `repository_checks_enabled` | boolean | no | GitLab will periodically run `git fsck` in all project and wiki repositories to look for silent disk corruption issues. | +| `repository_size_limit` | integer | no | **[PREMIUM]** Size limit per repository (MB) | | `repository_storages` | array of strings | no | A list of names of enabled storage paths, taken from `gitlab.yml`. New projects will be created in one of these stores, chosen at random. | | `require_two_factor_authentication` | boolean | no | (**If enabled, requires:** `two_factor_grace_period`) Require all users to set up Two-factor authentication. | | `restricted_visibility_levels` | array of strings | no | Selected levels cannot be used by non-admin users for groups, projects or snippets. Can take `private`, `internal` and `public` as a parameter. Default is `null` which means there is no restriction. | | `rsa_key_restriction` | integer | no | The minimum allowed bit length of an uploaded RSA key. Default is `0` (no restriction). `-1` disables RSA keys. | | `send_user_confirmation_email` | boolean | no | Send confirmation email on sign-up. | | `session_expire_delay` | integer | no | Session duration in minutes. GitLab restart is required to apply changes | -| `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text`) Enable shared runners for new projects. | +| `shared_runners_enabled` | boolean | no | (**If enabled, requires:** `shared_runners_text` and `shared_runners_minutes`) Enable shared runners for new projects. | +| `shared_runners_minutes` | integer | required by: `shared_runners_enabled` | **[PREMIUM]** Set the maximum number of pipeline minutes that a group can use on shared Runners per month. | | `shared_runners_text` | string | required by: `shared_runners_enabled` | Shared runners text. | | `sign_in_text` | string | no | Text on the login page. | | `signin_enabled` | string | no | (Deprecated: Use `password_authentication_enabled_for_web` instead) Flag indicating if password authentication is enabled for the web interface. | | `signup_enabled` | boolean | no | Enable registration. Default is `true`. | +| `slack_app_enabled` | boolean | no | **[PREMIUM]** (**If enabled, requires:** `slack_app_id`, `slack_app_secret` and `slack_app_secret`) Enable Slack app. | +| `slack_app_id` | string | required by: `slack_app_enabled` | **[PREMIUM]** The app id of the Slack-app. | +| `slack_app_secret` | string | required by: `slack_app_enabled` | **[PREMIUM]** The app secret of the Slack-app. | +| `slack_app_verification_token` | string | required by: `slack_app_enabled` | **[PREMIUM]** The verification token of the Slack-app. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to `0` for unlimited time. | | `terms` | text | required by: `enforce_terms` | (**Required by:** `enforce_terms`) Markdown content for the ToS. | | `throttle_authenticated_api_enabled` | boolean | no | (**If enabled, requires:** `throttle_authenticated_api_period_in_seconds` and `throttle_authenticated_api_requests_per_period`) Enable authenticated API request rate limit. Helps reduce request volume (e.g. from crawlers or abusive bots). | @@ -238,3 +310,4 @@ are listed in the descriptions of the relevant settings. | `user_show_add_ssh_key_message` | boolean | no | When set to `false` disable the "You won't be able to pull or push project code via SSH" warning shown to users with no uploaded SSH key. | | `version_check_enabled` | boolean | no | Let GitLab inform you when an update is available. | | `local_markdown_version` | integer | no | Increase this value when any cached markdown should be invalidated. | +| `geo_node_allowed_ips` | string | yes | **[PREMIUM]** Comma-separated list of IPs and CIDRs of allowed secondary nodes. For example, `1.1.1.1, 2.2.2.0/24`. | diff --git a/doc/api/users.md b/doc/api/users.md index 4667a985eb9..e1fccc14df3 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -70,11 +70,11 @@ Username search is case insensitive. GET /users ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` | -| `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` | -| `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | +| Attribute | Type | Required | Description | +| ------------ | ------ | -------- | ----------- | +| `order_by` | string | no | Return users ordered by `id`, `name`, `username`, `created_at`, or `updated_at` fields. Default is `id` | +| `sort` | string | no | Return users sorted in `asc` or `desc` order. Default is `desc` | +| `two_factor` | string | no | Filter users by Two-factor authentication. Filter values are `enabled` or `disabled`. By default it returns all users | ```json [ @@ -147,6 +147,24 @@ GET /users ] ``` +Users on GitLab [Silver or higher](https://about.gitlab.com/pricing/) will also see +the `group_saml` provider option: + +```json +[ + { + "id": 1, + ... + "identities": [ + {"provider": "github", "extern_uid": "2435223452345"}, + {"provider": "bitbucket", "extern_uid": "john.smith"}, + {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}, + {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10} + ], + ... + } +] + You can lookup users by external UID and provider: ``` @@ -223,6 +241,8 @@ Parameters: - `id` (required) - The ID of a user +Example Responses: + ```json { "id": 1, @@ -258,9 +278,39 @@ Parameters: "can_create_project": true, "two_factor_enabled": true, "external": false, - "private_profile": false, - "shared_runners_minutes_limit": 133 + "private_profile": false +} +``` + +Users on GitLab [Starter, Bronze, or higher](https://about.gitlab.com/pricing/) will also see +the `shared_runners_minutes_limit` and `extra_shared_runners_minutes_limit` parameters. + +```json +{ + "id": 1, + "username": "john_smith", + "shared_runners_minutes_limit": 133, "extra_shared_runners_minutes_limit": 133 + ... +} +``` + +Users on GitLab.com [Silver, or higher](https://about.gitlab.com/pricing/) will also +see the `group_saml` option: + +```json +{ + "id": 1, + "username": "john_smith", + "shared_runners_minutes_limit": 133, + "extra_shared_runners_minutes_limit": 133 + "identities": [ + {"provider": "github", "extern_uid": "2435223452345"}, + {"provider": "bitbucket", "extern_uid": "john.smith"}, + {"provider": "google_oauth2", "extern_uid": "8776128412476123468721346"}, + {"provider": "group_saml", "extern_uid": "123789", "saml_provider_id": 10} + ], + ... } ``` @@ -287,32 +337,30 @@ POST /users Parameters: -- `email` (required) - Email -- `password` (optional) - Password -- `reset_password` (optional) - Send user password reset link - true or false (default) -- `force_random_password` (optional) - Set user password to a random value - true or false (default) -- `username` (required) - Username -- `name` (required) - Name -- `skype` (optional) - Skype ID -- `linkedin` (optional) - LinkedIn -- `twitter` (optional) - Twitter account -- `website_url` (optional) - Website URL -- `organization` (optional) - Organization name -- `projects_limit` (optional) - Number of projects user can create -- `extern_uid` (optional) - External UID -- `provider` (optional) - External provider name -- `group_id_for_saml` (optional) - ID of group where SAML has been configured -- `bio` (optional) - User's biography -- `location` (optional) - User's location -- `public_email` (optional) - The public email of the user -- `admin` (optional) - User is admin - true or false (default) -- `can_create_group` (optional) - User can create groups - true or false -- `skip_confirmation` (optional) - Skip confirmation - true or false (default) -- `external` (optional) - Flags the user as external - true or false(default) -- `avatar` (optional) - Image file for user's avatar -- `private_profile` (optional) - User's profile is private - true or false -- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user -- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user +- `email` (required) - Email +- `password` (optional) - Password +- `reset_password` (optional) - Send user password reset link - true or false(default) +- `username` (required) - Username +- `name` (required) - Name +- `skype` (optional) - Skype ID +- `linkedin` (optional) - LinkedIn +- `twitter` (optional) - Twitter account +- `website_url` (optional) - Website URL +- `organization` (optional) - Organization name +- `projects_limit` (optional) - Number of projects user can create +- `extern_uid` (optional) - External UID +- `provider` (optional) - External provider name +- `bio` (optional) - User's biography +- `location` (optional) - User's location +- `public_email` (optional) - The public email of the user +- `admin` (optional) - User is admin - true or false (default) +- `can_create_group` (optional) - User can create groups - true or false +- `skip_confirmation` (optional) - Skip confirmation - true or false (default) +- `external` (optional) - Flags the user as external - true or false(default) +- `avatar` (optional) - Image file for user's avatar +- `private_profile` (optional) - User's profile is private - true or false +- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user **[STARTER]** +- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]** ## User modification @@ -348,6 +396,8 @@ Parameters: - `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user - `avatar` (optional) - Image file for user's avatar - `private_profile` (optional) - User's profile is private - true or false +- `shared_runners_minutes_limit` (optional) - Pipeline minutes quota for this user **[STARTER]** +- `extra_shared_runners_minutes_limit` (optional) - Extra pipeline minutes quota for this user **[STARTER]** On password update, user will be forced to change it upon next login. Note, at the moment this method does only return a `404` error, @@ -370,9 +420,7 @@ Parameters: [moved to the ghost user](../user/profile/account/delete_account.md#associated-records) will be deleted instead, as well as groups owned solely by this user. -## User - -### For normal users +## List current user (for normal users) Gets currently authenticated user. @@ -418,7 +466,7 @@ GET /user } ``` -### For admins +## List current user (for admins) Parameters: @@ -497,9 +545,9 @@ Get the status of a user. GET /users/:id_or_username/status ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id_or_username` | string | yes | The id or username of the user to get a status of | +| Attribute | Type | Required | Description | +| ---------------- | ------ | -------- | ----------- | +| `id_or_username` | string | yes | The id or username of the user to get a status of | ```bash curl "https://gitlab.example.com/users/janedoe/status" @@ -523,8 +571,8 @@ Set the status of the current user. PUT /user/status ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ----------- | | `emoji` | string | no | The name of the emoji to use as status, if omitted `speech_balloon` is used. Emoji name can be one of the specified names in the [Gemojione index][gemojione-index]. | | `message` | string | no | The message to set as a status. It can also contain emoji codes. | @@ -546,7 +594,7 @@ Example responses ## List user projects -Please refer to the [List of user projects ](projects.md#list-user-projects). +Please refer to the [List of user projects](projects.md#list-user-projects). ## List SSH keys @@ -722,9 +770,9 @@ GET /user/gpg_keys/:key_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `key_id` | integer | yes | The ID of the GPG key | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------- | +| `key_id` | integer | yes | The ID of the GPG key | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1 @@ -750,9 +798,9 @@ POST /user/gpg_keys Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| key | string | yes | The new GPG key | +| Attribute | Type | Required | Description | +| --------- | ------ | -------- | ----------- | +| key | string | yes | The new GPG key | ```bash curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys @@ -780,9 +828,9 @@ DELETE /user/gpg_keys/:key_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `key_id` | integer | yes | The ID of the GPG key | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------- | +| `key_id` | integer | yes | The ID of the GPG key | ```bash curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/user/gpg_keys/1 @@ -800,9 +848,9 @@ GET /users/:id/gpg_keys Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the user | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys @@ -830,10 +878,10 @@ GET /users/:id/gpg_keys/:key_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the user | -| `key_id` | integer | yes | The ID of the GPG key | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `key_id` | integer | yes | The ID of the GPG key | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 @@ -859,10 +907,10 @@ POST /users/:id/gpg_keys Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the user | -| `key_id` | integer | yes | The ID of the GPG key | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `key_id` | integer | yes | The ID of the GPG key | ```bash curl --data "key=-----BEGIN PGP PUBLIC KEY BLOCK-----\r\n\r\nxsBNBFV..." --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys @@ -890,10 +938,10 @@ DELETE /users/:id/gpg_keys/:key_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the user | -| `key_id` | integer | yes | The ID of the GPG key | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ----------- | +| `id` | integer | yes | The ID of the user | +| `key_id` | integer | yes | The ID of the GPG key | ```bash curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/2/gpg_keys/1 @@ -1074,10 +1122,10 @@ GET /users/:user_id/impersonation_tokens Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the user | -| `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) | +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | ---------------------------------------------------------- | +| `user_id` | integer | yes | The ID of the user | +| `state` | string | no | filter tokens based on state (`all`, `active`, `inactive`) | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens @@ -1126,10 +1174,10 @@ GET /users/:user_id/impersonation_tokens/:impersonation_token_id Parameters: -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the user | -| `impersonation_token_id` | integer | yes | The ID of the impersonation token | +| Attribute | Type | Required | Description | +| ------------------------ | ------- | -------- | --------------------------------- | +| `user_id` | integer | yes | The ID of the user | +| `impersonation_token_id` | integer | yes | The ID of the impersonation token | ``` curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/users/42/impersonation_tokens/2 @@ -1155,7 +1203,6 @@ Example response: ## Create an impersonation token > Requires admin permissions. - > Token values are returned once. Make sure you save it - you won't be able to access it again. It creates a new impersonation token. Note that only administrators can do this. @@ -1167,12 +1214,12 @@ settings page. POST /users/:user_id/impersonation_tokens ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `user_id` | integer | yes | The ID of the user | -| `name` | string | yes | The name of the impersonation token | -| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)| -| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) | +| Attribute | Type | Required | Description | +| ------------ | ------- | -------- | ----------- | +| `user_id` | integer | yes | The ID of the user | +| `name` | string | yes | The name of the impersonation token | +| `expires_at` | date | no | The expiration date of the impersonation token in ISO format (`YYYY-MM-DD`)| +| `scopes` | array | yes | The array of scopes of the impersonation token (`api`, `read_user`) | ``` curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --data "name=mytoken" --data "expires_at=2017-04-04" --data "scopes[]=api" https://gitlab.example.com/api/v4/users/42/impersonation_tokens @@ -1219,15 +1266,15 @@ Parameters: ### Get user activities (admin only) ->**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above. +NOTE: **Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above. Get the last activity date for all users, sorted from oldest to newest. The activities that update the timestamp are: - - Git HTTP/SSH activities (such as clone, push) - - User logging in into GitLab - - User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8) +- Git HTTP/SSH activities (such as clone, push) +- User logging in into GitLab +- User visiting pages related to Dashboards, Projects, Issues and Merge Requests ([introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/54947) in GitLab 11.8) By default, it shows the activity for all users in the last 6 months, but this can be amended by using the `from` parameter. @@ -1270,4 +1317,4 @@ Example response: Please note that `last_activity_at` is deprecated, please use `last_activity_on`. -[gemojione-index]: https://github.com/jonathanwiesel/gemojione/blob/master/config/index.json
\ No newline at end of file +[gemojione-index]: https://github.com/jonathanwiesel/gemojione/blob/master/config/index.json diff --git a/doc/ci/README.md b/doc/ci/README.md index da864a0b3cc..d851a56ee0e 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -81,6 +81,7 @@ GitLab CI/CD supports numerous configuration options: | [Git submodules for CI/CD](git_submodules.md) | Configure jobs for using Git submodules.| | [SSH keys for CI/CD](ssh_keys/README.md) | Using SSH keys in your CI pipelines. | | [Pipelines triggers](triggers/README.md) | Trigger pipelines through the API. | +| [Pipelines for Merge Requests](merge_request_pipelines/index.md) | Design a pipeline structure for running a pipeline in merge requests. | | [Integrate with Kubernetes clusters](../user/project/clusters/index.md) | Connect your project to Google Kubernetes Engine (GKE) or an existing Kubernetes cluster. | | [GitLab Runner](https://docs.gitlab.com/runner/) | Configure your own GitLab Runners to execute your scripts. | | [Optimize GitLab and Runner for large repositories](large_repositories/index.md) | Recommended strategies for handling large repos. | diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index c3dbcf6a19f..e70ae0bd154 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -1,8 +1,9 @@ --- -type: reference +type: reference, index +last_update: 2019-07-03 --- -# Pipelines for merge requests +# Pipelines for Merge Requests > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/15310) in GitLab 11.6. @@ -75,135 +76,13 @@ when a merge request was created or updated. For example:  -## Pipelines for merged results **[PREMIUM]** +## Pipelines for Merged Results **[PREMIUM]** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. -> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222), but [can be enabled manually](#enabling-pipelines-for-merged-results). +Read the [documentation on Pipelines for Merged Results](pipelines_for_merged_results/index.md). -It's possible for your source and target branches to diverge, which can result -in the scenario that source branch's pipeline was green, the target's pipeline was green, -but the combined output fails. +### Merge Trains **[PREMIUM]** -By having your merge request pipeline automatically -create a new ref that contains the merge result of the source and target branch -(then running a pipeline on that ref), we can better test that the combined result -is also valid. - -GitLab can run pipelines for merge requests -on this merged result. That is, where the source and target branches are combined into a -new ref and a pipeline for this ref validates the result prior to merging. - - - -There are some cases where creating a combined ref is not possible or not wanted. -For example, a source branch that has conflicts with the target branch -or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a "detached" state -and runs on the source branch ref as if it was a regular pipeline. - -The detached state serves to warn you that you are working in a situation -subjected to merge problems, and helps to highlight that you should -get out of WIP status or resolve merge conflicts as soon as possible. - -### Requirements and limitations - -Pipelines for merged results require: - -- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. -- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. - -In addition, pipelines for merged results have the following limitations: - -- Forking/cross-repo workflows are not currently supported. To follow progress, - see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713). -- This feature is not available for - [fast forward merges](../../user/project/merge_requests/fast_forward_merge.md) yet. - To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226). - -### Enabling Pipelines for merged results - -To enable pipelines on merged results at the project level: - -1. Visit your project's **Settings > General** and expand **Merge requests**. -1. Check **Merge pipelines will try to validate the post-merge result prior to merging**. -1. Click **Save changes** button. - - - -CAUTION: **Warning:** -Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](#configuring-pipelines-for-merge-requests), -otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state. - -## Merge Trains **[PREMIUM]** - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0. -> This feature is disabled by default, but [can be enabled manually](#enabling-merge-trains). - -[Pipelines for merged results](#pipelines-for-merged-results-premium) introduces -running a build on the result of the merged code prior to merging, as a way to keep master green. - -There's a scenario, however, for teams with a high number of changes in the target branch (typically master) where in many or even all cases, -by the time the merged code is validated another commit has made it to master, invalidating the merged result. -You'd need some kind of queuing, cancellation or retry mechanism for these scenarios -in order to ensure an orderly flow of changes into the target branch. - -Each MR that joins a merge train joins as the last item in the train, -just as it works in the current state. However, instead of queuing and waiting, -each item takes the completed state of the previous (pending) merge ref, adds its own changes, -and starts the pipeline immediately in parallel under the assumption that everything is going to pass. - -In this way, if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying. -If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch, -it creates a new pipeline targeting the merge result of the previous MR plus the target branch. -Pipelines invalidated through failures are immediately canceled and requeued. - -### Requirements and limitations - -Merge trains have the following requirements and limitations: - -- This feature requires that - [pipelines for merged results](#pipelines-for-merged-results-premium) are - **configured properly**. -- Each merge train can generate a merge ref and run a pipeline **one at a time**. - We plan to make the pipelines for merged results - [run in parallel](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) in a - future release. - -### Enabling Merge Trains - -To enable merge trains at the project level: - -1. Visit your project's **Settings > General** and expand **Merge requests**. -1. Check **Allow merge trains**. -1. Click **Save changes** button. - - - -### How to add a merge request to a merge train - -To add a merge request to a merge train: - -1. Click "Start/Add merge train" button in a merge request - - - -### How to remove a merge request from a merge train - -1. Click "Remove from merge train" button in the merge request widget. - - - -### Tips: Start/Add to merge train when pipeline succeeds - -You can add a merge request to a merge train only when the latest pipeline in the -merge request finished. While the pipeline is running or pending, you cannot add -the merge request to a train because the current change of the merge request may -be broken thus it could affect the following merge requests. - -In this case, you can schedule to add the merge request to a merge train **when the latest -pipeline succeeds**. You can see the following button instead of the regular "Start/Add merge train" -button while the latest pipeline is running. - - +Read the [documentation on Merge Trains](pipelines_for_merged_results/merge_trains/index.md). ## Excluding certain jobs @@ -289,3 +168,15 @@ to integrate your job with [GitLab Merge Request API](../../api/merge_requests.m You can find the list of available variables in [the reference sheet](../variables/predefined_variables.md). The variable names begin with the `CI_MERGE_REQUEST_` prefix. + +<!-- ## 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/merge_request_pipelines/img/merge_request_pipeline.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png Binary files differindex 58d5581f628..58d5581f628 100644 --- a/doc/ci/merge_request_pipelines/img/merge_request_pipeline.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline.png diff --git a/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png Binary files differindex 0a84e61d284..0a84e61d284 100644 --- a/doc/ci/merge_request_pipelines/img/merge_request_pipeline_config.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merge_request_pipeline_config.png diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md new file mode 100644 index 00000000000..3c5088089fa --- /dev/null +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/index.md @@ -0,0 +1,78 @@ +--- +type: reference +last_update: 2019-07-03 +--- + +# Pipelines for Merged Results **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/7380) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10. +> This feature is disabled by default until we resolve issues with [contention handling](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222), but [can be enabled manually](#enabling-pipelines-for-merged-results). + +It's possible for your source and target branches to diverge, which can result +in the scenario that source branch's pipeline was green, the target's pipeline was green, +but the combined output fails. + +By having your merge request pipeline automatically +create a new ref that contains the merge result of the source and target branch +(then running a pipeline on that ref), we can better test that the combined result +is also valid. + +GitLab can run pipelines for merge requests +on this merged result. That is, where the source and target branches are combined into a +new ref and a pipeline for this ref validates the result prior to merging. + + + +There are some cases where creating a combined ref is not possible or not wanted. +For example, a source branch that has conflicts with the target branch +or a merge request that is still in WIP status. In this case, the merge request pipeline falls back to a "detached" state +and runs on the source branch ref as if it was a regular pipeline. + +The detached state serves to warn you that you are working in a situation +subjected to merge problems, and helps to highlight that you should +get out of WIP status or resolve merge conflicts as soon as possible. + +## Requirements and limitations + +Pipelines for merged results require: + +- [GitLab Runner](https://gitlab.com/gitlab-org/gitlab-runner) 11.9 or newer. +- [Gitaly](https://gitlab.com/gitlab-org/gitaly) 1.21.0 or newer. + +In addition, pipelines for merged results have the following limitations: + +- Forking/cross-repo workflows are not currently supported. To follow progress, + see [#9713](https://gitlab.com/gitlab-org/gitlab-ee/issues/9713). +- This feature is not available for + [fast forward merges](../../../user/project/merge_requests/fast_forward_merge.md) yet. + To follow progress, see [#58226](https://gitlab.com/gitlab-org/gitlab-ce/issues/58226). + +## Enabling Pipelines for Merged Results + +To enable pipelines on merged results at the project level: + +1. Visit your project's **Settings > General** and expand **Merge requests**. +1. Check **Merge pipelines will try to validate the post-merge result prior to merging**. +1. Click **Save changes** button. + + + +CAUTION: **Warning:** +Make sure your `gitlab-ci.yml` file is [configured properly for pipelines for merge requests](../index.md#configuring-pipelines-for-merge-requests), +otherwise pipelines for merged results won't run and your merge requests will be stuck in an unresolved state. + +## Merge Trains **[PREMIUM]** + +Read the [documentation on Merge Trains](merge_trains/index.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/merge_request_pipelines/img/merge_train_cancel.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png Binary files differindex 1561fdcc7a5..1561fdcc7a5 100644 --- a/doc/ci/merge_request_pipelines/img/merge_train_cancel.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_cancel_v12_0.png diff --git a/doc/ci/merge_request_pipelines/img/merge_train_config.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png Binary files differindex fb0af43556e..fb0af43556e 100644 --- a/doc/ci/merge_request_pipelines/img/merge_train_config.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_config_v12_0.png diff --git a/doc/ci/merge_request_pipelines/img/merge_train_start.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png Binary files differindex f20108157d2..f20108157d2 100644 --- a/doc/ci/merge_request_pipelines/img/merge_train_start.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_v12_0.png diff --git a/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png Binary files differindex 62c2f2f5ff5..62c2f2f5ff5 100644 --- a/doc/ci/merge_request_pipelines/img/merge_train_start_when_pipeline_succeeds.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/img/merge_train_start_when_pipeline_succeeds_v12_0.png diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md new file mode 100644 index 00000000000..c5ff6f9ebed --- /dev/null +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/merge_trains/index.md @@ -0,0 +1,88 @@ +--- +type: reference +last_update: 2019-07-03 +--- + +# Merge Trains **[PREMIUM]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9186) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.0. +> This feature is disabled by default, but [can be enabled manually](#enabling-merge-trains). + +[Pipelines for merged results](../index.md#pipelines-for-merged-results-premium) introduces +running a build on the result of the merged code prior to merging, as a way to keep master green. + +There's a scenario, however, for teams with a high number of changes in the target branch (typically master) where in many or even all cases, +by the time the merged code is validated another commit has made it to master, invalidating the merged result. +You'd need some kind of queuing, cancellation or retry mechanism for these scenarios +in order to ensure an orderly flow of changes into the target branch. + +Each MR that joins a merge train joins as the last item in the train, +just as it works in the current state. However, instead of queuing and waiting, +each item takes the completed state of the previous (pending) merge ref, adds its own changes, +and starts the pipeline immediately in parallel under the assumption that everything is going to pass. + +In this way, if all the pipelines in the train merge successfully, no pipeline time is wasted either queuing or retrying. +If the button is subsequently pressed in a different MR, instead of creating a new pipeline for the target branch, +it creates a new pipeline targeting the merge result of the previous MR plus the target branch. +Pipelines invalidated through failures are immediately canceled and requeued. + +## Requirements and limitations + +Merge trains have the following requirements and limitations: + +- This feature requires that + [pipelines for merged results](../index.md#pipelines-for-merged-results-premium) are + **configured properly**. +- Each merge train can generate a merge ref and run a pipeline **one at a time**. + We plan to make the pipelines for merged results + [run in parallel](https://gitlab.com/gitlab-org/gitlab-ee/issues/11222) in a + future release. + +## Enabling Merge Trains + +To enable merge trains at the project level: + +1. Visit your project's **Settings > General** and expand **Merge requests**. +1. Check **Allow merge trains**. +1. Click **Save changes** button. + + + +## How to add a merge request to a merge train + +To add a merge request to a merge train: + +1. Click "Start/Add merge train" button in a merge request + + + +## How to remove a merge request from a merge train + +1. Click "Remove from merge train" button in the merge request widget. + + + +## Start/Add to merge train when pipeline succeeds + +You can add a merge request to a merge train only when the latest pipeline in the +merge request finished. While the pipeline is running or pending, you cannot add +the merge request to a train because the current change of the merge request may +be broken thus it could affect the following merge requests. + +In this case, you can schedule to add the merge request to a merge train **when the latest +pipeline succeeds**. You can see the following button instead of the regular "Start/Add merge train" +button while the latest pipeline is running. + + + +<!-- ## 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/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index 7dbb9af2869..e911e97d3c8 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -78,7 +78,7 @@ future GitLab releases.** | `CI_PIPELINE_ID` | 8.10 | all | The unique id of the current pipeline that GitLab CI uses internally | | `CI_PIPELINE_IID` | 11.0 | all | The unique id of the current pipeline scoped to project | | `CI_PIPELINE_SOURCE` | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, and `pipeline`. For pipelines created before GitLab 9.5, this will show as `unknown` | -| `CI_PIPELINE_TRIGGERED` | all | all | The flag to indicate that job was [triggered] | +| `CI_PIPELINE_TRIGGERED` | all | all | The flag to indicate that job was [triggered](../triggers/README.md) | | `CI_PIPELINE_URL` | 11.1 | 0.5 | Pipeline details URL | | `CI_PROJECT_DIR` | all | all | The full path where the repository is cloned and where the job is run. If the GitLab Runner `builds_dir` parameter is set, this variable is set relative to the value of `builds_dir`. For more information, see [Advanced configuration](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-runners-section) for GitLab Runner. | | `CI_PROJECT_ID` | all | all | The unique id of the current project that GitLab CI uses internally | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 2759f1c5160..3e564e4244c 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -973,6 +973,8 @@ review_app: stop_review_app: stage: deploy + variables: + GIT_STRATEGY: none script: make delete-app when: manual environment: @@ -987,6 +989,10 @@ Once the `review_app` job is successfully finished, it will trigger the set it up to `manual` so it will need a [manual action](#whenmanual) via GitLab's web interface in order to run. +Also in the example, `GIT_STRATEGY` is set to `none` so that GitLab Runner won’t +try to check out the code after the branch is deleted when the `stop_review_app` +job is [automatically triggered](../environments.md#automatically-stopping-an-environment). + The `stop_review_app` job is **required** to have the following keywords defined: - `when` - [reference](#when) diff --git a/doc/customization/issue_closing.md b/doc/customization/issue_closing.md index 680c51e7524..9333f55ca9c 100644 --- a/doc/customization/issue_closing.md +++ b/doc/customization/issue_closing.md @@ -1,3 +1,5 @@ --- -redirect_to: '../user/project/issues/automatic_issue_closing.md' +redirect_to: '../user/project/issues/managing_issues.md#closing-issues-automatically' --- + +This document was moved to [another location](../user/project/issues/managing_issues.md#closing-issues-automatically). diff --git a/doc/customization/system_header_and_footer_messages.md b/doc/customization/system_header_and_footer_messages.md index 9d6931c730d..7eee79abc77 100644 --- a/doc/customization/system_header_and_footer_messages.md +++ b/doc/customization/system_header_and_footer_messages.md @@ -1,6 +1,7 @@ # Adding a system message to every page -> [Introduced][ee-1283] in [GitLab Premium][eep] 10.7. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5023) in [GitLab Premium](https://about.gitlab.com/pricing/) 10.7. +> [Added](https://gitlab.com/gitlab-org/gitlab-ce/issues/55057) to [GitLab Core](https://about.gitlab.com/pricing/) in 11.9. Navigate to the **Admin** area and go to the **Appearance** page. diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index d9595bd7bba..f4fa0caeb01 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -6,10 +6,13 @@ scheduling into milestones. Labelling is a task for everyone. Most issues will have labels for at least one of the following: -- Type: ~feature, ~bug, ~customer, etc. -- Subject: ~wiki, ~"Container Registry", ~ldap, ~api, ~frontend, etc. -- Team: ~Plan, ~Manage, ~Quality, etc. -- Stage: ~"devops:plan", ~"devops:create", etc. +- Type: ~feature, ~bug, ~backstage, etc. +- Subject: ~wiki, ~"Container Registry", ~ldap, ~api, etc. +- Team: ~Documentation, ~Delivery, etc. +- Stage: ~"devops::plan", ~"devops::create", etc. +- Group: ~"group::source code" ~"group::knowledge" ~"group::editor", etc. +- Department: ~UX, ~Quality +- Specialization: ~frontend, ~backend - Release Scoping: ~Deliverable, ~Stretch, ~"Next Patch Release" - Priority: ~P1, ~P2, ~P3, ~P4 - Severity: ~S1, ~S2, ~S3, ~S4 @@ -27,8 +30,7 @@ labels, you can _always_ add the team and type, and often also the subject. Type labels are very important. They define what kind of issue this is. Every issue should have one or more. -Examples of type labels are ~feature, ~bug, ~customer, ~security, -and ~direction. +Examples of type labels are ~feature, ~bug, ~backstage and ~security A number of type labels have a priority assigned to them, which automatically makes them float to the top, depending on their importance. @@ -56,19 +58,20 @@ issue is labeled with a subject label corresponding to your expertise. Subject labels are always all-lowercase. -## Team labels +## Team labels + +**Important**: Most of the team labels will be soon deprecated in favor of [Group labels](#group-labels). Team labels specify what team is responsible for this issue. Assigning a team label makes sure issues get the attention of the appropriate people. -The current team labels are: +The team labels planned for deprecation are: - ~Configure - ~Create - ~Defend - ~Distribution -- ~Documentation - ~Ecosystem - ~Geo - ~Gitaly @@ -77,12 +80,15 @@ The current team labels are: - ~Memory - ~Monitor - ~Plan -- ~Quality - ~Release - ~Secure -- ~UX - ~Verify +The following team labels are **true** teams per our [organization structure](https://about.gitlab.com/company/team/structure/#organizational-structure) which will remain post deprecation. + +- ~Delivery +- ~Documentation + The descriptions on the [labels page][labels-page] explain what falls under the responsibility of each team. @@ -92,6 +98,7 @@ indicate if an issue needs backend work, frontend work, or both. Team labels are always capitalized so that they show up as the first label for any issue. + ## Stage labels Stage labels specify which [DevOps stage][devops-stages] the issue belongs to. @@ -132,10 +139,44 @@ The Stage labels are used to generate the [direction pages][direction-pages] aut Group labels specify which [groups][structure-groups] the issue belongs to. -Examples include: - -- ~"group::control" -- ~"group::editor" +The current group labels are: + +* ~"group::access" +* ~"group::measure" +* ~"group::source code" +* ~"group::knowledge" +* ~"group::editor" +* ~"group::gitaly" +* ~"group::gitter" +* ~"group::team planning" +* ~"group::enterprise planning" +* ~"group::certify" +* ~"group::ci and runner" +* ~"group::testing" +* ~"group::package" +* ~"group::progressive delivery" +* ~"group::release management" +* ~"group::autodevops and kubernetes" +* ~"group::serverless and paas" +* ~"group::apm" +* ~"group::health" +* ~"group::static analysis" +* ~"group::dynamic analysis" +* ~"group::software composition analysis" +* ~"group::runtime application security" +* ~"group::threat management" +* ~"group::application infrastructure security" +* ~"group::activation" +* ~"group::adoption" +* ~"group::upsell" +* ~"group::retention" +* ~"group::fulfillment" +* ~"group::telemetry" +* ~"group::distribution" +* ~"group::geo" +* ~"group::memory" +* ~"group::ecosystem" + These labels are [scoped labels](../../user/project/labels.md#scoped-labels-premium) and thus are mutually exclusive. @@ -147,6 +188,20 @@ can be applied to a single issue. You can find the groups listed in the [structure-groups]: https://about.gitlab.com/company/team/structure/#groups [product-categories]: https://about.gitlab.com/handbook/product/categories/ +## Department labels + +The current department labels are: + +* ~UX +* ~Quality + +## Specialization labels + +These labels narrow the [specialization](https://about.gitlab.com/company/team/structure/#specialist) on a unit of work. + +* ~frontend +* ~backend + ## Release Scoping labels Release Scoping labels help us clearly communicate expectations of the work for the diff --git a/doc/development/contributing/merge_request_workflow.md b/doc/development/contributing/merge_request_workflow.md index 6064f59ed10..ce5d9786e6e 100644 --- a/doc/development/contributing/merge_request_workflow.md +++ b/doc/development/contributing/merge_request_workflow.md @@ -65,7 +65,7 @@ request is as follows: 1. If you are contributing documentation, choose `Documentation` from the "Choose a template" menu and fill in the description according to the template. 1. Mention the issue(s) your merge request solves, using the `Solves #XXX` or - `Closes #XXX` syntax to [auto-close](../../user/project/issues/automatic_issue_closing.md) + `Closes #XXX` syntax to [auto-close](../../user/project/issues/managing_issues.md#closing-issues-automatically) the issue(s) once the merge request is merged. 1. If you're allowed to (Core team members, for example), set a relevant milestone and [labels](issue_workflow.md). diff --git a/doc/development/ee_features.md b/doc/development/ee_features.md index 34d41cf4958..6f4a36d4066 100644 --- a/doc/development/ee_features.md +++ b/doc/development/ee_features.md @@ -1036,7 +1036,14 @@ to avoid conflicts during CE to EE merge. ### Backporting changes from EE to CE -When working in EE-specific features, you might have to tweak a few files that are not EE-specific. Here is a workflow to make sure those changes end up backported safely into CE too. +Until the work completed to merge the ce and ee codebases, which is tracked on [epic &802](https://gitlab.com/groups/gitlab-org/-/epics/802), there exists times in which some changes for EE require specific changes to the CE +code base. Examples of backports include the following: + +* Features intended or originally built for EE that are later decided to move to CE +* Sometimes some code in CE may impact the EE feature + +Here is a workflow to make sure those changes end up backported safely into CE too. + (This approach does not refer to changes introduced via [csslab](https://gitlab.com/gitlab-org/csslab/).) 1. **Make your changes in the EE branch.** If possible, keep a separated commit (to be squashed) to help backporting and review. diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 4dad8815fcb..f961a2fc837 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -82,7 +82,7 @@ go lint: image: golang:1.11 script: - go get -u golang.org/x/lint/golint - - golint -set_exit_status + - golint -set_exit_status $(go list ./... | grep -v "vendor/") ``` Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-ce/issues/56836) diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md index 0c268eff9f1..fd16047b8e4 100644 --- a/doc/gitlab-basics/README.md +++ b/doc/gitlab-basics/README.md @@ -22,7 +22,7 @@ The following are guides to basic GitLab functionality: - [Fork a project](fork-project.md), to duplicate projects so they can be worked on in parallel. - [Add a file](add-file.md), to add new files to a project's repository. - [Add an image](add-image.md), to add new images to a project's repository. -- [Create an issue](../user/project/issues/create_new_issue.md), to start collaborating within a project. +- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue), to start collaborating within a project. - [Create a merge request](add-merge-request.md), to request changes made in a branch be merged into a project's repository. - See how these features come together in the [GitLab Flow introduction video](https://youtu.be/InKNIvky2KE) and [GitLab Flow page](../workflow/gitlab_flow.md). diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md index 6e2a09fc030..5fa5f1bf2e2 100644 --- a/doc/gitlab-basics/create-issue.md +++ b/doc/gitlab-basics/create-issue.md @@ -1,5 +1,5 @@ --- -redirect_to: '../user/project/issues/index.md#issue-actions' +redirect_to: '../user/project/issues/index.md#viewing-and-managing-issues' --- -This document was moved to [another location](../user/project/issues/index.md#issue-actions). +This document was moved to [another location](../user/project/issues/index.md#viewing-and-managing-issues). diff --git a/doc/install/installation.md b/doc/install/installation.md index 4c1021d097f..70e5ab28931 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -560,7 +560,7 @@ NOTE: **Note:** If you want to use HTTPS, see [Using HTTPS](#using-https) for the additional steps. NOTE: **Note:** -Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with "Check GitLab API access: FAILED. code: 401" and pushing commits will be rejected with "[remote rejected] master -> master (hook declined)". +Make sure your hostname can be resolved on the machine itself by either a proper DNS record or an additional line in `/etc/hosts` ("127.0.0.1 hostname"). This might be necessary, for example, if you set up GitLab behind a reverse proxy. If the hostname cannot be resolved, the final installation check will fail with `Check GitLab API access: FAILED. code: 401` and pushing commits will be rejected with `[remote rejected] master -> master (hook declined)`. NOTE: **Note:** GitLab Shell application startup time can be greatly reduced by disabling RubyGems. This can be done in several ways: diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index f64fdb1e28b..877330b8c44 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -167,7 +167,7 @@ To disable the Elasticsearch integration: 1. Find the 'Elasticsearch' section and uncheck 'Search with Elasticsearch enabled' and 'Elasticsearch indexing' 1. Click **Save** for the changes to take effect -1. [Optional] Delete the existing index by running the command `sudo gitlab-rake gitlab:elastic:delete_index` +1. (Optional) Delete the existing index by running the command `sudo gitlab-rake gitlab:elastic:delete_index` ## Adding GitLab's data to the Elasticsearch index diff --git a/doc/intro/README.md b/doc/intro/README.md index d9c733d4285..9a8cd925e48 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -15,7 +15,7 @@ Create projects and groups. Create issues, labels, milestones, cast your vote, and review issues. -- [Create an issue](../user/project/issues/create_new_issue.md) +- [Create an issue](../user/project/issues/managing_issues.md#create-a-new-issue) - [Assign labels to issues](../user/project/labels.md) - [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md) - [Use voting to express your like/dislike to issues and merge requests](../workflow/award_emoji.md) @@ -26,7 +26,7 @@ Create merge requests and review code. - [Fork a project and contribute to it](../workflow/forking_workflow.md) - [Create a new merge request](../gitlab-basics/add-merge-request.md) -- [Automatically close issues from merge requests](../user/project/issues/automatic_issue_closing.md) +- [Automatically close issues from merge requests](../user/project/issues/managing_issues.md#closing-issues-automatically) - [Automatically merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) - [Revert any commit](../user/project/merge_requests/revert_changes.md) - [Cherry-pick any commit](../user/project/merge_requests/cherry_pick_changes.md) diff --git a/doc/public_access/public_access.md b/doc/public_access/public_access.md index b1637181855..d04428fdbfe 100644 --- a/doc/public_access/public_access.md +++ b/doc/public_access/public_access.md @@ -29,6 +29,12 @@ in users. Any logged in user will have [Guest permissions](../user/permissions.md) on the repository. +NOTE: **Note:** +From July 2019, the `Internal` visibility setting is disabled for new projects, groups, +and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` +visibility setting keep this setting. You can read more about the change in the +[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388). + ### Private projects Private projects can only be cloned and viewed by project members. diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 41d12128e51..bd788cb138c 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -175,8 +175,8 @@ When using Auto DevOps, you may want to deploy different environments to different Kubernetes clusters. This is possible due to the 1:1 connection that [exists between them](../../user/project/clusters/index.md#multiple-kubernetes-clusters-premium). -In the [Auto DevOps template](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/lib/gitlab/ci/templates/Auto-DevOps.gitlab-ci.yml) -(used behind the scenes by Auto DevOps), there are currently 3 defined environment names that you need to know: +In the [Auto DevOps template] (used behind the scenes by Auto DevOps), there +are currently 3 defined environment names that you need to know: - `review/` (every environment starting with `review/`) - `staging` @@ -662,25 +662,32 @@ to the desired environment. See [Limiting environment scopes of variables](../.. ### Customizing `.gitlab-ci.yml` -If you want to modify the CI/CD pipeline used by Auto DevOps, you can copy the -[Auto DevOps template] into your project's repo and edit as you see fit. - -Assuming that your project is new or it doesn't have a `.gitlab-ci.yml` file -present: - -1. From your project home page, either click on the "Set up CI/CD" button, or click - on the plus button and (`+`), then "New file" -1. Pick `.gitlab-ci.yml` as the template type -1. Select "Auto-DevOps" from the template dropdown -1. Edit the template or add any jobs needed -1. Give an appropriate commit message and hit "Commit changes" - -TIP: **Tip:** The Auto DevOps template includes useful comments to help you -customize it. For example, if you want deployments to go to a staging environment -instead of directly to a production one, you can enable the `staging` job by -renaming `.staging` to `staging`. Then make sure to uncomment the `when` key of -the `production` job to turn it into a manual action instead of deploying -automatically. +Everything about Auto DevOps is customizable since the [Auto DevOps template] +is just an example of a [`.gitlab-ci.yml`](../../ci/yaml/README.md) and uses +only features that are available to any `.gitlab-ci.yml`. + +Auto DevOps is completely customizable because the [Auto DevOps template]: + +- Is just an implementation of a [`.gitlab-ci.yml`](../../ci/yaml/README.md) file. +- Uses only features available to any implementation of `.gitlab-ci.yml`. + +If you want to modify the CI/CD pipeline used by Auto DevOps, you can [`include` +the template](../../ci/yaml/README.md#includetemplate) and customize as +needed. To do this, add a `.gitlab-ci.yml` file to the root of your repository +containing the following: + +```yml +include: + - template: Auto-DevOps.gitlab-ci.yml +``` + +Then add any extra changes you want. Your additions will be merged with the +[Auto DevOps template] using the behaviour described for +[`include`](../../ci/yaml/README.md#include). + +It is also possible to copy and paste the contents of the [Auto DevOps +template] into your project and edit this as needed. You may prefer to do it +that way if you want to specifically remove any part of it. ### Using components of Auto-DevOps diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 469a7c09250..2246ea8ed5a 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -111,7 +111,7 @@ file. [Ingress](https://kubernetes.github.io/ingress-nginx/) can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto -DevOps] or deploy your own web apps. +DevOps](../../topics/autodevops/index.md) or deploy your own web apps. NOTE: **Note:** The diff --git a/doc/user/gitlab_com/index.md b/doc/user/gitlab_com/index.md index 2fb6cec55fa..886fb6e6f55 100644 --- a/doc/user/gitlab_com/index.md +++ b/doc/user/gitlab_com/index.md @@ -352,3 +352,13 @@ High Performance TCP/HTTP Load Balancer: [unicorn-worker-killer]: https://rubygems.org/gems/unicorn-worker-killer "unicorn-worker-killer" [4010]: https://gitlab.com/gitlab-com/infrastructure/issues/4010 "Find a good value for maximum timeout for Shared Runners" [4070]: https://gitlab.com/gitlab-com/infrastructure/issues/4070 "Configure per-runner timeout for shared-runners-manager-X on GitLab.com" + +## Other admin area settings + +This area highlights other noteworthy admin area settings on GitLab.com that differ from default settings. This list is not exhaustive. + +NOTE: **Note:** +From July 2019, the `Internal` visibility setting is disabled for new projects, groups, +and snippets on GitLab.com. Existing projects, groups, and snippets using the `Internal` +visibility setting keep this setting. You can read more about the change in the +[relevant issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/12388). diff --git a/doc/user/markdown.md b/doc/user/markdown.md index a08b41aaecb..eaae9964367 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -288,7 +288,7 @@ $example = array( > If this is not rendered correctly, [view it in GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/doc/user/markdown.md#inline-diff). -With inline diff tags you can display {+ additions +} or [- deletions -]. +With inline diff tags you can display `{+ additions +}` or `[- deletions -]`. The wrapping tags can be either curly braces or square brackets: diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 03abef9fc62..33fff0fed74 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -122,8 +122,8 @@ The following table depicts the various user permission levels in a project. | Transfer project to another namespace | | | | | ✓ | | Remove project | | | | | ✓ | | Delete issues | | | | | ✓ | -| Force push to protected branches [^4] | | | | | | -| Remove protected branches [^4] | | | | | | +| Force push to protected branches (*4*) | | | | | | +| Remove protected branches (*4*) | | | | | | - (*1*): All users are able to perform this action on public and internal projects, but not private projects. - (*2*): Guest users can only view the confidential issues they created themselves diff --git a/doc/user/project/canary_deployments.md b/doc/user/project/canary_deployments.md index cce862b0911..9bb282f1b78 100644 --- a/doc/user/project/canary_deployments.md +++ b/doc/user/project/canary_deployments.md @@ -44,7 +44,7 @@ Canary deployments require that you properly configure Deploy Boards: 1. Follow the steps to [enable Deploy Boards](deploy_boards.md#enabling-deploy-boards). 1. To track canary deployments you need to label your Kubernetes deployments and - pods with `track: canary`. To get started quickly, you can use the [Auto Deploy] + pods with `track: canary`. To get started quickly, you can use the [Auto Deploy](../../ci/autodeploy/index.md) template for canary deployments that GitLab provides. Depending on the deploy, the label should be either `stable` or `canary`. @@ -62,7 +62,6 @@ can easily notice them.  -[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy" [eep]: https://about.gitlab.com/pricing/ [ee-1659]: https://gitlab.com/gitlab-org/gitlab-ee/issues/1659 [kube-canary]: https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/#canary-deployments diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index c6ee168bad0..d21455fb5ca 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -222,7 +222,7 @@ functionalities needed to successfully build and deploy a containerized application. Bear in mind that the same credentials are used for all the applications running on the cluster. -## 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. diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index dc97a44fd68..5d36e1d4be3 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -156,6 +156,6 @@ Learn more about Cycle Analytics in the following resources: [environment]: ../../ci/yaml/README.md#environment [GitLab flow]: ../../workflow/gitlab_flow.md [idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab -[issue closing pattern]: issues/automatic_issue_closing.md +[issue closing pattern]: issues/managing_issues.md#closing-issues-automatically [permissions]: ../permissions.md [yml]: ../../ci/yaml/README.md diff --git a/doc/user/project/deploy_boards.md b/doc/user/project/deploy_boards.md index 175384bc985..0d51e8ae19a 100644 --- a/doc/user/project/deploy_boards.md +++ b/doc/user/project/deploy_boards.md @@ -125,6 +125,6 @@ version of your application. [kube-service]: integrations/kubernetes.md "Kubernetes project service" [review apps]: ../../ci/review_apps/index.md "Review Apps documentation" [variables]: ../../ci/variables/README.md "GitLab CI variables" -[autodeploy]: ../../ci/autodeploy/index.md "GitLab Autodeploy" +[autodeploy]: ../../topics/autodevops/index.md#auto-deploy "GitLab Autodeploy" [kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry" [runners]: ../../ci/runners/README.md diff --git a/doc/user/project/integrations/prometheus_library/haproxy.md b/doc/user/project/integrations/prometheus_library/haproxy.md index abb0c01ad18..6be8fc82431 100644 --- a/doc/user/project/integrations/prometheus_library/haproxy.md +++ b/doc/user/project/integrations/prometheus_library/haproxy.md @@ -11,8 +11,8 @@ The [Prometheus service](../prometheus.md) must be enabled. | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code) | -| HTTP Error Rate (%) | sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) | +| Throughput (req/sec) | `sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m])) by (code)` | +| HTTP Error Rate (%) | `sum(rate(haproxy_frontend_http_requests_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_requests_total{%{environment_filter}}[2m]))` | ## Configuring Prometheus to monitor for HAProxy metrics diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index c4fea178ab5..7db9629c002 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -14,9 +14,9 @@ NGINX server metrics are detected, which tracks the pages and content directly s | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code) | -| Latency (ms) | avg(nginx_server_requestMsec{%{environment_filter}}) | -| HTTP Error Rate (HTTP Errors / sec) | sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m])) | +| Throughput (req/sec) | `sum(rate(nginx_server_requests{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) by (code)` | +| Latency (ms) | `avg(nginx_server_requestMsec{%{environment_filter}})` | +| HTTP Error Rate (HTTP Errors / sec) | `sum(rate(nginx_server_requests{code="5xx", %{environment_filter}}[2m]))` | ## Configuring Prometheus to monitor for NGINX metrics diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md index de7fc93f0a4..fd743855a8c 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -14,9 +14,9 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code) | -| Latency (ms) | sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000 | -| HTTP Error Rate (%) | sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100 | +| Throughput (req/sec) | `sum(label_replace(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m]), "status_code", "${1}xx", "status", "(.)..")) by (status_code)` | +| Latency (ms) | `sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_sum{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_ingress_upstream_latency_seconds_count{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 1000` | +| HTTP Error Rate (%) | `sum(rate(nginx_ingress_controller_requests{status=~"5.*",namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) / sum(rate(nginx_ingress_controller_requests{namespace="%{kube_namespace}",ingress=~".*%{ci_environment_slug}.*"}[2m])) * 100` | ## Configuring NGINX ingress monitoring diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md index 31ac53c0d14..b03787b3e0d 100644 --- a/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress_vts.md @@ -14,9 +14,9 @@ GitLab has support for automatically detecting and monitoring the Kubernetes NGI | Name | Query | | ---- | ----- | -| Throughput (req/sec) | sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code) | -| Latency (ms) | avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}) | -| HTTP Error Rate (%) | sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100 | +| Throughput (req/sec) | `sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) by (status_code)` | +| Latency (ms) | `avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"})` | +| HTTP Error Rate (%) | `sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) / sum(rate(nginx_upstream_responses_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) * 100` | ## Configuring NGINX ingress monitoring diff --git a/doc/user/project/issues/automatic_issue_closing.md b/doc/user/project/issues/automatic_issue_closing.md index c3e06b219ff..dab79327d6a 100644 --- a/doc/user/project/issues/automatic_issue_closing.md +++ b/doc/user/project/issues/automatic_issue_closing.md @@ -1,63 +1,5 @@ -# Automatic issue closing - ->**Notes:** -> -> - This is the user docs. In order to change the default issue closing pattern, -> follow the steps in the [administration docs]. -> - For performance reasons, automatic issue closing is disabled for the very -> first push from an existing repository. - -When a commit or merge request resolves one or more issues, it is possible to -automatically have these issues closed when the commit or merge request lands -in the project's default branch. - -If a commit message or merge request description contains a sentence matching -a certain regular expression, all issues referenced from the matched text will -be closed. This happens when the commit is pushed to a project's -[**default** branch](../repository/branches/index.md#default-branch), or when a -commit or merge request is merged into it. - -## Default closing pattern value - -When not specified, the default issue closing pattern as shown below will be -used: - -```bash -((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) -``` - -Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's -source code that can match references to: - -- A local issue (`#123`). -- A cross-project issue (`group/project#123`). -- A link to an issue - (`https://gitlab.example.com/group/project/issues/123`). - --- - -This translates to the following keywords: - -- Close, Closes, Closed, Closing, close, closes, closed, closing -- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing -- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving -- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing - +redirect_to: 'managing_issues.md#closing-issues-automatically' --- -For example the following commit message: - -``` -Awesome commit message - -Fix #20, Fixes #21 and Closes group/otherproject#22. -This commit is also related to #17 and fixes #18, #19 -and https://gitlab.example.com/group/otherproject/issues/23. -``` - -will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed -to, as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as -it does not match the pattern. It works with multi-line commit messages as well -as one-liners when used with `git commit -m`. - -[administration docs]: ../../../administration/issue_closing_pattern.md +This document was moved to [another location](managing_issues.md#closing-issues-automatically). diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md index 1d88745af9f..04f1c8e1a4a 100644 --- a/doc/user/project/issues/closing_issues.md +++ b/doc/user/project/issues/closing_issues.md @@ -1,59 +1,5 @@ -# Closing Issues +--- +redirect_to: 'managing_issues.md#closing-issues' +--- -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -## Directly - -Whenever you decide that's no longer need for that issue, -close the issue using the close button: - - - -## Via Merge Request - -When a merge request resolves the discussion over an issue, you can -make it close that issue(s) when merged. - -All you need is to use a [keyword](automatic_issue_closing.md) -accompanying the issue number, add to the description of that MR. - -In this example, the keyword "closes" prefixing the issue number will create a relationship -in such a way that the merge request will close the issue when merged. - -Mentioning various issues in the same line also works for this purpose: - -```md -Closes #333, #444, #555 and #666 -``` - -If the issue is in a different repository rather then the MR's, -add the full URL for that issue(s): - -```md -Closes #333, #444, and https://gitlab.com/<username>/<projectname>/issues/<xxx> -``` - -All the following keywords will produce the same behaviour: - -- Close, Closes, Closed, Closing, close, closes, closed, closing -- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing -- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving - - - -If you use any other word before the issue number, the issue and the MR will -link to each other, but the MR will NOT close the issue(s) when merged. - - - -## From the Issue Board - -You can close an issue from [Issue Boards](../issue_board.md) by dragging an issue card -from its list and dropping into **Closed**. - - - -## Customizing the issue closing pattern - -Alternatively, a GitLab **administrator** can -[customize the issue closing pattern](../../../administration/issue_closing_pattern.md). +This document was moved to [another location](managing_issues.md#closing-issues). diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md index c2916c79876..8eec29716c1 100644 --- a/doc/user/project/issues/create_new_issue.md +++ b/doc/user/project/issues/create_new_issue.md @@ -1,104 +1,5 @@ -# Create a new Issue +--- +redirect_to: 'managing_issues.md#create-a-new-issue' +--- -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -When you create a new issue, you'll be prompted to fill in -the information illustrated on the image below. - - - -Read through the [issue data and actions documentation](issue_data_and_actions.md#parts-of-an-issue) -to understand these fields one by one. - -## New issue from the Issue Tracker - -Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue: - - - -## New issue from an opened issue - -From an **opened issue** in your project, click **New Issue** to create a new -issue in the same project: - - - -## New issue from the project's dashboard - -From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown -menu with a few options. Select **New Issue** to create an issue in that project: - - - -## New issue from the Issue Board - -From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list. -It opens a new issue for that project labeled after its respective list. - - - -## New issue via email - -At the bottom of a project's Issues List page, a link to **Email a new issue to this project** -is displayed if your GitLab instance has [incoming email](../../../administration/incoming_email.md) configured. - - - -When you click this link, an email address is displayed which belongs to you for creating issues in this project. -You can save this address as a contact in your email client for easy acceess. - -CAUTION: **Caution:** -This is a private email address, generated just for you. **Keep it to yourself**, -as anyone who gets ahold of it can create issues or merge requests as if they -were you. If the address is compromised, or you'd like it to be regenerated for -any reason, click **Email a new issue to this project** again and click the reset link. - -Sending an email to this address will create a new issue on your behalf for -this project, where: - -- The email subject becomes the issue title. -- The email body becomes the issue description. -- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. - -NOTE: **Note:** -In GitLab 11.7, we updated the format of the generated email address. -However the older format is still supported, allowing existing aliases -or contacts to continue working._ - -## New issue via Service Desk **[PREMIUM]** - -Enable [Service Desk](../service_desk.md) to your project and offer email support. -By doing so, when your customer sends a new email, a new issue can be created in -the appropriate project and followed up from there. - -## New issue from the group-level Issue Tracker - -Head to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker -for all projects in your Group. Select the project you'd like to add an issue for -using the dropdown button at the top-right of the page. - - - -We'll keep track of the project you selected most recently, and use it as the default -for your next visit. This should save you a lot of time and clicks, if you mostly -create issues for the same project. - - - -## New issue via URL with prefilled fields - -You can link directly to the new issue page for a given project, with prefilled -field values using query string parameters in a URL. This is useful for embedding -a URL in an external HTML page, and also certain scenarios where you want the user to -create an issue with certain fields prefilled. - -The title, description, and description template fields can be prefilled using -this method. The description and description template fields cannot be pre-entered -in the same URL (since a description template just populates the description field). - -Follow these examples to form your new issue URL with prefilled fields. - -- For a new issue in the GitLab Community Edition project with a pre-entered title - and a pre-entered description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` -- For a new issue in the GitLab Community Edition project with a pre-entered title - and a pre-entered description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` +This document was moved to [another location](managing_issues.md#create-a-new-issue). diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md index ff5b1f2ce50..93dc2a2e4ca 100644 --- a/doc/user/project/issues/crosslinking_issues.md +++ b/doc/user/project/issues/crosslinking_issues.md @@ -25,9 +25,8 @@ git commit -m "this is my commit message. Related to https://gitlab.com/<usernam Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. -**Note:** Linking your first commit to your issue is going to be relevant -for tracking your process far ahead with -[GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/)). +NOTE: **Note:** Linking your first commit to your issue is going to be relevant +for tracking your process with [GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/). It will measure the time taken for planning the implementation of that issue, which is the time between creating an issue and making the first commit. @@ -35,14 +34,13 @@ which is the time between creating an issue and making the first commit. Mentioning related issues in merge requests and other issues is useful for your team members and collaborators to know that there are opened -issues around that same idea. +issues regarding the same topic. -You do that as explained above, when -[mentioning an issue from a commit message](#from-commit-messages). +You do that as explained above, when [mentioning an issue from a commit message](#from-commit-messages). -When mentioning the issue "A" in issue "B", the issue "A" will also -display a notification in its tracker. The same is valid for mentioning -issues in merge requests. +When mentioning issue `#111` in issue `#222`, issue `#111` will also display a notification +in its tracker. That is, you only need to mention the relationship once for it to +display in both issues. The same is valid when mentioning issues in [merge requests](#from-merge-requests).  @@ -53,10 +51,7 @@ they do for [related issues](#from-related-issues). When you mention an issue in a merge request description, it will simply [link the issue and merge request together](#from-related-issues). Additionally, -you can also [set an issue to close as soon as the merge request is merged](closing_issues.md#via-merge-request). +you can also [set an issue to close automatically](managing_issues.md#closing-issues-automatically) +as soon as the merge request is merged.  - -### Close an issue by merging a merge request - -To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing pattern](automatic_issue_closing.md). diff --git a/doc/user/project/issues/csv_import.md b/doc/user/project/issues/csv_import.md index b0b1cfcfdf7..cc0d5ac9028 100644 --- a/doc/user/project/issues/csv_import.md +++ b/doc/user/project/issues/csv_import.md @@ -7,7 +7,8 @@ Issues can be imported to a project by uploading a CSV file with the columns The user uploading the CSV file will be set as the author of the imported issues. -> **Note:** A permission level of `Developer` or higher is required to import issues. +NOTE: **Note:** A permission level of [Developer](../../permissions.md), or higher, is required +to import issues. ## Prepare for the import @@ -24,42 +25,26 @@ To import issues: 1. Select the file and click the **Import issues** button. The file is processed in the background and a notification email is sent -to you once the import is completed. +to you once the import is complete. ## CSV file format -### Header row +When importing issues from a CSV file, it must be formatted in a certain way: -CSV files must contain a header row where the first column header is `title` and the second is `description`. -If additional columns are present, they will be ignored. +- **header row:** CSV files must contain a header row where the first column header + is `title` and the second is `description`. If additional columns are present, they + will be ignored. +- **separators:** The column separator is automatically detected from the header row. + Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). + The row separator can be either `CRLF` or `LF`. +- **double-quote character:** The double-quote (`"`) character is used to quote fields, + enabling the use of the column separator within a field (see the third line in the + sample CSV data below). To insert a double-quote (`"`) within a quoted + field, use two double-quote characters in succession, i.e. `""`. +- **data rows:** After the header row, succeeding rows must follow the same column + order. The issue title is required while the description is optional. -### Column separator - -The column separator is automatically detected from the header row. - -Supported separator characters are: commas (`,`), semicolons (`;`), and tabs (`\t`). - -### Row separator - -Lines ending in either `CRLF` or `LF` are supported. - -### Quote character - -The double-quote (`"`) character is used to quote fields so you can use the column separator within a field. To insert -a double-quote (`"`) within a quoted field, use two double-quote characters in succession, i.e. `""`. - -### Data rows - -After the header row, succeeding rows must follow the same column order. The issue title is required while the -description is optional. - -### File size - -The limit depends on the configuration value of Max Attachment Size for the GitLab instance. - -For GitLab.com, it is set to 10 MB. - -## Sample data +Sample CSV data: ```csv title,description @@ -67,3 +52,9 @@ My Issue Title,My Issue Description Another Title,"A description, with a comma" "One More Title","One More Description" ``` + +### File size + +The limit depends on the configuration value of Max Attachment Size for the GitLab instance. + +For GitLab.com, it is set to 10 MB. diff --git a/doc/user/project/issues/deleting_issues.md b/doc/user/project/issues/deleting_issues.md index 536a0de8974..e50259e0dcf 100644 --- a/doc/user/project/issues/deleting_issues.md +++ b/doc/user/project/issues/deleting_issues.md @@ -1,13 +1,5 @@ -# Deleting Issues +--- +redirect_to: 'managing_issues.md#deleting-issues' +--- -> [Introduced][ce-2982] in GitLab 8.6 - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -You can delete an issue by editing it and clicking on the delete button. - - - ->**Note:** Only [project owners](../../permissions.md) can delete issues. - -[ce-2982]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982
\ No newline at end of file +This document was moved to [another location](managing_issues.md#deleting-issues). diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index 987c16dfab6..bd3298497d2 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -4,30 +4,32 @@ Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. -Due dates can be used in issues to keep track of deadlines and make sure -features are shipped on time. Due dates require at least [Reporter permissions](../../permissions.md#project-members-permissions) -to be able to edit them. On the contrary, they can be seen by everybody. +Due dates can be used in issues to keep track of deadlines and make sure features are +shipped on time. Users must have at least [Reporter permissions](../../permissions.md) +to be able to edit them, but they can be seen by everybody with permission to view +the issue. ## Setting a due date -When creating or editing an issue, you can see the due date field from where -a calendar will appear to help you choose the date you want. To remove it, -select the date text and delete it. +When creating or editing an issue, you can click in the **due date** field and a calendar +will appear to help you choose the date you want. To remove the date, select the date +text and delete it. The date is related to the server's timezone, not the timezone of +the user setting the due date.  -A quicker way to set a due date is via the issue sidebar. Simply expand the -sidebar and select **Edit** to pick a due date or remove the existing one. +You can also set a due date via the issue sidebar. Expand the +sidebar and click **Edit** to pick a due date or remove the existing one. Changes are saved immediately.  ## Making use of due dates -Issues that have a due date can be distinctively seen in the issue tracker +Issues that have a due date can be easily seen in the issue tracker, displaying a date next to them. Issues where the date is overdue will have the icon and the date colored red. You can sort issues by those that are -_Due soon_ or _Due later_ from the dropdown menu in the right. +`Due soon` or `Due later` from the dropdown menu on the right.  @@ -36,14 +38,13 @@ Due dates also appear in your [todos list](../../../workflow/todos.md).  The day before an open issue is due, an email will be sent to all participants -of the issue. Both the due date and the day before are calculated using the +of the issue. Like the due date, the "day before the due date" is determined by the server's timezone. Issues with due dates can also be exported as an iCalendar feed. The URL of the feed can be added to calendar applications. The feed is accessible by clicking -on the _Subscribe to calendar_ button on the following pages: +on the **Subscribe to calendar** button on the following pages: -- on the **Assigned Issues** page that is linked on the right-hand side of the - GitLab header +- on the **Assigned Issues** page that is linked on the right-hand side of the GitLab header - on the **Project Issues** page - on the **Group Issues** page diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 4acbb4cc3f6..f69b841e908 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -6,8 +6,9 @@ Issues are the fundamental medium for collaborating on ideas and planning work i The GitLab issue tracker is an advanced tool for collaboratively developing ideas, solving problems, and planning work. -Issues can allow you, your team, and your collaborators to share and discuss proposals before and during their implementation. -However, they can be used for a variety of other purposes, customized to your needs and workflow. +Issues can allow you, your team, and your collaborators to share and discuss proposals +before, and during, their implementation. However, they can be used for a variety of +other purposes, customized to your needs and workflow. Issues are always associated with a specific project, but if you have multiple projects in a group, you can also view all the issues collectively at the group level. @@ -17,13 +18,15 @@ you can also view all the issues collectively at the group level. - Discussing the implementation of a new idea - Tracking tasks and work status - Accepting feature proposals, questions, support requests, or bug reports -- Elaborating new code implementations +- Elaborating on new code implementations -See also the blog post "[Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/)". +See also [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/). ## Parts of an issue -Issues contain a variety of content and metadata, enabling a large range of flexibility in how they are used. Each issue can contain the following attributes, though some items may remain unset. +Issues contain a variety of content and metadata, enabling a large range of flexibility +in how they are used. Each issue can contain the following attributes, though not all items +must be set. <table class="borderless-table fixed-table"> <tr> @@ -70,23 +73,36 @@ Issues contain a variety of content and metadata, enabling a large range of flex ## Viewing and managing issues -While you can view and manage the full detail of an issue at its URL, you can also work with multiple issues at a time using the Issues List, Issue Boards, Epics **[ULTIMATE]**, and issue references. +While you can view and manage the full details of an issue on the [issue page](#issue-page), +you can also work with multiple issues at a time using the [Issues List](#issues-list), +[Issue Boards](#issue-boards), Issue references, and [Epics](#epics-ultimate)**[ULTIMATE]**. + +Key actions for Issues include: + +- [Creating issues](managing_issues.md#create-a-new-issue) +- [Moving issues](managing_issues.md#moving-issues) +- [Closing issues](managing_issues.md#closing-issues) +- [Deleting issues](managing_issues.md#deleting-issues) ### Issue page  -On an issue’s page, you can view all aspects of the issue, and you can also modify them if you you have the necessary [permissions](../../permissions.md). - -For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page. +On an issue's page, you can view [all aspects of the issue](issue_data_and_actions.md), +and modify them if you you have the necessary [permissions](../../permissions.md). ### Issues list  -On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the issue list by [any search query](../../search/index.md#issues-and-merge-requests-per-project) and/or specific metadata, such as label(s), assignees(s), status, and more. From this view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. +On the Issues List, you can view all issues in the current project, or from multiple +projects when opening the Issues List from the higher-level group context. Filter the +issue list with a [search query](../../search/index.md#issues-and-merge-requests-per-project), +including specific metadata, such as label(s), assignees(s), status, and more. From this +view, you can also make certain changes [in bulk](../bulk_editing.md) to the displayed issues. -For more information on interacting with Issues, see the [Issue Data and Actions](issue_data_and_actions.md) page. +For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page +for a rundown of all the fields and information in an issue. For sorting by issue priority, see [Label Priority](../labels.md#label-priority). @@ -94,44 +110,55 @@ For sorting by issue priority, see [Label Priority](../labels.md#label-priority)  -Issue boards are Kanban boards with columns that display issues based on their labels or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using highly customizable workflows. +[Issue boards](../issue_board.md) are Kanban boards with columns that display issues based on their labels +or their assignees**[PREMIUM]**. They offer the flexibility to manage issues using +highly customizable workflows. -You can reorder issues within a column, or drag an issue card to another column; its associated label or assignee will change to match that of the new column. The entire board can also be filtered to only include issues from a certain milestone or an overarching label. - -For more information, see the [Issue Boards](../issue_board.md) page. +You can reorder issues within a column. If you drag an issue card to another column, its +associated label or assignee will change to match that of the new column. The entire +board can also be filtered to only include issues from a certain milestone or an overarching +label. ### Epics **[ULTIMATE]** -Epics let you manage your portfolio of projects more efficiently and with less effort by tracking groups of issues that share a theme, across projects and milestones. - -For more information, see the [Epics](../../group/epics/index.md) page. +[Epics](../../group/epics/index.md) let you manage your portfolio of projects more +efficiently and with less effort by tracking groups of issues that share a theme, across +projects and milestones. ### Related issues **[STARTER]** -You can mark two issues as related, so that when viewing each one, the other is always listed in its Related Issues section. This can help display important context, such as past work, dependencies, or duplicates. - -For more information, see [Related Issues](related_issues.md). +You can mark two issues as related, so that when viewing one, the other is always +listed in its [Related Issues](related_issues.md) section. This can help display important +context, such as past work, dependencies, or duplicates. ### Crosslinking issues -When you reference an issue from another issue or merge request by including its URL or ID, the referenced issue displays a message in the Activity stream about the reference, with a link to the other issue or MR. +You can [crosslink issues](crosslinking_issues.md) by referencing an issue from another +issue or merge request by including its URL or ID. The referenced issue displays a +message in the Activity stream about the reference, with a link to the other issue or MR. -For more information, see [Crosslinking issues](crosslinking_issues.md). +### Similar issues -## Issue actions +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866) in GitLab 11.6. -- [Create an issue](create_new_issue.md) -- [Create an issue from a template](../../project/description_templates.md#using-the-templates) -- [Close an issue](closing_issues.md) -- [Move an issue](moving_issues.md) -- [Delete an issue](deleting_issues.md) -- [Create a merge request from an issue](issue_data_and_actions.md#22-create-merge-request) +To prevent duplication of issues for the same topic, GitLab searches for similar issues +when new issues are being created. + +When typing in the title in the **New Issue** page, GitLab searches titles and descriptions +across all issues the user has access to in the current project. Up 5 similar issues, +sorted by most recently updated, are displayed below the title box. Note that this feature +requires [GraphQL](../../../api/graphql/index.md) to be enabled. -## Advanced issue management + -- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues in order to change their status, assignee, milestone, or labels in bulk. +## Other Issue actions + +- [Create an issue from a template](../../project/description_templates.md#using-the-templates) +- [Set a due date](due_dates.md) +- [Bulk edit issues](../bulk_editing.md) - From the Issues List, select multiple issues + in order to change their status, assignee, milestone, or labels in bulk. - [Import issues](csv_import.md) - [Export issues](csv_export.md) **[STARTER]** - [Issues API](../../../api/issues.md) -- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, - or Bugzilla. +- Configure an [external issue tracker](../../../integration/external-issue-tracker.md) + such as Jira, Redmine, or Bugzilla. diff --git a/doc/user/project/issues/issue_data_and_actions.md b/doc/user/project/issues/issue_data_and_actions.md index 2103f331aa2..9898cd6cf15 100644 --- a/doc/user/project/issues/issue_data_and_actions.md +++ b/doc/user/project/issues/issue_data_and_actions.md @@ -48,7 +48,7 @@ which you can click to mark that issue as done (which will be reflected in the T #### 3. Assignee An issue can be assigned to yourself, another person, or [many people](#31-multiple-assignees-STARTER). -The assignee(s) can be changed as much as needed. The idea is that the assignees are +The assignee(s) can be changed as often as needed. The idea is that the assignees are responsible for that issue until it's reassigned to someone else to take it from there. When assigned to someone, it will appear in their assigned issues list. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md new file mode 100644 index 00000000000..91dbf0d848e --- /dev/null +++ b/doc/user/project/issues/managing_issues.md @@ -0,0 +1,225 @@ +# Managing Issues + +[GitLab Issues](index.md) are the fundamental medium for collaborating on ideas and +planning work in GitLab. [Creating](#create-a-new-issue), [moving](#moving-issues), +[closing](#closing-issues), and [deleting](#deleting-issues) are key actions that +you can do with issues. + +## Create a new Issue + +When you create a new issue, you'll be prompted to fill in the [data and fields of the issue](issue_data_and_actions.md#parts-of-an-issue), as illustrated below. + + + +### Accessing the new Issue form + +There are many ways to get to the new Issue form from within a project: + +- Navigate to your **Project's Dashboard** > **Issues** > **New Issue**: + +  + +- From an **opened issue** in your project, click **New Issue** to create a new + issue in the same project: + +  + +- From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown + menu with a few options. Select **New Issue** to create an issue in that project: + +  + +- From an **Issue Board**, create a new issue by clicking on the plus sign (**+**) at the top of a list. + It opens a new issue for that project, pre-labeled with its respective list. + +  + +### New issue from the group-level Issue Tracker + +Go to the Group dashboard and click "Issues" in the sidebar to visit the Issue Tracker +for all projects in your Group. Select the project you'd like to add an issue for +using the dropdown button at the top-right of the page. + + + +We'll keep track of the project you selected most recently, and use it as the default +for your next visit. This should save you a lot of time and clicks, if you mostly +create issues for the same project. + + + +### New issue via Service Desk **[PREMIUM]** + +Enable [Service Desk](../service_desk.md) for your project and offer email support. +By doing so, when your customer sends a new email, a new issue can be created in +the appropriate project and followed up from there. + +### New issue via email + +A link to **Email a new issue to this project** is displayed at the bottom of a project's +**Issues List** page, if your GitLab instance has [incoming email](../../../administration/incoming_email.md) +configured. + + + +When you click this link, an email address is generated and displayed, which should be used +by **you only**, to create issues in this project. You can save this address as a +contact in your email client for easy acceess. + +CAUTION: **Caution:** +This is a private email address, generated just for you. **Keep it to yourself**, +as anyone who knows it can create issues or merge requests as if they +were you. If the address is compromised, or you'd like it to be regenerated for +any reason, click **Email a new issue to this project** again and click the reset link. + +Sending an email to this address will create a new issue in your name for +this project, where: + +- The email subject becomes the issue title. +- The email body becomes the issue description. +- [Markdown](../../markdown.md) and [quick actions](../quick_actions.md) are supported. + +NOTE: **Note:** +In GitLab 11.7, we updated the format of the generated email address. However the +older format is still supported, allowing existing aliases or contacts to continue working. + +### New issue via URL with prefilled fields + +You can link directly to the new issue page for a given project, with prefilled +field values using query string parameters in a URL. This is useful for embedding +a URL in an external HTML page, and also certain scenarios where you want the user to +create an issue with certain fields prefilled. + +The title, description, and description template fields can be prefilled using +this method. You cannot pre-fill both the description and description template fields +in the same URL (since a description template also populates the description field). + +Follow these examples to form your new issue URL with prefilled fields. + +- For a new issue in the GitLab Community Edition project with a pre-filled title + and a pre-filled description, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issue[description]=Research%20idea` +- For a new issue in the GitLab Community Edition project with a pre-filled title + and a pre-filled description template, the URL would be `https://gitlab.com/gitlab-org/gitlab-ce/issues/new?issue[title]=Validate%20new%20concept&issuable_template=Research%20proposal` + +## Moving Issues + +Moving an issue will copy it to a new location (project), and close it in the old project, +but it will not be deleted. There will also be a system note added to both issues +indicating where it came from and went to. + +The "Move issue" button is at the bottom of the right-sidebar when viewing the issue. + + + +### Moving Issues in Bulk + +If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. + +To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](https://docs.gitlab.com/ee/raketasks/backup_restore.html#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console. + +```ruby +project = Project.find_by_full_path('full path of the project where issues are moved from') +issues = project.issues +admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues +target_project = Project.find_by_full_path('full path of target project where issues moved to') + +issues.each do |issue| + if issue.state != "closed" && issue.moved_to.nil? + Issues::MoveService.new(project, admin_user).execute(issue, target_project) + else + puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" + end +end; nil +``` + +## Closing Issues + +When you decide that an issue is resolved, or no longer needed, you can close the issue +using the close button: + + + +You can also close an issue from the [Issue Boards](../issue_board.md) by dragging an issue card +from its list and dropping it into the **Closed** list. + + + +### Closing issues automatically + +NOTE: **Note:** +For performance reasons, automatic issue closing is disabled for the very first +push from an existing repository. + +When a commit or merge request resolves one or more issues, it is possible to have +these issues closed automatically when the commit or merge request reaches the project's +default branch. + +If a commit message or merge request description contains text matching a [defined pattern](#default-closing-pattern), +all issues referenced in the matched text will be closed. This happens when the commit +is pushed to a project's [**default** branch](../repository/branches/index.md#default-branch), +or when a commit or merge request is merged into it. + +For example, if `Closes #4, #6, Related to #5` is included in a Merge Request +description, issues `#4` and `#6` will close automatically when the MR is merged, but not `#5`. +Using `Related to` flags `#5` as a [related issue](related_issues.md), +but it will not close automatically. + + + +If the issue is in a different repository than the MR, add the full URL for the issue(s): + +```md +Closes #4, #6, and https://gitlab.com/<username>/<projectname>/issues/<xxx> +``` + +#### Default closing pattern + +When not specified, the default issue closing pattern as shown below will be used: + +```bash +((?:[Cc]los(?:e[sd]?|ing)|[Ff]ix(?:e[sd]|ing)?|[Rr]esolv(?:e[sd]?|ing)|[Ii]mplement(?:s|ed|ing)?)(:?) +(?:(?:issues? +)?%{issue_ref}(?:(?:, *| +and +)?)|([A-Z][A-Z0-9_]+-\d+))+) +``` + +This translates to the following keywords: + +- Close, Closes, Closed, Closing, close, closes, closed, closing +- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing +- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving +- Implement, Implements, Implemented, Implementing, implement, implements, implemented, implementing + +Note that `%{issue_ref}` is a complex regular expression defined inside GitLab's +source code that can match references to: + +- A local issue (`#123`). +- A cross-project issue (`group/project#123`). +- A link to an issue (`https://gitlab.example.com/group/project/issues/123`). + +For example the following commit message: + +``` +Awesome commit message + +Fix #20, Fixes #21 and Closes group/otherproject#22. +This commit is also related to #17 and fixes #18, #19 +and https://gitlab.example.com/group/otherproject/issues/23. +``` + +will close `#18`, `#19`, `#20`, and `#21` in the project this commit is pushed to, +as well as `#22` and `#23` in group/otherproject. `#17` won't be closed as it does +not match the pattern. It works with multi-line commit messages as well as one-liners +when used from the command line with `git commit -m`. + +#### Customizing the issue closing pattern **[CORE ONLY]** + +In order to change the default issue closing pattern, GitLab administrators must edit the +[`gitlab.rb` or `gitlab.yml` file](../../../administration/issue_closing_pattern.md) +of your installation. + +## Deleting Issues + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2982) in GitLab 8.6 + +Users with [project owner permission](../../permissions.md) can delete an issue by +editing it and clicking on the delete button. + + diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md index 8aac2c01444..8331f865b83 100644 --- a/doc/user/project/issues/moving_issues.md +++ b/doc/user/project/issues/moving_issues.md @@ -1,35 +1,5 @@ -# Moving Issues - -Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. - -Moving an issue will close it and duplicate it on the specified project. -There will also be a system note added to both issues indicating where it came from or went to. - -You can move an issue with the "Move issue" button at the bottom of the right-sidebar when viewing the issue. - - - -## Troubleshooting - -### Moving Issues in Bulk - -If you have advanced technical skills you can also bulk move all the issues from one project to another in the rails console. The below script will move all the issues from one project to another that are not in status **closed**. - -To access rails console run `sudo gitlab-rails console` on the GitLab server and run the below script. Please be sure to change **project**, **admin_user** and **target_project** to your values. We do also recommend [creating a backup](https://docs.gitlab.com/ee/raketasks/backup_restore.html#creating-a-backup-of-the-gitlab-system) before attempting any changes in the console. - -```ruby -project = Project.find_by_full_path('full path of the project where issues are moved from') -issues = project.issues -admin_user = User.find_by_username('username of admin user') # make sure user has permissions to move the issues -target_project = Project.find_by_full_path('full path of target project where issues moved to') - -issues.each do |issue| - if issue.state != "closed" && issue.moved_to.nil? - Issues::MoveService.new(project, admin_user).execute(issue, target_project) - else - puts "issue with id: #{issue.id} and title: #{issue.title} was not moved" - end -end; nil - -``` +--- +redirect_to: 'managing_issues.md#moving-issues' +--- +This document was moved to [another location](managing_issues.md#moving-issues). diff --git a/doc/user/project/issues/similar_issues.md b/doc/user/project/issues/similar_issues.md index e90ecd88ec6..9cbac53ee41 100644 --- a/doc/user/project/issues/similar_issues.md +++ b/doc/user/project/issues/similar_issues.md @@ -1,16 +1,5 @@ -# Similar issues +--- +redirect_to: 'index.md#similar-issues' +--- -> [Introduced][ce-22866] in GitLab 11.6. - -Similar issues suggests issues that are similar when new issues are being created. -This features requires [GraphQL] to be enabled. - - - -You can see the similar issues when typing in the title in the new issue form. -This searches both titles and descriptions across all issues the user has access -to in the current project. It then displays the first 5 issues sorted by most -recently updated. - -[GraphQL]: ../../../api/graphql/index.md -[ce-22866]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22866 +This document was moved to [another location](index.md#similar-issues). diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 447b338928c..169b10572b0 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -23,7 +23,7 @@ With GitLab merge requests, you can: - Build, test, and deploy your code in a per-branch basis with built-in [GitLab CI/CD](../../../ci/README.md) - Prevent the merge request from being merged before it's ready with [WIP MRs](#work-in-progress-merge-requests) - View the deployment process through [Pipeline Graphs](../../../ci/pipelines.md#visualizing-pipelines) -- [Automatically close the issue(s)](../../project/issues/closing_issues.md#via-merge-request) that originated the implementation proposed in the merge request +- [Automatically close the issue(s)](../../project/issues/managing_issues.md#closing-issues-automatically) that originated the implementation proposed in the merge request - Assign it to any registered user, and change the assignee how many times you need - Assign a [milestone](../../project/milestones/index.md) and track the development of a broader implementation - Organize your issues and merge requests consistently throughout the project with [labels](../../project/labels.md) diff --git a/doc/user/project/merge_requests/squash_and_merge.md b/doc/user/project/merge_requests/squash_and_merge.md index 39fd2588811..38459584eed 100644 --- a/doc/user/project/merge_requests/squash_and_merge.md +++ b/doc/user/project/merge_requests/squash_and_merge.md @@ -50,7 +50,10 @@ 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](revert_changes.md) if necessary. +meaningful commit messages and: + +- It's simpler to [revert](revert_changes.md) if necessary. +- The merged branch will retain the full commit history. ## Enabling squash for a merge request 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 9cd868067bc..142178ba241 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 @@ -15,7 +15,7 @@ being merged, and it will stay disabled until the "WIP" flag has been removed. There are several ways to flag a merge request as a Work In Progress: -- Add "[WIP]" or "WIP:" to the start of the merge request's title. Clicking on +- Add `[WIP]` or `WIP:` to the start of the merge request's title. Clicking on **Start the title with WIP:**, under the title box, when editing the merge request's description will have the same effect. - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests) @@ -30,7 +30,7 @@ There are several ways to flag a merge request as a Work In Progress: Similar to above, when a Merge Request is ready to be merged, you can remove the "Work in Progress" flag in several ways: -- Remove "[WIP]" or "WIP:" from the start of the merge request's title. Clicking on +- Remove `[WIP]` or `WIP:` from the start of the merge request's title. Clicking on **Remove the WIP: prefix from the title**, under the title box, when editing the merge request's description, will have the same effect. - Add the `/wip` [quick action](../quick_actions.md#quick-actions-for-issues-and-merge-requests) diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 002addfc043..f9feae36dbc 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -187,7 +187,8 @@ information in the UI. DANGER: **Warning:** This is a destructive action that leads to data loss. Use with caution. -If you have at least Developer [permissions](../../permissions.md#gitlab-cicd-permissions) +If you are either the owner of a given job or have Master +[permissions](../../permissions.md#gitlab-cicd-permissions) on the project, you can erase a single job via the UI which will also remove the artifacts and the job's trace. diff --git a/doc/user/project/repository/branches/index.md b/doc/user/project/repository/branches/index.md index 13e4f2ce163..a81c9197ec1 100644 --- a/doc/user/project/repository/branches/index.md +++ b/doc/user/project/repository/branches/index.md @@ -21,7 +21,7 @@ branch for your project. You can choose another branch to be your project's default under your project's **Settings > Repository**. The default branch is the branch affected by the -[issue closing pattern](../../issues/automatic_issue_closing.md), +[issue closing pattern](../../issues/managing_issues.md#closing-issues-automatically), which means that _an issue will be closed when a merge request is merged to the **default branch**_. diff --git a/doc/user/project/repository/web_editor.md b/doc/user/project/repository/web_editor.md index ce9d23bf911..253e5374f52 100644 --- a/doc/user/project/repository/web_editor.md +++ b/doc/user/project/repository/web_editor.md @@ -114,7 +114,7 @@ If your [project is already configured with a deployment service][project-servic After the branch is created, you can edit files in the repository to fix the issue. When a merge request is created based on the newly created branch, -the description field will automatically display the [issue closing pattern] +the description field will automatically display the [issue closing pattern](../issues/managing_issues.md#closing-issues-automatically) `Closes #ID`, where `ID` the ID of the issue. This will close the issue once the merge request is merged. @@ -181,4 +181,3 @@ through the web editor, you can choose to use another of your linked email addresses from the **User Settings > Edit Profile** page. [ce-2808]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2808 -[issue closing pattern]: ../issues/automatic_issue_closing.md diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 40e2486ace5..45bd8c29a48 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -4,7 +4,7 @@ comments: false # Workflow -- [Automatic issue closing](../user/project/issues/automatic_issue_closing.md) +- [Automatic issue closing](../user/project/issues/managing_issues.md#closing-issues-automatically) - [Change your time zone](timezone.md) - [Cycle Analytics](../user/project/cycle_analytics.md) - [Description templates](../user/project/description_templates.md) diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md index 3e24557591c..0cb390e1242 100644 --- a/doc/workflow/gitlab_flow.md +++ b/doc/workflow/gitlab_flow.md @@ -175,7 +175,7 @@ A merge request is an online place to discuss the change and review the code. If you open the merge request but do not assign it to anyone, it is a "Work In Progress" merge request. These are used to discuss the proposed implementation but are not ready for inclusion in the `master` branch yet. -Start the title of the merge request with "[WIP]" or "WIP:" to prevent it from being merged before it's ready. +Start the title of the merge request with `[WIP]` or `WIP:` to prevent it from being merged before it's ready. When you think the code is ready, assign the merge request to a reviewer. The reviewer can merge the changes when they think the code is ready for inclusion in the `master` branch. diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 5d560f2e000..d49d29c805a 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -64,18 +64,18 @@ These settings can be configured on project page under the name of the project. Below is the table of events users can be notified of: -| Event | Sent to | Settings level | -|------------------------------|-------------------------------------------------------------------|------------------------------| -| New SSH key added | User | Security email, always sent. | -| New email added | User | Security email, always sent. | -| Email changed | User | Security email, always sent. | -| Password changed | User | Security email, always sent. | -| New user created | User | Sent on user creation, except for omniauth (LDAP)| -| User added to project | User | Sent when user is added to project | -| Project access level changed | User | Sent when user project access level is changed | -| User added to group | User | Sent when user is added to group | -| Group access level changed | User | Sent when user group access level is changed | -| Project moved | Project members [1] | [1] not disabled | +| Event | Sent to | Settings level | +|------------------------------|---------------------|------------------------------| +| New SSH key added | User | Security email, always sent. | +| New email added | User | Security email, always sent. | +| Email changed | User | Security email, always sent. | +| Password changed | User | Security email, always sent. | +| New user created | User | Sent on user creation, except for omniauth (LDAP)| +| User added to project | User | Sent when user is added to project | +| Project access level changed | User | Sent when user project access level is changed | +| User added to group | User | Sent when user is added to group | +| Group access level changed | User | Sent when user group access level is changed | +| Project moved | Project members (1) | (1) not disabled | ### Issue / Epics / Merge request events |
