diff options
Diffstat (limited to 'doc')
456 files changed, 7033 insertions, 2237 deletions
diff --git a/doc/README.md b/doc/README.md index 1cdb5bc7b47..c3db960514f 100644 --- a/doc/README.md +++ b/doc/README.md @@ -364,6 +364,7 @@ The following documentation relates to the DevOps **Secure** stage: | [Dependency Scanning](user/application_security/dependency_scanning/index.md) **(ULTIMATE)** | Analyze your dependencies for known vulnerabilities. | | [Dynamic Application Security Testing (DAST)](user/application_security/dast/index.md) **(ULTIMATE)** | Analyze running web applications for known vulnerabilities. | | [Group Security Dashboard](user/application_security/security_dashboard/index.md#group-security-dashboard) **(ULTIMATE)** | View vulnerabilities in all the projects in a group and its subgroups. | +| [Instance Security Dashboard](user/application_security/security_dashboard/index.md#instance-security-dashboard) **(ULTIMATE)** | View vulnerabilities in all the projects you're interested in. | | [License Compliance](user/application_security/license_compliance/index.md) **(ULTIMATE)** | Search your project's dependencies for their licenses. | | [Pipeline Security Dashboard](user/application_security/security_dashboard/index.md#pipeline-security-dashboard) **(ULTIMATE)** | View the security reports for your project's pipelines. | | [Project Security Dashboard](user/application_security/security_dashboard/index.md#project-security-dashboard) **(ULTIMATE)** | View the latest security reports for your project. | diff --git a/doc/administration/audit_events.md b/doc/administration/audit_events.md index ccb4ccbd525..7d3be9e1bd3 100644 --- a/doc/administration/audit_events.md +++ b/doc/administration/audit_events.md @@ -18,7 +18,7 @@ permission level, who added a new user, or who removed a user. ## Use-cases -- Check who was the person who changed the permission level of a particular +- Check who the person was that changed the permission level of a particular user for a project in GitLab. - Use it to track which users have access to a certain group of projects in GitLab, and who gave them that permission level. @@ -80,6 +80,9 @@ From there, you can see the following actions: - Project was archived - Project was unarchived - Added/removed/updated protected branches +- Release was added to a project +- Release was updated +- Release milestone associations changed ### Instance events **(PREMIUM ONLY)** @@ -104,7 +107,7 @@ recorded: - Started/stopped user impersonation It is possible to filter particular actions by choosing an audit data type from -the filter drop-down. You can further filter by specific group, project or user +the filter dropdown box. You can further filter by specific group, project or user (for authentication events).  diff --git a/doc/administration/auditor_users.md b/doc/administration/auditor_users.md index 9b4d0f443cf..46f8ae25916 100644 --- a/doc/administration/auditor_users.md +++ b/doc/administration/auditor_users.md @@ -9,7 +9,7 @@ resources on the GitLab instance. Auditor users can have full access to their own resources (projects, groups, snippets, etc.), and read-only access to **all** other resources, except the -Admin area. To put another way, they are just regular users (who can be added +Admin Area. To put another way, they are just regular users (who can be added to projects, create personal snippets, create milestones on their groups, etc.) who also happen to have read-only access to all projects on the system that they haven't been explicitly [given access][permissions] to. @@ -28,7 +28,7 @@ To sum up, assuming you have logged-in as an Auditor user: have the same access as the [permissions] they were given to. For example, if they were added as a Developer, they could then push commits or comment on issues. -- The Auditor cannot view the Admin area, or perform any admin actions. +- The Auditor cannot view the Admin Area, or perform any admin actions. For more information about what an Auditor can or can't do, see the [Permissions and restrictions of an Auditor user](#permissions-and-restrictions-of-an-auditor-user) @@ -73,7 +73,7 @@ instance, with the following permissions/restrictions: - Can read issues / MRs - Can read project snippets - Cannot be Admin and Auditor at the same time -- Cannot access the Admin area +- Cannot access the Admin Area - In a group / project they're not a member of: - Cannot access project settings - Cannot access group settings diff --git a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md index 743893d984a..800bb28c664 100644 --- a/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md +++ b/doc/administration/auth/how_to_configure_ldap_gitlab_ce/index.md @@ -23,7 +23,7 @@ For example, [Active Directory](https://docs.microsoft.com/en-us/previous-versio - [Oracle Internet Directory](https://www.oracle.com/middleware/technologies/internet-directory.html) - [OpenLDAP](http://www.openldap.org/) - [389 Directory](http://directory.fedoraproject.org/) -- [OpenDJ (Renamed to Foregerock Directory Services)](https://www.forgerock.com/platform/directory-services) +- [OpenDJ (Renamed to Forgerock Directory Services)](https://www.forgerock.com/platform/directory-services) - [ApacheDS](https://directory.apache.org/) > GitLab uses the [Net::LDAP](https://rubygems.org/gems/net-ldap) library under the hood. This means it supports all [IETF](https://tools.ietf.org/html/rfc2251) compliant LDAPv3 servers. diff --git a/doc/administration/auth/ldap-ee.md b/doc/administration/auth/ldap-ee.md index 34fd97a24ee..a15e34c33a5 100644 --- a/doc/administration/auth/ldap-ee.md +++ b/doc/administration/auth/ldap-ee.md @@ -452,7 +452,7 @@ things to check to debug the situation. links by visiting the GitLab group, then **Settings dropdown > LDAP groups**. - Check that the user has an LDAP identity: 1. Sign in to GitLab as an administrator user. - 1. Navigate to **Admin area > Users**. + 1. Navigate to **Admin Area > Users**. 1. Search for the user 1. Open the user, by clicking on their name. Do not click 'Edit'. 1. Navigate to the **Identities** tab. There should be an LDAP identity with diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index d449a5a72af..857f554f2fe 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -52,7 +52,7 @@ If a user is deleted from the LDAP server, they will be blocked in GitLab as well. Users will be immediately blocked from logging in. However, there is an LDAP check cache time of one hour (see note) which means users that are already logged in or are using Git over SSH will still be able to access -GitLab for up to one hour. Manually block the user in the GitLab Admin area to +GitLab for up to one hour. Manually block the user in the GitLab Admin Area to immediately block all access. NOTE: **Note**: diff --git a/doc/administration/file_hooks.md b/doc/administration/file_hooks.md new file mode 100644 index 00000000000..5ef739a4289 --- /dev/null +++ b/doc/administration/file_hooks.md @@ -0,0 +1,116 @@ +# File hooks + +> Introduced in GitLab 10.6. +> Until 12.8 the feature name was Plugins. + +With custom file hooks, GitLab administrators can introduce custom integrations +without modifying GitLab's source code. + +NOTE: **Note:** +Instead of writing and supporting your own file hook you can make changes +directly to the GitLab source code and contribute back upstream. This way we can +ensure functionality is preserved across versions and covered by tests. + +NOTE: **Note:** +File hooks must be configured on the filesystem of the GitLab server. Only GitLab +server administrators will be able to complete these tasks. Explore +[system hooks] or [webhooks] as an option if you do not have filesystem access. + +A file hook will run on each event so it's up to you to filter events or projects +within a file hook code. You can have as many file hooks as you want. Each file hook will +be triggered by GitLab asynchronously in case of an event. For a list of events +see the [system hooks] documentation. + +## Setup + +The file hooks must be placed directly into the `plugins` directory, subdirectories +will be ignored. There is an +[`example` directory inside `plugins`](https://gitlab.com/gitlab-org/gitlab/tree/master/plugins/examples) +where you can find some basic examples. + +Follow the steps below to set up a custom hook: + +1. On the GitLab server, navigate to the plugin directory. + For an installation from source the path is usually + `/home/git/gitlab/plugins/`. For Omnibus installs the path is + usually `/opt/gitlab/embedded/service/gitlab-rails/plugins`. + + For [highly available] configurations, your hook file should exist on each + application server. + +1. Inside the `plugins` directory, create a file with a name of your choice, + without spaces or special characters. +1. Make the hook file executable and make sure it's owned by the Git user. +1. Write the code to make the file hook function as expected. That can be + in any language, and ensure the 'shebang' at the top properly reflects the + language type. For example, if the script is in Ruby the shebang will + probably be `#!/usr/bin/env ruby`. +1. The data to the file hook will be provided as JSON on STDIN. It will be exactly + same as for [system hooks] + +That's it! Assuming the file hook code is properly implemented, the hook will fire +as appropriate. The file hooks file list is updated for each event, there is no +need to restart GitLab to apply a new file hook. + +If a file hook executes with non-zero exit code or GitLab fails to execute it, a +message will be logged to: + +- `gitlab-rails/plugin.log` in an Omnibus installation. +- `log/plugin.log` in a source installation. + +## Creating file hooks + +Below is an example that will only response on the event `project_create` and +will inform the admins from the GitLab instance that a new project has been created. + +```ruby +# By using the embedded ruby version we eliminate the possibility that our chosen language +# would be unavailable from +#!/opt/gitlab/embedded/bin/ruby +require 'json' +require 'mail' + +# The incoming variables are in JSON format so we need to parse it first. +ARGS = JSON.parse(STDIN.read) + +# We only want to trigger this file hook on the event project_create +return unless ARGS['event_name'] == 'project_create' + +# We will inform our admins of our gitlab instance that a new project is created +Mail.deliver do + from 'info@gitlab_instance.com' + to 'admin@gitlab_instance.com' + subject "new project " + ARGS['name'] + body ARGS['owner_name'] + 'created project ' + ARGS['name'] +end +``` + +## Validation + +Writing your own file hook can be tricky and it's easier if you can check it +without altering the system. A rake task is provided so that you can use it +in a staging environment to test your file hook before using it in production. +The rake task will use a sample data and execute each of file hook. The output +should be enough to determine if the system sees your file hook and if it was +executed without errors. + +```bash +# Omnibus installations +sudo gitlab-rake file_hooks:validate + +# Installations from source +cd /home/git/gitlab +bundle exec rake file_hooks:validate RAILS_ENV=production +``` + +Example of output: + +``` +Validating file hooks from /plugins directory +* /home/git/gitlab/plugins/save_to_file.clj succeed (zero exit code) +* /home/git/gitlab/plugins/save_to_file.rb failure (non-zero exit code) +``` + +[system hooks]: ../system_hooks/system_hooks.md +[webhooks]: ../user/project/integrations/webhooks.md +[highly available]: ./high_availability/README.md diff --git a/doc/administration/geo/replication/database.md b/doc/administration/geo/replication/database.md index 72c3692716b..bddd30dbb2a 100644 --- a/doc/administration/geo/replication/database.md +++ b/doc/administration/geo/replication/database.md @@ -266,13 +266,13 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o 1. SSH into your GitLab **secondary** server and login as root: - ``` + ```sh sudo -i ``` 1. Stop application server and Sidekiq - ``` + ```sh gitlab-ctl stop unicorn gitlab-ctl stop sidekiq ``` @@ -295,7 +295,7 @@ There is an [issue where support is being discussed](https://gitlab.com/gitlab-o 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: - ``` + ```sh editor server.crt ``` diff --git a/doc/administration/geo/replication/datatypes.md b/doc/administration/geo/replication/datatypes.md new file mode 100644 index 00000000000..75ce7503c34 --- /dev/null +++ b/doc/administration/geo/replication/datatypes.md @@ -0,0 +1,168 @@ +# Geo data types support + +A Geo data type is a specific class of data that is required by one or more GitLab features to +store relevant information. + +To replicate data produced by these features with Geo, we use several strategies to access, transfer, and verify them. + +## Data types + +We currently distinguish between three different data types: + +- [Git repositories](#git-repositories) +- [Blobs](#blobs) +- [Database](#database) + +See the list below of each feature or component we replicate, its corresponding data type, replication and +verification methods: + +| Type | Feature / component | Replication method | Verification method | +|----------|-----------------------------------------------|---------------------------------------------|----------------------| +| Database | Application data in PostgreSQL | Native | Native | +| Database | Redis | _N/A_ (*1*) | _N/A_ | +| Database | Elasticsearch | Native | Native | +| Database | Personal snippets | Postgres Replication | Postgres Replication | +| Database | Project snippets | Postgres Replication | Postgres Replication | +| Database | SSH public keys | Postgres Replication | Postgres Replication | +| Git | Project repository | Geo with Gitaly | Gitaly Checksum | +| Git | Project wiki repository | Geo with Gitaly | Gitaly Checksum | +| Git | Project designs repository | Geo with Gitaly | Gitaly Checksum | +| Git | Object pools for forked project deduplication | Geo with Gitaly | _Not implemented_ | +| Blobs | User uploads _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | User uploads _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | LFS objects _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | LFS objects _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | CI job artifacts _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | CI job artifacts _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Archived CI build traces _(filesystem)_ | Geo with API | _Not implemented_ | +| Blobs | Archived CI build traces _(object storage)_ | Geo with API/Managed (*2*) | _Not implemented_ | +| Blobs | Container registry _(filesystem)_ | Geo with API/Docker API | _Not implemented_ | +| Blobs | Container registry _(object storage)_ | Geo with API/Managed/Docker API (*2*) | _Not implemented_ | + +- (*1*): Redis replication can be used as part of HA with Redis sentinel. It's not used between Geo nodes. +- (*2*): Object storage replication can be performed by Geo or by your object storage provider/appliance + native replication feature. + +### Git repositories + +A GitLab instance can have one or more repository shards. Each shard has a Gitaly instance that +is responsible for allowing access and operations on the locally stored Git repositories. It can run +on a machine with a single disk, multiple disks mounted as a single mount-point (like with a RAID array), +or using LVM. + +It requires no special filesystem and can work with NFS or a mounted Storage Appliance (there may be +performance limitations when using a remote filesystem). + +Communication is done via Gitaly's own gRPC API. There are three possible ways of synchronization: + +- Using regular Git clone/fetch from one Geo node to another (with special authentication). +- Using repository snapshots (for when the first method fails or repository is corrupt). +- Manual trigger from the Admin UI (a combination of both of the above). + +Each project can have at most 3 different repositories: + +- A project repository, where the source code is stored. +- A wiki repository, where the wiki content is stored. +- A design repository, where design artifacts are indexed (assets are actually in LFS). + +They all live in the same shard and share the same base name with a `-wiki` and `-design` suffix +for Wiki and Design Repository cases. + +### Blobs + +GitLab stores files and blobs such as Issue attachments or LFS objects into either: + +- The filesystem in a specific location. +- An Object Storage solution. Object Storage solutions can be: + - Cloud based like Amazon S3 Google Cloud Storage. + - Self hosted (like MinIO). + - A Storage Appliance that exposes an Object Storage-compatible API. + +When using the filesystem store instead of Object Storage, you need to use network mounted filesystems +to run GitLab when using more than one server (for example with a High Availability setup). + +With respect to replication and verification: + +- We transfer files and blobs using an internal API request. +- With Object Storage, you can either: + - Use a cloud provider replication functionality. + - Have GitLab replicate it for you. + +### Database + +GitLab relies on data stored in multiple databases, for different use-cases. +PostgreSQL is the single point of truth for user-generated content in the Web interface, like issues content, comments +as well as permissions and credentials. + +PostgreSQL can also hold some level of cached data like HTML rendered Markdown, cached merge-requests diff (this can +also be configured to be offloaded to object storage). + +We use PostgreSQL's own replication functionality to replicate data from the primary to secondary nodes. + +We use Redis both as a cache store and to hold persistent data for our background jobs system. Because both +use-cases has data that are exclusive to the same Geo node, we don't replicate it between nodes. + +Elasticsearch is an optional database, that can enable advanced searching capabilities, like improved Global Search +in both source-code level and user generated content in Issues / Merge-Requests and discussions. Currently it's not +supported in Geo. + +## Limitations on replication/verification + +The following table lists the GitLab features along with their replication +and verification status on a **secondary** node. + +You can keep track of the progress to implement the missing items in +these epics/issues: + +- [Unreplicated Data Types](https://gitlab.com/groups/gitlab-org/-/epics/893) +- [Verify all replicated data](https://gitlab.com/groups/gitlab-org/-/epics/1430) + +DANGER: **DANGER** +Features not on this list, or with **No** in the **Replicated** column, +are not replicated on the **secondary** node. Failing over without manually +replicating data from those features will cause the data to be **lost**. +If you wish to use those features on a **secondary** node, or to execute a failover +successfully, you must replicate their data using some other means. + +| Feature | Replicated | Verified | Notes | +|-----------------------------------------------------|--------------------------|-----------------------------|---------------------------------------------| +| Application data in PostgreSQL | **Yes** | **Yes** | | +| Project repository | **Yes** | **Yes** | | +| Project wiki repository | **Yes** | **Yes** | | +| Project designs repository | **Yes** | [No][design-verification] | | +| Uploads | **Yes** | [No][upload-verification] | Verified only on transfer, or manually (*1*)| +| LFS objects | **Yes** | [No][lfs-verification] | Verified only on transfer, or manually (*1*)| +| CI job artifacts (other than traces) | **Yes** | [No][artifact-verification] | Verified only manually (*1*) | +| Archived traces | **Yes** | [No][artifact-verification] | Verified only on transfer, or manually (*1*)| +| Personal snippets | **Yes** | **Yes** | | +| Project snippets | **Yes** | **Yes** | | +| Object pools for forked project deduplication | **Yes** | No | | +| [Server-side Git Hooks][custom-hooks] | No | No | | +| [Elasticsearch integration][elasticsearch] | No | No | | +| [GitLab Pages][gitlab-pages] | [No][pages-replication] | No | | +| [Container Registry][container-registry] | **Yes** | No | | +| [NPM Registry][npm-registry] | No | No | | +| [Maven Repository][maven-repository] | No | No | | +| [Conan Repository][conan-repository] | No | No | | +| [External merge request diffs][merge-request-diffs] | [No][diffs-replication] | No | | +| Content in object storage | **Yes** | No | | + +- (*1*): The integrity can be verified manually using + [Integrity Check Rake Task](../../raketasks/check.md) on both nodes and comparing the output between them. + +[design-replication]: https://gitlab.com/groups/gitlab-org/-/epics/1633 +[design-verification]: https://gitlab.com/gitlab-org/gitlab/issues/32467 +[upload-verification]: https://gitlab.com/groups/gitlab-org/-/epics/1817 +[lfs-verification]: https://gitlab.com/gitlab-org/gitlab/issues/8922 +[artifact-verification]: https://gitlab.com/gitlab-org/gitlab/issues/8923 +[diffs-replication]: https://gitlab.com/gitlab-org/gitlab/issues/33817 +[pages-replication]: https://gitlab.com/groups/gitlab-org/-/epics/589 + +[custom-hooks]: ../../custom_hooks.md +[elasticsearch]: ../../../integration/elasticsearch.md +[gitlab-pages]: ../../pages/index.md +[container-registry]: ../../packages/container_registry.md +[npm-registry]: ../../../user/packages/npm_registry/index.md +[maven-repository]: ../../../user/packages/maven_repository/index.md +[conan-repository]: ../../../user/packages/conan_repository/index.md +[merge-request-diffs]: ../../merge_request_diffs.md diff --git a/doc/administration/geo/replication/external_database.md b/doc/administration/geo/replication/external_database.md index 4451d3c6c08..6948dcc0c68 100644 --- a/doc/administration/geo/replication/external_database.md +++ b/doc/administration/geo/replication/external_database.md @@ -13,13 +13,13 @@ developed and tested. We aim to be compatible with most external 1. SSH into a GitLab **primary** application server and login as root: - ```sh + ```bash sudo -i ``` 1. Execute the command below to define the node as **primary** node: - ```sh + ```bash gitlab-ctl set-geo-primary-node ``` @@ -47,7 +47,7 @@ configures the **primary** node's database to be replicated by making changes to `pg_hba.conf` and `postgresql.conf`. Make the following configuration changes manually to your external database configuration: -``` +```plaintext ## ## Geo Primary Role ## - pg_hba.conf @@ -55,7 +55,7 @@ manually to your external database configuration: host replication gitlab_replicator <trusted secondary IP>/32 md5 ``` -``` +```plaintext ## ## Geo Primary Role ## - postgresql.conf @@ -75,7 +75,7 @@ hot_standby = on Make the following configuration changes manually to your `postgresql.conf` of external replica database: -``` +```plaintext ## ## Geo Secondary Role ## - postgresql.conf diff --git a/doc/administration/geo/replication/high_availability.md b/doc/administration/geo/replication/high_availability.md index faa9d051107..19266a6b358 100644 --- a/doc/administration/geo/replication/high_availability.md +++ b/doc/administration/geo/replication/high_availability.md @@ -123,6 +123,20 @@ a single node only, rather than as a PostgreSQL cluster. Configure the [**secondary** database](database.md) as a read-only replica of the **primary** database. Use the following as a guide. +1. Generate an MD5 hash of the desired password for the database user that the + GitLab application will use to access the read-replica database: + + Note that the username (`gitlab` by default) is incorporated into the hash. + + ```sh + gitlab-ctl pg-password-md5 gitlab + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # fca0b89a972d69f00eb3ec98a5838484 + ``` + + Use this hash to fill in `<md5_hash_of_your_password>` in the next step. + 1. Edit `/etc/gitlab/gitlab.rb` in the replica database machine, and add the following: @@ -167,6 +181,22 @@ only a single machine, rather than as a PostgreSQL cluster. Configure the tracking database. +1. Generate an MD5 hash of the desired password for the database user that the + GitLab application will use to access the tracking database: + + Note that the username (`gitlab_geo` by default) is incorporated into the + hash. + + ```sh + gitlab-ctl pg-password-md5 gitlab_geo + # Enter password: <your_password_here> + # Confirm password: <your_password_here> + # fca0b89a972d69f00eb3ec98a5838484 + ``` + + Use this hash to fill in `<tracking_database_password_md5_hash>` in the next + step. + 1. Edit `/etc/gitlab/gitlab.rb` in the tracking database machine, and add the following: diff --git a/doc/administration/geo/replication/img/adding_a_secondary_node.png b/doc/administration/geo/replication/img/adding_a_secondary_node.png Binary files differindex 5421b578672..e33b690da18 100644 --- a/doc/administration/geo/replication/img/adding_a_secondary_node.png +++ b/doc/administration/geo/replication/img/adding_a_secondary_node.png diff --git a/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png b/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png Binary files differindex 4b04ba8d1f1..0d1b12e925f 100644 --- a/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png +++ b/doc/administration/geo/replication/img/single_git_add_geolocation_rule.png diff --git a/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png b/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png Binary files differindex c19ad57c953..4dfb78986da 100644 --- a/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png +++ b/doc/administration/geo/replication/img/single_git_add_traffic_policy_endpoints.png diff --git a/doc/administration/geo/replication/img/single_git_clone_panel.png b/doc/administration/geo/replication/img/single_git_clone_panel.png Binary files differindex 8aa0bd2f7d8..427224f5b78 100644 --- a/doc/administration/geo/replication/img/single_git_clone_panel.png +++ b/doc/administration/geo/replication/img/single_git_clone_panel.png diff --git a/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png b/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png Binary files differindex a554532f3b8..ecc4859ca17 100644 --- a/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png +++ b/doc/administration/geo/replication/img/single_git_create_policy_records_with_traffic_policy.png diff --git a/doc/administration/geo/replication/img/single_git_created_policy_record.png b/doc/administration/geo/replication/img/single_git_created_policy_record.png Binary files differindex 74c42395e15..f541c0dd236 100644 --- a/doc/administration/geo/replication/img/single_git_created_policy_record.png +++ b/doc/administration/geo/replication/img/single_git_created_policy_record.png diff --git a/doc/administration/geo/replication/img/single_git_name_policy.png b/doc/administration/geo/replication/img/single_git_name_policy.png Binary files differindex 1a976539e94..5571a41cb3c 100644 --- a/doc/administration/geo/replication/img/single_git_name_policy.png +++ b/doc/administration/geo/replication/img/single_git_name_policy.png diff --git a/doc/administration/geo/replication/img/single_git_policy_diagram.png b/doc/administration/geo/replication/img/single_git_policy_diagram.png Binary files differindex d62952dbbb3..eacd4de0e29 100644 --- a/doc/administration/geo/replication/img/single_git_policy_diagram.png +++ b/doc/administration/geo/replication/img/single_git_policy_diagram.png diff --git a/doc/administration/geo/replication/img/single_git_traffic_policies.png b/doc/administration/geo/replication/img/single_git_traffic_policies.png Binary files differindex b3193c23d99..197b0ac182f 100644 --- a/doc/administration/geo/replication/img/single_git_traffic_policies.png +++ b/doc/administration/geo/replication/img/single_git_traffic_policies.png diff --git a/doc/administration/geo/replication/index.md b/doc/administration/geo/replication/index.md index 0d2ca9ea9d9..04f61775b29 100644 --- a/doc/administration/geo/replication/index.md +++ b/doc/administration/geo/replication/index.md @@ -252,74 +252,13 @@ This list of limitations only reflects the latest version of GitLab. If you are ### Limitations on replication/verification -The following table lists the GitLab features along with their replication -and verification status on a **secondary** node. - You can keep track of the progress to implement the missing items in these epics/issues: - [Unreplicated Data Types](https://gitlab.com/groups/gitlab-org/-/epics/893) - [Verify all replicated data](https://gitlab.com/groups/gitlab-org/-/epics/1430) -| Feature | Replicated | Verified | Notes | -|-----------------------------------------------------|--------------------------|-----------------------------|--------------------------------------------| -| All database content | **Yes** | **Yes** | | -| Project repository | **Yes** | **Yes** | | -| Project wiki repository | **Yes** | **Yes** | | -| Project designs repository | **Yes** | [No][design-verification] | Behind feature flag (2) | -| Uploads | **Yes** | [No][upload-verification] | Verified only on transfer, or manually (1) | -| LFS Objects | **Yes** | [No][lfs-verification] | Verified only on transfer, or manually (1) | -| CI job artifacts (other than traces) | **Yes** | [No][artifact-verification] | Verified only manually (1) | -| Archived traces | **Yes** | [No][artifact-verification] | Verified only on transfer, or manually (1) | -| Personal snippets | **Yes** | **Yes** | | -| Version-controlled personal snippets | No | No | [Not yet supported][unsupported-snippets] | -| Project snippets | **Yes** | **Yes** | | -| Version-controlled project snippets | No | No | [Not yet supported][unsupported-snippets] | -| Object pools for forked project deduplication | **Yes** | No | | -| [Server-side Git Hooks][custom-hooks] | No | No | | -| [Elasticsearch integration][elasticsearch] | No | No | | -| [GitLab Pages][gitlab-pages] | [No][pages-replication] | No | | -| [Container Registry][container-registry] | **Yes** | No | | -| [NPM Registry][npm-registry] | No | No | | -| [Maven Repository][maven-repository] | No | No | | -| [Conan Repository][conan-repository] | No | No | | -| [External merge request diffs][merge-request-diffs] | [No][diffs-replication] | No | | -| Content in object storage | **Yes** | No | | - -[design-replication]: https://gitlab.com/groups/gitlab-org/-/epics/1633 -[design-verification]: https://gitlab.com/gitlab-org/gitlab/issues/32467 -[upload-verification]: https://gitlab.com/groups/gitlab-org/-/epics/1817 -[lfs-verification]: https://gitlab.com/gitlab-org/gitlab/issues/8922 -[artifact-verification]: https://gitlab.com/gitlab-org/gitlab/issues/8923 -[diffs-replication]: https://gitlab.com/gitlab-org/gitlab/issues/33817 -[pages-replication]: https://gitlab.com/groups/gitlab-org/-/epics/589 - -[unsupported-snippets]: https://gitlab.com/gitlab-org/gitlab/issues/14228 -[custom-hooks]: ../../custom_hooks.md -[elasticsearch]: ../../../integration/elasticsearch.md -[gitlab-pages]: ../../pages/index.md -[container-registry]: ../../packages/container_registry.md -[npm-registry]: ../../../user/packages/npm_registry/index.md -[maven-repository]: ../../../user/packages/maven_repository/index.md -[conan-repository]: ../../../user/packages/conan_repository/index.md -[merge-request-diffs]: ../../merge_request_diffs.md - -1. The integrity can be verified manually using -[Integrity Check Rake Task](../../raketasks/check.md) -on both nodes and comparing the output between them. -1. Enable the `enable_geo_design_sync` feature flag by running the -following in a Rails console: - - ```ruby - Feature.disable(:enable_geo_design_sync) - ``` - -DANGER: **DANGER** -Features not on this list, or with **No** in the **Replicated** column, -are not replicated on the **secondary** node. Failing over without manually -replicating data from those features will cause the data to be **lost**. -If you wish to use those features on a **secondary** node, or to execute a failover -successfully, you must replicate their data using some other means. +There is a complete list of all GitLab [data types](datatypes.md) and [existing support for replication and verification](datatypes.md#limitations-on-replicationverification). ## Frequently Asked Questions diff --git a/doc/administration/geo/replication/troubleshooting.md b/doc/administration/geo/replication/troubleshooting.md index 0a2602261d1..7c36d55027a 100644 --- a/doc/administration/geo/replication/troubleshooting.md +++ b/doc/administration/geo/replication/troubleshooting.md @@ -51,6 +51,7 @@ Checking Geo ... GitLab Geo is available ... yes GitLab Geo is enabled ... yes +This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai" GitLab Geo secondary database is correctly configured ... yes Database replication enabled? ... yes Database replication working? ... yes @@ -115,34 +116,36 @@ Any **secondary** nodes should point only to read-only instances. #### Can Geo detect the current node correctly? -Geo finds the current machine's name in `/etc/gitlab/gitlab.rb` by: +Geo finds the current machine's Geo node name in `/etc/gitlab/gitlab.rb` by: - Using the `gitlab_rails['geo_node_name']` setting. - If that is not defined, using the `external_url` setting. -To get a machine's name, run: - -```sh -sudo gitlab-rails runner "puts GeoNode.current_node_name" -``` - This name is used to look up the node with the same **Name** in **Admin Area > Geo**. -To check if current machine is correctly finding its node: +To check if the current machine has a node name that matches a node in the +database, run the check task: ```sh -sudo gitlab-rails runner "puts Gitlab::Geo.current_node.inspect" +sudo gitlab-rake gitlab:geo:check ``` -and expect something like: +It displays the current machine's node name and whether the matching database +record is a **primary** or **secondary** node. -```ruby -#<GeoNode id: 2, schema: "https", host: "gitlab.example.com", port: 443, relative_url_root: "", primary: false, ...> +``` +This machine's Geo node name matches a database record ... yes, found a secondary node named "Shanghai" ``` -By running the command above, `primary` should be `true` when executed in -the **primary** node, and `false` on any **secondary** node. +``` +This machine's Geo node name matches a database record ... no + Try fixing it: + You could add or update a Geo node database record, setting the name to "https://example.com/". + Or you could set this machine's Geo node name to match the name of an existing database record: "London", "Shanghai" + For more information see: + doc/administration/geo/replication/troubleshooting.md#can-geo-detect-the-current-node-correctly +``` ## Fixing errors found when running the Geo check rake task @@ -208,9 +211,9 @@ sudo gitlab-rake gitlab:geo:check Checking Geo ... Finished ``` - - Ensure that you have added the secondary node in the admin area of the primary node. + - Ensure that you have added the secondary node in the Admin Area of the primary node. - Ensure that you entered the `external_url` or `gitlab_rails['geo_node_name']` when adding the secondary node in the admin are of the primary node. - - Prior to GitLab 12.4, edit the secondary node in the admin area of the primary node and ensure that there is a trailing `/` in the `Name` field. + - Prior to GitLab 12.4, edit the secondary node in the Admin Area of the primary node and ensure that there is a trailing `/` in the `Name` field. 1. Check returns Exception: PG::UndefinedTable: ERROR: relation "geo_nodes" does not exist @@ -295,7 +298,7 @@ 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 + sudo gitlab-psql ``` Note: **Note:** Using `gitlab-rails dbconsole` will not work, because managing replication slots requires superuser permissions. @@ -318,6 +321,40 @@ Slots where `active` is `f` are not active. SELECT pg_drop_replication_slot('<name_of_extra_slot>'); ``` +### Message: "ERROR: canceling statement due to conflict with recovery" + +This error may rarely occur under normal usage, and the system is resilient +enough to recover. + +However, under certain conditions, some database queries on secondaries may run +excessively long, which increases the frequency of this error. At some point, +some of these queries will never be able to complete due to being canceled +every time. + +These long-running queries are +[planned to be removed in the future](https://gitlab.com/gitlab-org/gitlab/issues/34269), +but as a workaround, we recommend enabling +[hot_standby_feedback](https://www.postgresql.org/docs/10/hot-standby.html#HOT-STANDBY-CONFLICT). +This increases the likelihood of bloat on the **primary** node as it prevents +`VACUUM` from removing recently-dead rows. However, it has been used +successfully in production on GitLab.com. + +To enable `hot_standby_feedback`, add the following to `/etc/gitlab/gitlab.rb` +on the **secondary** node: + +```ruby +postgresql['hot_standby_feedback'] = 'on' +``` + +Then reconfigure GitLab: + +```sh +sudo gitlab-ctl reconfigure +``` + +To help us resolve this problem, consider commenting on +[the issue](https://gitlab.com/gitlab-org/gitlab/issues/4489). + ### Very large repositories never successfully synchronize on the **secondary** node GitLab places a timeout on all repository clones, including project imports @@ -457,16 +494,55 @@ The following steps are for Omnibus installs only. Using Geo with source-based i To check the configuration: +1. SSH into an app node in the **secondary**: + + ```sh + sudo -i + ``` + + Note: An app node is any machine running at least one of the following services: + + - `puma` + - `unicorn` + - `sidekiq` + - `geo-logcursor` + 1. Enter the database console: + If the tracking database is running on the same node: + ```sh gitlab-geo-psql ``` -1. Check whether any tables are present. If everything is working, you - should see something like this: + Or, if the tracking database is running on a different node, you must specify + the user and host when entering the database console: + + ```sh + gitlab-geo-psql -U gitlab_geo -h <IP of tracking database> + ``` + + You will be prompted for the password of the `gitlab_geo` user. You can find + it in plaintext in `/etc/gitlab/gitlab.rb` at: + + ```ruby + geo_secondary['db_password'] = '<geo_tracking_db_password>' + ``` + + This password is normally set on the tracking database during + [Step 3: Configure the tracking database on the secondary node](high_availability.md#step-3-configure-the-tracking-database-on-the-secondary-node), + and it is set on the app nodes during + [Step 4: Configure the frontend application servers on the secondary node](high_availability.md#step-4-configure-the-frontend-application-servers-on-the-secondary-node). + +1. Check whether any tables are present with the following statement: ```sql + SELECT * from information_schema.foreign_tables; + ``` + + If everything is working, you should see something like this: + + ``` gitlabhq_geo_production=# SELECT * from information_schema.foreign_tables; foreign_table_catalog | foreign_table_schema | foreign_table_name | foreign_server_catalog | foreign_server_name -------------------------+----------------------+-------------------------------------------------+-------------------------+--------------------- @@ -482,7 +558,7 @@ To check the configuration: 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 ]--------+------------------------------------------------------------ @@ -518,7 +594,7 @@ To check the configuration: 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 diff --git a/doc/administration/geo/replication/version_specific_updates.md b/doc/administration/geo/replication/version_specific_updates.md index 5288cc6e186..7ce38d80c88 100644 --- a/doc/administration/geo/replication/version_specific_updates.md +++ b/doc/administration/geo/replication/version_specific_updates.md @@ -357,7 +357,7 @@ is prepended with the relevant node for better clarity: 1. **(secondary)** Save the snippet below in a file, let's say `/tmp/replica.sh`. Modify the embedded paths if necessary: - ``` + ```bash #!/bin/bash PORT="5432" diff --git a/doc/administration/git_protocol.md b/doc/administration/git_protocol.md index c1742ff87a7..436f1a55369 100644 --- a/doc/administration/git_protocol.md +++ b/doc/administration/git_protocol.md @@ -37,10 +37,9 @@ service is already configured to accept the `GIT_PROTOCOL` environment and users need not do anything more. For Omnibus GitLab and installations from source, you have to manually update -the SSH configuration of your server: +the SSH configuration of your server by adding the line below to the `/etc/ssh/sshd_config` file: -``` -# /etc/ssh/sshd_config +```plaintext AcceptEnv GIT_PROTOCOL ``` @@ -69,7 +68,7 @@ GIT_TRACE_CURL=1 git -c protocol.version=2 ls-remote https://your-gitlab-instanc You should see that the `Git-Protocol` header is sent: -``` +```plaintext 16:29:44.577888 http.c:657 => Send header: Git-Protocol: version=2 ``` @@ -105,7 +104,7 @@ GIT_SSH_COMMAND="ssh -v" git -c protocol.version=2 ls-remote ssh://your-gitlab-i You should see that the `GIT_PROTOCOL` environment variable is sent: -``` +```plaintext debug1: Sending env GIT_PROTOCOL = version=2 ``` diff --git a/doc/administration/gitaly/img/architecture_v12_4.png b/doc/administration/gitaly/img/architecture_v12_4.png Binary files differindex 1054083bb28..6a3955a483b 100644 --- a/doc/administration/gitaly/img/architecture_v12_4.png +++ b/doc/administration/gitaly/img/architecture_v12_4.png diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 9218ffa4006..1aad0d80db4 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -38,19 +38,21 @@ This is an optional way to deploy Gitaly which can benefit GitLab installations that are larger than a single machine. Most installations will be better served with the default configuration used by Omnibus and the GitLab source installation guide. +Follow transition to Gitaly on its own server, [Gitaly servers will need to be upgraded before other servers in your cluster](https://docs.gitlab.com/omnibus/update/#upgrading-gitaly-servers). Starting with GitLab 11.4, Gitaly is able to serve all Git requests without requiring a shared NFS mount for Git repository data. Between 11.4 and 11.8 the exception was the [Elasticsearch indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). But since 11.8 the indexer uses Gitaly for data access as well. NFS can still -be leveraged for redudancy on block level of the Git data. But only has to +be leveraged for redundancy on block level of the Git data. But only has to be mounted on the Gitaly server. -Starting with GitLab 11.8, it is possible to use Elasticsearch in conjunction with +From GitLab v11.8 to v12.2, it is possible to use Elasticsearch in conjunction with a Gitaly setup that isn't utilising NFS. In order to use Elasticsearch in this -scenario, the [new repository indexer](../../integration/elasticsearch.md#elasticsearch-repository-indexer-beta) -needs to be enabled in your GitLab configuration. +scenario, the [new repository indexer](../../integration/elasticsearch.md#elasticsearch-repository-indexer) +needs to be enabled in your GitLab configuration. [Since GitLab v12.3](https://gitlab.com/gitlab-org/gitlab/issues/6481), +the new indexer becomes the default and no configuration is required. NOTE: **Note:** While Gitaly can be used as a replacement for NFS, it's not recommended to use EFS as it may impact GitLab's performance. Review the [relevant documentation](../high_availability/nfs.md#avoid-using-awss-elastic-file-system-efs) @@ -162,11 +164,21 @@ Git operations in GitLab will result in an API error. postgresql['enable'] = false redis['enable'] = false nginx['enable'] = false - prometheus['enable'] = false unicorn['enable'] = false sidekiq['enable'] = false gitlab_workhorse['enable'] = false + # If you don't want to run monitoring services uncomment the following (not recommended) + # alertmanager['enable'] = false + # gitlab_exporter['enable'] = false + # grafana['enable'] = false + # node_exporter['enable'] = false + # prometheus['enable'] = false + + # Enable prometheus monitoring - comment out if you disable monitoring services above. + # This makes Prometheus listen on all interfaces. You must use firewalls to restrict access to this address/port. + prometheus['listen_address'] = '0.0.0.0:9090' + # Prevent database connections during 'gitlab-ctl reconfigure' gitlab_rails['rake_cache_clear'] = false gitlab_rails['auto_migrate'] = false @@ -189,9 +201,14 @@ Git operations in GitLab will result in an API error. 1. Append the following to `/etc/gitlab/gitlab.rb` for each respective server: + <!-- + updates to following example must also be made at + https://gitlab.com/gitlab-org/charts/gitlab/blob/master/doc/advanced/external-gitaly/external-omnibus-gitaly.md#configure-omnibus-gitlab + --> + On `gitaly1.internal`: - ``` + ```ruby git_data_dirs({ 'default' => { 'path' => '/var/opt/gitlab/git-data' @@ -204,7 +221,7 @@ Git operations in GitLab will result in an API error. On `gitaly2.internal`: - ``` + ```ruby git_data_dirs({ 'storage2' => { 'path' => '/srv/gitlab/git-data' @@ -502,7 +519,7 @@ To configure Gitaly with TLS: To observe what type of connections are actually being used in a production environment you can use the following Prometheus query: -``` +```prometheus sum(rate(gitaly_connections_total[5m])) by (type) ``` @@ -559,14 +576,14 @@ a few things that you need to do: 1. Make sure the [`git` user home directory](https://docs.gitlab.com/omnibus/settings/configuration.html#moving-the-home-directory-for-a-user) is on local disk. 1. Configure [database lookup of SSH keys](../operations/fast_ssh_key_lookup.md) - to eliminate the need for a shared authorized_keys file. + to eliminate the need for a shared `authorized_keys` file. 1. Configure [object storage for job artifacts](../job_artifacts.md#using-object-storage) including [incremental logging](../job_logs.md#new-incremental-logging-architecture). 1. Configure [object storage for LFS objects](../lfs/lfs_administration.md#storing-lfs-objects-in-remote-object-storage). 1. Configure [object storage for uploads](../uploads.md#using-object-storage-core-only). -1. Configure [object storage for Merge Request Diffs](../merge_request_diffs.md#using-object-storage). -1. Configure [object storage for Packages](../packages/index.md#using-object-storage) (Optional Feature). -1. Configure [object storage for Dependency Proxy](../packages/dependency_proxy.md#using-object-storage) (Optional Feature). +1. Configure [object storage for merge request diffs](../merge_request_diffs.md#using-object-storage). +1. Configure [object storage for packages](../packages/index.md#using-object-storage) (optional feature). +1. Configure [object storage for dependency proxy](../packages/dependency_proxy.md#using-object-storage) (optional feature). NOTE: **Note:** One current feature of GitLab that still requires a shared directory (NFS) is @@ -601,7 +618,7 @@ This will limit the number of in-flight RPC calls for the given RPC's. The limit is applied per repository. In the example above, each on the Gitaly server can have at most 20 simultaneous PostUploadPack calls in flight, and the same for SSHUploadPack. If another request comes in for -a repository that hase used up its 20 slots, that request will get +a repository that has used up its 20 slots, that request will get queued. You can observe the behavior of this queue via the Gitaly logs and via @@ -631,14 +648,14 @@ machine. Use Prometheus to see what the current authentication behavior of your GitLab installation is. -``` +```prometheus sum(rate(gitaly_authentications_total[5m])) by (enforced, status) ``` In a system where authentication is configured correctly, and where you have live traffic, you will see something like this: -``` +```prometheus {enforced="true",status="ok"} 4424.985419441742 ``` @@ -667,7 +684,7 @@ gitaly['auth_transitioning'] = true After you have applied this, your Prometheus query should return something like this: -``` +```prometheus {enforced="false",status="would be ok"} 4424.985419441742 ``` @@ -713,7 +730,7 @@ gitaly['auth_transitioning'] = false Refresh your Prometheus query. You should now see the same kind of result as you did in the beginning: -``` +```prometheus {enforced="true",status="ok"} 4424.985419441742 ``` @@ -745,7 +762,7 @@ Git implementation itself. Because Rugged+Unicorn was so efficient, GitLab's application code ended up with lots of duplicate Git object lookups (like looking up the -`master` commmit a dozen times in one request). We could write +`master` commit a dozen times in one request). We could write inefficient code without being punished for it. When we migrated these Git lookups to Gitaly calls, we were suddenly @@ -853,14 +870,14 @@ gitaly-debug -h ### Commits, pushes, and clones return a 401 -``` +```plaintext remote: GitLab: 401 Unauthorized ``` You will need to sync your `gitlab-secrets.json` file with your GitLab app nodes. -### Client side GRPC logs +### Client side gRPC logs Gitaly uses the [gRPC](https://grpc.io/) RPC framework. The Ruby gRPC client has its own log file which may contain useful information when @@ -885,7 +902,7 @@ Assuming your `grpc_client_handled_total` counter only observes Gitaly, the following query shows you RPCs are (most likely) internally implemented as calls to `gitaly-ruby`: -``` +```prometheus sum(rate(grpc_client_handled_total[5m])) by (grpc_method) > 0 ``` @@ -910,7 +927,7 @@ Confirm the following are all true: ``` - When any user adds or modifies a file from the repository using the GitLab - UI, it immediatley fails with a red `401 Unauthorized` banner. + UI, it immediately fails with a red `401 Unauthorized` banner. - Creating a new project and [initializing it with a README](../../gitlab-basics/create-project.md#blank-projects) successfully creates the project but doesn't create the README. - When [tailing the logs](https://docs.gitlab.com/omnibus/settings/logs.html#tail-logs-in-a-console-on-the-server) on an app node and reproducing the error, you get `401` errors diff --git a/doc/administration/gitaly/praefect.md b/doc/administration/gitaly/praefect.md index 6193a40ac4f..72c3f996841 100644 --- a/doc/administration/gitaly/praefect.md +++ b/doc/administration/gitaly/praefect.md @@ -25,15 +25,22 @@ The most common architecture for Praefect is simplified in the diagram below: ```mermaid graph TB GitLab --> Praefect; - Praefect --> Gitaly-1; - Praefect --> Gitaly-2; - Praefect --> Gitaly-3; + Praefect --- PostgreSQL; + Praefect --> Gitaly1; + Praefect --> Gitaly2; + Praefect --> Gitaly3; ``` Where `GitLab` is the collection of clients that can request Git operations. -The Praefect node has threestorage nodes attached. Praefect itself doesn't +The Praefect node has three storage nodes attached. Praefect itself doesn't store data, but connects to three Gitaly nodes, `Gitaly-1`, `Gitaly-2`, and `Gitaly-3`. +In order to keep track of replication state, Praefect relies on a +PostgreSQL database. This database is a single point of failure so you +should use a highly available PostgreSQL server for this. GitLab +itself needs a HA PostgreSQL server too, so you could optionally co-locate the Praefect +SQL database on the PostgreSQL server you use for the rest of GitLab. + Praefect may be enabled on its own node or can be run on the GitLab server. In the example below we will use a separate server, but the optimal configuration for Praefect is still being determined. @@ -62,6 +69,53 @@ We need to manage the following secrets and make them match across hosts: `PRAEFECT_EXTERNAL_TOKEN` because Gitaly clients must not be able to access internal nodes of the Praefect cluster directly; that could lead to data loss. +1. `PRAEFECT_SQL_PASSWORD`: this password is used by Praefect to connect to + PostgreSQL. + +#### Network addresses + +1. `POSTGRESQL_SERVER`: the host name or IP address of your PostgreSQL server + +#### PostgreSQL + +To set up a Praefect cluster you need a highly available PostgreSQL +server. You need PostgreSQL 9.6 or newer. Praefect needs to have a SQL +user with the right to create databases. + +In the instructions below we assume you have administrative access to +your PostgreSQL server via `psql`. Depending on your environment, you +may also be able to do this via the web interface of your cloud +platform, or via your configuration management system, etc. + +Below we assume that you have administrative access as the `postgres` +user. First open a `psql` session as the `postgres` user: + +```shell +psql -h POSTGRESQL_SERVER -U postgres -d template1 +``` + +Once you are connected, run the following command. Replace +`PRAEFECT_SQL_PASSWORD` with the actual (random) password you +generated for the `praefect` SQL user: + +```sql +CREATE ROLE praefect WITH LOGIN CREATEDB PASSWORD 'PRAEFECT_SQL_PASSWORD'; +\q # exit psql +``` + +Now connect as the `praefect` user to create the database. This has +the side effect of verifying that you have access: + +```shell +psql -h POSTGRESQL_SERVER -U praefect -d template1 +``` + +Once you have connected as the `praefect` user, run: + +```sql +CREATE DATABASE praefect_production WITH ENCODING=UTF8; +\q # quit psql +``` #### Praefect @@ -118,10 +172,39 @@ praefect['virtual_storages'] = { } } } + +praefect['database_host'] = 'POSTGRESQL_SERVER' +praefect['database_port'] = 5432 +praefect['database_user'] = 'praefect' +praefect['database_password'] = 'PRAEFECT_SQL_PASSWORD' +praefect['database_dbname'] = 'praefect_production' + +# Uncomment the line below if you do not want to use an encrypted +# connection to PostgreSQL +# praefect['database_sslmode'] = 'disable' + +# Uncomment and modify these lines if you are using a TLS client +# certificate to connect to PostgreSQL +# praefect['database_sslcert'] = '/path/to/client-cert' +# praefect['database_sslkey'] = '/path/to/client-key' + +# Uncomment and modify this line if your PostgreSQL server uses a custom +# CA +# praefect['database_sslrootcert'] = '/path/to/rootcert' ``` Save the file and [reconfigure Praefect](../restart_gitlab.md#omnibus-gitlab-reconfigure). +After you reconfigure, verify that Praefect can reach PostgreSQL: + +```shell +sudo -u git /opt/gitlab/embedded/bin/praefect -config /var/opt/gitlab/praefect/config.toml sql-ping +``` + +If the check fails, make sure you have followed the steps correctly. If you edit `/etc/gitlab/gitlab.rb`, +remember to run `sudo gitlab-ctl reconfigure` again before trying the +`sql-ping` command. + #### Gitaly Next we will configure each Gitaly server assigned to Praefect. Configuration for these diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md index d411fb7f20f..13b6bd88453 100644 --- a/doc/administration/high_availability/README.md +++ b/doc/administration/high_availability/README.md @@ -224,14 +224,9 @@ users are, how much automation you use, mirroring, and repo/change size. - **Supported Users (approximate):** 2,000 - **Test RPS Rates:** API: 40 RPS, Web: 4 RPS, Git: 4 RPS -- **Status:** Work-in-progress - **Known Issues:** For the latest list of known performance issues head [here](https://gitlab.com/gitlab-org/gitlab/issues?label_name%5B%5D=Quality%3Aperformance-issues). -NOTE: **Note:** This architecture is a work-in-progress of the work so far. The -Quality team will be certifying this environment in late 2019 or early 2020. The specifications -may be adjusted prior to certification based on performance testing. - | Service | Nodes | Configuration | GCP type | | ----------------------------|-------|-----------------------|---------------| | GitLab Rails <br> - Puma workers on each node set to 90% of available CPUs with 8 threads | 3 | 8 vCPU, 7.2GB Memory | n1-highcpu-8 | @@ -255,14 +250,9 @@ vendors a best effort like for like can be used. - **Supported Users (approximate):** 5,000 - **Test RPS Rates:** API: 100 RPS, Web: 10 RPS, Git: 10 RPS -- **Status:** Work-in-progress - **Known Issues:** For the latest list of known performance issues head [here](https://gitlab.com/gitlab-org/gitlab/issues?label_name%5B%5D=Quality%3Aperformance-issues). -NOTE: **Note:** This architecture is a work-in-progress of the work so far. The -Quality team will be certifying this environment in late 2019 or early 2020. The specifications -may be adjusted prior to certification based on performance testing. - | Service | Nodes | Configuration | GCP type | | ----------------------------|-------|-----------------------|---------------| | GitLab Rails <br> - Puma workers on each node set to 90% of available CPUs with 16 threads | 3 | 16 vCPU, 14.4GB Memory | n1-highcpu-16 | diff --git a/doc/administration/high_availability/consul.md b/doc/administration/high_availability/consul.md index 392b9b76c31..71d380dbec7 100644 --- a/doc/administration/high_availability/consul.md +++ b/doc/administration/high_availability/consul.md @@ -64,7 +64,7 @@ command to verify all server nodes are communicating: The output should be similar to: -``` +```plaintext Node Address Status Type Build Protocol DC CONSUL_NODE_ONE XXX.XXX.XXX.YYY:8301 alive server 0.9.2 2 gitlab_consul CONSUL_NODE_TWO XXX.XXX.XXX.YYY:8301 alive server 0.9.2 2 gitlab_consul @@ -80,8 +80,8 @@ check the [Troubleshooting section](#troubleshooting) before proceeding. To see which nodes are part of the cluster, run the following on any member in the cluster -``` -# /opt/gitlab/embedded/bin/consul members +```shell +$ /opt/gitlab/embedded/bin/consul members Node Address Status Type Build Protocol DC consul-b XX.XX.X.Y:8301 alive server 0.9.0 2 gitlab_consul consul-c XX.XX.X.Y:8301 alive server 0.9.0 2 gitlab_consul @@ -100,7 +100,7 @@ If it is necessary to restart the server cluster, it is important to do this in To be safe, we recommend you only restart one server agent at a time to ensure the cluster remains intact. -For larger clusters, it is possible to restart multiple agents at a time. See the [Consul consensus document](https://www.consul.io/docs/internals/consensus.html#deployment-table) for how many failures it can tolerate. This will be the number of simulateneous restarts it can sustain. +For larger clusters, it is possible to restart multiple agents at a time. See the [Consul consensus document](https://www.consul.io/docs/internals/consensus.html#deployment-table) for how many failures it can tolerate. This will be the number of simultaneous restarts it can sustain. ## Upgrades for bundled Consul @@ -127,7 +127,7 @@ By default, the server agents will attempt to [bind](https://www.consul.io/docs/ You will see messages like the following in `gitlab-ctl tail consul` output if you are running into this issue: -``` +```plaintext 2017-09-25_19:53:39.90821 2017/09/25 19:53:39 [WARN] raft: no known peers, aborting election 2017-09-25_19:53:41.74356 2017/09/25 19:53:41 [ERR] agent: failed to sync remote state: No cluster leader ``` @@ -154,7 +154,7 @@ In the case that a node has multiple private IPs the agent be confused as to whi You will see messages like the following in `gitlab-ctl tail consul` output if you are running into this issue: -``` +```plaintext 2017-11-09_17:41:45.52876 ==> Starting Consul agent... 2017-11-09_17:41:45.53057 ==> Error creating agent: Failed to get advertise address: Multiple private IPs found. Please configure one. ``` @@ -181,10 +181,10 @@ If you lost enough server agents in the cluster to break quorum, then the cluste By default, GitLab does not store anything in the Consul cluster that cannot be recreated. To erase the Consul database and reinitialize -``` -# gitlab-ctl stop consul -# rm -rf /var/opt/gitlab/consul/data -# gitlab-ctl start consul +```shell +gitlab-ctl stop consul +rm -rf /var/opt/gitlab/consul/data +gitlab-ctl start consul ``` After this, the cluster should start back up, and the server agents rejoin. Shortly after that, the client agents should rejoin as well. diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index 02684f575d4..8e57b049730 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -229,7 +229,7 @@ available database connections. In this document we are assuming 3 database nodes, which makes this configuration: -``` +```ruby postgresql['max_wal_senders'] = 4 ``` @@ -352,7 +352,7 @@ When installing the GitLab package, do not supply `EXTERNAL_URL` value. to inform `gitlab-ctl` that they are standby nodes initially and it need not attempt to register them as primary node - ``` + ```ruby # HA setting to specify if a node should attempt to be master on initialization repmgr['master_on_initialization'] = false ``` @@ -396,7 +396,7 @@ Select one node as a primary node. The output should be similar to the following: - ``` + ```plaintext Role | Name | Upstream | Connection String ----------+----------|----------|---------------------------------------- * master | HOSTNAME | | host=HOSTNAME user=gitlab_repmgr dbname=gitlab_repmgr @@ -442,7 +442,7 @@ Select one node as a primary node. The output should be similar to the following: - ``` + ```plaintext Role | Name | Upstream | Connection String ----------+---------|-----------|------------------------------------------------ * master | MASTER | | host=MASTER_NODE_NAME user=gitlab_repmgr dbname=gitlab_repmgr @@ -463,7 +463,7 @@ gitlab-ctl repmgr cluster show The output should be similar to: -``` +```plaintext Role | Name | Upstream | Connection String ----------+--------------|--------------|-------------------------------------------------------------------- * master | MASTER | | host=MASTER port=5432 user=gitlab_repmgr dbname=gitlab_repmgr @@ -652,7 +652,7 @@ On secondary nodes, edit `/etc/gitlab/gitlab.rb` and add all the configuration added to primary node, noted above. In addition, append the following configuration: -``` +```ruby # HA setting to specify if a node should attempt to be master on initialization repmgr['master_on_initialization'] = false ``` @@ -706,7 +706,7 @@ After deploying the configuration follow these steps: gitlab-psql -d gitlabhq_production ``` - ``` + ```shell CREATE EXTENSION pg_trgm; ``` @@ -804,7 +804,7 @@ consul['configuration'] = { On secondary nodes, edit `/etc/gitlab/gitlab.rb` and add all the information added to primary node, noted above. In addition, append the following configuration -``` +```ruby # HA setting to specify if a node should attempt to be master on initialization repmgr['master_on_initialization'] = false ``` @@ -908,7 +908,7 @@ after it has been restored to service. It will output something like: - ``` + ```plaintext 959789412 ``` @@ -1052,7 +1052,7 @@ Now there should not be errors. If errors still occur then there is another prob You may get this error when running `gitlab-rake gitlab:db:configure` or you may see the error in the PgBouncer log file. -``` +```plaintext PG::ConnectionBad: ERROR: pgbouncer cannot connect to server ``` @@ -1063,13 +1063,13 @@ You can confirm that this is the issue by checking the PostgreSQL log on the mas database node. If you see the following error then `trust_auth_cidr_addresses` is the problem. -``` +```plaintext 2018-03-29_13:59:12.11776 FATAL: no pg_hba.conf entry for host "123.123.123.123", user "pgbouncer", database "gitlabhq_production", SSL off ``` To fix the problem, add the IP address to `/etc/gitlab/gitlab.rb`. -``` +```ruby postgresql['trust_auth_cidr_addresses'] = %w(123.123.123.123/32 <other_cidrs>) ``` diff --git a/doc/administration/high_availability/gitlab.md b/doc/administration/high_availability/gitlab.md index 71ab169a801..b4269cd4e38 100644 --- a/doc/administration/high_availability/gitlab.md +++ b/doc/administration/high_availability/gitlab.md @@ -11,7 +11,7 @@ these additional steps before proceeding with GitLab installation. 1. If necessary, install the NFS client utility packages using the following commands: - ``` + ```shell # Ubuntu/Debian apt-get install nfs-common @@ -24,7 +24,7 @@ these additional steps before proceeding with GitLab installation. to configure your NFS server. See [NFS documentation](nfs.md) for the various options. Here is an example snippet to add to `/etc/fstab`: - ``` + ```plaintext 10.1.0.1:/var/opt/gitlab/.ssh /var/opt/gitlab/.ssh nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2 10.1.0.1:/var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/uploads nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2 10.1.0.1:/var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-rails/shared nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2 @@ -35,7 +35,7 @@ these additional steps before proceeding with GitLab installation. 1. Create the shared directories. These may be different depending on your NFS mount locations. - ``` + ```shell mkdir -p /var/opt/gitlab/.ssh /var/opt/gitlab/gitlab-rails/uploads /var/opt/gitlab/gitlab-rails/shared /var/opt/gitlab/gitlab-ci/builds /var/opt/gitlab/git-data ``` diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index f7c5593e211..1d0dc420987 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -132,7 +132,7 @@ For supported database architecture, please see our documentation on Below is an example of an NFS mount point defined in `/etc/fstab` we use on GitLab.com: -``` +```plaintext 10.1.1.1:/var/opt/gitlab/git-data /var/opt/gitlab/git-data nfs4 defaults,soft,rsize=1048576,wsize=1048576,noatime,nofail,lookupcache=positive 0 2 ``` @@ -149,7 +149,7 @@ Note there are several options that you should consider using: It's recommended to nest all GitLab data dirs within a mount, that allows automatic restore of backups without manually moving existing data. -``` +```plaintext mountpoint └── gitlab-data ├── builds diff --git a/doc/administration/high_availability/pgbouncer.md b/doc/administration/high_availability/pgbouncer.md index 09b33c3554a..7b93159628d 100644 --- a/doc/administration/high_availability/pgbouncer.md +++ b/doc/administration/high_availability/pgbouncer.md @@ -83,7 +83,7 @@ In a HA setup, it's recommended to run a PgBouncer node separately for each data The output should be similar to the following: - ``` + ```plaintext name | host | port | database | force_user | pool_size | reserve_pool | pool_mode | max_connections | current_connections ---------------------+-------------+------+---------------------+------------+-----------+--------------+-----------+-----------------+--------------------- gitlabhq_production | MASTER_HOST | 5432 | gitlabhq_production | | 20 | 0 | | 0 | 0 @@ -102,7 +102,7 @@ If you're running more than one PgBouncer node as recommended, then at this time As an example here's how you could do it with [HAProxy](https://www.haproxy.org/): -``` +```plaintext global log /dev/log local0 log localhost local1 notice diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index 9b733034f5b..8e94b56a940 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -391,7 +391,7 @@ The prerequisites for a HA Redis setup are the following: prevent database migrations from running on upgrade, add the following configuration to your `/etc/gitlab/gitlab.rb` file: - ``` + ```ruby gitlab_rails['auto_migrate'] = false ``` @@ -439,7 +439,7 @@ The prerequisites for a HA Redis setup are the following: 1. To prevent reconfigure from running automatically on upgrade, run: - ``` + ```shell sudo touch /etc/gitlab/skip-auto-reconfigure ``` @@ -569,7 +569,7 @@ multiple machines with the Sentinel daemon. 1. To prevent database migrations from running on upgrade, run: - ``` + ```shell sudo touch /etc/gitlab/skip-auto-reconfigure ``` @@ -898,14 +898,14 @@ Before proceeding with the troubleshooting below, check your firewall rules: You can check if everything is correct by connecting to each server using `redis-cli` application, and sending the `info replication` command as below. -``` +```shell /opt/gitlab/embedded/bin/redis-cli -h <redis-host-or-ip> -a '<redis-password>' info replication ``` When connected to a `master` Redis, you will see the number of connected `slaves`, and a list of each with connection details: -``` +```plaintext # Replication role:master connected_slaves:1 @@ -920,7 +920,7 @@ repl_backlog_histlen:1048576 When it's a `slave`, you will see details of the master connection and if its `up` or `down`: -``` +```plaintext # Replication role:slave master_host:10.133.1.58 @@ -959,7 +959,7 @@ To make sure your configuration is correct: 1. SSH into your GitLab application server 1. Enter the Rails console: - ``` + ```shell # For Omnibus installations sudo gitlab-rails console @@ -985,7 +985,7 @@ To make sure your configuration is correct: 1. Then back in the Rails console from the first step, run: - ``` + ```ruby redis.info ``` diff --git a/doc/administration/housekeeping.md b/doc/administration/housekeeping.md index 9083619841e..ca3480f1146 100644 --- a/doc/administration/housekeeping.md +++ b/doc/administration/housekeeping.md @@ -5,14 +5,13 @@ ## Automatic housekeeping GitLab automatically runs `git gc` and `git repack` on repositories -after Git pushes. If needed you can change how often this happens, or -to turn it off, go to **Admin area > Settings** -(`/admin/application_settings`). +after Git pushes. You can change how often this happens or turn it off in +**Admin Area > Settings > Repository** (`/admin/application_settings/repository`). ## Manual housekeeping -The housekeeping function will run a `repack` or `gc` depending on the -"Automatic Git repository housekeeping" settings configured in **Admin area > Settings** +The housekeeping function runs `repack` or `gc` depending on the +**Housekeeping** settings configured in **Admin Area > Settings > Repository**. For example in the following scenario a `git repack -d` will be executed: diff --git a/doc/administration/img/repository_storages_admin_ui.png b/doc/administration/img/repository_storages_admin_ui.png Binary files differindex 315b4b0144c..51b2f5f8c15 100644 --- a/doc/administration/img/repository_storages_admin_ui.png +++ b/doc/administration/img/repository_storages_admin_ui.png diff --git a/doc/administration/incoming_email.md b/doc/administration/incoming_email.md index a0360f1d252..1550787d532 100644 --- a/doc/administration/incoming_email.md +++ b/doc/administration/incoming_email.md @@ -7,7 +7,7 @@ GitLab has several features based on receiving incoming emails: - [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/creating_merge_requests.md#create-new-merge-requests-by-email): +- [New merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only): allow GitLab users to create a new merge request by sending an email to a user-specific email address. - [Service Desk](../user/project/service_desk.md): provide e-mail support to @@ -79,7 +79,7 @@ email address in order to sign up. If you also host a public-facing GitLab instance at `hooli.com` and set your incoming email domain to `hooli.com`, an attacker could abuse the "Create new issue by email" or -"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email)" +"[Create new merge request by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only)" features by using a project's unique address as the email when signing up for Slack, which would send a confirmation email, which would create a new issue or merge request on the project owned by the attacker, allowing them to click the diff --git a/doc/administration/index.md b/doc/administration/index.md index 2a9980cddb3..8172acd09b4 100644 --- a/doc/administration/index.md +++ b/doc/administration/index.md @@ -119,7 +119,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [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/managing_issues.md#new-issue-via-email) and - [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#create-new-merge-requests-by-email), and to enable [Service Desk](../user/project/service_desk.md). + [merge requests by email](../user/project/merge_requests/creating_merge_requests.md#new-merge-request-by-email-core-only), 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 emails. @@ -200,6 +200,7 @@ Learn how to install, configure, update, and maintain your GitLab instance. - [Log system](logs.md): Where to look for logs. - [Sidekiq Troubleshooting](troubleshooting/sidekiq.md): Debug when Sidekiq appears hung and is not processing jobs. - [Troubleshooting Elasticsearch](troubleshooting/elasticsearch.md) +- [GitLab application limits](instance_limits.md) ### Support Team Docs diff --git a/doc/administration/instance_limits.md b/doc/administration/instance_limits.md new file mode 100644 index 00000000000..d68b825ed88 --- /dev/null +++ b/doc/administration/instance_limits.md @@ -0,0 +1,44 @@ +--- +type: reference +--- + +# GitLab application limits + +GitLab, like most large applications, enforces limits within certain features to maintain a +minimum quality of performance. Allowing some features to be limitless could affect security, +performance, data, or could even exhaust the allocated resources for the application. + +## Number of comments per issue, merge request or commit + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22388) in GitLab 12.4. + +There's a limit to the number of comments that can be submitted on an issue, +merge request, or commit. When the limit is reached, system notes can still be +added so that the history of events is not lost, but user-submitted comments +will fail. + +- **Max limit:** 5.000 comments + +## Number of pipelines per Git push + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/51401) in GitLab 11.10. + +The number of pipelines that can be created in a single push is 4. +This is to prevent the accidental creation of pipelines when `git push --all` +or `git push --mirror` is used. + +Read more in the [CI documentation](../ci/yaml/README.md#processing-git-pushes). + +## Retention of activity history + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/21164) in GitLab 8.12. + +Activity history for projects and individuals' profiles was limited to one year until [GitLab 11.4](https://gitlab.com/gitlab-org/gitlab-foss/issues/52246) when it was extended to two years, and in [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/33840) to three years. + +## Number of project webhooks + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/20730) in GitLab 12.6. + +A maximum number of project webhooks applies to each GitLab.com tier. Check the +[Maximum number of webhooks (per tier)](../user/project/integrations/webhooks.md#maximum-number-of-webhooks-per-tier) +section in the Webhooks page. diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 1af15648b97..42acc4cb80e 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -96,6 +96,6 @@ they will receive a `Connection failed` message. in GitLab 8.17. Terminal sessions use long-lived connections; by default, these may last -forever. You can configure a maximum session time in the Admin area of your +forever. You can configure a maximum session time in the Admin Area of your GitLab instance if you find this undesirable from a scalability or security point of view. diff --git a/doc/administration/job_artifacts.md b/doc/administration/job_artifacts.md index ec2f40700f5..7a3d116ea58 100644 --- a/doc/administration/job_artifacts.md +++ b/doc/administration/job_artifacts.md @@ -267,7 +267,7 @@ you can flip the feature flag from a Rails console. ## Set the maximum file size of the artifacts Provided the artifacts are enabled, you can change the maximum file size of the -artifacts through the [Admin area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only). +artifacts through the [Admin Area settings](../user/admin_area/settings/continuous_integration.md#maximum-artifacts-size-core-only). ## Storage statistics @@ -294,3 +294,149 @@ memory and disk I/O. [reconfigure gitlab]: restart_gitlab.md#omnibus-gitlab-reconfigure "How to reconfigure Omnibus GitLab" [restart gitlab]: restart_gitlab.md#installations-from-source "How to restart GitLab" [gitlab workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse "GitLab Workhorse repository" + +## Troubleshooting + +### Job artifacts using too much disk space + +Job artifacts can fill up your disk space quicker than expected. Some possible +reasons are: + +- Users have configured job artifacts expiration to be longer than necessary. +- The number of jobs run, and hence artifacts generated, is higher than expected. +- Job logs are larger than expected, and have accumulated over time. + +In these and other cases, you'll need to identify the projects most responsible +for disk space usage, figure out what types of artifacts are using the most +space, and in some cases, manually delete job artifacts to reclaim disk space. + +#### List projects by total size of job artifacts stored + +List the top 20 projects, sorted by the total size of job artifacts stored, by +running the following code in the Rails console (`sudo gitlab-rails console`): + +```ruby +include ActionView::Helpers::NumberHelper +ProjectStatistics.order(build_artifacts_size: :desc).limit(20).each do |s| + puts "#{number_to_human_size(s.build_artifacts_size)} \t #{s.project.full_path}" +end +``` + +You can change the number of projects listed by modifying `.limit(20)` to the +number you want. + +#### List largest artifacts in a single project + +List the 50 largest job artifacts in a single project by running the following +code in the Rails console (`sudo gitlab-rails console`): + +```ruby +include ActionView::Helpers::NumberHelper +project = Project.find_by_full_path('path/to/project') +Ci::JobArtifact.where(project: project).order(size: :desc).limit(50).map { |a| puts "ID: #{a.id} - #{a.file_type}: #{number_to_human_size(a.size)}" } +``` + +You can change the number of job artifacts listed by modifying `.limit(50)` to +the number you want. + +#### Delete job artifacts from jobs completed before a specific date + +CAUTION: **CAUTION:** +These commands remove data permanently from the database and from disk. We +highly recommend running them only under the guidance of a Support Engineer, or +running them in a test environment with a backup of the instance ready to be +restored, just in case. + +If you need to manually remove job artifacts associated with multiple jobs while +**retaining their job logs**, this can be done from the Rails console (`sudo gitlab-rails console`): + +1. Select jobs to be deleted: + + To select all jobs with artifacts for a single project: + + ```ruby + project = Project.find_by_full_path('path/to/project') + builds_with_artifacts = project.builds.with_artifacts_archive + ``` + + To select all jobs with artifacts across the entire GitLab instance: + + ```ruby + builds_with_artifacts = Ci::Build.with_artifacts_archive + ``` + +1. Delete job artifacts older than a specific date: + + NOTE: **NOTE:** + This step will also erase artifacts that users have chosen to + ["keep"](../user/project/pipelines/job_artifacts.html#browsing-artifacts). + + ```ruby + builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) + builds_to_clear.find_each do |build| + build.artifacts_expire_at = Time.now + build.erase_erasable_artifacts! + end + ``` + + `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new + date or time in the past. Other valid examples are: + + - `7.days.ago` + - `3.months.ago` + - `1.year.ago` + +#### Delete job artifacts and logs from jobs completed before a specific date + +CAUTION: **CAUTION:** +These commands remove data permanently from the database and from disk. We +highly recommend running them only under the guidance of a Support Engineer, or +running them in a test environment with a backup of the instance ready to be +restored, just in case. + +If you need to manually remove ALL job artifacts associated with multiple jobs, +**including job logs**, this can be done from the Rails console (`sudo gitlab-rails console`): + +1. Select jobs to be deleted: + + To select jobs with artifacts for a single project: + + ```ruby + project = Project.find_by_full_path('path/to/project') + builds_with_artifacts = project.builds.with_existing_job_artifacts + ``` + + To select jobs with artifacts across the entire GitLab instance: + + ```ruby + builds_with_artifacts = Ci::Build.with_existing_job_artifacts + ``` + +1. Select the user which will be mentioned in the web UI as erasing the job: + + ```ruby + admin_user = User.find_by(username: 'username') + ``` + +1. Erase job artifacts and logs older than a specific date: + + ```ruby + builds_to_clear = builds_with_artifacts.where("finished_at < ?", 1.week.ago) + builds_to_clear.find_each do |build| + print "Ci::Build ID #{build.id}... " + + if build.erasable? + build.erase(erased_by: admin_user) + puts "Erased" + else + puts "Skipped (Nothing to erase or not erasable)" + end + end + ``` + + `1.week.ago` is a Rails `ActiveSupport::Duration` method which calculates a new + date or time in the past. Other valid examples are: + + - `7.days.ago` + - `3.months.ago` + - `1.year.ago` diff --git a/doc/administration/job_logs.md b/doc/administration/job_logs.md index 6042786d101..fc37fbb170d 100644 --- a/doc/administration/job_logs.md +++ b/doc/administration/job_logs.md @@ -81,7 +81,7 @@ with one change: _the stored path of the first two phases is different_. This in log architecture stores chunks of logs in Redis and a persistent store (object storage or database) instead of file storage. Redis is used as first-class storage, and it stores up-to 128KB of data. Once the full chunk is sent, it is flushed to a persistent store, either object storage (temporary directory) or database. -After a while, the data in Redis and a persitent store will be archived to [object storage](#uploading-logs-to-object-storage). +After a while, the data in Redis and a persistent store will be archived to [object storage](#uploading-logs-to-object-storage). The data are stored in the following Redis namespace: `Gitlab::Redis::SharedState`. diff --git a/doc/administration/lfs/lfs_administration.md b/doc/administration/lfs/lfs_administration.md index f3b8029f487..fbf48619854 100644 --- a/doc/administration/lfs/lfs_administration.md +++ b/doc/administration/lfs/lfs_administration.md @@ -238,8 +238,8 @@ and [projects APIs](../../api/projects.md). ## Troubleshooting: `Google::Apis::TransmissionError: execution expired` -If LFS integration is configred with Google Cloud Storage and background uploads (`background_upload: true` and `direct_upload: false`), -Sidekiq workers may encouter this error. This is because the uploading timed out with very large files. +If LFS integration is configured with Google Cloud Storage and background uploads (`background_upload: true` and `direct_upload: false`), +Sidekiq workers may encounter this error. This is because the uploading timed out with very large files. LFS files up to 6Gb can be uploaded without any extra steps, otherwise you need to use the following workaround. ```shell diff --git a/doc/administration/logs.md b/doc/administration/logs.md index f4a1c754252..c69f787a5d8 100644 --- a/doc/administration/logs.md +++ b/doc/administration/logs.md @@ -96,7 +96,7 @@ request that have been performed and how much time it took. This task is more useful for GitLab contributors and developers. Use part of this log file when you are going to report bug. For example: -``` +```plaintext Started GET "/gitlabhq/yaml_db/tree/master" for 168.111.56.1 at 2015-02-12 19:34:53 +0200 Processing by Projects::TreeController#show as HTML Parameters: {"project_id"=>"gitlabhq/yaml_db", "id"=>"master"} @@ -151,7 +151,7 @@ installations from source. It helps you discover events happening in your instance such as user creation, project removing and so on. For example: -``` +```plaintext October 06, 2014 11:56: User "Administrator" (admin@example.com) was created October 06, 2014 11:56: Documentcloud created a new project "Documentcloud / Underscore" October 06, 2014 11:56: Gitlab Org created a new project "Gitlab Org / Gitlab Ce" @@ -167,7 +167,7 @@ installations from source. It contains information about [integrations](../user/project/integrations/project_services.md) activities such as Jira, Asana and Irker services. It uses JSON format like the example below: -``` json +```json {"severity":"ERROR","time":"2018-09-06T14:56:20.439Z","service_class":"JiraService","project_id":8,"project_path":"h5bp/html5-boilerplate","message":"Error sending message","client_url":"http://jira.gitlap.com:8080","error":"execution expired"} {"severity":"INFO","time":"2018-09-06T17:15:16.365Z","service_class":"JiraService","project_id":3,"project_path":"namespace2/project2","message":"Successfully posted","client_url":"http://jira.example.com"} ``` @@ -249,7 +249,7 @@ Instead of the format above, you can opt to generate JSON logs for Sidekiq. For example: ```json -{"severity":"INFO","time":"2018-04-03T22:57:22.071Z","queue":"cronjob:update_all_mirrors","args":[],"class":"UpdateAllMirrorsWorker","retry":false,"queue_namespace":"cronjob","jid":"06aeaa3b0aadacf9981f368e","created_at":"2018-04-03T22:57:21.930Z","enqueued_at":"2018-04-03T22:57:21.931Z","pid":10077,"message":"UpdateAllMirrorsWorker JID-06aeaa3b0aadacf9981f368e: done: 0.139 sec","job_status":"done","duration":0.139,"completed_at":"2018-04-03T22:57:22.071Z"} +{"severity":"INFO","time":"2018-04-03T22:57:22.071Z","queue":"cronjob:update_all_mirrors","args":[],"class":"UpdateAllMirrorsWorker","retry":false,"queue_namespace":"cronjob","jid":"06aeaa3b0aadacf9981f368e","created_at":"2018-04-03T22:57:21.930Z","enqueued_at":"2018-04-03T22:57:21.931Z","pid":10077,"message":"UpdateAllMirrorsWorker JID-06aeaa3b0aadacf9981f368e: done: 0.139 sec","job_status":"done","duration":0.139,"completed_at":"2018-04-03T22:57:22.071Z","db_duration":0.05,"db_duration_s":0.0005,"gitaly_duration":0,"gitaly_calls":0} ``` For Omnibus GitLab installations, add the configuration option: @@ -276,7 +276,7 @@ installations from source. GitLab Shell is used by GitLab for executing Git commands and provide SSH access to Git repositories. For example: -``` +```plaintext I, [2015-02-13T06:17:00.671315 #9291] INFO -- : Adding project root/example.git at </var/opt/gitlab/git-data/repositories/root/dcdcdcdcd.git>. I, [2015-02-13T06:17:00.679433 #9291] INFO -- : Moving existing hooks directory and symlinking global hooks directory for /var/opt/gitlab/git-data/repositories/root/example.git. ``` @@ -294,7 +294,7 @@ serving the GitLab application. You can look at this log if, for example, your application does not respond. This log contains all information about the state of Unicorn processes at any given time. -``` +```plaintext I, [2015-02-13T06:14:46.680381 #9047] INFO -- : Refreshing Gem list I, [2015-02-13T06:14:56.931002 #9047] INFO -- : listening on addr=127.0.0.1:8080 fd=12 I, [2015-02-13T06:14:56.931381 #9047] INFO -- : listening on addr=/var/opt/gitlab/gitlab-rails/sockets/gitlab.socket fd=13 @@ -421,6 +421,47 @@ etc. For example: {"severity":"DEBUG","time":"2019-10-17T06:23:13.227Z","correlation_id":null,"message":"redacted_search_result","class_name":"Milestone","id":2,"ability":"read_milestone","current_user_id":2,"query":"project"} ``` +## `exceptions_json.log` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/17819) in GitLab 12.6. + +This file lives in +`/var/log/gitlab/gitlab-rails/exceptions_json.log` for Omnibus GitLab +packages or in `/home/git/gitlab/log/exceptions_json.log` for installations +from source. + +It logs the information about exceptions being tracked by `Gitlab::ErrorTracking` which provides standard and consistent way of [processing rescued exceptions](https://gitlab.com/gitlab-org/gitlab/blob/master/doc/development/logging.md#exception-handling). + +Each line contains a JSON line that can be ingested by Elasticsearch. For example: + +```json +{ + "severity": "ERROR", + "time": "2019-12-17T11:49:29.485Z", + "correlation_id": "AbDVUrrTvM1", + "extra.server": { + "os": { + "name": "Darwin", + "version": "Darwin Kernel Version 19.2.0", + "build": "19.2.0", + }, + "runtime": { + "name": "ruby", + "version": "ruby 2.6.5p114 (2019-10-01 revision 67812) [x86_64-darwin18]" + } + }, + "extra.project_id": 55, + "extra.relation_key": "milestones", + "extra.relation_index": 1, + "exception.class": "NoMethodError", + "exception.message": "undefined method `strong_memoize' for #<Gitlab::ImportExport::RelationFactory:0x00007fb5d917c4b0>", + "exception.backtrace": [ + "lib/gitlab/import_export/relation_factory.rb:329:in `unique_relation?'", + "lib/gitlab/import_export/relation_factory.rb:345:in `find_or_create_object!'" + ] +} +``` + [repocheck]: repository_checks.md [Rack Attack]: ../security/rack_attack.md [Rate Limit]: ../user/admin_area/settings/rate_limits_on_raw_endpoints.md diff --git a/doc/administration/monitoring/gitlab_instance_administration_project/index.md b/doc/administration/monitoring/gitlab_instance_administration_project/index.md index b07bbafaf7d..8675521ddb1 100644 --- a/doc/administration/monitoring/gitlab_instance_administration_project/index.md +++ b/doc/administration/monitoring/gitlab_instance_administration_project/index.md @@ -1,7 +1,9 @@ # GitLab instance administration project NOTE: **Note:** -This feature is not yet available and is [planned for 12.6](https://gitlab.com/gitlab-org/gitlab/issues/32351). +This feature is available behind a feature flag called `self_monitoring_project` +since [12.7](https://gitlab.com/gitlab-org/gitlab/issues/32351). The feature flag +will be removed once we [add dashboards to display metrics](https://gitlab.com/groups/gitlab-org/-/epics/2367). GitLab has been adding the ability for administrators to see insights into the health of their GitLab instance. In order to surface this experience in a native way, similar to how diff --git a/doc/administration/monitoring/performance/gitlab_configuration.md b/doc/administration/monitoring/performance/gitlab_configuration.md index 9a25cc04ee7..1bff170768a 100644 --- a/doc/administration/monitoring/performance/gitlab_configuration.md +++ b/doc/administration/monitoring/performance/gitlab_configuration.md @@ -1,8 +1,12 @@ # GitLab Configuration +CAUTION: **InfluxDB is deprecated in favor of Prometheus:** +InfluxDB support is scheduled to be removed in GitLab 13.0. +You are advised to use [Prometheus](../prometheus/index.md) instead. + GitLab Performance Monitoring is disabled by default. To enable it and change any of its -settings, navigate to the Admin area in **Settings > Metrics** -(`/admin/application_settings`). +settings, navigate to **Admin Area > Settings > Metrics and profiling** +(`/admin/application_settings/metrics_and_profiling`). The minimum required settings you need to set are the InfluxDB host and port. Make sure _Enable InfluxDB Metrics_ is checked and hit **Save** to save the @@ -28,7 +32,7 @@ have been performed. Read more on: -- [Introduction to GitLab Performance Monitoring](introduction.md) +- [Introduction to GitLab Performance Monitoring](index.md) - [InfluxDB Configuration](influxdb_configuration.md) - [InfluxDB Schema](influxdb_schema.md) - [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/administration/monitoring/performance/grafana_configuration.md b/doc/administration/monitoring/performance/grafana_configuration.md index ccba0a55479..2fbbeb0b774 100644 --- a/doc/administration/monitoring/performance/grafana_configuration.md +++ b/doc/administration/monitoring/performance/grafana_configuration.md @@ -1,5 +1,9 @@ # Grafana Configuration +CAUTION: **InfluxDB is deprecated in favor of Prometheus:** +InfluxDB support is scheduled to be removed in GitLab 13.0. +You are advised to use [Prometheus](../prometheus/index.md) instead. + [Grafana](https://grafana.com/) is a tool that allows you to visualize time series metrics through graphs and dashboards. It supports several backend data stores, including InfluxDB. GitLab writes performance data to InfluxDB @@ -53,14 +57,14 @@ repository. To use this repository you must first clone it: -``` +```shell git clone https://gitlab.com/gitlab-org/influxdb-management.git cd influxdb-management ``` Next you must install the required dependencies: -``` +```shell gem install bundler bundle install ``` @@ -109,14 +113,14 @@ repository for more information on this process. 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. Go to the **Admin Area > Settings > Metrics and profiling**. +1. 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**. +1. The new link will be available in the **Admin Area > Monitoring > Metrics Dashboard**. ## Security Update @@ -135,7 +139,7 @@ echo "0" > /var/opt/gitlab/grafana/CVE_reset_status To reinstate your old data, move it back into its original location: -``` +```shell sudo mv /var/opt/gitlab/grafana/data.bak.xxxx/ /var/opt/gitlab/grafana/data/ ``` @@ -152,7 +156,7 @@ For more information and further mitigation details, please refer to our [blog p Read more on: -- [Introduction to GitLab Performance Monitoring](introduction.md) +- [Introduction to GitLab Performance Monitoring](index.md) - [GitLab Configuration](gitlab_configuration.md) - [InfluxDB Installation/Configuration](influxdb_configuration.md) - [InfluxDB Schema](influxdb_schema.md) diff --git a/doc/administration/monitoring/performance/img/performance_bar.png b/doc/administration/monitoring/performance/img/performance_bar.png Binary files differindex d206d5a4268..be06e0b2f94 100644 --- a/doc/administration/monitoring/performance/img/performance_bar.png +++ b/doc/administration/monitoring/performance/img/performance_bar.png diff --git a/doc/administration/monitoring/performance/img/performance_bar_frontend.png b/doc/administration/monitoring/performance/img/performance_bar_frontend.png Binary files differindex 489f855fe33..32a241e032b 100644 --- a/doc/administration/monitoring/performance/img/performance_bar_frontend.png +++ b/doc/administration/monitoring/performance/img/performance_bar_frontend.png diff --git a/doc/administration/monitoring/performance/img/performance_bar_gitaly_threshold.png b/doc/administration/monitoring/performance/img/performance_bar_gitaly_threshold.png Binary files differindex d4bf5c69ffa..4e42d904cdf 100644 --- a/doc/administration/monitoring/performance/img/performance_bar_gitaly_threshold.png +++ b/doc/administration/monitoring/performance/img/performance_bar_gitaly_threshold.png diff --git a/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning.png b/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning.png Binary files differindex 966549554a4..74711387ffe 100644 --- a/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning.png +++ b/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning.png diff --git a/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning_expanded.png b/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning_expanded.png Binary files differindex 3362186bb48..36553f513e1 100644 --- a/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning_expanded.png +++ b/doc/administration/monitoring/performance/img/performance_bar_request_selector_warning_expanded.png diff --git a/doc/administration/monitoring/performance/index.md b/doc/administration/monitoring/performance/index.md index 5204ab40dc9..6569f6a8c6d 100644 --- a/doc/administration/monitoring/performance/index.md +++ b/doc/administration/monitoring/performance/index.md @@ -1,5 +1,9 @@ # GitLab Performance Monitoring +CAUTION: **InfluxDB is deprecated in favor of Prometheus:** +InfluxDB support is scheduled to be removed in GitLab 13.0. +You are advised to use [Prometheus](../prometheus/index.md) instead. + GitLab comes with its own application performance measuring system as of GitLab 8.4, simply called "GitLab Performance Monitoring". GitLab Performance Monitoring is available in both the Community and Enterprise editions. diff --git a/doc/administration/monitoring/performance/influxdb_configuration.md b/doc/administration/monitoring/performance/influxdb_configuration.md index f1f588a924d..b18be09ef4b 100644 --- a/doc/administration/monitoring/performance/influxdb_configuration.md +++ b/doc/administration/monitoring/performance/influxdb_configuration.md @@ -1,5 +1,9 @@ # InfluxDB Configuration +CAUTION: **InfluxDB is deprecated in favor of Prometheus:** +InfluxDB support is scheduled to be removed in GitLab 13.0. +You are advised to use [Prometheus](../prometheus/index.md) instead. + The default settings provided by [InfluxDB] are not sufficient for a high traffic GitLab environment. The settings discussed in this document are based on the settings GitLab uses for GitLab.com, depending on your own needs you may need to @@ -44,7 +48,7 @@ upcoming InfluxDB releases. Make sure you have the following in your configuration file: -``` +```toml [data] dir = "/var/lib/influxdb/data" engine = "tsm1" @@ -56,7 +60,7 @@ Production environments should have the InfluxDB admin panel **disabled**. This feature can be disabled by adding the following to your InfluxDB configuration file: -``` +```toml [admin] enabled = false ``` @@ -67,7 +71,7 @@ HTTP is required when using the [InfluxDB CLI] or other tools such as Grafana, thus it should be enabled. When enabling make sure to _also_ enable authentication: -``` +```toml [http] enabled = true auth-enabled = true @@ -81,7 +85,7 @@ admin user](#create-a-new-admin-user)._ GitLab writes data to InfluxDB via UDP and thus this must be enabled. Enabling UDP can be done using the following settings: -``` +```toml [[udp]] enabled = true bind-address = ":8089" @@ -134,7 +138,7 @@ allowing traffic from members of said VLAN. If you want to [enable authentication](#http), you might want to [create an admin user][influx-admin]: -``` +```shell influx -execute "CREATE USER jeff WITH PASSWORD '1234' WITH ALL PRIVILEGES" ``` @@ -164,7 +168,7 @@ influx -execute 'SHOW DATABASES' The output should be similar to: -``` +```plaintext name: databases --------------- name @@ -178,7 +182,7 @@ That's it! Now your GitLab instance should send data to InfluxDB. Read more on: -- [Introduction to GitLab Performance Monitoring](introduction.md) +- [Introduction to GitLab Performance Monitoring](index.md) - [GitLab Configuration](gitlab_configuration.md) - [InfluxDB Schema](influxdb_schema.md) - [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/administration/monitoring/performance/influxdb_schema.md b/doc/administration/monitoring/performance/influxdb_schema.md index eff0e29f58d..adbccdaaeb8 100644 --- a/doc/administration/monitoring/performance/influxdb_schema.md +++ b/doc/administration/monitoring/performance/influxdb_schema.md @@ -1,5 +1,9 @@ # InfluxDB Schema +CAUTION: **InfluxDB is deprecated in favor of Prometheus:** +InfluxDB support is scheduled to be removed in GitLab 13.0. +You are advised to use [Prometheus](../prometheus/index.md) instead. + The following measurements are currently stored in InfluxDB: - `PROCESS_file_descriptors` @@ -39,7 +43,7 @@ while the method name is stored in the tag `method`. The tag `action` contains the full name of the transaction action. Both the `method` and `action` fields are in the following format: -``` +```plaintext ClassName#method_name ``` @@ -91,7 +95,7 @@ Depending on the event type additional tags may be available as well. Read more on: -- [Introduction to GitLab Performance Monitoring](introduction.md) +- [Introduction to GitLab Performance Monitoring](index.md) - [GitLab Configuration](gitlab_configuration.md) - [InfluxDB Configuration](influxdb_configuration.md) - [Grafana Install/Configuration](grafana_configuration.md) diff --git a/doc/administration/monitoring/performance/performance_bar.md b/doc/administration/monitoring/performance/performance_bar.md index 98c611ea140..fe4c29fbb01 100644 --- a/doc/administration/monitoring/performance/performance_bar.md +++ b/doc/administration/monitoring/performance/performance_bar.md @@ -52,8 +52,9 @@ And requests with warnings are indicated in the request selector with a ## Enable the Performance Bar via the Admin panel GitLab Performance Bar is disabled by default. To enable it for a given group, -navigate to the Admin area in **Settings > Metrics and Profiling > Profiling - Performance bar** -(`admin/application_settings/metrics_and_profiling`). +navigate to **Admin Area > Settings > Metrics and profiling** +(`admin/application_settings/metrics_and_profiling`), and expand the section +**Profiling - Performance bar**. The only required setting you need to set is the full path of the group that will be allowed to display the Performance Bar. diff --git a/doc/administration/monitoring/prometheus/gitlab_metrics.md b/doc/administration/monitoring/prometheus/gitlab_metrics.md index 57048059476..f3da5a6dd2f 100644 --- a/doc/administration/monitoring/prometheus/gitlab_metrics.md +++ b/doc/administration/monitoring/prometheus/gitlab_metrics.md @@ -6,8 +6,8 @@ installations from source you'll have to configure it yourself. To enable the GitLab Prometheus metrics: -1. Log into GitLab as an administrator, and go to the Admin area. -1. Navigate to GitLab's **Settings > Metrics and profiling**. +1. Log into GitLab as an administrator. +1. Navigate to **Admin Area > Settings > Metrics and profiling**. 1. Find the **Metrics - Prometheus** section, and click **Enable Prometheus Metrics**. 1. [Restart GitLab](../../restart_gitlab.md#omnibus-gitlab-restart) for the changes to take effect. @@ -26,7 +26,7 @@ The following metrics are available: | Metric | Type | Since | Description | Labels | |:---------------------------------------------------------------|:----------|-----------------------:|:----------------------------------------------------------------------------------------------------|:----------------------------------------------------| | `gitlab_banzai_cached_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached output exists | controller, action | -| `gitlab_banzai_cacheless_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached outupt does not exist | controller, action | +| `gitlab_banzai_cacheless_render_real_duration_seconds` | Histogram | 9.4 | Duration of rendering Markdown into HTML when cached output does not exist | controller, action | | `gitlab_cache_misses_total` | Counter | 10.2 | Cache read miss | controller, action | | `gitlab_cache_operation_duration_seconds` | Histogram | 10.2 | Cache access time | | | `gitlab_cache_operations_total` | Counter | 12.2 | Cache operations by controller/action | controller, action, operation | @@ -59,7 +59,7 @@ The following metrics are available: | `gitlab_transaction_event_push_commit_total` | Counter | 9.4 | Counter for commits | branch | | `gitlab_transaction_event_push_tag_total` | Counter | 9.4 | Counter for tag pushes | | | `gitlab_transaction_event_rails_exception_total` | Counter | 9.4 | Counter for number of rails exceptions | | -| `gitlab_transaction_event_receive_email_total` | Counter | 9.4 | Counter for recieved emails | handler | +| `gitlab_transaction_event_receive_email_total` | Counter | 9.4 | Counter for received emails | handler | | `gitlab_transaction_event_remote_mirrors_failed_total` | Counter | 10.8 | Counter for failed remote mirrors | | | `gitlab_transaction_event_remote_mirrors_finished_total` | Counter | 10.8 | Counter for finished remote mirrors | | | `gitlab_transaction_event_remote_mirrors_running_total` | Counter | 10.8 | Counter for running remote mirrors | | @@ -154,10 +154,10 @@ Some basic Ruby runtime metrics are available: | `ruby_sampler_duration_seconds` | Counter | 11.1 | Time spent collecting stats | | `ruby_process_cpu_seconds_total` | Gauge | 12.0 | Total amount of CPU time per process | | `ruby_process_max_fds` | Gauge | 12.0 | Maximum number of open file descriptors per process | -| `ruby_process_resident_memory_bytes` | Gauge | 12.0 | Memory usage by process, measured in bytes | +| `ruby_process_resident_memory_bytes` | Gauge | 12.0 | Memory usage by process | | `ruby_process_start_time_seconds` | Gauge | 12.0 | UNIX timestamp of process start time | -[GC.stat]: https://ruby-doc.org/core-2.6.3/GC.html#method-c-stat +[GC.stat]: https://ruby-doc.org/core-2.6.5/GC.html#method-c-stat ## Unicorn Metrics diff --git a/doc/administration/monitoring/prometheus/index.md b/doc/administration/monitoring/prometheus/index.md index eb7a2d791c1..62bacf9791e 100644 --- a/doc/administration/monitoring/prometheus/index.md +++ b/doc/administration/monitoring/prometheus/index.md @@ -245,7 +245,7 @@ To add a Prometheus dashboard for a single server GitLab setup: 1. Create a new data source in Grafana. 1. Name your data source i.e GitLab. -1. Select `Prometheus` in the type drop down. +1. Select `Prometheus` in the type dropdown box. 1. Add your Prometheus listen address as the URL and set access to `Browser`. 1. Set the HTTP method to `GET`. 1. Save & Test your configuration to verify that it works. diff --git a/doc/administration/operations/cleaning_up_redis_sessions.md b/doc/administration/operations/cleaning_up_redis_sessions.md index fd469ae23e3..38fac8a0eca 100644 --- a/doc/administration/operations/cleaning_up_redis_sessions.md +++ b/doc/administration/operations/cleaning_up_redis_sessions.md @@ -22,7 +22,7 @@ settings outlined in First we define a shell function with the proper Redis connection details. -``` +```shell rcli() { # This example works for Omnibus installations of GitLab 7.3 or newer. For an # installation from source you will have to change the socket path and the @@ -37,7 +37,7 @@ rcli ping Now we do a search to see if there are any session keys in the old format for us to clean up. -``` +```shell # returns the number of old-format session keys in Redis rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l ``` @@ -45,7 +45,7 @@ rcli keys '*' | grep '^[a-f0-9]\{32\}$' | wc -l If the number is larger than zero, you can proceed to expire the keys from Redis. If the number is zero there is nothing to clean up. -``` +```shell # Tell Redis to expire each matched key after 600 seconds. rcli keys '*' | grep '^[a-f0-9]\{32\}$' | awk '{ print "expire", $0, 600 }' | rcli # This will print '(integer) 1' for each key that gets expired. diff --git a/doc/administration/operations/extra_sidekiq_processes.md b/doc/administration/operations/extra_sidekiq_processes.md index e15f91ebab2..1be89f759da 100644 --- a/doc/administration/operations/extra_sidekiq_processes.md +++ b/doc/administration/operations/extra_sidekiq_processes.md @@ -59,8 +59,8 @@ To start extra Sidekiq processes, you must enable `sidekiq-cluster`: sudo gitlab-ctl reconfigure ``` -Once the extra Sidekiq processes are added, you can visit the "Background Jobs" -section under the admin area in GitLab (`/admin/background_jobs`). +Once the extra Sidekiq processes are added, you can visit the +**Admin Area > Monitoring > Background Jobs** (`/admin/background_jobs`) in GitLab.  diff --git a/doc/administration/operations/fast_ssh_key_lookup.md b/doc/administration/operations/fast_ssh_key_lookup.md index 9a38e8ddd23..96571b0a5d9 100644 --- a/doc/administration/operations/fast_ssh_key_lookup.md +++ b/doc/administration/operations/fast_ssh_key_lookup.md @@ -53,7 +53,7 @@ Add the following to your `sshd_config` file. This is usually located at `/etc/ssh/sshd_config`, but it will be `/assets/sshd_config` if you're using Omnibus Docker: -``` +```plaintext AuthorizedKeysCommand /opt/gitlab/embedded/service/gitlab-shell/bin/gitlab-shell-authorized-keys-check git %u %k AuthorizedKeysCommandUser git ``` @@ -117,7 +117,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: 1. First, download the package and install the required packages: - ``` + ```shell sudo su - cd /tmp curl --remote-name https://mirrors.evowise.com/pub/OpenBSD/OpenSSH/portable/openssh-7.5p1.tar.gz @@ -127,7 +127,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: 1. Prepare the build by copying files to the right place: - ``` + ```shell mkdir -p /root/rpmbuild/{SOURCES,SPECS} cp ./openssh-7.5p1/contrib/redhat/openssh.spec /root/rpmbuild/SPECS/ cp openssh-7.5p1.tar.gz /root/rpmbuild/SOURCES/ @@ -136,7 +136,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: 1. Next, set the spec settings properly: - ``` + ```shell sed -i -e "s/%define no_gnome_askpass 0/%define no_gnome_askpass 1/g" openssh.spec sed -i -e "s/%define no_x11_askpass 0/%define no_x11_askpass 1/g" openssh.spec sed -i -e "s/BuildPreReq/BuildRequires/g" openssh.spec @@ -144,19 +144,19 @@ the database. The following instructions can be used to build OpenSSH 7.5: 1. Build the RPMs: - ``` + ```shell rpmbuild -bb openssh.spec ``` 1. Ensure the RPMs were built: - ``` + ```shell ls -al /root/rpmbuild/RPMS/x86_64/ ``` You should see something as the following: - ``` + ```plaintext total 1324 drwxr-xr-x. 2 root root 4096 Jun 20 19:37 . drwxr-xr-x. 3 root root 19 Jun 20 19:37 .. @@ -170,7 +170,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: with its own version, which may prevent users from logging in, so be sure that the file is backed up and restored after installation: - ``` + ```shell timestamp=$(date +%s) cp /etc/pam.d/sshd pam-ssh-conf-$timestamp rpm -Uvh /root/rpmbuild/RPMS/x86_64/*.rpm @@ -179,7 +179,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: 1. Verify the installed version. In another window, attempt to login to the server: - ``` + ```shell ssh -v <your-centos-machine> ``` @@ -191,7 +191,7 @@ the database. The following instructions can be used to build OpenSSH 7.5: sure everything is working! If you need to downgrade, simple install the older package: - ``` + ```shell # Only run this if you run into a problem logging in yum downgrade openssh-server openssh openssh-clients ``` diff --git a/doc/administration/operations/puma.md b/doc/administration/operations/puma.md new file mode 100644 index 00000000000..2490cf1f0ae --- /dev/null +++ b/doc/administration/operations/puma.md @@ -0,0 +1,46 @@ +# Switching to Puma + +## Puma + +GitLab plans to use [Puma](https://github.com/puma/puma) to replace +[Unicorn](https://bogomips.org/unicorn/). + +## Why switch to Puma? + +Puma has a multi-thread architecture which uses less memory than a multi-process +application server like Unicorn. + +Most Rails applications requests normally include a proportion of I/O wait time. +During I/O wait time MRI Ruby will release the GVL (Global VM Lock) to other threads. +Multi-threaded Puma can therefore still serve more requests than a single process. + +## Performance caveat when using Puma with Rugged + +For deployments where NFS is used to store Git repository, we allow GitLab to use +[Direct Git Access](../gitaly/#direct-git-access-in-gitlab-rails) to improve performance via usage of [Rugged](https://github.com/libgit2/rugged). + +Rugged usage is automatically enabled if Direct Git Access is present, unless it +is disabled by [feature flags](../../development/gitaly.md#legacy-rugged-code). + +MRI Ruby uses a GVL. This allows MRI Ruby to be multi-threaded, but running at +most on a single core. Since Rugged can use a thread for long periods of +time (due to intensive I/O operations of Git access), this can starve other threads +that might be processing requests. This is not a case for Unicorn or Puma running +in a single thread mode, as concurrently at most one request is being processed. + +We are actively working on removing Rugged usage. Even though performance without Rugged +is acceptable today, in some cases it might be still beneficial to run with it. + +Given the caveat of running Rugged with multi-threaded Puma, and acceptable +performance of Gitaly, we are disabling Rugged usage if Puma multi-threaded is +used (when Puma is configured to run with more than one thread). + +This default behavior may not be the optimal configuration in some situations. If Rugged +plays an important role in your deployment, we suggest you benchmark to find the +optimal configuration: + +- The safest option is to start with single-threaded Puma. When working with +Rugged, single-threaded Puma does work the same as Unicorn. + +- To force Rugged auto detect with multi-threaded Puma, you can use [feature +flags](../../development/gitaly.md#legacy-rugged-code). diff --git a/doc/administration/packages/container_registry.md b/doc/administration/packages/container_registry.md index e735d8dd97e..6ef1a3ec607 100644 --- a/doc/administration/packages/container_registry.md +++ b/doc/administration/packages/container_registry.md @@ -98,7 +98,7 @@ There are two ways you can configure the Registry's external domain. Either: for that domain. Since the container Registry requires a TLS certificate, in the end it all boils -down to how easy or pricey is to get a new one. +down to how easy or pricey it is to get a new one. Please take this into consideration before configuring the Container Registry for the first time. @@ -398,6 +398,9 @@ To configure the `s3` storage driver in Omnibus: 1. Save the file and [reconfigure GitLab](../restart_gitlab.md#omnibus-gitlab-reconfigure) for the changes to take effect. +NOTE: **Note:** +`your-s3-bucket` should only be the name of a bucket that exists, and can't include subdirectories. + **Installations from source** Configuring the storage driver is done in your registry config YML file created @@ -408,9 +411,9 @@ when you [deployed your docker registry](https://docs.docker.com/registry/deploy ```yml storage: s3: - accesskey: 'AKIAKIAKI' - secretkey: 'secret123' - bucket: 'gitlab-registry-bucket-AKIAKIAKI' + accesskey: 's3-access-key' + secretkey: 's3-secret-key-for-access-key' + bucket: 'your-s3-bucket' region: 'your-s3-region' regionendpoint: 'your-s3-regionendpoint' cache: @@ -419,6 +422,9 @@ storage: enabled: true ``` +NOTE: **Note:** +`your-s3-bucket` should only be the name of a bucket that exists, and can't include subdirectories. + ## Change the registry's internal port NOTE: **Note:** @@ -625,13 +631,36 @@ mounting the docker-daemon and setting `privileged = false` in the Runner's ```toml [runners.docker] - image = "ruby:2.1" + image = "ruby:2.6" privileged = false volumes = ["/var/run/docker.sock:/var/run/docker.sock", "/cache"] ``` Additional information about this: [issue 18239](https://gitlab.com/gitlab-org/gitlab-foss/issues/18239). +### `unauthorized: authentication required` when pushing large images + +Example error: + +```shell +docker push gitlab.example.com/myproject/docs:latest +The push refers to a repository [gitlab.example.com/myproject/docs] +630816f32edb: Preparing +530d5553aec8: Preparing +... +4b0bab9ff599: Waiting +d1c800db26c7: Waiting +42755cf4ee95: Waiting +unauthorized: authentication required +``` + +GitLab has a default token expiration of 5 minutes for the registry. When pushing +larger images, or images that take longer than 5 minutes to push, users may +encounter this error. + +Administrators can increase the token duration in **Admin area > Settings > +Container Registry > Authorization token duration (minutes)**. + ### AWS S3 with the GitLab registry error when pushing large images When using AWS S3 with the GitLab registry, an error may occur when pushing diff --git a/doc/administration/packages/index.md b/doc/administration/packages/index.md index 58dd8201c15..432e72e03e3 100644 --- a/doc/administration/packages/index.md +++ b/doc/administration/packages/index.md @@ -8,6 +8,7 @@ The Packages feature allows GitLab to act as a repository for the following: | Software repository | Description | Available in GitLab version | | ------------------- | ----------- | --------------------------- | +| [NuGet Repository](../../user/packages/nuget_repository/index.md) | The GitLab NuGet Repository enables every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ | | [Conan Repository](../../user/packages/conan_repository/index.md) | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ | | [Maven Repository](../../user/packages/maven_repository/index.md) | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ | | [NPM Registry](../../user/packages/npm_registry/index.md) | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ | diff --git a/doc/administration/pages/index.md b/doc/administration/pages/index.md index d1b58f2ee18..434cb2447c8 100644 --- a/doc/administration/pages/index.md +++ b/doc/administration/pages/index.md @@ -32,11 +32,11 @@ In the case of [custom domains](#custom-domains) (but not ports `80` and/or `443`. For that reason, there is some flexibility in the way which you can set it up: -1. Run the Pages daemon in the same server as GitLab, listening on a secondary IP. -1. Run the Pages daemon in a separate server. In that case, the +- Run the Pages daemon in the same server as GitLab, listening on a **secondary IP**. +- Run the Pages daemon in a [separate server](#running-gitlab-pages-on-a-separate-server). In that case, the [Pages path](#change-storage-path) must also be present in the server that the Pages daemon is installed, so you will have to share it via network. -1. Run the Pages daemon in the same server as GitLab, listening on the same IP +- Run the Pages daemon in the same server as GitLab, listening on the same IP but on different ports. In that case, you will have to proxy the traffic with a loadbalancer. If you choose that route note that you should use TCP load balancing for HTTPS. If you use TLS-termination (HTTPS-load balancing) the @@ -182,7 +182,7 @@ The [GitLab Pages README](https://gitlab.com/gitlab-org/gitlab-pages#caveats) ha In addition to the wildcard domains, you can also have the option to configure GitLab Pages to work with custom domains. Again, there are two options here: support custom domains with and without TLS certificates. The easiest setup is -that without TLS certificates. In either case, you'll need a secondary IP. If +that without TLS certificates. In either case, you'll need a **secondary IP**. If you have IPv6 as well as IPv4 addresses, you can use them both. ### Custom domains @@ -257,8 +257,8 @@ When adding a custom domain, users will be required to prove they own it by adding a GitLab-controlled verification code to the DNS records for that domain. If your userbase is private or otherwise trusted, you can disable the -verification requirement. Navigate to `Admin area ➔ Settings` and uncheck -**Require users to prove ownership of custom domains** in the Pages section. +verification requirement. Navigate to **Admin Area > Settings > Preferences** and +uncheck **Require users to prove ownership of custom domains** in the **Pages** section. This setting is enabled by default. ### Let's Encrypt integration @@ -307,6 +307,27 @@ Pages access control is disabled by default. To enable it: 1. [Reconfigure GitLab][reconfigure]. 1. Users can now configure it in their [projects' settings](../../user/project/pages/pages_access_control.md). +#### Disabling public access to all Pages websites + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/32095) in GitLab 12.7. + +You can enforce [Access Control](#access-control) for all GitLab Pages websites hosted +on your GitLab instance. By doing so, only logged-in users will have access to them. +This setting overrides Access Control set by users in individual projects. + +This can be useful to preserve information published with Pages websites to the users +of your instance only. +To do that: + +1. Navigate to your instance's **Admin Area > Settings > Preferences** and expand **Pages** settings. +1. Check the **Disable public access to Pages sites** checkbox. +1. Click **Save changes**. + +CAUTION: **Warning:** +This action will not make all currently public web-sites private until they redeployed. +This issue among others will be resolved by +[changing GitLab Pages configuration mechanism](https://gitlab.com/gitlab-org/gitlab-pages/issues/282). + ### Running behind a proxy Like the rest of GitLab, Pages can be used in those environments where external @@ -395,10 +416,26 @@ Omnibus GitLab 11.1. ## Set maximum pages size -The maximum size of the unpacked archive per project can be configured in the -Admin area under the Application settings in the **Maximum size of pages (MB)**. +You can configure the maximum size of the unpacked archive per project in +**Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**. The default is 100MB. +### Override maximum pages size per project or group **(PREMIUM ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/16610) in GitLab 12.7. + +To override the global maximum pages size for a specific project: + +1. Navigate to your project's **Settings > Pages** page. +1. Edit the **Maximum size of pages**. +1. Click **Save changes**. + +To override the global maximum pages size for a specific group: + +1. Navigate to your group's **Settings > General** page and expand **Pages**. +1. Edit the **Maximum size of pages**. +1. Click **Save changes**. + ## Running GitLab Pages on a separate server You can run the GitLab Pages daemon on a separate server in order to decrease the load on your main application server. diff --git a/doc/administration/pages/source.md b/doc/administration/pages/source.md index be8bba3c95b..738eb87d53d 100644 --- a/doc/administration/pages/source.md +++ b/doc/administration/pages/source.md @@ -433,8 +433,8 @@ are stored. ## Set maximum Pages size -The maximum size of the unpacked archive per project can be configured in the -Admin area under the Application settings in the **Maximum size of pages (MB)**. +The maximum size of the unpacked archive per project can be configured in +**Admin Area > Settings > Preferences > Pages**, in **Maximum size of pages (MB)**. The default is 100MB. ## Backup diff --git a/doc/administration/plugins.md b/doc/administration/plugins.md index df75d3a24bc..dbb733b9b19 100644 --- a/doc/administration/plugins.md +++ b/doc/administration/plugins.md @@ -1,115 +1,5 @@ -# GitLab Plugin system +--- +redirect_to: 'file_hooks.md' +--- -> Introduced in GitLab 10.6. - -With custom plugins, GitLab administrators can introduce custom integrations -without modifying GitLab's source code. - -NOTE: **Note:** -Instead of writing and supporting your own plugin you can make changes -directly to the GitLab source code and contribute back upstream. This way we can -ensure functionality is preserved across versions and covered by tests. - -NOTE: **Note:** -Plugins must be configured on the filesystem of the GitLab server. Only GitLab -server administrators will be able to complete these tasks. Explore -[system hooks] or [webhooks] as an option if you do not have filesystem access. - -A plugin will run on each event so it's up to you to filter events or projects -within a plugin code. You can have as many plugins as you want. Each plugin will -be triggered by GitLab asynchronously in case of an event. For a list of events -see the [system hooks] documentation. - -## Setup - -The plugins must be placed directly into the `plugins` directory, subdirectories -will be ignored. There is an -[`example` directory inside `plugins`](https://gitlab.com/gitlab-org/gitlab-foss/tree/master/plugins/examples) -where you can find some basic examples. - -Follow the steps below to set up a custom hook: - -1. On the GitLab server, navigate to the plugin directory. - For an installation from source the path is usually - `/home/git/gitlab/plugins/`. For Omnibus installs the path is - usually `/opt/gitlab/embedded/service/gitlab-rails/plugins`. - - For [highly available] configurations, your hook file should exist on each - application server. - -1. Inside the `plugins` directory, create a file with a name of your choice, - without spaces or special characters. -1. Make the hook file executable and make sure it's owned by the Git user. -1. Write the code to make the plugin function as expected. That can be - in any language, and ensure the 'shebang' at the top properly reflects the - language type. For example, if the script is in Ruby the shebang will - probably be `#!/usr/bin/env ruby`. -1. The data to the plugin will be provided as JSON on STDIN. It will be exactly - same as for [system hooks] - -That's it! Assuming the plugin code is properly implemented, the hook will fire -as appropriate. The plugins file list is updated for each event, there is no -need to restart GitLab to apply a new plugin. - -If a plugin executes with non-zero exit code or GitLab fails to execute it, a -message will be logged to: - -- `gitlab-rails/plugin.log` in an Omnibus installation. -- `log/plugin.log` in a source installation. - -## Creating plugins - -Below is an example that will only response on the event `project_create` and -will inform the admins from the GitLab instance that a new project has been created. - -```ruby -# By using the embedded ruby version we eliminate the possibility that our chosen language -# would be unavailable from -#!/opt/gitlab/embedded/bin/ruby -require 'json' -require 'mail' - -# The incoming variables are in JSON format so we need to parse it first. -ARGS = JSON.parse(STDIN.read) - -# We only want to trigger this plugin on the event project_create -return unless ARGS['event_name'] == 'project_create' - -# We will inform our admins of our gitlab instance that a new project is created -Mail.deliver do - from 'info@gitlab_instance.com' - to 'admin@gitlab_instance.com' - subject "new project " + ARGS['name'] - body ARGS['owner_name'] + 'created project ' + ARGS['name'] -end -``` - -## Validation - -Writing your own plugin can be tricky and it's easier if you can check it -without altering the system. A rake task is provided so that you can use it -in a staging environment to test your plugin before using it in production. -The rake task will use a sample data and execute each of plugin. The output -should be enough to determine if the system sees your plugin and if it was -executed without errors. - -```bash -# Omnibus installations -sudo gitlab-rake plugins:validate - -# Installations from source -cd /home/git/gitlab -bundle exec rake plugins:validate RAILS_ENV=production -``` - -Example of output: - -``` -Validating plugins from /plugins directory -* /home/git/gitlab/plugins/save_to_file.clj succeed (zero exit code) -* /home/git/gitlab/plugins/save_to_file.rb failure (non-zero exit code) -``` - -[system hooks]: ../system_hooks/system_hooks.md -[webhooks]: ../user/project/integrations/webhooks.md -[highly available]: ./high_availability/README.md +This document was moved to [File Hooks](file_hooks.md), after the Plugins feature was renamed to File Hooks. diff --git a/doc/administration/raketasks/uploads/migrate.md b/doc/administration/raketasks/uploads/migrate.md index 26c811ca54d..aef15e3f388 100644 --- a/doc/administration/raketasks/uploads/migrate.md +++ b/doc/administration/raketasks/uploads/migrate.md @@ -1,4 +1,4 @@ -# Uploads Migrate Rake Task +# Uploads Migrate Rake Tasks ## Migrate to Object Storage @@ -110,7 +110,15 @@ sudo -u git -H bundle exec rake "gitlab:uploads:migrate[FileUploader, MergeReque To migrate all uploads created by legacy uploaders, run: -```shell +**Omnibus Installation** + +```bash +gitlab-rake gitlab:uploads:legacy:migrate +``` + +**Source Installation** + +```bash bundle exec rake gitlab:uploads:legacy:migrate ``` diff --git a/doc/administration/repository_checks.md b/doc/administration/repository_checks.md index 6bf10441369..decd708a85d 100644 --- a/doc/administration/repository_checks.md +++ b/doc/administration/repository_checks.md @@ -36,10 +36,9 @@ in `repocheck.log`: - `/var/log/gitlab/gitlab-rails` for Omnibus installations - `/home/git/gitlab/log` for installations from source -If for some reason the periodic repository check caused a lot of false -alarms you can choose to clear *all* repository check states by -clicking "Clear all repository checks" on the **Settings** page of the -admin panel (`/admin/application_settings`). +If the periodic repository check causes false alarms, you can clear all repository check states by +navigating to **Admin Area > Settings > Repository** +(`/admin/application_settings/repository`) and clicking **Clear all repository checks**. --- [ce-3232]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/3232 "Auto git fsck" diff --git a/doc/administration/repository_storage_paths.md b/doc/administration/repository_storage_paths.md index d31b1d7fcd6..dfd0a618a73 100644 --- a/doc/administration/repository_storage_paths.md +++ b/doc/administration/repository_storage_paths.md @@ -110,7 +110,7 @@ Once you set the multiple storage paths, you can choose where new projects will be stored under **Admin Area > Settings > Repository > Repository storage > Storage nodes for new projects**. - + Beginning with GitLab 8.13.4, multiple paths can be chosen. New projects will be randomly placed on one of the selected paths. diff --git a/doc/administration/troubleshooting/debug.md b/doc/administration/troubleshooting/debug.md index 3007b711405..b754b954391 100644 --- a/doc/administration/troubleshooting/debug.md +++ b/doc/administration/troubleshooting/debug.md @@ -196,7 +196,7 @@ is a Unicorn worker that is spinning via `top`. Try to use the `gdb` techniques above. In addition, using `strace` may help isolate issues: ```shell -strace -tt -T -f -s 1024 -p <PID of unicorn worker> -o /tmp/unicorn.txt +strace -ttTfyyy -s 1024 -p <PID of unicorn worker> -o /tmp/unicorn.txt ``` If you cannot isolate which Unicorn worker is the issue, try to run `strace` @@ -204,7 +204,7 @@ on all the Unicorn workers to see where the `/internal/allowed` endpoint gets stuck: ```shell -ps auwx | grep unicorn | awk '{ print " -p " $2}' | xargs strace -tt -T -f -s 1024 -o /tmp/unicorn.txt +ps auwx | grep unicorn | awk '{ print " -p " $2}' | xargs strace -ttTfyyy -s 1024 -o /tmp/unicorn.txt ``` The output in `/tmp/unicorn.txt` may help diagnose the root cause. diff --git a/doc/administration/troubleshooting/elasticsearch.md b/doc/administration/troubleshooting/elasticsearch.md index 5846514c574..a582e07b141 100644 --- a/doc/administration/troubleshooting/elasticsearch.md +++ b/doc/administration/troubleshooting/elasticsearch.md @@ -106,7 +106,7 @@ graph TD; D2 --> |Yes| D4 D4 --> |No| D5 D4 --> |Yes| D6 - D{Is the error concerning<br>the beta indexer?} + D{Is the error concerning<br>the Go indexer?} D1[It would be best<br>to speak with an<br>Elasticsearch admin.] D2{Is the ICU development<br>package installed?} D3>This package is required.<br>Install the package<br>and retry.] @@ -245,12 +245,13 @@ much to "integrate" here. If the issue is: -- Not concerning the beta indexer, it is almost always an +- With the Go indexer, check if the ICU development package is installed. + This is a required package so make sure you install it. + Go indexer was a beta indexer which can be optionally turned on/off, but in 12.3 it reached stable status and is now the default. +- Not concerning the Go indexer, it is almost always an Elasticsearch-side issue. This means you should reach out to your Elasticsearch admin regarding the error(s) you are seeing. If you are unsure here, it never hurts to reach out to GitLab support. -- With the beta indexer, check if the ICU development package is installed. - This is a required package so make sure you install it. Beyond that, you will want to review the error. If it is: @@ -324,7 +325,7 @@ feel free to update that page with issues you encounter and solutions. ## Replication -Setting up Elasticsearch isn't too bad, but it can be a bit finnicky and time consuming. +Setting up Elasticsearch isn't too bad, but it can be a bit finicky and time consuming. The easiest method is to spin up a docker container with the required version and bind ports 9200/9300 so it can be used. diff --git a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md index cb0b24ae026..0ab8d629b61 100644 --- a/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md +++ b/doc/administration/troubleshooting/gitlab_rails_cheat_sheet.md @@ -743,6 +743,8 @@ Namespace.find_by_full_path("user/proj").namespace_statistics.update(shared_runn ### Remove artifacts more than a week old +The Latest version of these steps can be found in the [job artifacts documentation](../job_artifacts.md) + ```ruby ### SELECTING THE BUILDS TO CLEAR # For a single project: diff --git a/doc/administration/troubleshooting/postgresql.md b/doc/administration/troubleshooting/postgresql.md index 65c6952bf1c..ab302c919b2 100644 --- a/doc/administration/troubleshooting/postgresql.md +++ b/doc/administration/troubleshooting/postgresql.md @@ -41,7 +41,7 @@ This section is for links to information elsewhere in the GitLab documentation. - [Using Slony to update PostgreSQL](../../update/upgrading_postgresql_using_slony.md) - Uses replication to handle PostgreSQL upgrades - providing the schemas are the same. - - Reduces downtime to a short window for swinging over to the newer vewrsion. + - Reduces downtime to a short window for swinging over to the newer version. - Managing Omnibus PostgreSQL versions [from the development docs](https://docs.gitlab.com/omnibus/development/managing-postgresql-versions.html) diff --git a/doc/administration/troubleshooting/sidekiq.md b/doc/administration/troubleshooting/sidekiq.md index 41657368ea4..91361dddf02 100644 --- a/doc/administration/troubleshooting/sidekiq.md +++ b/doc/administration/troubleshooting/sidekiq.md @@ -174,7 +174,7 @@ the query details. ## Managing Sidekiq queues It is possible to use [Sidekiq API](https://github.com/mperham/sidekiq/wiki/API) -to perform a number of troubleshoting on Sidekiq. +to perform a number of troubleshooting on Sidekiq. These are the administrative commands and it should only be used if currently admin interface is not suitable due to scale of installation. diff --git a/doc/api/README.md b/doc/api/README.md index e756cd51997..ef3b578f04e 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -410,7 +410,7 @@ This method is controlled by the following parameters: In the example below, we list 50 [projects](projects.md) per page, ordered by `id` ascending. ```bash -curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" +curl --request GET --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects?pagination=keyset&per_page=50&order_by=id&sort=asc" ``` The response header includes a link to the next page. For example: @@ -426,7 +426,7 @@ Status: 200 OK The link to the next page contains an additional filter `id_after=42` which excludes records we have retrieved already. Note the type of filter depends on the `order_by` option used and we may have more than one additional filter. -The `Link` header is absent when the end of the collection has been reached and there are no additional records to retrieve. +When the end of the collection has been reached and there are no additional records to retrieve, the `Link` header is absent and the resulting array is empty. We recommend using only the given link to retrieve the next page instead of building your own URL. Apart from the headers shown, we don't expose additional pagination headers. diff --git a/doc/api/api_resources.md b/doc/api/api_resources.md index c2713f54c47..6eba9bf23bf 100644 --- a/doc/api/api_resources.md +++ b/doc/api/api_resources.md @@ -29,6 +29,7 @@ The following API resources are available in the project context: | [Deployments](deployments.md) | `/projects/:id/deployments` | | [Discussions](discussions.md) (threaded comments) | `/projects/:id/issues/.../discussions`, `/projects/:id/snippets/.../discussions`, `/projects/:id/merge_requests/.../discussions`, `/projects/:id/commits/.../discussions` (also available for groups) | | [Environments](environments.md) | `/projects/:id/environments` | +| [Error Tracking](error_tracking.md) | `/projects/:id/error_tracking/settings` | | [Events](events.md) | `/projects/:id/events` (also available for users and standalone) | | [Issues](issues.md) | `/projects/:id/issues` (also available for groups and standalone) | | [Issues Statistics](issues_statistics.md) | `/projects/:id/issues_statistics` (also available for groups and standalone) | @@ -105,6 +106,7 @@ The following API resources are available outside of project and group contexts | Resource | Available endpoints | |:--------------------------------------------------|:------------------------------------------------------------------------| +| [Appearance](appearance.md) **(CORE ONLY)** | `/application/appearance` | | [Applications](applications.md) | `/applications` | | [Audit Events](audit_events.md) **(PREMIUM ONLY)** | `/audit_events` | | [Avatar](avatar.md) | `/avatar` | diff --git a/doc/api/appearance.md b/doc/api/appearance.md new file mode 100644 index 00000000000..e2c10fa2574 --- /dev/null +++ b/doc/api/appearance.md @@ -0,0 +1,80 @@ +# Appearance API **(CORE ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/16647) in GitLab 12.7. + +Appearance API allows you to maintain GitLab's appearance as if using the GitLab UI at +`/admin/appearance`. The API requires administrator privileges. + +## Get current appearance configuration + +List the current appearance configuration of the GitLab instance. + +``` +GET /application/appearance +``` + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/appearance +``` + +Example response: + +```json +{ + "title": "GitLab Test Instance", + "description": "gitlab-test.example.com", + "logo": "/uploads/-/system/appearance/logo/1/logo.png", + "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", + "favicon": "/uploads/-/system/appearance/favicon/1/favicon.png", + "new_project_guidelines": "Please read the FAQs for help.", + "header_message": "", + "footer_message": "", + "message_background_color": "#e75e40", + "message_font_color": "#ffffff", + "email_header_and_footer_enabled": false +} +``` + +## Change appearance configuration + +Use an API call to modify GitLab instance appearance configuration. + +``` +PUT /application/appearance +``` + +| Attribute | Type | Required | Description | +| --------------------------------- | ------- | -------- | ----------- | +| `title` | string | no | Instance title on the sign in / sign up page +| `description` | string | no | Markdown text shown on the sign in / sign up page +| `logo` | mixed | no | Instance image used on the sign in / sign up page +| `header_logo` | mixed | no | Instance image used for the main navigation bar +| `favicon` | mixed | no | Instance favicon in .ico/.png format +| `new_project_guidelines` | string | no | Markdown text shown on the new project page +| `header_message` | string | no | Message within the system header bar +| `footer_message` | string | no | Message within the system footer bar +| `message_background_color` | string | no | Background color for the system header / footer bar +| `message_font_color` | string | no | Font color for the system header / footer bar +| `email_header_and_footer_enabled` | boolean | no | Add header and footer to all outgoing emails if enabled + +```bash +curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/application/appearance?email_header_and_footer_enabled=true&header_message=test +``` + +Example response: + +```json +{ + "title": "GitLab Test Instance", + "description": "gitlab-test.example.com", + "logo": "/uploads/-/system/appearance/logo/1/logo.png", + "header_logo": "/uploads/-/system/appearance/header_logo/1/header.png", + "favicon": "/uploads/-/system/appearance/favicon/1/favicon.png", + "new_project_guidelines": "Please read the FAQs for help.", + "header_message": "test", + "footer_message": "", + "message_background_color": "#e75e40", + "message_font_color": "#ffffff", + "email_header_and_footer_enabled": true +} +``` diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 916c99d5f89..3890a71f283 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -15,6 +15,16 @@ GET /projects/:id/deployments | `sort` | string | no | Return deployments sorted in `asc` or `desc` order. Default is `asc` | | `updated_after` | datetime | no | Return deployments updated after the specified date | | `updated_before` | datetime | no | Return deployments updated before the specified date | +| `environment` | string | no | The name of the environment to filter deployments by | +| `status` | string | no | The status to filter deployments by | + +The status attribute can be one of the following values: + +- created +- running +- success +- failed +- canceled ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments" @@ -349,3 +359,19 @@ Example of a response: "deployable": null } ``` + +## List of merge requests associated with a deployment + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/35739) in GitLab 12.7. + +This API retrieves the list of merge requests shipped with a given deployment: + +``` +GET /projects/:id/deployments/:deployment_id/merge_requests +``` + +It supports the same parameters as the [Merge Requests API](./merge_requests.md#list-merge-requests) and will return a response using the same format: + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42" +``` diff --git a/doc/api/epics.md b/doc/api/epics.md index 531c75fd8c5..109c12c1052 100644 --- a/doc/api/epics.md +++ b/doc/api/epics.md @@ -29,6 +29,14 @@ are paginated. Read more on [pagination](README.md#pagination). +CAUTION: **Deprecation** +> `reference` attribute in response is deprecated in favour of `references`. +> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/merge_requests/20354) + +NOTE: **Note** +> `references.relative` is relative to the group that the epic is being requested. When epic is fetched from its origin group +> `relative` format would be the same as `short` format and when requested cross groups it is expected to be the same as `full` format. + ## List epics for a group Gets all epics of the requested group and its subgroups. @@ -45,6 +53,7 @@ GET /groups/:id/epics?state=opened | `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `author_id` | integer | no | Return epics created by the given user `id` | | `labels` | string | no | Return epics matching a comma separated list of labels names. Label names from the epic group or a parent group can be used | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413)| | `order_by` | string | no | Return epics ordered by `created_at` or `updated_at` fields. Default is `created_at` | | `sort` | string | no | Return epics sorted in `asc` or `desc` order. Default is `desc` | | `search` | string | no | Search epics against their `title` and `description` | @@ -73,6 +82,51 @@ Example response: "state": "opened", "web_url": "http://localhost:3001/groups/test/-/epics/4", "reference": "&4", + "references": { + "short": "&4", + "relative": "&4", + "full": "test&4" + }, + "author": { + "id": 10, + "name": "Lu Mayer", + "username": "kam", + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/018729e129a6f31c80a6327a30196823?s=80&d=identicon", + "web_url": "http://localhost:3001/kam" + }, + "start_date": null, + "start_date_is_fixed": false, + "start_date_fixed": null, + "start_date_from_milestones": null, //deprecated in favor of start_date_from_inherited_source + "start_date_from_inherited_source": null, + "end_date": "2018-07-31", //deprecated in favor of due_date + "due_date": "2018-07-31", + "due_date_is_fixed": false, + "due_date_fixed": null, + "due_date_from_milestones": "2018-07-31", //deprecated in favor of start_date_from_inherited_source + "due_date_from_inherited_source": "2018-07-31", + "created_at": "2018-07-17T13:36:22.770Z", + "updated_at": "2018-07-18T12:22:05.239Z", + "closed_at": "2018-08-18T12:22:05.239Z", + "labels": [], + "upvotes": 4, + "downvotes": 0 + }, + { + "id": 50, + "iid": 35, + "group_id": 17, + "title": "Accusamus iste et ullam ratione voluptatem omnis debitis dolor est.", + "description": "Molestias dolorem eos vitae expedita impedit necessitatibus quo voluptatum.", + "state": "opened", + "web_url": "http://localhost:3001/groups/test/sample/-/epics/4", + "reference": "&4", + "references": { + "short": "&4", + "relative": "sample&4", + "full": "test/sample&4" + }, "author": { "id": 10, "name": "Lu Mayer", @@ -131,6 +185,11 @@ Example response: "state": "opened", "web_url": "http://localhost:3001/groups/test/-/epics/5", "reference": "&5", + "references": { + "short": "&5", + "relative": "&5", + "full": "test&5" + }, "author":{ "id": 7, "name": "Pamella Huel", @@ -199,8 +258,13 @@ Example response: "title": "Epic", "description": "Epic description", "state": "opened", - "web_url": "http://localhost:3001/groups/test/-/epics/5", + "web_url": "http://localhost:3001/groups/test/-/epics/6", "reference": "&6", + "references": { + "short": "&6", + "relative": "&6", + "full": "test&6" + }, "author": { "name" : "Alexandra Bashirian", "avatar_url" : null, @@ -269,8 +333,13 @@ Example response: "title": "New Title", "description": "Epic description", "state": "opened", - "web_url": "http://localhost:3001/groups/test/-/epics/5", + "web_url": "http://localhost:3001/groups/test/-/epics/6", "reference": "&6", + "references": { + "short": "&6", + "relative": "&6", + "full": "test&6" + }, "author": { "name" : "Alexandra Bashirian", "avatar_url" : null, @@ -372,6 +441,13 @@ Example response: "avatar_url": "http://www.gravatar.com/avatar/a2f5c6fcef64c9c69cb8779cb292be1b?s=80&d=identicon", "web_url": "http://localhost:3001/arnita" }, + "web_url": "http://localhost:3001/groups/test/-/epics/5", + "reference": "&5", + "references": { + "short": "&5", + "relative": "&5", + "full": "test&5" + }, "start_date": null, "end_date": null, "created_at": "2018-01-21T06:21:13.165Z", diff --git a/doc/api/error_tracking.md b/doc/api/error_tracking.md new file mode 100644 index 00000000000..3c1fbb7dc7a --- /dev/null +++ b/doc/api/error_tracking.md @@ -0,0 +1,32 @@ +# Error Tracking settings API + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/34940) in GitLab 12.7. + +## Error Tracking project settings + +The project settings API allows you to retrieve the Error Tracking settings for a project. Only for project maintainers. + +### Get Error Tracking settings + +``` +GET /projects/:id/error_tracking/settings +``` + +| Attribute | Type | Required | Description | +| --------- | ------- | -------- | --------------------- | +| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/1/error_tracking/settings +``` + +Example response: + +```json +{ + "active": true, + "project_name": "sample sentry project", + "sentry_external_url": "https://sentry.io/myawesomeproject/project", + "api_url": "https://sentry.io/api/0/projects/myawesomeproject/project" +} +``` diff --git a/doc/api/events.md b/doc/api/events.md index 1cd7047b867..1dc0b054ee6 100644 --- a/doc/api/events.md +++ b/doc/api/events.md @@ -66,12 +66,13 @@ Parameters: | `target_type` | string | no | Include only events of a particular [target type][target-types] | | `before` | date | no | Include only events created before a particular date. Please see [here for the supported format][date-formatting] | | `after` | date | no | Include only events created after a particular date. Please see [here for the supported format][date-formatting] | +| `scope` | string | no | Include all events across a user's projects. | | `sort` | string | no | Sort events in `asc` or `desc` order by `created_at`. Default is `desc` | Example request: ```bash -curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01 +curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/events?target_type=issue&action=created&after=2017-01-31&before=2017-03-01&scope=all ``` Example response: diff --git a/doc/api/geo_nodes.md b/doc/api/geo_nodes.md index e44d69f1419..f54694ed15b 100644 --- a/doc/api/geo_nodes.md +++ b/doc/api/geo_nodes.md @@ -3,6 +3,61 @@ In order to interact with Geo node endpoints, you need to authenticate yourself as an admin. +## Create a new Geo node + +Creates a new Geo node. + +``` +POST /geo_nodes +``` + +```bash +curl --header "PRIVATE-TOKEN: <your_access_token>" https://primary.example.com/api/v4/geo_nodes \ + --request POST \ + -d "name=himynameissomething" \ + -d "url=https://another-node.example.com/" +``` + +| Attribute | Type | Required | Description | +| ----------------------------| ------- | -------- | -----------------------------------------------------------------| +| `primary` | boolean | no | Specifying whether this node will be primary. Defaults to false. | +| `enabled` | boolean | no | Flag indicating if the Geo node is enabled. Defaults to true. | +| `name` | string | yes | The unique identifier for the Geo node. Must match `geo_node_name` if it is set in `gitlab.rb`, otherwise it must match `external_url` | +| `url` | string | yes | The user-facing URL for the Geo node. | +| `internal_url` | string | no | The URL defined on the primary node that secondary nodes should use to contact it. Returns `url` if not set. | +| `files_max_capacity` | integer | no | Control the maximum concurrency of LFS/attachment backfill for this secondary node. Defaults to 10. | +| `repos_max_capacity` | integer | no | Control the maximum concurrency of repository backfill for this secondary node. Defaults to 25. | +| `verification_max_capacity` | integer | no | Control the maximum concurrency of repository verification for this node. Defaults to 100. | +| `container_repositories_max_capacity` | integer | no | Control the maximum concurrency of container repository sync for this node. Defaults to 10. | +| `sync_object_storage` | boolean | no | Flag indicating if the secondary Geo node will replicate blobs in Object Storage. Defaults to false. | + +Example response: + +```json +{ + "id": 3, + "name": "Test Node 1", + "url": "https://secondary.example.com/", + "internal_url": "https://secondary.example.com/", + "primary": false, + "enabled": true, + "current": false, + "files_max_capacity": 10, + "repos_max_capacity": 25, + "verification_max_capacity": 100, + "container_repositories_max_capacity": 10, + "sync_object_storage": false, + "clone_protocol": "http", + "web_edit_url": "https://primary.example.com/admin/geo/nodes/3/edit", + "web_geo_projects_url": "http://secondary.example.com/admin/geo/projects", + "_links": { + "self": "https://primary.example.com/api/v4/geo_nodes/3", + "status": "https://primary.example.com/api/v4/geo_nodes/3/status", + "repair": "https://primary.example.com/api/v4/geo_nodes/3/repair" + } +} +``` + ## Retrieve configuration about all Geo nodes ``` diff --git a/doc/api/graphql/reference/gitlab_schema.graphql b/doc/api/graphql/reference/gitlab_schema.graphql index 4673356cf9d..23ffae3b097 100644 --- a/doc/api/graphql/reference/gitlab_schema.graphql +++ b/doc/api/graphql/reference/gitlab_schema.graphql @@ -38,6 +38,9 @@ type AddAwardEmojiPayload { errors: [String!]! } +""" +An emoji awarded by a user. +""" type AwardEmoji { """ The emoji description @@ -71,17 +74,44 @@ type AwardEmoji { } type Blob implements Entry { + """ + Flat path of the entry + """ flatPath: String! + + """ + ID of the entry + """ id: ID! + + """ + LFS ID of the blob + """ lfsOid: String + + """ + Name of the entry + """ name: String! + + """ + Path of the entry + """ path: String! """ - Last commit sha for entry + Last commit sha for the entry """ sha: String! + + """ + Type of tree entry + """ type: EntryType! + + """ + Web URL of the blob + """ webUrl: String } @@ -502,7 +532,13 @@ type CreateSnippetPayload { snippet: Snippet } -type Design implements Noteable { +""" +A single design +""" +type Design implements DesignFields & Noteable { + """ + The diff refs for this design + """ diffRefs: DiffRefs! """ @@ -531,13 +567,33 @@ type Design implements Noteable { ): DiscussionConnection! """ - The change that happened to the design at this version + How this design was changed in the current version """ event: DesignVersionEvent! + + """ + The filename of the design + """ filename: String! + + """ + The full path to the design file + """ fullPath: String! + + """ + The ID of this design + """ id: ID! + + """ + The URL of the image + """ image: String! + + """ + The issue the design belongs to + """ issue: Issue! """ @@ -569,6 +625,10 @@ type Design implements Noteable { The total count of user-created notes for this design """ notesCount: Int! + + """ + The project the design belongs to + """ project: Project! """ @@ -597,9 +657,12 @@ type Design implements Noteable { ): DesignVersionConnection! } +""" +A collection of designs. +""" type DesignCollection { """ - All designs for this collection + All designs for the design collection """ designs( """ @@ -638,11 +701,19 @@ type DesignCollection { """ last: Int ): DesignConnection! + + """ + Issue associated with the design collection + """ issue: Issue! + + """ + Project associated with the design collection + """ project: Project! """ - All versions related to all designs ordered newest first + All versions related to all designs, ordered newest first """ versions( """ @@ -702,6 +773,53 @@ type DesignEdge { node: Design } +interface DesignFields { + """ + The diff refs for this design + """ + diffRefs: DiffRefs! + + """ + How this design was changed in the current version + """ + event: DesignVersionEvent! + + """ + The filename of the design + """ + filename: String! + + """ + The full path to the design file + """ + fullPath: String! + + """ + The ID of this design + """ + id: ID! + + """ + The URL of the image + """ + image: String! + + """ + The issue the design belongs to + """ + issue: Issue! + + """ + The total count of user-created notes for this design + """ + notesCount: Int! + + """ + The project the design belongs to + """ + project: Project! +} + """ Autogenerated input type of DesignManagementDelete """ @@ -799,7 +917,7 @@ type DesignManagementUploadPayload { type DesignVersion { """ - All designs that were changed in this version + All designs that were changed in the version """ designs( """ @@ -822,7 +940,15 @@ type DesignVersion { """ last: Int ): DesignConnection! + + """ + ID of the design version + """ id: ID! + + """ + SHA of the design version + """ sha: ID! } @@ -862,7 +988,7 @@ type DesignVersionEdge { } """ -Mutation event of a Design within a Version +Mutation event of a design within a version """ enum DesignVersionEvent { """ @@ -957,13 +1083,44 @@ type DestroySnippetPayload { } type DetailedStatus { + """ + Path of the details for the pipeline status + """ detailsPath: String! + + """ + Favicon of the pipeline status + """ favicon: String! + + """ + Group of the pipeline status + """ group: String! + + """ + Indicates if the pipeline status has further details + """ hasDetails: Boolean! + + """ + Icon of the pipeline status + """ icon: String! + + """ + Label of the pipeline status + """ label: String! + + """ + Text of the pipeline status + """ text: String! + + """ + Tooltip associated with the pipeline status + """ tooltip: String! } @@ -1215,15 +1372,34 @@ type DiscussionEdge { } interface Entry { + """ + Flat path of the entry + """ flatPath: String! + + """ + ID of the entry + """ id: ID! + + """ + Name of the entry + """ name: String! + + """ + Path of the entry + """ path: String! """ - Last commit sha for entry + Last commit sha for the entry """ sha: String! + + """ + Type of tree entry + """ type: EntryType! } @@ -1236,6 +1412,59 @@ enum EntryType { tree } +""" +Describes where code is deployed for a project +""" +type Environment { + """ + ID of the environment + """ + id: ID! + + """ + Human-readable name of the environment + """ + name: String! +} + +""" +The connection type for Environment. +""" +type EnvironmentConnection { + """ + A list of edges. + """ + edges: [EnvironmentEdge] + + """ + A list of nodes. + """ + nodes: [Environment] + + """ + Information to aid in pagination. + """ + pageInfo: PageInfo! +} + +""" +An edge in a connection. +""" +type EnvironmentEdge { + """ + A cursor for use in pagination. + """ + cursor: String! + + """ + The item at the end of the edge. + """ + node: Environment +} + +""" +Represents an epic. +""" type Epic implements Noteable { """ Author of the epic @@ -1547,7 +1776,7 @@ type Epic implements Noteable { state: EpicState! """ - Boolean flag for whether the currently logged in user is subscribed to this epic + Indicates the currently logged in user is subscribed to the epic """ subscribed: Boolean! @@ -1594,6 +1823,9 @@ type EpicConnection { pageInfo: PageInfo! } +""" +Counts of descendent epics. +""" type EpicDescendantCount { """ Number of closed sub-epics @@ -1631,6 +1863,9 @@ type EpicEdge { node: Epic } +""" +Relationship between an epic and an issue +""" type EpicIssue implements Noteable { """ Assignees of the issue @@ -1693,7 +1928,7 @@ type EpicIssue implements Noteable { designCollection: DesignCollection """ - Deprecated. Use `design_collection`. + Deprecated. Use `design_collection` """ designs: DesignCollection @deprecated(reason: "use design_collection") @@ -1863,7 +2098,7 @@ type EpicIssue implements Noteable { state: IssueState! """ - Boolean flag for whether the currently logged in user is subscribed to this issue + Indicates the currently logged in user is subscribed to the issue """ subscribed: Boolean! @@ -1968,42 +2203,42 @@ Check permissions for the current user on an epic """ type EpicPermissions { """ - Whether or not a user can perform `admin_epic` on this resource + Indicates the user can perform `admin_epic` on this resource """ adminEpic: Boolean! """ - Whether or not a user can perform `award_emoji` on this resource + Indicates the user can perform `award_emoji` on this resource """ awardEmoji: Boolean! """ - Whether or not a user can perform `create_epic` on this resource + Indicates the user can perform `create_epic` on this resource """ createEpic: Boolean! """ - Whether or not a user can perform `create_note` on this resource + Indicates the user can perform `create_note` on this resource """ createNote: Boolean! """ - Whether or not a user can perform `destroy_epic` on this resource + Indicates the user can perform `destroy_epic` on this resource """ destroyEpic: Boolean! """ - Whether or not a user can perform `read_epic` on this resource + Indicates the user can perform `read_epic` on this resource """ readEpic: Boolean! """ - Whether or not a user can perform `read_epic_iid` on this resource + Indicates the user can perform `read_epic_iid` on this resource """ readEpicIid: Boolean! """ - Whether or not a user can perform `update_epic` on this resource + Indicates the user can perform `update_epic` on this resource """ updateEpic: Boolean! } @@ -2079,7 +2314,7 @@ enum EpicSort { } """ -State of a GitLab epic +State of an epic. """ enum EpicState { all @@ -2088,20 +2323,23 @@ enum EpicState { } """ -State event of a GitLab Epic +State event of an epic """ enum EpicStateEvent { """ - Close the Epic + Close the epic """ CLOSE """ - Reopen the Epic + Reopen the epic """ REOPEN } +""" +A node of an epic tree. +""" input EpicTreeNodeFieldsInputType { """ The id of the epic_issue or issue that the actual epic or issue is switched with @@ -2154,6 +2392,38 @@ type EpicTreeReorderPayload { errors: [String!]! } +type GrafanaIntegration { + """ + Timestamp of the issue's creation + """ + createdAt: Time! + + """ + Indicates whether Grafana integration is enabled + """ + enabled: Boolean! + + """ + Url for the Grafana host for the Grafana integration + """ + grafanaUrl: String! + + """ + Internal ID of the Grafana integration + """ + id: ID! + + """ + API token for the Grafana integration + """ + token: String! + + """ + Timestamp of the issue's last activity + """ + updatedAt: Time! +} + type Group { """ Avatar URL of the group @@ -2325,6 +2595,11 @@ type Group { lfsEnabled: Boolean """ + Indicates if a group is disabled from getting mentioned + """ + mentionsDisabled: Boolean + + """ Name of the namespace """ name: String! @@ -2432,7 +2707,7 @@ type Group { type GroupPermissions { """ - Whether or not a user can perform `read_group` on this resource + Indicates the user can perform `read_group` on this resource """ readGroup: Boolean! } @@ -2508,7 +2783,7 @@ type Issue implements Noteable { designCollection: DesignCollection """ - Deprecated. Use `design_collection`. + Deprecated. Use `design_collection` """ designs: DesignCollection @deprecated(reason: "use design_collection") @@ -2663,7 +2938,7 @@ type Issue implements Noteable { state: IssueState! """ - Boolean flag for whether the currently logged in user is subscribed to this issue + Indicates the currently logged in user is subscribed to the issue """ subscribed: Boolean! @@ -2768,42 +3043,42 @@ Check permissions for the current user on a issue """ type IssuePermissions { """ - Whether or not a user can perform `admin_issue` on this resource + Indicates the user can perform `admin_issue` on this resource """ adminIssue: Boolean! """ - Whether or not a user can perform `create_design` on this resource + Indicates the user can perform `create_design` on this resource """ createDesign: Boolean! """ - Whether or not a user can perform `create_note` on this resource + Indicates the user can perform `create_note` on this resource """ createNote: Boolean! """ - Whether or not a user can perform `destroy_design` on this resource + Indicates the user can perform `destroy_design` on this resource """ destroyDesign: Boolean! """ - Whether or not a user can perform `read_design` on this resource + Indicates the user can perform `read_design` on this resource """ readDesign: Boolean! """ - Whether or not a user can perform `read_issue` on this resource + Indicates the user can perform `read_issue` on this resource """ readIssue: Boolean! """ - Whether or not a user can perform `reopen_issue` on this resource + Indicates the user can perform `reopen_issue` on this resource """ reopenIssue: Boolean! """ - Whether or not a user can perform `update_issue` on this resource + Indicates the user can perform `update_issue` on this resource """ updateIssue: Boolean! } @@ -3561,42 +3836,42 @@ Check permissions for the current user on a merge request """ type MergeRequestPermissions { """ - Whether or not a user can perform `admin_merge_request` on this resource + Indicates the user can perform `admin_merge_request` on this resource """ adminMergeRequest: Boolean! """ - Whether or not a user can perform `cherry_pick_on_current_merge_request` on this resource + Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource """ cherryPickOnCurrentMergeRequest: Boolean! """ - Whether or not a user can perform `create_note` on this resource + Indicates the user can perform `create_note` on this resource """ createNote: Boolean! """ - Whether or not a user can perform `push_to_source_branch` on this resource + Indicates the user can perform `push_to_source_branch` on this resource """ pushToSourceBranch: Boolean! """ - Whether or not a user can perform `read_merge_request` on this resource + Indicates the user can perform `read_merge_request` on this resource """ readMergeRequest: Boolean! """ - Whether or not a user can perform `remove_source_branch` on this resource + Indicates the user can perform `remove_source_branch` on this resource """ removeSourceBranch: Boolean! """ - Whether or not a user can perform `revert_on_current_merge_request` on this resource + Indicates the user can perform `revert_on_current_merge_request` on this resource """ revertOnCurrentMergeRequest: Boolean! """ - Whether or not a user can perform `update_merge_request` on this resource + Indicates the user can perform `update_merge_request` on this resource """ updateMergeRequest: Boolean! } @@ -4209,27 +4484,27 @@ type NoteEdge { type NotePermissions { """ - Whether or not a user can perform `admin_note` on this resource + Indicates the user can perform `admin_note` on this resource """ adminNote: Boolean! """ - Whether or not a user can perform `award_emoji` on this resource + Indicates the user can perform `award_emoji` on this resource """ awardEmoji: Boolean! """ - Whether or not a user can perform `create_note` on this resource + Indicates the user can perform `create_note` on this resource """ createNote: Boolean! """ - Whether or not a user can perform `read_note` on this resource + Indicates the user can perform `read_note` on this resource """ readNote: Boolean! """ - Whether or not a user can perform `resolve_note` on this resource + Indicates the user can perform `resolve_note` on this resource """ resolveNote: Boolean! } @@ -4312,26 +4587,70 @@ type PageInfo { } type Pipeline { + """ + Base SHA of the source branch + """ beforeSha: String + + """ + Timestamp of the pipeline's commit + """ committedAt: Time """ Coverage percentage """ coverage: Float + + """ + Timestamp of the pipeline's creation + """ createdAt: Time! + + """ + Detailed status of the pipeline + """ detailedStatus: DetailedStatus! """ Duration of the pipeline in seconds """ duration: Int + + """ + Timestamp of the pipeline's completion + """ finishedAt: Time + + """ + ID of the pipeline + """ id: ID! + + """ + Internal ID of the pipeline + """ iid: String! + + """ + SHA of the pipeline's commit + """ sha: String! + + """ + Timestamp when the pipeline was started + """ startedAt: Time + + """ + Status of the pipeline (CREATED, WAITING_FOR_RESOURCE, PREPARING, PENDING, + RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL, SCHEDULED) + """ status: PipelineStatusEnum! + + """ + Timestamp of the pipeline's last activity + """ updatedAt: Time! """ @@ -4377,17 +4696,17 @@ type PipelineEdge { type PipelinePermissions { """ - Whether or not a user can perform `admin_pipeline` on this resource + Indicates the user can perform `admin_pipeline` on this resource """ adminPipeline: Boolean! """ - Whether or not a user can perform `destroy_pipeline` on this resource + Indicates the user can perform `destroy_pipeline` on this resource """ destroyPipeline: Boolean! """ - Whether or not a user can perform `update_pipeline` on this resource + Indicates the user can perform `update_pipeline` on this resource """ updatePipeline: Boolean! } @@ -4403,15 +4722,21 @@ enum PipelineStatusEnum { SCHEDULED SKIPPED SUCCESS + WAITING_FOR_RESOURCE } type Project { """ - Archived status of the project + Indicates the archived status of the project """ archived: Boolean """ + Indicates if issues referenced by merge requests and commits within the default branch are closed automatically + """ + autocloseReferencedIssues: Boolean + + """ URL to avatar image file of the project """ avatarUrl: String @@ -4437,6 +4762,41 @@ type Project { descriptionHtml: String """ + Environments of the project + """ + environments( + """ + Returns the elements in the list that come after the specified cursor. + """ + after: String + + """ + Returns the elements in the list that come before the specified cursor. + """ + before: String + + """ + Returns the first _n_ elements from the list. + """ + first: Int + + """ + Returns the last _n_ elements from the list. + """ + last: Int + + """ + Name of the environment + """ + name: String + + """ + Search query + """ + search: String + ): EnvironmentConnection + + """ Number of times the project has been forked """ forksCount: Int! @@ -4447,6 +4807,11 @@ type Project { fullPath: ID! """ + Grafana integration details for the project + """ + grafanaIntegration: GrafanaIntegration + + """ Group of the project """ group: Group @@ -4880,6 +5245,11 @@ type Project { statistics: ProjectStatistics """ + The commit message used to apply merge request suggestions + """ + suggestionCommitMessage: String + + """ List of project tags """ tagList: String @@ -4942,207 +5312,207 @@ type ProjectEdge { type ProjectPermissions { """ - Whether or not a user can perform `admin_operations` on this resource + Indicates the user can perform `admin_operations` on this resource """ adminOperations: Boolean! """ - Whether or not a user can perform `admin_project` on this resource + Indicates the user can perform `admin_project` on this resource """ adminProject: Boolean! """ - Whether or not a user can perform `admin_remote_mirror` on this resource + Indicates the user can perform `admin_remote_mirror` on this resource """ adminRemoteMirror: Boolean! """ - Whether or not a user can perform `admin_wiki` on this resource + Indicates the user can perform `admin_wiki` on this resource """ adminWiki: Boolean! """ - Whether or not a user can perform `archive_project` on this resource + Indicates the user can perform `archive_project` on this resource """ archiveProject: Boolean! """ - Whether or not a user can perform `change_namespace` on this resource + Indicates the user can perform `change_namespace` on this resource """ changeNamespace: Boolean! """ - Whether or not a user can perform `change_visibility_level` on this resource + Indicates the user can perform `change_visibility_level` on this resource """ changeVisibilityLevel: Boolean! """ - Whether or not a user can perform `create_deployment` on this resource + Indicates the user can perform `create_deployment` on this resource """ createDeployment: Boolean! """ - Whether or not a user can perform `create_design` on this resource + Indicates the user can perform `create_design` on this resource """ createDesign: Boolean! """ - Whether or not a user can perform `create_issue` on this resource + Indicates the user can perform `create_issue` on this resource """ createIssue: Boolean! """ - Whether or not a user can perform `create_label` on this resource + Indicates the user can perform `create_label` on this resource """ createLabel: Boolean! """ - Whether or not a user can perform `create_merge_request_from` on this resource + Indicates the user can perform `create_merge_request_from` on this resource """ createMergeRequestFrom: Boolean! """ - Whether or not a user can perform `create_merge_request_in` on this resource + Indicates the user can perform `create_merge_request_in` on this resource """ createMergeRequestIn: Boolean! """ - Whether or not a user can perform `create_pages` on this resource + Indicates the user can perform `create_pages` on this resource """ createPages: Boolean! """ - Whether or not a user can perform `create_pipeline` on this resource + Indicates the user can perform `create_pipeline` on this resource """ createPipeline: Boolean! """ - Whether or not a user can perform `create_pipeline_schedule` on this resource + Indicates the user can perform `create_pipeline_schedule` on this resource """ createPipelineSchedule: Boolean! """ - Whether or not a user can perform `create_snippet` on this resource + Indicates the user can perform `create_snippet` on this resource """ createSnippet: Boolean! """ - Whether or not a user can perform `create_wiki` on this resource + Indicates the user can perform `create_wiki` on this resource """ createWiki: Boolean! """ - Whether or not a user can perform `destroy_design` on this resource + Indicates the user can perform `destroy_design` on this resource """ destroyDesign: Boolean! """ - Whether or not a user can perform `destroy_pages` on this resource + Indicates the user can perform `destroy_pages` on this resource """ destroyPages: Boolean! """ - Whether or not a user can perform `destroy_wiki` on this resource + Indicates the user can perform `destroy_wiki` on this resource """ destroyWiki: Boolean! """ - Whether or not a user can perform `download_code` on this resource + Indicates the user can perform `download_code` on this resource """ downloadCode: Boolean! """ - Whether or not a user can perform `download_wiki_code` on this resource + Indicates the user can perform `download_wiki_code` on this resource """ downloadWikiCode: Boolean! """ - Whether or not a user can perform `fork_project` on this resource + Indicates the user can perform `fork_project` on this resource """ forkProject: Boolean! """ - Whether or not a user can perform `push_code` on this resource + Indicates the user can perform `push_code` on this resource """ pushCode: Boolean! """ - Whether or not a user can perform `push_to_delete_protected_branch` on this resource + Indicates the user can perform `push_to_delete_protected_branch` on this resource """ pushToDeleteProtectedBranch: Boolean! """ - Whether or not a user can perform `read_commit_status` on this resource + Indicates the user can perform `read_commit_status` on this resource """ readCommitStatus: Boolean! """ - Whether or not a user can perform `read_cycle_analytics` on this resource + Indicates the user can perform `read_cycle_analytics` on this resource """ readCycleAnalytics: Boolean! """ - Whether or not a user can perform `read_design` on this resource + Indicates the user can perform `read_design` on this resource """ readDesign: Boolean! """ - Whether or not a user can perform `read_pages_content` on this resource + Indicates the user can perform `read_pages_content` on this resource """ readPagesContent: Boolean! """ - Whether or not a user can perform `read_project` on this resource + Indicates the user can perform `read_project` on this resource """ readProject: Boolean! """ - Whether or not a user can perform `read_project_member` on this resource + Indicates the user can perform `read_project_member` on this resource """ readProjectMember: Boolean! """ - Whether or not a user can perform `read_wiki` on this resource + Indicates the user can perform `read_wiki` on this resource """ readWiki: Boolean! """ - Whether or not a user can perform `remove_fork_project` on this resource + Indicates the user can perform `remove_fork_project` on this resource """ removeForkProject: Boolean! """ - Whether or not a user can perform `remove_pages` on this resource + Indicates the user can perform `remove_pages` on this resource """ removePages: Boolean! """ - Whether or not a user can perform `remove_project` on this resource + Indicates the user can perform `remove_project` on this resource """ removeProject: Boolean! """ - Whether or not a user can perform `rename_project` on this resource + Indicates the user can perform `rename_project` on this resource """ renameProject: Boolean! """ - Whether or not a user can perform `request_access` on this resource + Indicates the user can perform `request_access` on this resource """ requestAccess: Boolean! """ - Whether or not a user can perform `update_pages` on this resource + Indicates the user can perform `update_pages` on this resource """ updatePages: Boolean! """ - Whether or not a user can perform `update_wiki` on this resource + Indicates the user can perform `update_wiki` on this resource """ updateWiki: Boolean! """ - Whether or not a user can perform `upload_file` on this resource + Indicates the user can perform `upload_file` on this resource """ uploadFile: Boolean! } @@ -5437,6 +5807,16 @@ type SentryDetailedError { frequency: [SentryErrorFrequency!]! """ + GitLab commit SHA attributed to the Error based on the release version + """ + gitlabCommit: String + + """ + Path to the GitLab page for the GitLab commit attributed to the error + """ + gitlabCommitPath: String + + """ ID (global ID) of the error """ id: ID! @@ -5706,48 +6086,75 @@ type SnippetEdge { type SnippetPermissions { """ - Whether or not a user can perform `admin_snippet` on this resource + Indicates the user can perform `admin_snippet` on this resource """ adminSnippet: Boolean! """ - Whether or not a user can perform `award_emoji` on this resource + Indicates the user can perform `award_emoji` on this resource """ awardEmoji: Boolean! """ - Whether or not a user can perform `create_note` on this resource + Indicates the user can perform `create_note` on this resource """ createNote: Boolean! """ - Whether or not a user can perform `read_snippet` on this resource + Indicates the user can perform `read_snippet` on this resource """ readSnippet: Boolean! """ - Whether or not a user can perform `report_snippet` on this resource + Indicates the user can perform `report_snippet` on this resource """ reportSnippet: Boolean! """ - Whether or not a user can perform `update_snippet` on this resource + Indicates the user can perform `update_snippet` on this resource """ updateSnippet: Boolean! } type Submodule implements Entry { + """ + Flat path of the entry + """ flatPath: String! + + """ + ID of the entry + """ id: ID! + + """ + Name of the entry + """ name: String! + + """ + Path of the entry + """ path: String! """ - Last commit sha for entry + Last commit sha for the entry """ sha: String! + + """ + Tree URL for the sub-module + """ treeUrl: String + + """ + Type of tree entry + """ type: EntryType! + + """ + Web URL for the sub-module + """ webUrl: String } @@ -6130,12 +6537,15 @@ type ToggleAwardEmojiPayload { errors: [String!]! """ - True when the emoji was awarded, false when it was removed + Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. """ toggledOn: Boolean! } type Tree { + """ + Blobs of the tree + """ blobs( """ Returns the elements in the list that come after the specified cursor. @@ -6162,6 +6572,10 @@ type Tree { Last commit for the tree """ lastCommit: Commit + + """ + Sub-modules of the tree + """ submodules( """ Returns the elements in the list that come after the specified cursor. @@ -6183,6 +6597,10 @@ type Tree { """ last: Int ): SubmoduleConnection! + + """ + Trees of the tree + """ trees( """ Returns the elements in the list that come after the specified cursor. @@ -6210,16 +6628,39 @@ type Tree { Represents a directory """ type TreeEntry implements Entry { + """ + Flat path of the entry + """ flatPath: String! + + """ + ID of the entry + """ id: ID! + + """ + Name of the entry + """ name: String! + + """ + Path of the entry + """ path: String! """ - Last commit sha for entry + Last commit sha for the entry """ sha: String! + + """ + Type of tree entry + """ type: EntryType! + + """ + Web URL for the tree entry (directory) + """ webUrl: String } @@ -6609,7 +7050,7 @@ type UserEdge { type UserPermissions { """ - Whether or not a user can perform `create_snippet` on this resource + Indicates the user can perform `create_snippet` on this resource """ createSnippet: Boolean! } diff --git a/doc/api/graphql/reference/gitlab_schema.json b/doc/api/graphql/reference/gitlab_schema.json index 398ae52c130..6239a398c7e 100644 --- a/doc/api/graphql/reference/gitlab_schema.json +++ b/doc/api/graphql/reference/gitlab_schema.json @@ -310,7 +310,21 @@ "fields": [ { "name": "archived", - "description": "Archived status of the project", + "description": "Indicates the archived status of the project", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "autocloseReferencedIssues", + "description": "Indicates if issues referenced by merge requests and commits within the default branch are closed automatically", "args": [ ], @@ -393,6 +407,79 @@ "deprecationReason": null }, { + "name": "environments", + "description": "Environments of the project", + "args": [ + { + "name": "name", + "description": "Name of the environment", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "search", + "description": "Search query", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "after", + "description": "Returns the elements in the list that come after the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "before", + "description": "Returns the elements in the list that come before the specified cursor.", + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "first", + "description": "Returns the first _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + }, + { + "name": "last", + "description": "Returns the last _n_ elements from the list.", + "type": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + }, + "defaultValue": null + } + ], + "type": { + "kind": "OBJECT", + "name": "EnvironmentConnection", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "forksCount", "description": "Number of times the project has been forked", "args": [ @@ -429,6 +516,20 @@ "deprecationReason": null }, { + "name": "grafanaIntegration", + "description": "Grafana integration details for the project", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "GrafanaIntegration", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "group", "description": "Group of the project", "args": [ @@ -1498,6 +1599,20 @@ "deprecationReason": null }, { + "name": "suggestionCommitMessage", + "description": "The commit message used to apply merge request suggestions", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "tagList", "description": "List of project tags", "args": [ @@ -1586,7 +1701,7 @@ "fields": [ { "name": "adminOperations", - "description": "Whether or not a user can perform `admin_operations` on this resource", + "description": "Indicates the user can perform `admin_operations` on this resource", "args": [ ], @@ -1604,7 +1719,7 @@ }, { "name": "adminProject", - "description": "Whether or not a user can perform `admin_project` on this resource", + "description": "Indicates the user can perform `admin_project` on this resource", "args": [ ], @@ -1622,7 +1737,7 @@ }, { "name": "adminRemoteMirror", - "description": "Whether or not a user can perform `admin_remote_mirror` on this resource", + "description": "Indicates the user can perform `admin_remote_mirror` on this resource", "args": [ ], @@ -1640,7 +1755,7 @@ }, { "name": "adminWiki", - "description": "Whether or not a user can perform `admin_wiki` on this resource", + "description": "Indicates the user can perform `admin_wiki` on this resource", "args": [ ], @@ -1658,7 +1773,7 @@ }, { "name": "archiveProject", - "description": "Whether or not a user can perform `archive_project` on this resource", + "description": "Indicates the user can perform `archive_project` on this resource", "args": [ ], @@ -1676,7 +1791,7 @@ }, { "name": "changeNamespace", - "description": "Whether or not a user can perform `change_namespace` on this resource", + "description": "Indicates the user can perform `change_namespace` on this resource", "args": [ ], @@ -1694,7 +1809,7 @@ }, { "name": "changeVisibilityLevel", - "description": "Whether or not a user can perform `change_visibility_level` on this resource", + "description": "Indicates the user can perform `change_visibility_level` on this resource", "args": [ ], @@ -1712,7 +1827,7 @@ }, { "name": "createDeployment", - "description": "Whether or not a user can perform `create_deployment` on this resource", + "description": "Indicates the user can perform `create_deployment` on this resource", "args": [ ], @@ -1730,7 +1845,7 @@ }, { "name": "createDesign", - "description": "Whether or not a user can perform `create_design` on this resource", + "description": "Indicates the user can perform `create_design` on this resource", "args": [ ], @@ -1748,7 +1863,7 @@ }, { "name": "createIssue", - "description": "Whether or not a user can perform `create_issue` on this resource", + "description": "Indicates the user can perform `create_issue` on this resource", "args": [ ], @@ -1766,7 +1881,7 @@ }, { "name": "createLabel", - "description": "Whether or not a user can perform `create_label` on this resource", + "description": "Indicates the user can perform `create_label` on this resource", "args": [ ], @@ -1784,7 +1899,7 @@ }, { "name": "createMergeRequestFrom", - "description": "Whether or not a user can perform `create_merge_request_from` on this resource", + "description": "Indicates the user can perform `create_merge_request_from` on this resource", "args": [ ], @@ -1802,7 +1917,7 @@ }, { "name": "createMergeRequestIn", - "description": "Whether or not a user can perform `create_merge_request_in` on this resource", + "description": "Indicates the user can perform `create_merge_request_in` on this resource", "args": [ ], @@ -1820,7 +1935,7 @@ }, { "name": "createPages", - "description": "Whether or not a user can perform `create_pages` on this resource", + "description": "Indicates the user can perform `create_pages` on this resource", "args": [ ], @@ -1838,7 +1953,7 @@ }, { "name": "createPipeline", - "description": "Whether or not a user can perform `create_pipeline` on this resource", + "description": "Indicates the user can perform `create_pipeline` on this resource", "args": [ ], @@ -1856,7 +1971,7 @@ }, { "name": "createPipelineSchedule", - "description": "Whether or not a user can perform `create_pipeline_schedule` on this resource", + "description": "Indicates the user can perform `create_pipeline_schedule` on this resource", "args": [ ], @@ -1874,7 +1989,7 @@ }, { "name": "createSnippet", - "description": "Whether or not a user can perform `create_snippet` on this resource", + "description": "Indicates the user can perform `create_snippet` on this resource", "args": [ ], @@ -1892,7 +2007,7 @@ }, { "name": "createWiki", - "description": "Whether or not a user can perform `create_wiki` on this resource", + "description": "Indicates the user can perform `create_wiki` on this resource", "args": [ ], @@ -1910,7 +2025,7 @@ }, { "name": "destroyDesign", - "description": "Whether or not a user can perform `destroy_design` on this resource", + "description": "Indicates the user can perform `destroy_design` on this resource", "args": [ ], @@ -1928,7 +2043,7 @@ }, { "name": "destroyPages", - "description": "Whether or not a user can perform `destroy_pages` on this resource", + "description": "Indicates the user can perform `destroy_pages` on this resource", "args": [ ], @@ -1946,7 +2061,7 @@ }, { "name": "destroyWiki", - "description": "Whether or not a user can perform `destroy_wiki` on this resource", + "description": "Indicates the user can perform `destroy_wiki` on this resource", "args": [ ], @@ -1964,7 +2079,7 @@ }, { "name": "downloadCode", - "description": "Whether or not a user can perform `download_code` on this resource", + "description": "Indicates the user can perform `download_code` on this resource", "args": [ ], @@ -1982,7 +2097,7 @@ }, { "name": "downloadWikiCode", - "description": "Whether or not a user can perform `download_wiki_code` on this resource", + "description": "Indicates the user can perform `download_wiki_code` on this resource", "args": [ ], @@ -2000,7 +2115,7 @@ }, { "name": "forkProject", - "description": "Whether or not a user can perform `fork_project` on this resource", + "description": "Indicates the user can perform `fork_project` on this resource", "args": [ ], @@ -2018,7 +2133,7 @@ }, { "name": "pushCode", - "description": "Whether or not a user can perform `push_code` on this resource", + "description": "Indicates the user can perform `push_code` on this resource", "args": [ ], @@ -2036,7 +2151,7 @@ }, { "name": "pushToDeleteProtectedBranch", - "description": "Whether or not a user can perform `push_to_delete_protected_branch` on this resource", + "description": "Indicates the user can perform `push_to_delete_protected_branch` on this resource", "args": [ ], @@ -2054,7 +2169,7 @@ }, { "name": "readCommitStatus", - "description": "Whether or not a user can perform `read_commit_status` on this resource", + "description": "Indicates the user can perform `read_commit_status` on this resource", "args": [ ], @@ -2072,7 +2187,7 @@ }, { "name": "readCycleAnalytics", - "description": "Whether or not a user can perform `read_cycle_analytics` on this resource", + "description": "Indicates the user can perform `read_cycle_analytics` on this resource", "args": [ ], @@ -2090,7 +2205,7 @@ }, { "name": "readDesign", - "description": "Whether or not a user can perform `read_design` on this resource", + "description": "Indicates the user can perform `read_design` on this resource", "args": [ ], @@ -2108,7 +2223,7 @@ }, { "name": "readPagesContent", - "description": "Whether or not a user can perform `read_pages_content` on this resource", + "description": "Indicates the user can perform `read_pages_content` on this resource", "args": [ ], @@ -2126,7 +2241,7 @@ }, { "name": "readProject", - "description": "Whether or not a user can perform `read_project` on this resource", + "description": "Indicates the user can perform `read_project` on this resource", "args": [ ], @@ -2144,7 +2259,7 @@ }, { "name": "readProjectMember", - "description": "Whether or not a user can perform `read_project_member` on this resource", + "description": "Indicates the user can perform `read_project_member` on this resource", "args": [ ], @@ -2162,7 +2277,7 @@ }, { "name": "readWiki", - "description": "Whether or not a user can perform `read_wiki` on this resource", + "description": "Indicates the user can perform `read_wiki` on this resource", "args": [ ], @@ -2180,7 +2295,7 @@ }, { "name": "removeForkProject", - "description": "Whether or not a user can perform `remove_fork_project` on this resource", + "description": "Indicates the user can perform `remove_fork_project` on this resource", "args": [ ], @@ -2198,7 +2313,7 @@ }, { "name": "removePages", - "description": "Whether or not a user can perform `remove_pages` on this resource", + "description": "Indicates the user can perform `remove_pages` on this resource", "args": [ ], @@ -2216,7 +2331,7 @@ }, { "name": "removeProject", - "description": "Whether or not a user can perform `remove_project` on this resource", + "description": "Indicates the user can perform `remove_project` on this resource", "args": [ ], @@ -2234,7 +2349,7 @@ }, { "name": "renameProject", - "description": "Whether or not a user can perform `rename_project` on this resource", + "description": "Indicates the user can perform `rename_project` on this resource", "args": [ ], @@ -2252,7 +2367,7 @@ }, { "name": "requestAccess", - "description": "Whether or not a user can perform `request_access` on this resource", + "description": "Indicates the user can perform `request_access` on this resource", "args": [ ], @@ -2270,7 +2385,7 @@ }, { "name": "updatePages", - "description": "Whether or not a user can perform `update_pages` on this resource", + "description": "Indicates the user can perform `update_pages` on this resource", "args": [ ], @@ -2288,7 +2403,7 @@ }, { "name": "updateWiki", - "description": "Whether or not a user can perform `update_wiki` on this resource", + "description": "Indicates the user can perform `update_wiki` on this resource", "args": [ ], @@ -2306,7 +2421,7 @@ }, { "name": "uploadFile", - "description": "Whether or not a user can perform `upload_file` on this resource", + "description": "Indicates the user can perform `upload_file` on this resource", "args": [ ], @@ -3346,6 +3461,20 @@ "deprecationReason": null }, { + "name": "mentionsDisabled", + "description": "Indicates if a group is disabled from getting mentioned", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "name", "description": "Name of the namespace", "args": [ @@ -3640,7 +3769,7 @@ "fields": [ { "name": "readGroup", - "description": "Whether or not a user can perform `read_group` on this resource", + "description": "Indicates the user can perform `read_group` on this resource", "args": [ ], @@ -3667,7 +3796,7 @@ { "kind": "OBJECT", "name": "Epic", - "description": null, + "description": "Represents an epic.", "fields": [ { "name": "author", @@ -4484,7 +4613,7 @@ }, { "name": "subscribed", - "description": "Boolean flag for whether the currently logged in user is subscribed to this epic", + "description": "Indicates the currently logged in user is subscribed to the epic", "args": [ ], @@ -5128,7 +5257,7 @@ "fields": [ { "name": "adminNote", - "description": "Whether or not a user can perform `admin_note` on this resource", + "description": "Indicates the user can perform `admin_note` on this resource", "args": [ ], @@ -5146,7 +5275,7 @@ }, { "name": "awardEmoji", - "description": "Whether or not a user can perform `award_emoji` on this resource", + "description": "Indicates the user can perform `award_emoji` on this resource", "args": [ ], @@ -5164,7 +5293,7 @@ }, { "name": "createNote", - "description": "Whether or not a user can perform `create_note` on this resource", + "description": "Indicates the user can perform `create_note` on this resource", "args": [ ], @@ -5182,7 +5311,7 @@ }, { "name": "readNote", - "description": "Whether or not a user can perform `read_note` on this resource", + "description": "Indicates the user can perform `read_note` on this resource", "args": [ ], @@ -5200,7 +5329,7 @@ }, { "name": "resolveNote", - "description": "Whether or not a user can perform `resolve_note` on this resource", + "description": "Indicates the user can perform `resolve_note` on this resource", "args": [ ], @@ -5590,7 +5719,7 @@ "fields": [ { "name": "createSnippet", - "description": "Whether or not a user can perform `create_snippet` on this resource", + "description": "Indicates the user can perform `create_snippet` on this resource", "args": [ ], @@ -6732,7 +6861,7 @@ "fields": [ { "name": "adminSnippet", - "description": "Whether or not a user can perform `admin_snippet` on this resource", + "description": "Indicates the user can perform `admin_snippet` on this resource", "args": [ ], @@ -6750,7 +6879,7 @@ }, { "name": "awardEmoji", - "description": "Whether or not a user can perform `award_emoji` on this resource", + "description": "Indicates the user can perform `award_emoji` on this resource", "args": [ ], @@ -6768,7 +6897,7 @@ }, { "name": "createNote", - "description": "Whether or not a user can perform `create_note` on this resource", + "description": "Indicates the user can perform `create_note` on this resource", "args": [ ], @@ -6786,7 +6915,7 @@ }, { "name": "readSnippet", - "description": "Whether or not a user can perform `read_snippet` on this resource", + "description": "Indicates the user can perform `read_snippet` on this resource", "args": [ ], @@ -6804,7 +6933,7 @@ }, { "name": "reportSnippet", - "description": "Whether or not a user can perform `report_snippet` on this resource", + "description": "Indicates the user can perform `report_snippet` on this resource", "args": [ ], @@ -6822,7 +6951,7 @@ }, { "name": "updateSnippet", - "description": "Whether or not a user can perform `update_snippet` on this resource", + "description": "Indicates the user can perform `update_snippet` on this resource", "args": [ ], @@ -7203,7 +7332,7 @@ "fields": [ { "name": "adminEpic", - "description": "Whether or not a user can perform `admin_epic` on this resource", + "description": "Indicates the user can perform `admin_epic` on this resource", "args": [ ], @@ -7221,7 +7350,7 @@ }, { "name": "awardEmoji", - "description": "Whether or not a user can perform `award_emoji` on this resource", + "description": "Indicates the user can perform `award_emoji` on this resource", "args": [ ], @@ -7239,7 +7368,7 @@ }, { "name": "createEpic", - "description": "Whether or not a user can perform `create_epic` on this resource", + "description": "Indicates the user can perform `create_epic` on this resource", "args": [ ], @@ -7257,7 +7386,7 @@ }, { "name": "createNote", - "description": "Whether or not a user can perform `create_note` on this resource", + "description": "Indicates the user can perform `create_note` on this resource", "args": [ ], @@ -7275,7 +7404,7 @@ }, { "name": "destroyEpic", - "description": "Whether or not a user can perform `destroy_epic` on this resource", + "description": "Indicates the user can perform `destroy_epic` on this resource", "args": [ ], @@ -7293,7 +7422,7 @@ }, { "name": "readEpic", - "description": "Whether or not a user can perform `read_epic` on this resource", + "description": "Indicates the user can perform `read_epic` on this resource", "args": [ ], @@ -7311,7 +7440,7 @@ }, { "name": "readEpicIid", - "description": "Whether or not a user can perform `read_epic_iid` on this resource", + "description": "Indicates the user can perform `read_epic_iid` on this resource", "args": [ ], @@ -7329,7 +7458,7 @@ }, { "name": "updateEpic", - "description": "Whether or not a user can perform `update_epic` on this resource", + "description": "Indicates the user can perform `update_epic` on this resource", "args": [ ], @@ -7356,7 +7485,7 @@ { "kind": "ENUM", "name": "EpicState", - "description": "State of a GitLab epic", + "description": "State of an epic.", "fields": null, "inputFields": null, "interfaces": null, @@ -7981,7 +8110,7 @@ { "kind": "OBJECT", "name": "EpicIssue", - "description": null, + "description": "Relationship between an epic and an issue", "fields": [ { "name": "assignees", @@ -8148,7 +8277,7 @@ }, { "name": "designs", - "description": "Deprecated. Use `design_collection`.", + "description": "Deprecated. Use `design_collection`", "args": [ ], @@ -8583,7 +8712,7 @@ }, { "name": "subscribed", - "description": "Boolean flag for whether the currently logged in user is subscribed to this issue", + "description": "Indicates the currently logged in user is subscribed to the issue", "args": [ ], @@ -8826,7 +8955,7 @@ "fields": [ { "name": "adminIssue", - "description": "Whether or not a user can perform `admin_issue` on this resource", + "description": "Indicates the user can perform `admin_issue` on this resource", "args": [ ], @@ -8844,7 +8973,7 @@ }, { "name": "createDesign", - "description": "Whether or not a user can perform `create_design` on this resource", + "description": "Indicates the user can perform `create_design` on this resource", "args": [ ], @@ -8862,7 +8991,7 @@ }, { "name": "createNote", - "description": "Whether or not a user can perform `create_note` on this resource", + "description": "Indicates the user can perform `create_note` on this resource", "args": [ ], @@ -8880,7 +9009,7 @@ }, { "name": "destroyDesign", - "description": "Whether or not a user can perform `destroy_design` on this resource", + "description": "Indicates the user can perform `destroy_design` on this resource", "args": [ ], @@ -8898,7 +9027,7 @@ }, { "name": "readDesign", - "description": "Whether or not a user can perform `read_design` on this resource", + "description": "Indicates the user can perform `read_design` on this resource", "args": [ ], @@ -8916,7 +9045,7 @@ }, { "name": "readIssue", - "description": "Whether or not a user can perform `read_issue` on this resource", + "description": "Indicates the user can perform `read_issue` on this resource", "args": [ ], @@ -8934,7 +9063,7 @@ }, { "name": "reopenIssue", - "description": "Whether or not a user can perform `reopen_issue` on this resource", + "description": "Indicates the user can perform `reopen_issue` on this resource", "args": [ ], @@ -8952,7 +9081,7 @@ }, { "name": "updateIssue", - "description": "Whether or not a user can perform `update_issue` on this resource", + "description": "Indicates the user can perform `update_issue` on this resource", "args": [ ], @@ -9202,11 +9331,11 @@ { "kind": "OBJECT", "name": "DesignCollection", - "description": null, + "description": "A collection of designs.", "fields": [ { "name": "designs", - "description": "All designs for this collection", + "description": "All designs for the design collection", "args": [ { "name": "ids", @@ -9309,7 +9438,7 @@ }, { "name": "issue", - "description": null, + "description": "Issue associated with the design collection", "args": [ ], @@ -9327,7 +9456,7 @@ }, { "name": "project", - "description": null, + "description": "Project associated with the design collection", "args": [ ], @@ -9345,7 +9474,7 @@ }, { "name": "versions", - "description": "All versions related to all designs ordered newest first", + "description": "All versions related to all designs, ordered newest first", "args": [ { "name": "after", @@ -9578,7 +9707,7 @@ }, { "name": "designs", - "description": "Deprecated. Use `design_collection`.", + "description": "Deprecated. Use `design_collection`", "args": [ ], @@ -9967,7 +10096,7 @@ }, { "name": "subscribed", - "description": "Boolean flag for whether the currently logged in user is subscribed to this issue", + "description": "Indicates the currently logged in user is subscribed to the issue", "args": [ ], @@ -10318,11 +10447,11 @@ { "kind": "OBJECT", "name": "Design", - "description": null, + "description": "A single design", "fields": [ { "name": "diffRefs", - "description": null, + "description": "The diff refs for this design", "args": [ ], @@ -10397,7 +10526,7 @@ }, { "name": "event", - "description": "The change that happened to the design at this version", + "description": "How this design was changed in the current version", "args": [ ], @@ -10415,7 +10544,7 @@ }, { "name": "filename", - "description": null, + "description": "The filename of the design", "args": [ ], @@ -10433,7 +10562,7 @@ }, { "name": "fullPath", - "description": null, + "description": "The full path to the design file", "args": [ ], @@ -10451,7 +10580,7 @@ }, { "name": "id", - "description": null, + "description": "The ID of this design", "args": [ ], @@ -10469,7 +10598,7 @@ }, { "name": "image", - "description": null, + "description": "The URL of the image", "args": [ ], @@ -10487,7 +10616,7 @@ }, { "name": "issue", - "description": null, + "description": "The issue the design belongs to", "args": [ ], @@ -10580,7 +10709,7 @@ }, { "name": "project", - "description": null, + "description": "The project the design belongs to", "args": [ ], @@ -10660,15 +10789,199 @@ "kind": "INTERFACE", "name": "Noteable", "ofType": null + }, + { + "kind": "INTERFACE", + "name": "DesignFields", + "ofType": null } ], "enumValues": null, "possibleTypes": null }, { + "kind": "INTERFACE", + "name": "DesignFields", + "description": null, + "fields": [ + { + "name": "diffRefs", + "description": "The diff refs for this design", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "DiffRefs", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "event", + "description": "How this design was changed in the current version", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "ENUM", + "name": "DesignVersionEvent", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "filename", + "description": "The filename of the design", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "fullPath", + "description": "The full path to the design file", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "The ID of this design", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "image", + "description": "The URL of the image", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "issue", + "description": "The issue the design belongs to", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Issue", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "notesCount", + "description": "The total count of user-created notes for this design", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Int", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "project", + "description": "The project the design belongs to", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Project", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": null, + "enumValues": null, + "possibleTypes": [ + { + "kind": "OBJECT", + "name": "Design", + "ofType": null + } + ] + }, + { "kind": "ENUM", "name": "DesignVersionEvent", - "description": "Mutation event of a Design within a Version", + "description": "Mutation event of a design within a version", "fields": null, "inputFields": null, "interfaces": null, @@ -10819,7 +11132,7 @@ "fields": [ { "name": "designs", - "description": "All designs that were changed in this version", + "description": "All designs that were changed in the version", "args": [ { "name": "after", @@ -10876,7 +11189,7 @@ }, { "name": "id", - "description": null, + "description": "ID of the design version", "args": [ ], @@ -10894,7 +11207,7 @@ }, { "name": "sha", - "description": null, + "description": "SHA of the design version", "args": [ ], @@ -10921,7 +11234,7 @@ { "kind": "OBJECT", "name": "EpicDescendantCount", - "description": null, + "description": "Counts of descendent epics.", "fields": [ { "name": "closedEpics", @@ -11428,7 +11741,7 @@ "fields": [ { "name": "blobs", - "description": null, + "description": "Blobs of the tree", "args": [ { "name": "after", @@ -11499,7 +11812,7 @@ }, { "name": "submodules", - "description": null, + "description": "Sub-modules of the tree", "args": [ { "name": "after", @@ -11556,7 +11869,7 @@ }, { "name": "trees", - "description": null, + "description": "Trees of the tree", "args": [ { "name": "after", @@ -12029,7 +12342,7 @@ "fields": [ { "name": "beforeSha", - "description": null, + "description": "Base SHA of the source branch", "args": [ ], @@ -12043,7 +12356,7 @@ }, { "name": "committedAt", - "description": null, + "description": "Timestamp of the pipeline's commit", "args": [ ], @@ -12071,7 +12384,7 @@ }, { "name": "createdAt", - "description": null, + "description": "Timestamp of the pipeline's creation", "args": [ ], @@ -12089,7 +12402,7 @@ }, { "name": "detailedStatus", - "description": null, + "description": "Detailed status of the pipeline", "args": [ ], @@ -12121,7 +12434,7 @@ }, { "name": "finishedAt", - "description": null, + "description": "Timestamp of the pipeline's completion", "args": [ ], @@ -12135,7 +12448,7 @@ }, { "name": "id", - "description": null, + "description": "ID of the pipeline", "args": [ ], @@ -12153,7 +12466,7 @@ }, { "name": "iid", - "description": null, + "description": "Internal ID of the pipeline", "args": [ ], @@ -12171,7 +12484,7 @@ }, { "name": "sha", - "description": null, + "description": "SHA of the pipeline's commit", "args": [ ], @@ -12189,7 +12502,7 @@ }, { "name": "startedAt", - "description": null, + "description": "Timestamp when the pipeline was started", "args": [ ], @@ -12203,7 +12516,7 @@ }, { "name": "status", - "description": null, + "description": "Status of the pipeline (CREATED, WAITING_FOR_RESOURCE, PREPARING, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL, SCHEDULED)", "args": [ ], @@ -12221,7 +12534,7 @@ }, { "name": "updatedAt", - "description": null, + "description": "Timestamp of the pipeline's last activity", "args": [ ], @@ -12270,7 +12583,7 @@ "fields": [ { "name": "adminPipeline", - "description": "Whether or not a user can perform `admin_pipeline` on this resource", + "description": "Indicates the user can perform `admin_pipeline` on this resource", "args": [ ], @@ -12288,7 +12601,7 @@ }, { "name": "destroyPipeline", - "description": "Whether or not a user can perform `destroy_pipeline` on this resource", + "description": "Indicates the user can perform `destroy_pipeline` on this resource", "args": [ ], @@ -12306,7 +12619,7 @@ }, { "name": "updatePipeline", - "description": "Whether or not a user can perform `update_pipeline` on this resource", + "description": "Indicates the user can perform `update_pipeline` on this resource", "args": [ ], @@ -12345,6 +12658,12 @@ "deprecationReason": null }, { + "name": "WAITING_FOR_RESOURCE", + "description": null, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "PREPARING", "description": null, "isDeprecated": false, @@ -12408,7 +12727,7 @@ "fields": [ { "name": "detailsPath", - "description": null, + "description": "Path of the details for the pipeline status", "args": [ ], @@ -12426,7 +12745,7 @@ }, { "name": "favicon", - "description": null, + "description": "Favicon of the pipeline status", "args": [ ], @@ -12444,7 +12763,7 @@ }, { "name": "group", - "description": null, + "description": "Group of the pipeline status", "args": [ ], @@ -12462,7 +12781,7 @@ }, { "name": "hasDetails", - "description": null, + "description": "Indicates if the pipeline status has further details", "args": [ ], @@ -12480,7 +12799,7 @@ }, { "name": "icon", - "description": null, + "description": "Icon of the pipeline status", "args": [ ], @@ -12498,7 +12817,7 @@ }, { "name": "label", - "description": null, + "description": "Label of the pipeline status", "args": [ ], @@ -12516,7 +12835,7 @@ }, { "name": "text", - "description": null, + "description": "Text of the pipeline status", "args": [ ], @@ -12534,7 +12853,7 @@ }, { "name": "tooltip", - "description": null, + "description": "Tooltip associated with the pipeline status", "args": [ ], @@ -12687,7 +13006,7 @@ "fields": [ { "name": "flatPath", - "description": null, + "description": "Flat path of the entry", "args": [ ], @@ -12705,7 +13024,7 @@ }, { "name": "id", - "description": null, + "description": "ID of the entry", "args": [ ], @@ -12723,7 +13042,7 @@ }, { "name": "name", - "description": null, + "description": "Name of the entry", "args": [ ], @@ -12741,7 +13060,7 @@ }, { "name": "path", - "description": null, + "description": "Path of the entry", "args": [ ], @@ -12759,7 +13078,7 @@ }, { "name": "sha", - "description": "Last commit sha for entry", + "description": "Last commit sha for the entry", "args": [ ], @@ -12777,7 +13096,7 @@ }, { "name": "type", - "description": null, + "description": "Type of tree entry", "args": [ ], @@ -12795,7 +13114,7 @@ }, { "name": "webUrl", - "description": null, + "description": "Web URL for the tree entry (directory)", "args": [ ], @@ -12826,7 +13145,7 @@ "fields": [ { "name": "flatPath", - "description": null, + "description": "Flat path of the entry", "args": [ ], @@ -12844,7 +13163,7 @@ }, { "name": "id", - "description": null, + "description": "ID of the entry", "args": [ ], @@ -12862,7 +13181,7 @@ }, { "name": "name", - "description": null, + "description": "Name of the entry", "args": [ ], @@ -12880,7 +13199,7 @@ }, { "name": "path", - "description": null, + "description": "Path of the entry", "args": [ ], @@ -12898,7 +13217,7 @@ }, { "name": "sha", - "description": "Last commit sha for entry", + "description": "Last commit sha for the entry", "args": [ ], @@ -12916,7 +13235,7 @@ }, { "name": "type", - "description": null, + "description": "Type of tree entry", "args": [ ], @@ -13102,7 +13421,7 @@ "fields": [ { "name": "flatPath", - "description": null, + "description": "Flat path of the entry", "args": [ ], @@ -13120,7 +13439,7 @@ }, { "name": "id", - "description": null, + "description": "ID of the entry", "args": [ ], @@ -13138,7 +13457,7 @@ }, { "name": "name", - "description": null, + "description": "Name of the entry", "args": [ ], @@ -13156,7 +13475,7 @@ }, { "name": "path", - "description": null, + "description": "Path of the entry", "args": [ ], @@ -13174,7 +13493,7 @@ }, { "name": "sha", - "description": "Last commit sha for entry", + "description": "Last commit sha for the entry", "args": [ ], @@ -13192,7 +13511,7 @@ }, { "name": "treeUrl", - "description": null, + "description": "Tree URL for the sub-module", "args": [ ], @@ -13206,7 +13525,7 @@ }, { "name": "type", - "description": null, + "description": "Type of tree entry", "args": [ ], @@ -13224,7 +13543,7 @@ }, { "name": "webUrl", - "description": null, + "description": "Web URL for the sub-module", "args": [ ], @@ -13367,7 +13686,7 @@ "fields": [ { "name": "flatPath", - "description": null, + "description": "Flat path of the entry", "args": [ ], @@ -13385,7 +13704,7 @@ }, { "name": "id", - "description": null, + "description": "ID of the entry", "args": [ ], @@ -13403,7 +13722,7 @@ }, { "name": "lfsOid", - "description": null, + "description": "LFS ID of the blob", "args": [ ], @@ -13417,7 +13736,7 @@ }, { "name": "name", - "description": null, + "description": "Name of the entry", "args": [ ], @@ -13435,7 +13754,7 @@ }, { "name": "path", - "description": null, + "description": "Path of the entry", "args": [ ], @@ -13453,7 +13772,7 @@ }, { "name": "sha", - "description": "Last commit sha for entry", + "description": "Last commit sha for the entry", "args": [ ], @@ -13471,7 +13790,7 @@ }, { "name": "type", - "description": null, + "description": "Type of tree entry", "args": [ ], @@ -13489,7 +13808,7 @@ }, { "name": "webUrl", - "description": null, + "description": "Web URL of the blob", "args": [ ], @@ -14808,7 +15127,7 @@ "fields": [ { "name": "adminMergeRequest", - "description": "Whether or not a user can perform `admin_merge_request` on this resource", + "description": "Indicates the user can perform `admin_merge_request` on this resource", "args": [ ], @@ -14826,7 +15145,7 @@ }, { "name": "cherryPickOnCurrentMergeRequest", - "description": "Whether or not a user can perform `cherry_pick_on_current_merge_request` on this resource", + "description": "Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource", "args": [ ], @@ -14844,7 +15163,7 @@ }, { "name": "createNote", - "description": "Whether or not a user can perform `create_note` on this resource", + "description": "Indicates the user can perform `create_note` on this resource", "args": [ ], @@ -14862,7 +15181,7 @@ }, { "name": "pushToSourceBranch", - "description": "Whether or not a user can perform `push_to_source_branch` on this resource", + "description": "Indicates the user can perform `push_to_source_branch` on this resource", "args": [ ], @@ -14880,7 +15199,7 @@ }, { "name": "readMergeRequest", - "description": "Whether or not a user can perform `read_merge_request` on this resource", + "description": "Indicates the user can perform `read_merge_request` on this resource", "args": [ ], @@ -14898,7 +15217,7 @@ }, { "name": "removeSourceBranch", - "description": "Whether or not a user can perform `remove_source_branch` on this resource", + "description": "Indicates the user can perform `remove_source_branch` on this resource", "args": [ ], @@ -14916,7 +15235,7 @@ }, { "name": "revertOnCurrentMergeRequest", - "description": "Whether or not a user can perform `revert_on_current_merge_request` on this resource", + "description": "Indicates the user can perform `revert_on_current_merge_request` on this resource", "args": [ ], @@ -14934,7 +15253,7 @@ }, { "name": "updateMergeRequest", - "description": "Whether or not a user can perform `update_merge_request` on this resource", + "description": "Indicates the user can perform `update_merge_request` on this resource", "args": [ ], @@ -15201,6 +15520,167 @@ }, { "kind": "OBJECT", + "name": "EnvironmentConnection", + "description": "The connection type for Environment.", + "fields": [ + { + "name": "edges", + "description": "A list of edges.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "EnvironmentEdge", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "nodes", + "description": "A list of nodes.", + "args": [ + + ], + "type": { + "kind": "LIST", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "Environment", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "pageInfo", + "description": "Information to aid in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "OBJECT", + "name": "PageInfo", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "EnvironmentEdge", + "description": "An edge in a connection.", + "fields": [ + { + "name": "cursor", + "description": "A cursor for use in pagination.", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "node", + "description": "The item at the end of the edge.", + "args": [ + + ], + "type": { + "kind": "OBJECT", + "name": "Environment", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", + "name": "Environment", + "description": "Describes where code is deployed for a project", + "fields": [ + { + "name": "id", + "description": "ID of the environment", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "name", + "description": "Human-readable name of the environment", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "SentryDetailedError", "description": null, "fields": [ @@ -15331,6 +15811,34 @@ "deprecationReason": null }, { + "name": "gitlabCommit", + "description": "GitLab commit SHA attributed to the Error based on the release version", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "gitlabCommitPath", + "description": "Path to the GitLab page for the GitLab commit attributed to the error", + "args": [ + + ], + "type": { + "kind": "SCALAR", + "name": "String", + "ofType": null + }, + "isDeprecated": false, + "deprecationReason": null + }, + { "name": "id", "description": "ID (global ID) of the error", "args": [ @@ -15664,6 +16172,127 @@ }, { "kind": "OBJECT", + "name": "GrafanaIntegration", + "description": null, + "fields": [ + { + "name": "createdAt", + "description": "Timestamp of the issue's creation", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "enabled", + "description": "Indicates whether Grafana integration is enabled", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Boolean", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "grafanaUrl", + "description": "Url for the Grafana host for the Grafana integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "id", + "description": "Internal ID of the Grafana integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "ID", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "token", + "description": "API token for the Grafana integration", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "String", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + }, + { + "name": "updatedAt", + "description": "Timestamp of the issue's last activity", + "args": [ + + ], + "type": { + "kind": "NON_NULL", + "name": null, + "ofType": { + "kind": "SCALAR", + "name": "Time", + "ofType": null + } + }, + "isDeprecated": false, + "deprecationReason": null + } + ], + "inputFields": null, + "interfaces": [ + + ], + "enumValues": null, + "possibleTypes": null + }, + { + "kind": "OBJECT", "name": "Metadata", "description": null, "fields": [ @@ -16604,7 +17233,7 @@ { "kind": "OBJECT", "name": "AwardEmoji", - "description": null, + "description": "An emoji awarded by a user.", "fields": [ { "name": "description", @@ -16948,7 +17577,7 @@ }, { "name": "toggledOn", - "description": "True when the emoji was awarded, false when it was removed", + "description": "Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji.", "args": [ ], @@ -20350,7 +20979,7 @@ { "kind": "INPUT_OBJECT", "name": "EpicTreeNodeFieldsInputType", - "description": null, + "description": "A node of an epic tree.", "fields": null, "inputFields": [ { @@ -20648,20 +21277,20 @@ { "kind": "ENUM", "name": "EpicStateEvent", - "description": "State event of a GitLab Epic", + "description": "State event of an epic", "fields": null, "inputFields": null, "interfaces": null, "enumValues": [ { "name": "REOPEN", - "description": "Reopen the Epic", + "description": "Reopen the epic", "isDeprecated": false, "deprecationReason": null }, { "name": "CLOSE", - "description": "Close the Epic", + "description": "Close the epic", "isDeprecated": false, "deprecationReason": null } diff --git a/doc/api/graphql/reference/index.md b/doc/api/graphql/reference/index.md index 9fb39322f5c..72fc82444ca 100644 --- a/doc/api/graphql/reference/index.md +++ b/doc/api/graphql/reference/index.md @@ -9,10 +9,12 @@ This documentation is self-generated based on GitLab current GraphQL schema. The API can be explored interactively using the [GraphiQL IDE](../index.md#graphiql). +Each table below documents a GraphQL type. Types match loosely to models, but not all +fields and methods on a model are available via GraphQL. -## Objects +## AddAwardEmojiPayload -### AddAwardEmojiPayload +Autogenerated return type of AddAwardEmoji | Name | Type | Description | | --- | ---- | ---------- | @@ -20,7 +22,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `awardEmoji` | AwardEmoji | The award emoji after mutation | -### AwardEmoji +## AwardEmoji + +An emoji awarded by a user. | Name | Type | Description | | --- | ---- | ---------- | @@ -31,20 +35,20 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `unicodeVersion` | String! | The unicode version for this emoji | | `user` | User! | The user who awarded the emoji | -### Blob +## Blob | Name | Type | Description | | --- | ---- | ---------- | -| `id` | ID! | | -| `sha` | String! | Last commit sha for entry | -| `name` | String! | | -| `type` | EntryType! | | -| `path` | String! | | -| `flatPath` | String! | | -| `webUrl` | String | | -| `lfsOid` | String | | +| `id` | ID! | ID of the entry | +| `sha` | String! | Last commit sha for the entry | +| `name` | String! | Name of the entry | +| `type` | EntryType! | Type of tree entry | +| `path` | String! | Path of the entry | +| `flatPath` | String! | Flat path of the entry | +| `webUrl` | String | Web URL of the blob | +| `lfsOid` | String | LFS ID of the blob | -### Commit +## Commit | Name | Type | Description | | --- | ---- | ---------- | @@ -60,7 +64,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `author` | User | Author of the commit | | `latestPipeline` | Pipeline | Latest pipeline of the commit | -### CreateDiffNotePayload +## CreateDiffNotePayload + +Autogenerated return type of CreateDiffNote | Name | Type | Description | | --- | ---- | ---------- | @@ -68,7 +74,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `note` | Note | The note after mutation | -### CreateEpicPayload +## CreateEpicPayload + +Autogenerated return type of CreateEpic | Name | Type | Description | | --- | ---- | ---------- | @@ -76,7 +84,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `epic` | Epic | The created epic | -### CreateImageDiffNotePayload +## CreateImageDiffNotePayload + +Autogenerated return type of CreateImageDiffNote | Name | Type | Description | | --- | ---- | ---------- | @@ -84,7 +94,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `note` | Note | The note after mutation | -### CreateNotePayload +## CreateNotePayload + +Autogenerated return type of CreateNote | Name | Type | Description | | --- | ---- | ---------- | @@ -92,7 +104,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `note` | Note | The note after mutation | -### CreateSnippetPayload +## CreateSnippetPayload + +Autogenerated return type of CreateSnippet | Name | Type | Description | | --- | ---- | ---------- | @@ -100,28 +114,34 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `snippet` | Snippet | The snippet after mutation | -### Design +## Design + +A single design | Name | Type | Description | | --- | ---- | ---------- | -| `id` | ID! | | -| `project` | Project! | | -| `issue` | Issue! | | +| `id` | ID! | The ID of this design | +| `project` | Project! | The project the design belongs to | +| `issue` | Issue! | The issue the design belongs to | +| `filename` | String! | The filename of the design | +| `fullPath` | String! | The full path to the design file | +| `image` | String! | The URL of the image | +| `diffRefs` | DiffRefs! | The diff refs for this design | +| `event` | DesignVersionEvent! | How this design was changed in the current version | | `notesCount` | Int! | The total count of user-created notes for this design | -| `filename` | String! | | -| `fullPath` | String! | | -| `event` | DesignVersionEvent! | The change that happened to the design at this version | -| `image` | String! | | -| `diffRefs` | DiffRefs! | | -### DesignCollection +## DesignCollection + +A collection of designs. | Name | Type | Description | | --- | ---- | ---------- | -| `project` | Project! | | -| `issue` | Issue! | | +| `project` | Project! | Project associated with the design collection | +| `issue` | Issue! | Issue associated with the design collection | + +## DesignManagementDeletePayload -### DesignManagementDeletePayload +Autogenerated return type of DesignManagementDelete | Name | Type | Description | | --- | ---- | ---------- | @@ -129,7 +149,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `version` | DesignVersion | The new version in which the designs are deleted | -### DesignManagementUploadPayload +## DesignManagementUploadPayload + +Autogenerated return type of DesignManagementUpload | Name | Type | Description | | --- | ---- | ---------- | @@ -138,14 +160,16 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `designs` | Design! => Array | The designs that were uploaded by the mutation | | `skippedDesigns` | Design! => Array | Any designs that were skipped from the upload due to there being no change to their content since their last version | -### DesignVersion +## DesignVersion | Name | Type | Description | | --- | ---- | ---------- | -| `id` | ID! | | -| `sha` | ID! | | +| `id` | ID! | ID of the design version | +| `sha` | ID! | SHA of the design version | -### DestroyNotePayload +## DestroyNotePayload + +Autogenerated return type of DestroyNote | Name | Type | Description | | --- | ---- | ---------- | @@ -153,7 +177,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `note` | Note | The note after mutation | -### DestroySnippetPayload +## DestroySnippetPayload + +Autogenerated return type of DestroySnippet | Name | Type | Description | | --- | ---- | ---------- | @@ -161,20 +187,20 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `snippet` | Snippet | The snippet after mutation | -### DetailedStatus +## DetailedStatus | Name | Type | Description | | --- | ---- | ---------- | -| `group` | String! | | -| `icon` | String! | | -| `favicon` | String! | | -| `detailsPath` | String! | | -| `hasDetails` | Boolean! | | -| `label` | String! | | -| `text` | String! | | -| `tooltip` | String! | | +| `group` | String! | Group of the pipeline status | +| `icon` | String! | Icon of the pipeline status | +| `favicon` | String! | Favicon of the pipeline status | +| `detailsPath` | String! | Path of the details for the pipeline status | +| `hasDetails` | Boolean! | Indicates if the pipeline status has further details | +| `label` | String! | Label of the pipeline status | +| `text` | String! | Text of the pipeline status | +| `tooltip` | String! | Tooltip associated with the pipeline status | -### DiffPosition +## DiffPosition | Name | Type | Description | | --- | ---- | ---------- | @@ -190,7 +216,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `width` | Int | Total width of the image | | `height` | Int | Total height of the image | -### DiffRefs +## DiffRefs | Name | Type | Description | | --- | ---- | ---------- | @@ -198,7 +224,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `baseSha` | String! | Merge base of the branch the comment was made on | | `startSha` | String! | SHA of the branch being compared against | -### Discussion +## Discussion | Name | Type | Description | | --- | ---- | ---------- | @@ -206,7 +232,18 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `replyId` | ID! | ID used to reply to this discussion | | `createdAt` | Time! | Timestamp of the discussion's creation | -### Epic +## Environment + +Describes where code is deployed for a project + +| Name | Type | Description | +| --- | ---- | ---------- | +| `name` | String! | Human-readable name of the environment | +| `id` | ID! | ID of the environment | + +## Epic + +Represents an epic. | Name | Type | Description | | --- | ---- | ---------- | @@ -239,10 +276,12 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `relativePosition` | Int | The relative position of the epic in the epic tree | | `relationPath` | String | | | `reference` | String! | | -| `subscribed` | Boolean! | Boolean flag for whether the currently logged in user is subscribed to this epic | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the epic | | `descendantCounts` | EpicDescendantCount | Number of open and closed descendant epics and issues | -### EpicDescendantCount +## EpicDescendantCount + +Counts of descendent epics. | Name | Type | Description | | --- | ---- | ---------- | @@ -251,7 +290,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `openedIssues` | Int | Number of opened epic issues | | `closedIssues` | Int | Number of closed epic issues | -### EpicIssue +## EpicIssue + +Relationship between an epic and an issue | Name | Type | Description | | --- | ---- | ---------- | @@ -274,7 +315,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `webPath` | String! | Web path of the issue | | `webUrl` | String! | Web URL of the issue | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | -| `subscribed` | Boolean! | Boolean flag for whether the currently logged in user is subscribed to this issue | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | | `timeEstimate` | Int! | Time estimate of the issue | | `totalTimeSpent` | Int! | Total time reported as spent on the issue | | `closedAt` | Time | Timestamp of when the issue was closed | @@ -283,26 +324,30 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue | | `epic` | Epic | Epic to which this issue belongs | | `weight` | Int | Weight of the issue | -| `designs` | DesignCollection | Deprecated. Use `design_collection`. | +| `designs` | DesignCollection | Deprecated. Use `design_collection` | | `designCollection` | DesignCollection | Collection of design images associated with this issue | | `epicIssueId` | ID! | ID of the epic-issue relation | | `relationPath` | String | URI path of the epic-issue relation | | `id` | ID | Global ID of the epic-issue relation | -### EpicPermissions +## EpicPermissions + +Check permissions for the current user on an epic | Name | Type | Description | | --- | ---- | ---------- | -| `readEpic` | Boolean! | Whether or not a user can perform `read_epic` on this resource | -| `readEpicIid` | Boolean! | Whether or not a user can perform `read_epic_iid` on this resource | -| `updateEpic` | Boolean! | Whether or not a user can perform `update_epic` on this resource | -| `destroyEpic` | Boolean! | Whether or not a user can perform `destroy_epic` on this resource | -| `adminEpic` | Boolean! | Whether or not a user can perform `admin_epic` on this resource | -| `createEpic` | Boolean! | Whether or not a user can perform `create_epic` on this resource | -| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | -| `awardEmoji` | Boolean! | Whether or not a user can perform `award_emoji` on this resource | +| `readEpic` | Boolean! | Indicates the user can perform `read_epic` on this resource | +| `readEpicIid` | Boolean! | Indicates the user can perform `read_epic_iid` on this resource | +| `updateEpic` | Boolean! | Indicates the user can perform `update_epic` on this resource | +| `destroyEpic` | Boolean! | Indicates the user can perform `destroy_epic` on this resource | +| `adminEpic` | Boolean! | Indicates the user can perform `admin_epic` on this resource | +| `createEpic` | Boolean! | Indicates the user can perform `create_epic` on this resource | +| `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | +| `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | + +## EpicSetSubscriptionPayload -### EpicSetSubscriptionPayload +Autogenerated return type of EpicSetSubscription | Name | Type | Description | | --- | ---- | ---------- | @@ -310,14 +355,27 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `epic` | Epic | The epic after mutation | -### EpicTreeReorderPayload +## EpicTreeReorderPayload + +Autogenerated return type of EpicTreeReorder | Name | Type | Description | | --- | ---- | ---------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Reasons why the mutation failed. | -### Group +## GrafanaIntegration + +| Name | Type | Description | +| --- | ---- | ---------- | +| `id` | ID! | Internal ID of the Grafana integration | +| `grafanaUrl` | String! | Url for the Grafana host for the Grafana integration | +| `token` | String! | API token for the Grafana integration | +| `enabled` | Boolean! | Indicates whether Grafana integration is enabled | +| `createdAt` | Time! | Timestamp of the issue's creation | +| `updatedAt` | Time! | Timestamp of the issue's last activity | + +## Group | Name | Type | Description | | --- | ---- | ---------- | @@ -335,18 +393,19 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `userPermissions` | GroupPermissions! | Permissions for the current user on the resource | | `webUrl` | String! | Web URL of the group | | `avatarUrl` | String | Avatar URL of the group | +| `mentionsDisabled` | Boolean | Indicates if a group is disabled from getting mentioned | | `parent` | Group | Parent group | | `epicsEnabled` | Boolean | Indicates if Epics are enabled for namespace | | `groupTimelogsEnabled` | Boolean | Indicates if Group timelogs are enabled for namespace | | `epic` | Epic | Find a single epic | -### GroupPermissions +## GroupPermissions | Name | Type | Description | | --- | ---- | ---------- | -| `readGroup` | Boolean! | Whether or not a user can perform `read_group` on this resource | +| `readGroup` | Boolean! | Indicates the user can perform `read_group` on this resource | -### Issue +## Issue | Name | Type | Description | | --- | ---- | ---------- | @@ -369,7 +428,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `webPath` | String! | Web path of the issue | | `webUrl` | String! | Web URL of the issue | | `relativePosition` | Int | Relative position of the issue (used for positioning in epic tree and issue boards) | -| `subscribed` | Boolean! | Boolean flag for whether the currently logged in user is subscribed to this issue | +| `subscribed` | Boolean! | Indicates the currently logged in user is subscribed to the issue | | `timeEstimate` | Int! | Time estimate of the issue | | `totalTimeSpent` | Int! | Total time reported as spent on the issue | | `closedAt` | Time | Timestamp of when the issue was closed | @@ -378,23 +437,27 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `taskCompletionStatus` | TaskCompletionStatus! | Task completion status of the issue | | `epic` | Epic | Epic to which this issue belongs | | `weight` | Int | Weight of the issue | -| `designs` | DesignCollection | Deprecated. Use `design_collection`. | +| `designs` | DesignCollection | Deprecated. Use `design_collection` | | `designCollection` | DesignCollection | Collection of design images associated with this issue | -### IssuePermissions +## IssuePermissions + +Check permissions for the current user on a issue | Name | Type | Description | | --- | ---- | ---------- | -| `readIssue` | Boolean! | Whether or not a user can perform `read_issue` on this resource | -| `adminIssue` | Boolean! | Whether or not a user can perform `admin_issue` on this resource | -| `updateIssue` | Boolean! | Whether or not a user can perform `update_issue` on this resource | -| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | -| `reopenIssue` | Boolean! | Whether or not a user can perform `reopen_issue` on this resource | -| `readDesign` | Boolean! | Whether or not a user can perform `read_design` on this resource | -| `createDesign` | Boolean! | Whether or not a user can perform `create_design` on this resource | -| `destroyDesign` | Boolean! | Whether or not a user can perform `destroy_design` on this resource | +| `readIssue` | Boolean! | Indicates the user can perform `read_issue` on this resource | +| `adminIssue` | Boolean! | Indicates the user can perform `admin_issue` on this resource | +| `updateIssue` | Boolean! | Indicates the user can perform `update_issue` on this resource | +| `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | +| `reopenIssue` | Boolean! | Indicates the user can perform `reopen_issue` on this resource | +| `readDesign` | Boolean! | Indicates the user can perform `read_design` on this resource | +| `createDesign` | Boolean! | Indicates the user can perform `create_design` on this resource | +| `destroyDesign` | Boolean! | Indicates the user can perform `destroy_design` on this resource | -### IssueSetConfidentialPayload +## IssueSetConfidentialPayload + +Autogenerated return type of IssueSetConfidential | Name | Type | Description | | --- | ---- | ---------- | @@ -402,7 +465,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `issue` | Issue | The issue after mutation | -### IssueSetDueDatePayload +## IssueSetDueDatePayload + +Autogenerated return type of IssueSetDueDate | Name | Type | Description | | --- | ---- | ---------- | @@ -410,7 +475,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `issue` | Issue | The issue after mutation | -### IssueSetWeightPayload +## IssueSetWeightPayload + +Autogenerated return type of IssueSetWeight | Name | Type | Description | | --- | ---- | ---------- | @@ -418,7 +485,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `issue` | Issue | The issue after mutation | -### Label +## Label | Name | Type | Description | | --- | ---- | ---------- | @@ -429,7 +496,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `color` | String! | Background color of the label | | `textColor` | String! | Text color of the label | -### MarkAsSpamSnippetPayload +## MarkAsSpamSnippetPayload + +Autogenerated return type of MarkAsSpamSnippet | Name | Type | Description | | --- | ---- | ---------- | @@ -437,7 +506,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `snippet` | Snippet | The snippet after mutation | -### MergeRequest +## MergeRequest | Name | Type | Description | | --- | ---- | ---------- | @@ -491,20 +560,24 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `reference` | String! | Internal reference of the merge request. Returned in shortened format by default | | `taskCompletionStatus` | TaskCompletionStatus! | Completion status of tasks | -### MergeRequestPermissions +## MergeRequestPermissions + +Check permissions for the current user on a merge request | Name | Type | Description | | --- | ---- | ---------- | -| `readMergeRequest` | Boolean! | Whether or not a user can perform `read_merge_request` on this resource | -| `adminMergeRequest` | Boolean! | Whether or not a user can perform `admin_merge_request` on this resource | -| `updateMergeRequest` | Boolean! | Whether or not a user can perform `update_merge_request` on this resource | -| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | -| `pushToSourceBranch` | Boolean! | Whether or not a user can perform `push_to_source_branch` on this resource | -| `removeSourceBranch` | Boolean! | Whether or not a user can perform `remove_source_branch` on this resource | -| `cherryPickOnCurrentMergeRequest` | Boolean! | Whether or not a user can perform `cherry_pick_on_current_merge_request` on this resource | -| `revertOnCurrentMergeRequest` | Boolean! | Whether or not a user can perform `revert_on_current_merge_request` on this resource | +| `readMergeRequest` | Boolean! | Indicates the user can perform `read_merge_request` on this resource | +| `adminMergeRequest` | Boolean! | Indicates the user can perform `admin_merge_request` on this resource | +| `updateMergeRequest` | Boolean! | Indicates the user can perform `update_merge_request` on this resource | +| `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | +| `pushToSourceBranch` | Boolean! | Indicates the user can perform `push_to_source_branch` on this resource | +| `removeSourceBranch` | Boolean! | Indicates the user can perform `remove_source_branch` on this resource | +| `cherryPickOnCurrentMergeRequest` | Boolean! | Indicates the user can perform `cherry_pick_on_current_merge_request` on this resource | +| `revertOnCurrentMergeRequest` | Boolean! | Indicates the user can perform `revert_on_current_merge_request` on this resource | -### MergeRequestSetAssigneesPayload +## MergeRequestSetAssigneesPayload + +Autogenerated return type of MergeRequestSetAssignees | Name | Type | Description | | --- | ---- | ---------- | @@ -512,7 +585,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `mergeRequest` | MergeRequest | The merge request after mutation | -### MergeRequestSetLabelsPayload +## MergeRequestSetLabelsPayload + +Autogenerated return type of MergeRequestSetLabels | Name | Type | Description | | --- | ---- | ---------- | @@ -520,7 +595,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `mergeRequest` | MergeRequest | The merge request after mutation | -### MergeRequestSetLockedPayload +## MergeRequestSetLockedPayload + +Autogenerated return type of MergeRequestSetLocked | Name | Type | Description | | --- | ---- | ---------- | @@ -528,7 +605,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `mergeRequest` | MergeRequest | The merge request after mutation | -### MergeRequestSetMilestonePayload +## MergeRequestSetMilestonePayload + +Autogenerated return type of MergeRequestSetMilestone | Name | Type | Description | | --- | ---- | ---------- | @@ -536,7 +615,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `mergeRequest` | MergeRequest | The merge request after mutation | -### MergeRequestSetSubscriptionPayload +## MergeRequestSetSubscriptionPayload + +Autogenerated return type of MergeRequestSetSubscription | Name | Type | Description | | --- | ---- | ---------- | @@ -544,7 +625,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `mergeRequest` | MergeRequest | The merge request after mutation | -### MergeRequestSetWipPayload +## MergeRequestSetWipPayload + +Autogenerated return type of MergeRequestSetWip | Name | Type | Description | | --- | ---- | ---------- | @@ -552,14 +635,14 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `mergeRequest` | MergeRequest | The merge request after mutation | -### Metadata +## Metadata | Name | Type | Description | | --- | ---- | ---------- | | `version` | String! | Version | | `revision` | String! | Revision | -### Milestone +## Milestone | Name | Type | Description | | --- | ---- | ---------- | @@ -572,7 +655,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `createdAt` | Time! | Timestamp of milestone creation | | `updatedAt` | Time! | Timestamp of last milestone update | -### Namespace +## Namespace | Name | Type | Description | | --- | ---- | ---------- | @@ -588,7 +671,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `requestAccessEnabled` | Boolean | Indicates if users can request access to namespace | | `rootStorageStatistics` | RootStorageStatistics | Aggregated storage statistics of the namespace. Only available for root namespaces | -### Note +## Note | Name | Type | Description | | --- | ---- | ---------- | @@ -607,17 +690,19 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `resolvedAt` | Time | Timestamp of the note's resolution | | `position` | DiffPosition | The position of this note on a diff | -### NotePermissions +## NotePermissions | Name | Type | Description | | --- | ---- | ---------- | -| `readNote` | Boolean! | Whether or not a user can perform `read_note` on this resource | -| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | -| `adminNote` | Boolean! | Whether or not a user can perform `admin_note` on this resource | -| `resolveNote` | Boolean! | Whether or not a user can perform `resolve_note` on this resource | -| `awardEmoji` | Boolean! | Whether or not a user can perform `award_emoji` on this resource | +| `readNote` | Boolean! | Indicates the user can perform `read_note` on this resource | +| `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | +| `adminNote` | Boolean! | Indicates the user can perform `admin_note` on this resource | +| `resolveNote` | Boolean! | Indicates the user can perform `resolve_note` on this resource | +| `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | -### PageInfo +## PageInfo + +Information about pagination in a connection. | Name | Type | Description | | --- | ---- | ---------- | @@ -626,34 +711,34 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `startCursor` | String | When paginating backwards, the cursor to continue. | | `endCursor` | String | When paginating forwards, the cursor to continue. | -### Pipeline +## Pipeline | Name | Type | Description | | --- | ---- | ---------- | | `userPermissions` | PipelinePermissions! | Permissions for the current user on the resource | -| `id` | ID! | | -| `iid` | String! | | -| `sha` | String! | | -| `beforeSha` | String | | -| `status` | PipelineStatusEnum! | | -| `detailedStatus` | DetailedStatus! | | +| `id` | ID! | ID of the pipeline | +| `iid` | String! | Internal ID of the pipeline | +| `sha` | String! | SHA of the pipeline's commit | +| `beforeSha` | String | Base SHA of the source branch | +| `status` | PipelineStatusEnum! | Status of the pipeline (CREATED, WAITING_FOR_RESOURCE, PREPARING, PENDING, RUNNING, FAILED, SUCCESS, CANCELED, SKIPPED, MANUAL, SCHEDULED) | +| `detailedStatus` | DetailedStatus! | Detailed status of the pipeline | | `duration` | Int | Duration of the pipeline in seconds | | `coverage` | Float | Coverage percentage | -| `createdAt` | Time! | | -| `updatedAt` | Time! | | -| `startedAt` | Time | | -| `finishedAt` | Time | | -| `committedAt` | Time | | +| `createdAt` | Time! | Timestamp of the pipeline's creation | +| `updatedAt` | Time! | Timestamp of the pipeline's last activity | +| `startedAt` | Time | Timestamp when the pipeline was started | +| `finishedAt` | Time | Timestamp of the pipeline's completion | +| `committedAt` | Time | Timestamp of the pipeline's commit | -### PipelinePermissions +## PipelinePermissions | Name | Type | Description | | --- | ---- | ---------- | -| `updatePipeline` | Boolean! | Whether or not a user can perform `update_pipeline` on this resource | -| `adminPipeline` | Boolean! | Whether or not a user can perform `admin_pipeline` on this resource | -| `destroyPipeline` | Boolean! | Whether or not a user can perform `destroy_pipeline` on this resource | +| `updatePipeline` | Boolean! | Indicates the user can perform `update_pipeline` on this resource | +| `adminPipeline` | Boolean! | Indicates the user can perform `admin_pipeline` on this resource | +| `destroyPipeline` | Boolean! | Indicates the user can perform `destroy_pipeline` on this resource | -### Project +## Project | Name | Type | Description | | --- | ---- | ---------- | @@ -673,7 +758,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `forksCount` | Int! | Number of times the project has been forked | | `createdAt` | Time | Timestamp of the project creation | | `lastActivityAt` | Time | Timestamp of the project last activity | -| `archived` | Boolean | Archived status of the project | +| `archived` | Boolean | Indicates the archived status of the project | | `visibility` | String | Visibility of the project | | `containerRegistryEnabled` | Boolean | Indicates if the project stores Docker container images in a container registry | | `sharedRunnersEnabled` | Boolean | Indicates if shared runners are enabled on the project | @@ -693,6 +778,8 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `onlyAllowMergeIfAllDiscussionsAreResolved` | Boolean | Indicates if merge requests of the project can only be merged when all the discussions are resolved | | `printingMergeRequestLinkEnabled` | Boolean | Indicates if a link to create or view a merge request should display after a push to Git repositories of the project from the command line | | `removeSourceBranchAfterMerge` | Boolean | Indicates if `Delete source branch` option should be enabled by default for all new merge requests of the project | +| `autocloseReferencedIssues` | Boolean | Indicates if issues referenced by merge requests and commits within the default branch are closed automatically | +| `suggestionCommitMessage` | String | The commit message used to apply merge request suggestions | | `namespace` | Namespace | Namespace of the project | | `group` | Group | Group of the project | | `statistics` | ProjectStatistics | Statistics of the project | @@ -700,56 +787,57 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `mergeRequest` | MergeRequest | A single merge request of the project | | `issue` | Issue | A single issue of the project | | `sentryDetailedError` | SentryDetailedError | Detailed version of a Sentry error on the project | +| `grafanaIntegration` | GrafanaIntegration | Grafana integration details for the project | | `serviceDeskEnabled` | Boolean | Indicates if the project has service desk enabled. | | `serviceDeskAddress` | String | E-mail address of the service desk. | -### ProjectPermissions - -| Name | Type | Description | -| --- | ---- | ---------- | -| `changeNamespace` | Boolean! | Whether or not a user can perform `change_namespace` on this resource | -| `changeVisibilityLevel` | Boolean! | Whether or not a user can perform `change_visibility_level` on this resource | -| `renameProject` | Boolean! | Whether or not a user can perform `rename_project` on this resource | -| `removeProject` | Boolean! | Whether or not a user can perform `remove_project` on this resource | -| `archiveProject` | Boolean! | Whether or not a user can perform `archive_project` on this resource | -| `removeForkProject` | Boolean! | Whether or not a user can perform `remove_fork_project` on this resource | -| `removePages` | Boolean! | Whether or not a user can perform `remove_pages` on this resource | -| `readProject` | Boolean! | Whether or not a user can perform `read_project` on this resource | -| `createMergeRequestIn` | Boolean! | Whether or not a user can perform `create_merge_request_in` on this resource | -| `readWiki` | Boolean! | Whether or not a user can perform `read_wiki` on this resource | -| `readProjectMember` | Boolean! | Whether or not a user can perform `read_project_member` on this resource | -| `createIssue` | Boolean! | Whether or not a user can perform `create_issue` on this resource | -| `uploadFile` | Boolean! | Whether or not a user can perform `upload_file` on this resource | -| `readCycleAnalytics` | Boolean! | Whether or not a user can perform `read_cycle_analytics` on this resource | -| `downloadCode` | Boolean! | Whether or not a user can perform `download_code` on this resource | -| `downloadWikiCode` | Boolean! | Whether or not a user can perform `download_wiki_code` on this resource | -| `forkProject` | Boolean! | Whether or not a user can perform `fork_project` on this resource | -| `readCommitStatus` | Boolean! | Whether or not a user can perform `read_commit_status` on this resource | -| `requestAccess` | Boolean! | Whether or not a user can perform `request_access` on this resource | -| `createPipeline` | Boolean! | Whether or not a user can perform `create_pipeline` on this resource | -| `createPipelineSchedule` | Boolean! | Whether or not a user can perform `create_pipeline_schedule` on this resource | -| `createMergeRequestFrom` | Boolean! | Whether or not a user can perform `create_merge_request_from` on this resource | -| `createWiki` | Boolean! | Whether or not a user can perform `create_wiki` on this resource | -| `pushCode` | Boolean! | Whether or not a user can perform `push_code` on this resource | -| `createDeployment` | Boolean! | Whether or not a user can perform `create_deployment` on this resource | -| `pushToDeleteProtectedBranch` | Boolean! | Whether or not a user can perform `push_to_delete_protected_branch` on this resource | -| `adminWiki` | Boolean! | Whether or not a user can perform `admin_wiki` on this resource | -| `adminProject` | Boolean! | Whether or not a user can perform `admin_project` on this resource | -| `updatePages` | Boolean! | Whether or not a user can perform `update_pages` on this resource | -| `adminRemoteMirror` | Boolean! | Whether or not a user can perform `admin_remote_mirror` on this resource | -| `createLabel` | Boolean! | Whether or not a user can perform `create_label` on this resource | -| `updateWiki` | Boolean! | Whether or not a user can perform `update_wiki` on this resource | -| `destroyWiki` | Boolean! | Whether or not a user can perform `destroy_wiki` on this resource | -| `createPages` | Boolean! | Whether or not a user can perform `create_pages` on this resource | -| `destroyPages` | Boolean! | Whether or not a user can perform `destroy_pages` on this resource | -| `readPagesContent` | Boolean! | Whether or not a user can perform `read_pages_content` on this resource | -| `adminOperations` | Boolean! | Whether or not a user can perform `admin_operations` on this resource | -| `createSnippet` | Boolean! | Whether or not a user can perform `create_snippet` on this resource | -| `readDesign` | Boolean! | Whether or not a user can perform `read_design` on this resource | -| `createDesign` | Boolean! | Whether or not a user can perform `create_design` on this resource | -| `destroyDesign` | Boolean! | Whether or not a user can perform `destroy_design` on this resource | - -### ProjectStatistics +## ProjectPermissions + +| Name | Type | Description | +| --- | ---- | ---------- | +| `changeNamespace` | Boolean! | Indicates the user can perform `change_namespace` on this resource | +| `changeVisibilityLevel` | Boolean! | Indicates the user can perform `change_visibility_level` on this resource | +| `renameProject` | Boolean! | Indicates the user can perform `rename_project` on this resource | +| `removeProject` | Boolean! | Indicates the user can perform `remove_project` on this resource | +| `archiveProject` | Boolean! | Indicates the user can perform `archive_project` on this resource | +| `removeForkProject` | Boolean! | Indicates the user can perform `remove_fork_project` on this resource | +| `removePages` | Boolean! | Indicates the user can perform `remove_pages` on this resource | +| `readProject` | Boolean! | Indicates the user can perform `read_project` on this resource | +| `createMergeRequestIn` | Boolean! | Indicates the user can perform `create_merge_request_in` on this resource | +| `readWiki` | Boolean! | Indicates the user can perform `read_wiki` on this resource | +| `readProjectMember` | Boolean! | Indicates the user can perform `read_project_member` on this resource | +| `createIssue` | Boolean! | Indicates the user can perform `create_issue` on this resource | +| `uploadFile` | Boolean! | Indicates the user can perform `upload_file` on this resource | +| `readCycleAnalytics` | Boolean! | Indicates the user can perform `read_cycle_analytics` on this resource | +| `downloadCode` | Boolean! | Indicates the user can perform `download_code` on this resource | +| `downloadWikiCode` | Boolean! | Indicates the user can perform `download_wiki_code` on this resource | +| `forkProject` | Boolean! | Indicates the user can perform `fork_project` on this resource | +| `readCommitStatus` | Boolean! | Indicates the user can perform `read_commit_status` on this resource | +| `requestAccess` | Boolean! | Indicates the user can perform `request_access` on this resource | +| `createPipeline` | Boolean! | Indicates the user can perform `create_pipeline` on this resource | +| `createPipelineSchedule` | Boolean! | Indicates the user can perform `create_pipeline_schedule` on this resource | +| `createMergeRequestFrom` | Boolean! | Indicates the user can perform `create_merge_request_from` on this resource | +| `createWiki` | Boolean! | Indicates the user can perform `create_wiki` on this resource | +| `pushCode` | Boolean! | Indicates the user can perform `push_code` on this resource | +| `createDeployment` | Boolean! | Indicates the user can perform `create_deployment` on this resource | +| `pushToDeleteProtectedBranch` | Boolean! | Indicates the user can perform `push_to_delete_protected_branch` on this resource | +| `adminWiki` | Boolean! | Indicates the user can perform `admin_wiki` on this resource | +| `adminProject` | Boolean! | Indicates the user can perform `admin_project` on this resource | +| `updatePages` | Boolean! | Indicates the user can perform `update_pages` on this resource | +| `adminRemoteMirror` | Boolean! | Indicates the user can perform `admin_remote_mirror` on this resource | +| `createLabel` | Boolean! | Indicates the user can perform `create_label` on this resource | +| `updateWiki` | Boolean! | Indicates the user can perform `update_wiki` on this resource | +| `destroyWiki` | Boolean! | Indicates the user can perform `destroy_wiki` on this resource | +| `createPages` | Boolean! | Indicates the user can perform `create_pages` on this resource | +| `destroyPages` | Boolean! | Indicates the user can perform `destroy_pages` on this resource | +| `readPagesContent` | Boolean! | Indicates the user can perform `read_pages_content` on this resource | +| `adminOperations` | Boolean! | Indicates the user can perform `admin_operations` on this resource | +| `createSnippet` | Boolean! | Indicates the user can perform `create_snippet` on this resource | +| `readDesign` | Boolean! | Indicates the user can perform `read_design` on this resource | +| `createDesign` | Boolean! | Indicates the user can perform `create_design` on this resource | +| `destroyDesign` | Boolean! | Indicates the user can perform `destroy_design` on this resource | + +## ProjectStatistics | Name | Type | Description | | --- | ---- | ---------- | @@ -761,7 +849,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `packagesSize` | Int! | Packages size of the project | | `wikiSize` | Int | Wiki size of the project | -### RemoveAwardEmojiPayload +## RemoveAwardEmojiPayload + +Autogenerated return type of RemoveAwardEmoji | Name | Type | Description | | --- | ---- | ---------- | @@ -769,7 +859,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `awardEmoji` | AwardEmoji | The award emoji after mutation | -### Repository +## Repository | Name | Type | Description | | --- | ---- | ---------- | @@ -778,7 +868,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `exists` | Boolean! | Indicates a corresponding Git repository exists on disk | | `tree` | Tree | Tree of the repository | -### RootStorageStatistics +## RootStorageStatistics | Name | Type | Description | | --- | ---- | ---------- | @@ -789,7 +879,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `packagesSize` | Int! | The packages size in bytes | | `wikiSize` | Int! | The wiki size in bytes | -### SentryDetailedError +## SentryDetailedError | Name | Type | Description | | --- | ---- | ---------- | @@ -814,15 +904,19 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `lastReleaseLastCommit` | String | Commit the error was last seen | | `firstReleaseShortVersion` | String | Release version the error was first seen | | `lastReleaseShortVersion` | String | Release version the error was last seen | +| `gitlabCommit` | String | GitLab commit SHA attributed to the Error based on the release version | +| `gitlabCommitPath` | String | Path to the GitLab page for the GitLab commit attributed to the error | -### SentryErrorFrequency +## SentryErrorFrequency | Name | Type | Description | | --- | ---- | ---------- | | `time` | Time! | Time the error frequency stats were recorded | | `count` | Int! | Count of errors received since the previously recorded time | -### Snippet +## Snippet + +Represents a snippet entry | Name | Type | Description | | --- | ---- | ---------- | @@ -841,38 +935,40 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `rawUrl` | String! | Raw URL of the snippet | | `descriptionHtml` | String | The GitLab Flavored Markdown rendering of `description` | -### SnippetPermissions +## SnippetPermissions | Name | Type | Description | | --- | ---- | ---------- | -| `createNote` | Boolean! | Whether or not a user can perform `create_note` on this resource | -| `awardEmoji` | Boolean! | Whether or not a user can perform `award_emoji` on this resource | -| `readSnippet` | Boolean! | Whether or not a user can perform `read_snippet` on this resource | -| `updateSnippet` | Boolean! | Whether or not a user can perform `update_snippet` on this resource | -| `adminSnippet` | Boolean! | Whether or not a user can perform `admin_snippet` on this resource | -| `reportSnippet` | Boolean! | Whether or not a user can perform `report_snippet` on this resource | +| `createNote` | Boolean! | Indicates the user can perform `create_note` on this resource | +| `awardEmoji` | Boolean! | Indicates the user can perform `award_emoji` on this resource | +| `readSnippet` | Boolean! | Indicates the user can perform `read_snippet` on this resource | +| `updateSnippet` | Boolean! | Indicates the user can perform `update_snippet` on this resource | +| `adminSnippet` | Boolean! | Indicates the user can perform `admin_snippet` on this resource | +| `reportSnippet` | Boolean! | Indicates the user can perform `report_snippet` on this resource | -### Submodule +## Submodule | Name | Type | Description | | --- | ---- | ---------- | -| `id` | ID! | | -| `sha` | String! | Last commit sha for entry | -| `name` | String! | | -| `type` | EntryType! | | -| `path` | String! | | -| `flatPath` | String! | | -| `webUrl` | String | | -| `treeUrl` | String | | +| `id` | ID! | ID of the entry | +| `sha` | String! | Last commit sha for the entry | +| `name` | String! | Name of the entry | +| `type` | EntryType! | Type of tree entry | +| `path` | String! | Path of the entry | +| `flatPath` | String! | Flat path of the entry | +| `webUrl` | String | Web URL for the sub-module | +| `treeUrl` | String | Tree URL for the sub-module | + +## TaskCompletionStatus -### TaskCompletionStatus +Completion status of tasks | Name | Type | Description | | --- | ---- | ---------- | | `count` | Int! | Number of total tasks | | `completedCount` | Int! | Number of completed tasks | -### Timelog +## Timelog | Name | Type | Description | | --- | ---- | ---------- | @@ -881,7 +977,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `user` | User! | The user that logged the time | | `issue` | Issue | The issue that logged time was added to | -### Todo +## Todo + +Representing a todo entry | Name | Type | Description | | --- | ---- | ---------- | @@ -895,7 +993,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `state` | TodoStateEnum! | State of the todo | | `createdAt` | Time! | Timestamp this todo was created | -### TodoMarkDonePayload +## TodoMarkDonePayload + +Autogenerated return type of TodoMarkDone | Name | Type | Description | | --- | ---- | ---------- | @@ -903,7 +1003,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `todo` | Todo! | The requested todo | -### TodoRestorePayload +## TodoRestorePayload + +Autogenerated return type of TodoRestore | Name | Type | Description | | --- | ---- | ---------- | @@ -911,7 +1013,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `todo` | Todo! | The requested todo | -### TodosMarkAllDonePayload +## TodosMarkAllDonePayload + +Autogenerated return type of TodosMarkAllDone | Name | Type | Description | | --- | ---- | ---------- | @@ -919,34 +1023,40 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `updatedIds` | ID! => Array | Ids of the updated todos | -### ToggleAwardEmojiPayload +## ToggleAwardEmojiPayload + +Autogenerated return type of ToggleAwardEmoji | Name | Type | Description | | --- | ---- | ---------- | | `clientMutationId` | String | A unique identifier for the client performing the mutation. | | `errors` | String! => Array | Reasons why the mutation failed. | | `awardEmoji` | AwardEmoji | The award emoji after mutation | -| `toggledOn` | Boolean! | True when the emoji was awarded, false when it was removed | +| `toggledOn` | Boolean! | Indicates the status of the emoji. True if the toggle awarded the emoji, and false if the toggle removed the emoji. | -### Tree +## Tree | Name | Type | Description | | --- | ---- | ---------- | | `lastCommit` | Commit | Last commit for the tree | -### TreeEntry +## TreeEntry + +Represents a directory | Name | Type | Description | | --- | ---- | ---------- | -| `id` | ID! | | -| `sha` | String! | Last commit sha for entry | -| `name` | String! | | -| `type` | EntryType! | | -| `path` | String! | | -| `flatPath` | String! | | -| `webUrl` | String | | +| `id` | ID! | ID of the entry | +| `sha` | String! | Last commit sha for the entry | +| `name` | String! | Name of the entry | +| `type` | EntryType! | Type of tree entry | +| `path` | String! | Path of the entry | +| `flatPath` | String! | Flat path of the entry | +| `webUrl` | String | Web URL for the tree entry (directory) | -### UpdateEpicPayload +## UpdateEpicPayload + +Autogenerated return type of UpdateEpic | Name | Type | Description | | --- | ---- | ---------- | @@ -954,7 +1064,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `epic` | Epic | The epic after mutation | -### UpdateNotePayload +## UpdateNotePayload + +Autogenerated return type of UpdateNote | Name | Type | Description | | --- | ---- | ---------- | @@ -962,7 +1074,9 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `note` | Note | The note after mutation | -### UpdateSnippetPayload +## UpdateSnippetPayload + +Autogenerated return type of UpdateSnippet | Name | Type | Description | | --- | ---- | ---------- | @@ -970,7 +1084,7 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `errors` | String! => Array | Reasons why the mutation failed. | | `snippet` | Snippet | The snippet after mutation | -### User +## User | Name | Type | Description | | --- | ---- | ---------- | @@ -980,8 +1094,8 @@ The API can be explored interactively using the [GraphiQL IDE](../index.md#graph | `avatarUrl` | String! | URL of the user's avatar | | `webUrl` | String! | Web URL of the user | -### UserPermissions +## UserPermissions | Name | Type | Description | | --- | ---- | ---------- | -| `createSnippet` | Boolean! | Whether or not a user can perform `create_snippet` on this resource | +| `createSnippet` | Boolean! | Indicates the user can perform `create_snippet` on this resource | diff --git a/doc/api/group_labels.md b/doc/api/group_labels.md index f3c3a821354..f41f3a0a402 100644 --- a/doc/api/group_labels.md +++ b/doc/api/group_labels.md @@ -4,6 +4,9 @@ This API supports managing of [group labels](../user/project/labels.md#project-labels-and-group-labels). It allows to list, create, update, and delete group labels. Furthermore, users can subscribe and unsubscribe to and from group labels. +NOTE: **Note:** +The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413). + ## List group labels Get all labels for a given group. @@ -32,6 +35,7 @@ Example response: "color": "#FF0000", "text_color" : "#FFFFFF", "description": null, + "description_html": null, "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -43,6 +47,7 @@ Example response: "color": "#228B22", "text_color" : "#FFFFFF", "description": null, + "description_html": null, "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -78,6 +83,7 @@ Example response: "color": "#FF0000", "text_color" : "#FFFFFF", "description": null, + "description_html": null, "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -113,6 +119,7 @@ Example response: "color": "#FFA500", "text_color" : "#FFFFFF", "description": "Describes new ideas", + "description_html": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -149,6 +156,7 @@ Example response: "color": "#FFA500", "text_color" : "#FFFFFF", "description": "Describes new ideas", + "description_html": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -204,6 +212,7 @@ Example response: "color": "#FFA500", "text_color" : "#FFFFFF", "description": "Describes new ideas", + "description_html": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -239,6 +248,7 @@ Example response: "color": "#FFA500", "text_color" : "#FFFFFF", "description": "Describes new ideas", + "description_html": "Describes new ideas", "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, diff --git a/doc/api/group_milestones.md b/doc/api/group_milestones.md index 61edd2522be..a77f12de5a1 100644 --- a/doc/api/group_milestones.md +++ b/doc/api/group_milestones.md @@ -98,7 +98,7 @@ Parameters: ## Delete group milestone -Only for user with developer access to the group. +Only for users with Developer access to the group. ``` DELETE /groups/:id/milestones/:milestone_id diff --git a/doc/api/groups.md b/doc/api/groups.md index 32e2a88f25b..f4dfefe3cb7 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -40,6 +40,7 @@ GET /groups "auto_devops_enabled": null, "subgroup_creation_level": "owner", "emails_disabled": null, + "mentions_disabled": null, "lfs_enabled": true, "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", "web_url": "http://localhost:3000/groups/foo-bar", @@ -73,6 +74,7 @@ GET /groups?statistics=true "auto_devops_enabled": null, "subgroup_creation_level": "owner", "emails_disabled": null, + "mentions_disabled": null, "lfs_enabled": true, "avatar_url": "http://localhost:3000/uploads/group/avatar/1/foo.jpg", "web_url": "http://localhost:3000/groups/foo-bar", @@ -144,6 +146,7 @@ GET /groups/:id/subgroups "auto_devops_enabled": null, "subgroup_creation_level": "owner", "emails_disabled": null, + "mentions_disabled": null, "lfs_enabled": true, "avatar_url": "http://gitlab.example.com/uploads/group/avatar/1/foo.jpg", "web_url": "http://gitlab.example.com/groups/foo-bar", @@ -486,6 +489,7 @@ Parameters: | `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | | `subgroup_creation_level` | integer | no | Allowed to create subgroups. Can be `owner` (Owners), or `maintainer` (Maintainers). | | `emails_disabled` | boolean | no | Disable email notifications | +| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | | `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. | @@ -531,6 +535,7 @@ PUT /groups/:id | `auto_devops_enabled` | boolean | no | Default to Auto DevOps pipeline for all projects within this group. | | `subgroup_creation_level` | integer | no | Allowed to create subgroups. Can be `owner` (Owners), or `maintainer` (Maintainers). | | `emails_disabled` | boolean | no | Disable email notifications | +| `mentions_disabled` | boolean | no | Disable the capability of a group from getting mentioned | | `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. | diff --git a/doc/api/issue_links.md b/doc/api/issue_links.md index 9351b3e4dd5..7c7901d5551 100644 --- a/doc/api/issue_links.md +++ b/doc/api/issue_links.md @@ -48,6 +48,7 @@ Parameters: "web_url": "http://example.com/example/example/issues/14", "confidential": false, "weight": null, + "link_type": "relates_to" } ] ``` @@ -66,6 +67,7 @@ POST /projects/:id/issues/:issue_iid/links | `issue_iid` | integer | yes | The internal ID of a project's issue | | `target_project_id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) of a target project | | `target_issue_iid` | integer/string | yes | The internal ID of a target project's issue | +| `link_type` | string | no | The type of the relation ("relates_to", "blocks", "is_blocked_by"), defaults to "relates_to"). Ignored unless `issue_link_types` feature flag is enabled. | ```bash curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/4/issues/1/links?target_project_id=5&target_issue_iid=1" @@ -134,7 +136,8 @@ Example response: "web_url": "http://example.com/example/example/issues/14", "confidential": false, "weight": null, - } + }, + "link_type": "relates_to" } ``` @@ -151,6 +154,7 @@ DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id | `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 | | `issue_link_id` | integer/string | yes | The ID of an issue relationship | +| `link_type` | string | no | The type of the relation ('relates_to', 'blocks', 'is_blocked_by'), defaults to 'relates_to' | ```json { @@ -213,6 +217,7 @@ DELETE /projects/:id/issues/:issue_iid/links/:issue_link_id "web_url": "http://example.com/example/example/issues/14", "confidential": false, "weight": null, - } + }, + "link_type": "relates_to" } ``` diff --git a/doc/api/issues.md b/doc/api/issues.md index fe551cfb397..3c28b55d1d6 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -12,6 +12,14 @@ are paginated. Read more on [pagination](README.md#pagination). +CAUTION: **Deprecation** +> `reference` attribute in response is deprecated in favour of `references`. +> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/merge_requests/20354) + +NOTE: **Note** +> `references.relative` is relative to the group / project that the issue is being requested. When issue is fetched from its project +> `relative` format would be the same as `short` format and when requested across groups / projects it is expected to be the same as `full` format. + ## List issues Get all issues the authenticated user has access to. By default it @@ -39,7 +47,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`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413)| | `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)_ | @@ -121,7 +129,12 @@ Example response: "merge_requests_count": 0, "user_notes_count": 1, "due_date": "2016-07-22", - "web_url": "http://example.com/example/example/issues/6", + "web_url": "http://example.com/my-group/my-project/issues/6", + "references": { + "short": "#6", + "relative": "my-group/my-project#6", + "full": "my-group/my-project#6" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -190,7 +203,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`, `:description_html`, `:text_color`. Default is `false`. The `description_html` attribute was introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413) | | `iids[]` | integer array | 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)_ | @@ -270,7 +283,12 @@ Example response: "closed_by" : null, "user_notes_count": 1, "due_date": null, - "web_url": "http://example.com/example/example/issues/1", + "web_url": "http://example.com/my-group/my-project/issues/1", + "references": { + "short": "#1", + "relative": "my-project#1", + "full": "my-group/my-project#1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -340,7 +358,7 @@ GET /projects/:id/issues?confidential=true | `iids[]` | integer array | 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`, `:description_html`, `:text_color`. Default is `false`. `description_html` Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413) | | `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)_ | @@ -426,7 +444,12 @@ Example response: }, "user_notes_count": 1, "due_date": "2016-07-22", - "web_url": "http://example.com/example/example/issues/1", + "web_url": "http://example.com/my-group/my-project/issues/1", + "references": { + "short": "#1", + "relative": "#1", + "full": "my-group/my-project#1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -543,7 +566,12 @@ Example response: "subscribed": false, "user_notes_count": 1, "due_date": null, - "web_url": "http://example.com/example/example/issues/1", + "web_url": "http://example.com/my-group/my-project/issues/1", + "references": { + "short": "#1", + "relative": "#1", + "full": "my-group/my-project#1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -668,7 +696,12 @@ Example response: "subscribed" : true, "user_notes_count": 0, "due_date": null, - "web_url": "http://example.com/example/example/issues/14", + "web_url": "http://example.com/my-group/my-project/issues/14", + "references": { + "short": "#14", + "relative": "#14", + "full": "my-group/my-project#14" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -778,7 +811,12 @@ Example response: "subscribed" : true, "user_notes_count": 0, "due_date": "2016-07-22", - "web_url": "http://example.com/example/example/issues/15", + "web_url": "http://example.com/my-group/my-project/issues/15", + "references": { + "short": "#15", + "relative": "#15", + "full": "my-group/my-project#15" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -900,7 +938,12 @@ Example response: "web_url": "https://gitlab.example.com/solon.cremin" }, "due_date": null, - "web_url": "http://example.com/example/example/issues/11", + "web_url": "http://example.com/my-group/my-project/issues/11", + "references": { + "short": "#11", + "relative": "#11", + "full": "my-group/my-project#11" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1001,7 +1044,12 @@ Example response: "web_url": "https://gitlab.example.com/solon.cremin" }, "due_date": null, - "web_url": "http://example.com/example/example/issues/11", + "web_url": "http://example.com/my-group/my-project/issues/11", + "references": { + "short": "#11", + "relative": "#11", + "full": "my-group/my-project#11" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1095,7 +1143,12 @@ Example response: }, "subscribed": false, "due_date": null, - "web_url": "http://example.com/example/example/issues/12", + "web_url": "http://example.com/my-group/my-project/issues/12", + "references": { + "short": "#12", + "relative": "#12", + "full": "my-group/my-project#12" + }, "confidential": false, "discussion_locked": false, "task_completion_status":{ @@ -1197,7 +1250,12 @@ Example response: "downvotes": 0, "merge_requests_count": 0, "due_date": null, - "web_url": "http://example.com/example/example/issues/110", + "web_url": "http://example.com/my-group/my-project/issues/10", + "references": { + "short": "#10", + "relative": "#10", + "full": "my-group/my-project#10" + }, "confidential": false, "discussion_locked": false, "task_completion_status":{ @@ -1436,6 +1494,11 @@ Example response: "force_remove_source_branch": false, "reference": "!11", "web_url": "https://gitlab.example.com/twitter/flight/merge_requests/4", + "references": { + "short": "!4", + "relative": "!4", + "full": "twitter/flight!4" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1566,6 +1629,12 @@ Example response: "should_remove_source_branch": null, "force_remove_source_branch": false, "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432", + "reference": "!6432", + "references": { + "short": "!6432", + "relative": "!6432", + "full": "gitlab-org/gitlab-test!6432" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, diff --git a/doc/api/keys.md b/doc/api/keys.md index 5dedb630a27..30b0cda6c8b 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -128,3 +128,65 @@ Example response: } } ``` + +Deploy Keys are bound to the creating user, so if you query with a deploy key +fingerprint you get additional information about the projects using that key: + +```sh +curl --header "PRIVATE-TOKEN: <your_access_token>" 'https://gitlab.example.com/api/v4/keys?fingerprint=SHA256%3AnUhzNyftwADy8AH3wFY31tAKs7HufskYTte2aXo%2FlCg +``` + +Example response: + +```json +{ + "id": 1, + "title": "Sample key 1", + "key": "ssh-rsa AAAAB3NzaC1yc2EAAAABJQAAAIEAiPWx6WM4lhHNedGfBpPJNPpZ7yKu+dnn1SJejgt1016k6YjzGGphH2TUxwKzxcKDKKezwkpfnxPkSMkuEspGRt/aZZ9wa++Oi7Qkr8prgHc4soW6NUlfDzpvZK2H5E7eQaSeP3SAwGmQKUFHCddNaP0L+hM7zhFNzjFvpaMgJw0=", + "created_at": "2019-11-14T15:11:13.222Z", + "user": { + "id": 1, + "name": "Administrator", + "username": "root", + "state": "active", + "avatar_url": "https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "http://0.0.0.0:3000/root", + "created_at": "2019-11-14T15:09:34.831Z", + "bio": null, + "location": null, + "public_email": "", + "skype": "", + "linkedin": "", + "twitter": "", + "website_url": "", + "organization": null, + "last_sign_in_at": "2019-11-16T22:41:26.663Z", + "confirmed_at": "2019-11-14T15:09:34.575Z", + "last_activity_on": "2019-11-20", + "email": "admin@example.com", + "theme_id": 1, + "color_scheme_id": 1, + "projects_limit": 100000, + "current_sign_in_at": "2019-11-19T14:42:18.078Z", + "identities": [ + ], + "can_create_group": true, + "can_create_project": true, + "two_factor_enabled": false, + "external": false, + "private_profile": false, + "shared_runners_minutes_limit": null, + "extra_shared_runners_minutes_limit": null + }, + "deploy_keys_projects": [ + { + "id": 1, + "deploy_key_id": 1, + "project_id": 1, + "created_at": "2020-01-09T07:32:52.453Z", + "updated_at": "2020-01-09T07:32:52.453Z", + "can_push": false + } + ] +} +``` diff --git a/doc/api/labels.md b/doc/api/labels.md index 525dbe02e5f..ac5156e8c20 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -1,5 +1,8 @@ # Labels API +NOTE: **Note:** +The `description_html` - was added to response JSON in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413). + ## List labels Get all labels for a given project. @@ -28,6 +31,7 @@ Example response: "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Bug reported by user", + "description_html": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, @@ -41,6 +45,7 @@ Example response: "text_color" : "#FFFFFF", "name" : "confirmed", "description": "Confirmed issue", + "description_html": "Confirmed issue", "open_issues_count": 2, "closed_issues_count": 5, "open_merge_requests_count": 0, @@ -54,6 +59,7 @@ Example response: "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Critical issue. Need fix ASAP", + "description_html": "Critical issue. Need fix ASAP", "open_issues_count": 1, "closed_issues_count": 3, "open_merge_requests_count": 1, @@ -67,6 +73,7 @@ Example response: "color" : "#f0ad4e", "text_color" : "#FFFFFF", "description": "Issue about documentation", + "description_html": "Issue about documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, @@ -80,6 +87,7 @@ Example response: "text_color" : "#FFFFFF", "name" : "enhancement", "description": "Enhancement proposal", + "description_html": "Enhancement proposal", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, @@ -117,6 +125,7 @@ Example response: "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Bug reported by user", + "description_html": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, @@ -155,6 +164,7 @@ Example response: "color" : "#5843AD", "text_color" : "#FFFFFF", "description":null, + "description_html":null, "open_issues_count": 0, "closed_issues_count": 0, "open_merge_requests_count": 0, @@ -214,6 +224,7 @@ Example response: "color" : "#8E44AD", "text_color" : "#FFFFFF", "description": "Documentation", + "description_html": "Documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, @@ -252,6 +263,7 @@ Example response: "name" : "documentation", "color" : "#8E44AD", "description": "Documentation", + "description_html": "Documentation", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 2, @@ -289,6 +301,7 @@ Example response: "color" : "#d9534f", "text_color" : "#FFFFFF", "description": "Bug reported by user", + "description_html": "Bug reported by user", "open_issues_count": 1, "closed_issues_count": 0, "open_merge_requests_count": 1, diff --git a/doc/api/merge_request_approvals.md b/doc/api/merge_request_approvals.md index 264e198c596..4552a56d808 100644 --- a/doc/api/merge_request_approvals.md +++ b/doc/api/merge_request_approvals.md @@ -6,7 +6,7 @@ Configuration for approvals on all Merge Requests (MR) in the project. Must be a ### Get Configuration ->**Note:** This API endpoint is only available on 10.6 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. You can request information about a project's approval configuration using the following endpoint: @@ -31,7 +31,7 @@ GET /projects/:id/approvals ### Change configuration ->**Note:** This API endpoint is only available on 10.6 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. If you are allowed to, you can change approval configuration using the following endpoint: @@ -63,7 +63,7 @@ POST /projects/:id/approvals ### Get project-level rules ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can request information about a project's approval rules using the following endpoint: @@ -137,7 +137,7 @@ GET /projects/:id/approval_rules ### Create project-level rule ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can create project approval rules using the following endpoint: @@ -213,7 +213,7 @@ POST /projects/:id/approval_rules ### Update project-level rule ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can update project approval rules using the following endpoint: @@ -292,7 +292,7 @@ PUT /projects/:id/approval_rules/:approval_rule_id ### Delete project-level rule ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can delete project approval rules using the following endpoint: @@ -310,7 +310,7 @@ DELETE /projects/:id/approval_rules/:approval_rule_id ### Change allowed approvers >**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead. ->**Note:** This API endpoint is only available on 10.6 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. If you are allowed to, you can change approvers and approver groups using the following endpoint: @@ -373,7 +373,7 @@ Configuration for approvals on a specific Merge Request. Must be authenticated f ### Get Configuration ->**Note:** This API endpoint is only available on 8.9 Starter and above. +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.9. You can request information about a merge request's approval status using the following endpoint: @@ -419,7 +419,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approvals ### Change approval configuration ->**Note:** This API endpoint is only available on 10.6 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. If you are allowed to, you can change `approvals_required` using the following endpoint: @@ -456,7 +456,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/approvals ### Change allowed approvers for Merge Request >**Note:** This API endpoint has been deprecated. Please use Approval Rule API instead. ->**Note:** This API endpoint is only available on 10.6 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/183) in [GitLab Starter](https://about.gitlab.com/pricing/) 10.6. If you are allowed to, you can change approvers and approver groups using the following endpoint: @@ -598,7 +598,7 @@ This includes additional information about the users who have already approved ### Get merge request level rules ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13712) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can request information about a merge request's approval rules using the following endpoint: @@ -674,7 +674,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/approval_rules ### Create merge request level rule ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can create merge request approval rules using the following endpoint: @@ -757,12 +757,12 @@ will be used. ### Update merge request level rule ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can update merge request approval rules using the following endpoint: ``` -PUT /projects/:id/merge_request/:merge_request_iid/approval_rules/:approval_rule_id +PUT /projects/:id/merge_requests/:merge_request_iid/approval_rules/:approval_rule_id ``` **Important:** Approvers and groups not in the `users`/`groups` param will be **removed** @@ -841,7 +841,7 @@ These are system generated rules. ### Delete merge request level rule ->**Note:** This API endpoint is only available on 12.3 Starter and above. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11877) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. You can delete merge request approval rules using the following endpoint: @@ -862,7 +862,7 @@ These are system generated rules. ## Approve Merge Request ->**Note:** This API endpoint is only available on 8.9 Starter and above. +> Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 8.9. If you are allowed to, you can approve a merge request using the following endpoint: @@ -925,7 +925,7 @@ does not match, the response code will be `409`. ## Unapprove Merge Request ->**Note:** This API endpoint is only available on 9.0 Starter and above. +>Introduced in [GitLab Starter](https://about.gitlab.com/pricing/) 9.0. If you did approve a merge request, you can unapprove it using the following endpoint: diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 541aa03450f..d85310de159 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -2,6 +2,14 @@ Every API call to merge requests must be authenticated. +CAUTION: **Deprecation** +> `reference` attribute in response is deprecated in favour of `references`. +> Introduced [GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/merge_requests/20354) + +NOTE: **Note** +> `references.relative` is relative to the group / project that the merge request is being requested. When merge request is fetched from its project +> `relative` format would be the same as `short` format and when requested across groups / projects it is expected to be the same as `full` format. + ## List merge requests > [Introduced][ce-13060] in GitLab 9.5. @@ -37,6 +45,7 @@ Parameters: | `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. | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413) | | `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 | @@ -134,6 +143,11 @@ Parameters: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "my-group/my-project!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -200,6 +214,7 @@ Parameters: | `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. | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413) | | `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 | @@ -296,6 +311,11 @@ Parameters: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -355,6 +375,7 @@ Parameters: | `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. | +| `with_labels_details` | Boolean | no | If `true`, response will return more details for each label in labels field: `:name`, `:color`, `:description`, `:description_html`, `:text_color`. Default is `false`. Introduced in [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21413)| | `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 | @@ -448,6 +469,11 @@ Parameters: "should_remove_source_branch": true, "force_remove_source_branch": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "my-project!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -524,7 +550,7 @@ Parameters: }, "user" : { "can_merge" : false - } + }, "assignee": { "id": 1, "name": "Administrator", @@ -574,6 +600,11 @@ Parameters: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -779,7 +810,12 @@ Parameters: "should_remove_source_branch": true, "force_remove_source_branch": false, "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1", + "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "discussion_locked": false, "time_stats": { "time_estimate": 0, @@ -989,6 +1025,11 @@ order for it to take effect: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1143,6 +1184,11 @@ Must include at least one non-required attribute from above. "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1313,6 +1359,11 @@ Parameters: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1486,6 +1537,11 @@ Parameters: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1557,6 +1613,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/rebase | --------- | ---- | -------- | ----------- | | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `merge_request_iid` | integer | yes | The internal ID of the merge request | +| `skip_ci` | boolean | no | Set to `true` to skip creating a CI pipeline | ```bash curl --header "PRIVATE-TOKEN: <your_access_token>" https://gitlab.example.com/api/v4/projects/76/merge_requests/1/rebase @@ -1772,6 +1829,11 @@ Example response: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -1918,6 +1980,11 @@ Example response: "allow_collaboration": false, "allow_maintainer_to_push": false, "web_url": "http://gitlab.example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, "time_stats": { "time_estimate": 0, "total_time_spent": 0, @@ -2078,7 +2145,12 @@ Example response: "should_remove_source_branch": true, "force_remove_source_branch": false, "squash": false, - "web_url": "http://example.com/example/example/merge_requests/1" + "web_url": "http://example.com/my-group/my-project/merge_requests/1", + "references": { + "short": "!1", + "relative": "!1", + "full": "my-group/my-project!1" + }, }, "target_url": "https://gitlab.example.com/gitlab-org/gitlab-ci/merge_requests/7", "body": "Et voluptas laudantium minus nihil recusandae ut accusamus earum aut non.", diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 44844470430..f3a1b7323ec 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -96,7 +96,7 @@ Parameters: ## Delete project milestone -Only for user with developer access to the project. +Only for users with Developer access to the project. ``` DELETE /projects/:id/milestones/:milestone_id @@ -137,7 +137,7 @@ Parameters: > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53861) in GitLab 11.9 -Only for users with developer access to the group. +Only for users with Developer access to the group. ``` POST /projects/:id/milestones/:milestone_id/promote diff --git a/doc/api/packages.md b/doc/api/packages.md index 5b490b872da..cadd5f0dc75 100644 --- a/doc/api/packages.md +++ b/doc/api/packages.md @@ -31,13 +31,15 @@ Example response: "id": 1, "name": "com/mycompany/my-app", "version": "1.0-SNAPSHOT", - "package_type": "maven" + "package_type": "maven", + "created_at": "2019-11-27T03:37:38.711Z" }, { "id": 2, "name": "@foo/bar", "version": "1.0.3", - "package_type": "npm" + "package_type": "npm", + "created_at": "2019-11-27T03:37:38.711Z" } ] ``` @@ -76,6 +78,18 @@ Example response: "_links": { "web_path": "/namespace1/project1/-/packages/1", "delete_api_path": "/namespace1/project1/-/packages/1" + }, + "created_at": "2019-11-27T03:37:38.711Z", + "build_info": { + "pipeline": { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + } } }, { @@ -86,6 +100,18 @@ Example response: "_links": { "web_path": "/namespace1/project1/-/packages/1", "delete_api_path": "/namespace1/project1/-/packages/1" + }, + "created_at": "2019-11-27T03:37:38.711Z", + "build_info": { + "pipeline": { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + } } } ] @@ -128,6 +154,18 @@ Example response: "_links": { "web_path": "/namespace1/project1/-/packages/1", "delete_api_path": "/namespace1/project1/-/packages/1" + }, + "created_at": "2019-11-27T03:37:38.711Z", + "build_info": { + "pipeline": { + "id": 123, + "status": "pending", + "ref": "new-pipeline", + "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a", + "web_url": "https://example.com/foo/bar/pipelines/47", + "created_at": "2016-08-11T11:28:34.085Z", + "updated_at": "2016-08-11T11:32:35.169Z", + } } } ``` diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index e1b2c12dd00..4bf44723065 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -14,7 +14,7 @@ GET /projects/:id/pipelines | `scope` | string | no | The scope of pipelines, one of: `running`, `pending`, `finished`, `branches`, `tags` | | `status` | string | no | The status of pipelines, one of: `running`, `pending`, `success`, `failed`, `canceled`, `skipped` | | `ref` | string | no | The ref of pipelines | -| `sha` | string | no | The sha or pipelines | +| `sha` | string | no | The sha of pipelines | | `yaml_errors`| boolean | no | Returns pipelines with invalid configurations | | `name`| string | no | The name of the user who triggered pipelines | | `username`| string | no | The username of the user who triggered pipelines | diff --git a/doc/api/project_level_variables.md b/doc/api/project_level_variables.md index 591911bb8ec..d4bda992f7c 100644 --- a/doc/api/project_level_variables.md +++ b/doc/api/project_level_variables.md @@ -86,7 +86,6 @@ curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitla "value": "new value", "protected": false, "variable_type": "env_var", - "protected": false, "masked": false, "environment_scope": "*" } diff --git a/doc/api/projects.md b/doc/api/projects.md index 209d41d62cd..8cfba68acee 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -156,6 +156,8 @@ When the user is authenticated and `simple` is not set this returns something li "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 37, "storage_size": 1038090, @@ -254,6 +256,8 @@ When the user is authenticated and `simple` is not set this returns something li "packages_enabled": true, "service_desk_enabled": false, "service_desk_address": null, + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 12, "storage_size": 2066080, @@ -385,6 +389,8 @@ This endpoint supports [keyset pagination](README.md#keyset-based-pagination) fo "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 37, "storage_size": 1038090, @@ -483,6 +489,8 @@ This endpoint supports [keyset pagination](README.md#keyset-based-pagination) fo "packages_enabled": true, "service_desk_enabled": false, "service_desk_address": null, + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 12, "storage_size": 2066080, @@ -593,6 +601,8 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 37, "storage_size": 1038090, @@ -688,6 +698,8 @@ Example response: "packages_enabled": true, "service_desk_enabled": false, "service_desk_address": null, + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 12, "storage_size": 2066080, @@ -755,6 +767,14 @@ GET /projects/:id "snippets_enabled": false, "resolve_outdated_diff_discussions": false, "container_registry_enabled": false, + "container_expiration_policy": { + "cadence": "7d", + "enabled": false, + "keep_n": null, + "older_than": null, + "name_regex": null, + "next_run_at": "2020-01-07T21:42:58.658Z" + }, "created_at": "2013-09-30T13:46:02Z", "last_activity_at": "2013-09-30T13:46:02Z", "creator_id": 3, @@ -829,6 +849,8 @@ GET /projects/:id "packages_enabled": true, "service_desk_enabled": false, "service_desk_address": null, + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "statistics": { "commit_count": 37, "storage_size": 1038090, @@ -979,6 +1001,7 @@ POST /projects | `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | +| `container_expiration_policy_attributes` | hash | no | Update the container expiration policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `enabled` (boolean) | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | @@ -986,6 +1009,7 @@ POST /projects | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `merge_method` | string | no | Set the [merge method](#project-merge-method) used | +| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch | | `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | @@ -1050,6 +1074,8 @@ POST /projects/user/:user_id | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `merge_method` | string | no | Set the [merge method](#project-merge-method) used | +| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch | +| `suggestion_commit_message` | string | no | The commit message used to apply merge request suggestions | | `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | @@ -1106,6 +1132,7 @@ PUT /projects/:id | `snippets_access_level` | string | no | One of `disabled`, `private` or `enabled` | | `resolve_outdated_diff_discussions` | boolean | no | Automatically resolve merge request diffs discussions on lines changed with a push | | `container_registry_enabled` | boolean | no | Enable container registry for this project | +| `container_expiration_policy_attributes` | hash | no | Update the container expiration policy for this project. Accepts: `cadence` (string), `keep_n` (string), `older_than` (string), `name_regex` (string), `enabled` (boolean) | | `shared_runners_enabled` | boolean | no | Enable shared runners for this project | | `visibility` | string | no | See [project visibility level](#project-visibility-level) | | `import_url` | string | no | URL to import repository from | @@ -1113,6 +1140,8 @@ PUT /projects/:id | `only_allow_merge_if_pipeline_succeeds` | boolean | no | Set whether merge requests can only be merged with successful jobs | | `only_allow_merge_if_all_discussions_are_resolved` | boolean | no | Set whether merge requests can only be merged when all the discussions are resolved | | `merge_method` | string | no | Set the [merge method](#project-merge-method) used | +| `autoclose_referenced_issues` | boolean | no | Set whether auto-closing referenced issues on default branch | +| `suggestion_commit_message` | string | no | The commit message used to apply merge request suggestions | | `remove_source_branch_after_merge` | boolean | no | Enable `Delete source branch` option by default for all new merge requests | | `lfs_enabled` | boolean | no | Enable LFS | | `request_access_enabled` | boolean | no | Allow users to request member access | @@ -1244,6 +1273,8 @@ Example responses: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "_links": { "self": "http://example.com/api/v4/projects", "issues": "http://example.com/api/v4/projects/1/issues", @@ -1332,6 +1363,8 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "_links": { "self": "http://example.com/api/v4/projects", "issues": "http://example.com/api/v4/projects/1/issues", @@ -1419,6 +1452,8 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "_links": { "self": "http://example.com/api/v4/projects", "issues": "http://example.com/api/v4/projects/1/issues", @@ -1593,6 +1628,8 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "_links": { "self": "http://example.com/api/v4/projects", "issues": "http://example.com/api/v4/projects/1/issues", @@ -1699,6 +1736,8 @@ Example response: "remove_source_branch_after_merge": false, "request_access_enabled": false, "merge_method": "merge", + "autoclose_referenced_issues": true, + "suggestion_commit_message": null, "_links": { "self": "http://example.com/api/v4/projects", "issues": "http://example.com/api/v4/projects/1/issues", diff --git a/doc/api/services.md b/doc/api/services.md index 02a31ba9d38..52123320651 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -2,6 +2,63 @@ >**Note:** This API requires an access token with Maintainer or Owner permissions +## List all active services + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/21330) in GitLab 12.7. + +Get a list of all active project services. + +``` +GET /projects/:id/services +``` + +Example response: + +```json +[ + { + "id": 75, + "title": "Jenkins CI", + "slug": "jenkins", + "created_at": "2019-11-20T11:20:25.297Z", + "updated_at": "2019-11-20T12:24:37.498Z", + "active": true, + "commit_events": true, + "push_events": true, + "issues_events": true, + "confidential_issues_events": true, + "merge_requests_events": true, + "tag_push_events": false, + "note_events": true, + "confidential_note_events": true, + "pipeline_events": true, + "wiki_page_events": true, + "job_events": true, + "comment_on_event_enabled": true + } + { + "id": 76, + "title": "Alerts endpoint", + "slug": "alerts", + "created_at": "2019-11-20T11:20:25.297Z", + "updated_at": "2019-11-20T12:24:37.498Z", + "active": true, + "commit_events": true, + "push_events": true, + "issues_events": true, + "confidential_issues_events": true, + "merge_requests_events": true, + "tag_push_events": true, + "note_events": true, + "confidential_note_events": true, + "pipeline_events": true, + "wiki_page_events": true, + "job_events": true, + "comment_on_event_enabled": true + } +] +``` + ## Asana Asana - Teamwork without email @@ -373,6 +430,7 @@ Parameters: | `send_from_committer_email` | boolean | false | Send from committer | | `push_events` | boolean | false | Enable notifications for push events | | `tag_push_events` | boolean | false | Enable notifications for tag push events | +| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected". Notifications will be always fired for tag pushes. | ### Delete Emails on push service @@ -669,6 +727,7 @@ Parameters: | `jira_issue_transition_id` | string | no | The ID of a transition that moves issues to a closed state. You can find this number under the Jira workflow administration (**Administration > Issues > Workflows**) by selecting **View** under **Operations** of the desired workflow of your project. The ID of each state can be found inside the parenthesis of each transition name under the **Transitions (id)** column. By default, this ID is set to `2`. | | `commit_events` | boolean | false | Enable notifications for commit events | | `merge_requests_events` | boolean | false | Enable notifications for merge request events | +| `comment_on_event_enabled` | boolean | false | Enable comments inside Jira issues on each GitLab event (commit / merge request) | ### Delete Jira service @@ -696,6 +755,7 @@ Example response: { "id": 4, "title": "Slack slash commands", + "slug": "slack-slash-commands", "created_at": "2017-06-27T05:51:39-07:00", "updated_at": "2017-06-27T05:51:39-07:00", "active": true, @@ -707,6 +767,7 @@ Example response: "note_events": true, "job_events": true, "pipeline_events": true, + "comment_on_event_enabled": false, "properties": { "token": "<your_access_token>" } diff --git a/doc/api/settings.md b/doc/api/settings.md index fa0efcaa5f0..316e5bb0109 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -180,7 +180,7 @@ are listed in the descriptions of the relevant settings. | Attribute | Type | Required | Description | | --------- | ---- | :------: | ----------- | -| `admin_notification_email` | string | no | Abuse reports will be sent to this address if it is set. Abuse reports are always available in the admin area. | +| `admin_notification_email` | string | no | Abuse reports will be sent to this address if it is set. Abuse reports are always available in the Admin Area. | | `after_sign_out_path` | string | no | Where to redirect users after logout. | | `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. | diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index 1b8c23b8e2d..b09b11dfd2a 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -3,7 +3,7 @@ All methods require administrator authorization. The URL endpoint of the system hooks can also be configured using the UI in -the admin area under **Hooks** (`/admin/hooks`). +the **Admin Area > System Hooks** (`/admin/hooks`). Read more about [system hooks](../system_hooks/system_hooks.md). diff --git a/doc/api/wikis.md b/doc/api/wikis.md index 570fb2168b2..035a89d80a5 100644 --- a/doc/api/wikis.md +++ b/doc/api/wikis.md @@ -86,7 +86,7 @@ POST /projects/:id/wikis | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `content` | string | yes | The content of the wiki page | | `title` | string | yes | The title of the wiki page | -| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` | +| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | ```bash curl --data "format=rdoc&title=Hello&content=Hello world" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/wikis" @@ -116,7 +116,7 @@ PUT /projects/:id/wikis/:slug | `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `content` | string | yes if `title` is not provided | The content of the wiki page | | `title` | string | yes if `content` is not provided | The title of the wiki page | -| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, and `asciidoc` | +| `format` | string | no | The format of the wiki page. Available formats are: `markdown` (default), `rdoc`, `asciidoc` and `org` | | `slug` | string | yes | The slug (a unique string) of the wiki page | ```bash diff --git a/doc/ci/README.md b/doc/ci/README.md index d1cf7e63c63..8a33298ea63 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -127,6 +127,7 @@ Its feature set is listed on the table below according to DevOps stages. | [GitLab Pages](../user/project/pages/index.md) | Deploy static websites. | | [GitLab Releases](../user/project/releases/index.md) | Add release notes to Git tags. | | [Review Apps](review_apps/index.md) | Configure GitLab CI/CD to preview code changes. | +| [Cloud deployment](cloud_deployment/index.md) | Deploy your application to a main cloud provider. | |---+---| | **Secure** || | [Container Scanning](../user/application_security/container_scanning/index.md) **(ULTIMATE)** | Check your Docker containers for known vulnerabilities.| diff --git a/doc/ci/caching/index.md b/doc/ci/caching/index.md index b6518c87e13..a85c096db70 100644 --- a/doc/ci/caching/index.md +++ b/doc/ci/caching/index.md @@ -59,7 +59,7 @@ Caches: - Are stored where the Runner is installed **and** uploaded to S3 if [distributed cache is enabled](https://docs.gitlab.com/runner/configuration/autoscale.html#distributed-runners-caching). - If defined per job, are used: - By the same job in a subsequent pipeline. - - By subsequent jobs in the same pipeline, if the they have identical dependencies. + - By subsequent jobs in the same pipeline, if they have identical dependencies. Artifacts: diff --git a/doc/ci/chatops/README.md b/doc/ci/chatops/README.md index d9236b47a9a..ec3d13e7500 100644 --- a/doc/ci/chatops/README.md +++ b/doc/ci/chatops/README.md @@ -61,7 +61,7 @@ ls: ## GitLab ChatOps Examples The GitLab.com team created a repository of [common ChatOps scripts they use to interact with our Production instance of GitLab](https://gitlab.com/gitlab-com/chatops). They are likely useful -to other adminstrators of GitLab instances and can serve as inspiration for ChatOps scripts you can write to interact with your own applications. +to other administrators of GitLab instances and can serve as inspiration for ChatOps scripts you can write to interact with your own applications. ## GitLab ChatOps icon diff --git a/doc/ci/cloud_deployment/index.md b/doc/ci/cloud_deployment/index.md new file mode 100644 index 00000000000..07ffe5439e3 --- /dev/null +++ b/doc/ci/cloud_deployment/index.md @@ -0,0 +1,63 @@ +--- +type: howto +--- + +# Cloud deployment + +Interacting with a major cloud provider such as Amazon AWS may have become a much needed task that's +part of your delivery process. GitLab is making this process less painful by providing Docker images +that come with the needed libraries and tools pre-installed. +By referencing them in your CI/CD pipeline, you'll be able to interact with your chosen +cloud provider more easily. + +## AWS + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/31167) in GitLab 12.6. + +GitLab's AWS Docker image provides the [AWS Command Line Interface](https://aws.amazon.com/cli/), +which enables you to run `aws` commands. As part of your deployment strategy, you can run `aws` commands directly from +`.gitlab-ci.yml` by specifying [GitLab's AWS Docker image](https://gitlab.com/gitlab-org/cloud-deploy). + +Some credentials are required to be able to run `aws` commands: + +1. Sign up for [an AWS account](https://docs.aws.amazon.com/IAM/latest/UserGuide/getting-set-up.html) if you don't have one yet. +1. Log in onto the console and create [a new IAM user](https://console.aws.amazon.com/iam/home#/home). +1. Select your newly created user to access its details. Navigate to **Security credentials > Create a new access key**. + + NOTE: **Note:** + A new **Access key ID** and **Secret access key** pair will be generated. Please take a note of them right away. + +1. In your GitLab project, go to **Settings > CI / CD**. Set the Access key ID and Secret access key as [environment variables](../variables/README.md#gitlab-cicd-environment-variables), using the following variable names: + + | Env. variable name | Value | + |:------------------------|:-------------------------| + | `AWS_ACCESS_KEY_ID` | Your "Access key ID" | + | `AWS_SECRET_ACCESS_KEY` | Your "Secret access key" | + +1. You can now use `aws` commands in the `.gitlab-ci.yml` file of this project: + + ```yml + deploy: + stage: deploy + image: registry.gitlab.com/gitlab-org/cloud-deploy:latest # see the note below + script: + - aws s3 ... + - aws create-deployment ... + ``` + + NOTE: **Note:** + Please note that the image used in the example above + (`registry.gitlab.com/gitlab-org/cloud-deploy:latest`) is hosted on the [GitLab + Container Registry](../../user/packages/container_registry/index.md) and is + ready to use. Alternatively, replace the image with another one hosted on [AWS ECR](#aws-ecr). + +### AWS ECR + +Instead of referencing an image hosted on the GitLab Registry, you are free to +reference any other image hosted on any third-party registry, such as +[Amazon Elastic Container Registry (ECR)](https://aws.amazon.com/ecr). + +To do so, please make sure to [push your image into your ECR +repository](https://docs.aws.amazon.com/AmazonECR/latest/userguide/docker-push-ecr-image.html) +before referencing it in your `.gitlab-ci.yml` file and replace the `image` +path to point to your ECR. diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index e58fe5e4604..8c6069bd939 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -32,14 +32,14 @@ A one-line example can be seen below: sudo gitlab-runner register \ --url "https://gitlab.example.com/" \ --registration-token "PROJECT_REGISTRATION_TOKEN" \ - --description "docker-ruby-2.1" \ + --description "docker-ruby:2.6" \ --executor "docker" \ - --docker-image ruby:2.1 \ + --docker-image ruby:2.6 \ --docker-services postgres:latest \ --docker-services mysql:latest ``` -The registered runner will use the `ruby:2.1` Docker image and will run two +The registered runner will use the `ruby:2.6` Docker image and will run two services, `postgres:latest` and `mysql:latest`, both of which will be accessible during the build process. @@ -194,7 +194,7 @@ services that you want to use during build time: ```yaml default: - image: ruby:2.2 + image: ruby:2.6 services: - postgres:9.3 @@ -214,15 +214,15 @@ default: before_script: - bundle install -test:2.1: - image: ruby:2.1 +test:2.6: + image: ruby:2.6 services: - postgres:9.3 script: - bundle exec rake spec -test:2.2: - image: ruby:2.2 +test:2.7: + image: ruby:2.7 services: - postgres:9.4 script: @@ -235,7 +235,7 @@ for `image` and `services`: ```yaml default: image: - name: ruby:2.2 + name: ruby:2.6 entrypoint: ["/bin/bash"] services: @@ -277,7 +277,7 @@ services: command: ["postgres"] image: - name: ruby:2.2 + name: ruby:2.6 entrypoint: ["/bin/bash"] before_script: @@ -513,7 +513,7 @@ To define which should be used, the GitLab Runner process reads the configuratio NOTE: **Note:** GitLab Runner reads this configuration **only** from `config.toml` and ignores it if -it's provided as an environment variable. This is because GitLab Runnner uses **only** +it's provided as an environment variable. This is because GitLab Runner uses **only** `config.toml` configuration and doesn't interpolate **ANY** environment variables at runtime. @@ -773,7 +773,7 @@ time. 1. Create any service container: `mysql`, `postgresql`, `mongodb`, `redis`. 1. Create cache container to store all volumes as defined in `config.toml` and - `Dockerfile` of build image (`ruby:2.1` as in above example). + `Dockerfile` of build image (`ruby:2.6` as in above example). 1. Create build container and link any service container to build container. 1. Start build container and send job script to the container. 1. Run job script. @@ -818,11 +818,11 @@ Finally, create a build container by executing the `build_script` file we created earlier: ```sh -docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.1 /bin/bash < build_script +docker run --name build -i --link=service-mysql:mysql --link=service-postgres:postgres ruby:2.6 /bin/bash < build_script ``` The above command will create a container named `build` that is spawned from -the `ruby:2.1` image and has two services linked to it. The `build_script` is +the `ruby:2.6` image and has two services linked to it. The `build_script` is piped using STDIN to the bash interpreter which in turn executes the `build_script` in the `build` container. diff --git a/doc/ci/enable_or_disable_ci.md b/doc/ci/enable_or_disable_ci.md index ff104d4e177..7c7640e23c3 100644 --- a/doc/ci/enable_or_disable_ci.md +++ b/doc/ci/enable_or_disable_ci.md @@ -38,18 +38,16 @@ To enable or disable GitLab CI/CD Pipelines in your project: 1. Navigate to **Settings > General > Visibility, project features, permissions**. 1. Expand the **Repository** section -1. Enable or disable the **Pipelines** checkbox as required. +1. Enable or disable the **Pipelines** toggle as required. **Project visibility** will also affect pipeline visibility. If set to: - **Private**: Only project members can access pipelines. - **Internal** or **Public**: Pipelines can be set to either **Only Project Members** - or **Everyone With Access** via the drop-down box. + or **Everyone With Access** via the dropdown box. Press **Save changes** for the settings to take effect. - - ## Site-wide admin setting You can disable GitLab CI/CD site-wide, by modifying the settings in `gitlab.yml` diff --git a/doc/ci/environments.md b/doc/ci/environments.md index 245a4d20e2d..55e93e19f66 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -232,6 +232,11 @@ declaring their names dynamically in `.gitlab-ci.yml`. Dynamic environments are a fundamental part of [Review apps](review_apps/index.md). +### Configuring incremental rollouts + +Learn how to release production changes to only a portion of your Kubernetes pods with +[incremental rollouts](environments/incremental_rollouts.md). + #### Allowed variables The `name` and `url` parameters for dynamic environments can use most available CI/CD variables, diff --git a/doc/ci/environments/img/incremental_rollouts_play_v12_7.png b/doc/ci/environments/img/incremental_rollouts_play_v12_7.png Binary files differnew file mode 100644 index 00000000000..314c4a07af0 --- /dev/null +++ b/doc/ci/environments/img/incremental_rollouts_play_v12_7.png diff --git a/doc/ci/environments/img/timed_rollout_v12_7.png b/doc/ci/environments/img/timed_rollout_v12_7.png Binary files differnew file mode 100644 index 00000000000..6b83bfc574e --- /dev/null +++ b/doc/ci/environments/img/timed_rollout_v12_7.png diff --git a/doc/ci/environments/incremental_rollouts.md b/doc/ci/environments/incremental_rollouts.md new file mode 100644 index 00000000000..0fa0af6a9fb --- /dev/null +++ b/doc/ci/environments/incremental_rollouts.md @@ -0,0 +1,113 @@ +--- +type: concepts, howto +--- + +# Incremental Rollouts with GitLab CI/CD + +When rolling out changes to your application, it is possible to release production changes +to only a portion of your Kubernetes pods as a risk mitigation strategy. By releasing +production changes gradually, error rates or performance degradation can be monitored, and +if there are no problems, all pods can be updated. + +GitLab supports both manually triggered and timed rollouts to a Kubernetes production system +using Incremental Rollouts. When using Manual Rollouts, the release of each tranche +of pods is manually triggered, while in Timed Rollouts, the release is performed in +tranches after a default pause of 5 minutes. +Timed rollouts can also be manually triggered before the pause period has expired. + +Manual and Timed rollouts are included automatically in projects controlled by +[AutoDevOps](../../topics/autodevops/index.md), but they are also configurable through +GitLab CI/CD in the `.gitlab-ci.yml` configuration file. + +Manually triggered rollouts can be implemented with your [Continuously Delivery](../introduction/index.md#continuous-delivery) +methodology, while timed rollouts do not require intervention and can be part of your +[Continuously Deployment](../introduction/index.md#continuous-deployment) strategy. +You can also combine both of them in a way that the app is deployed automatically +unless you eventually intervene manually if necessary. + +We created sample applications to demonstrate the three options, which you can +use as examples to build your own: + +- [Manual incremental rollouts](https://gitlab.com/gl-release/incremental-rollout-example/blob/master/.gitlab-ci.yml) +- [Timed incremental rollouts](https://gitlab.com/gl-release/timed-rollout-example/blob/master/.gitlab-ci.yml) +- [Both manual and timed rollouts](https://gitlab.com/gl-release/incremental-timed-rollout-example/blob/master/.gitlab-ci.yml) + +## Manual Rollouts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5415) in GitLab 10.8. + +It is possible to configure GitLab to do incremental rollouts manually through `.gitlab-ci.yml`. Manual configuration +allows more control over the this feature. The steps in an incremental rollout depend on the +number of pods that are defined for the deployment, which are configured when the Kubernetes +cluster is created. + +For example, if your application has 10 pods and a 10% rollout job is run, the new instance of the +application will be deployed to a single pod while the remaining 9 will present the previous instance. + +First we [define the template as manual](https://gitlab.com/gl-release/incremental-rollout-example/blob/master/.gitlab-ci.yml#L100-103): + +```yml +.manual_rollout_template: &manual_rollout_template + <<: *rollout_template + stage: production + when: manual +``` + +Then we [define the rollout amount for each step](https://gitlab.com/gl-release/incremental-rollout-example/blob/master/.gitlab-ci.yml#L152-155): + +```yml +rollout 10%: + <<: *manual_rollout_template + variables: + ROLLOUT_PERCENTAGE: 10 +``` + +When the jobs are built, a **play** button will appear next to the job's name. Click the **play** button +to release each stage of pods. You can also rollback by running a lower percentage job. Once 100% +is reached, you cannot roll back using this method. It is still possible to roll back by redeploying +the old version using the **Rollback** button on the environment page. + + + +A [deployable application](https://gitlab.com/gl-release/incremental-rollout-example) is +available, demonstrating manually triggered incremental rollouts. + +## Timed Rollouts + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/7545) in GitLab 11.4. + +Timed rollouts behave in the same way as manual rollouts, except that each job is defined with a delay +in minutes before it will deploy. Clicking on the job will reveal the countdown. + + + +It is possible to combine this functionality with manual incremental rollouts so that the job will +countdown and then deploy. + +First we [define the template as timed](https://gitlab.com/gl-release/timed-rollout-example/blob/master/.gitlab-ci.yml#L86-89): + +```yml +.timed_rollout_template: &timed_rollout_template + <<: *rollout_template + when: delayed + start_in: 1 minutes +``` + +We can define the delay period using the `start_in` key: + +```yml +start_in: 1 minutes +``` + +Then we [define the rollout amount for each step](https://gitlab.com/gl-release/timed-rollout-example/blob/master/.gitlab-ci.yml#L97-101): + +```yml +timed rollout 30%: + <<: *timed_rollout_template + stage: timed rollout 30% + variables: + ROLLOUT_PERCENTAGE: 30 +``` + +A [deployable application](https://gitlab.com/gl-release/timed-rollout-example) is +available, [demonstrating configuration of timed rollouts](https://gitlab.com/gl-release/timed-rollout-example/blob/master/.gitlab-ci.yml#L86-95). diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index 7af797f1851..dca11c40524 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -4,7 +4,7 @@ type: tutorial # Using Dpl as deployment tool -[Dpl](https://github.com/travis-ci/dpl) (prouncounced like the letters D-P-L) is a deploy tool made for +[Dpl](https://github.com/travis-ci/dpl) (pronounced like the letters D-P-L) is a deploy tool made for continuous deployment that's developed and used by Travis CI, but can also be used with GitLab CI. diff --git a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md index ffcc8195395..788d57b81f8 100644 --- a/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/devops_and_game_dev_with_gitlab_ci_cd/index.md @@ -26,7 +26,7 @@ Creating a strong CI/CD pipeline at the beginning of developing another game, [D was essential for the fast pace the team worked at. This tutorial will build upon my [previous introductory article](https://ryanhallcs.wordpress.com/2017/03/15/devops-and-game-dev/) and go through the following steps: -1. Using code from the previous article to start with a barebones [Phaser](https://phaser.io) game built by a gulp file +1. Using code from the previous article to start with a bare-bones [Phaser](https://phaser.io) game built by a gulp file 1. Adding and running unit tests 1. Creating a `Weapon` class that can be triggered to spawn a `Bullet` in a given direction 1. Adding a `Player` class that uses this weapon and moves around the screen diff --git a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md index 9a4fbfcce6d..66246a0fda2 100644 --- a/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-ruby-application-to-heroku.md @@ -71,12 +71,12 @@ gitlab-runner register \ --non-interactive \ --url "https://gitlab.com/" \ --registration-token "PROJECT_REGISTRATION_TOKEN" \ - --description "ruby-2.2" \ + --description "ruby:2.6" \ --executor "docker" \ - --docker-image ruby:2.2 \ + --docker-image ruby:2.6 \ --docker-postgres latest ``` -With the command above, you create a Runner that uses the [ruby:2.2](https://hub.docker.com/_/ruby) image and uses a [postgres](https://hub.docker.com/_/postgres) database. +With the command above, you create a Runner that uses the [ruby:2.6](https://hub.docker.com/_/ruby) image and uses a [postgres](https://hub.docker.com/_/postgres) database. To access the PostgreSQL database, connect to `host: postgres` as user `postgres` with no password. diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/select-template.png b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/select-template.png Binary files differdeleted file mode 100644 index 727995f463c..00000000000 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/select-template.png +++ /dev/null diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/select_template_v12_6.png b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/select_template_v12_6.png Binary files differnew file mode 100644 index 00000000000..97887db4486 --- /dev/null +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/select_template_v12_6.png diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/set_up_ci_v12_6.png b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/set_up_ci_v12_6.png Binary files differnew file mode 100644 index 00000000000..85fb58d4458 --- /dev/null +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/set_up_ci_v12_6.png diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/setup-ci.png b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/setup-ci.png Binary files differdeleted file mode 100644 index 50c6ca593c1..00000000000 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/img/setup-ci.png +++ /dev/null diff --git a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md index 541578db294..f91e89d3c4c 100644 --- a/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md +++ b/doc/ci/examples/test_phoenix_app_with_gitlab_ci_cd/index.md @@ -10,7 +10,7 @@ last_updated: 2019-03-06 # Testing a Phoenix application with GitLab CI/CD -[Phoenix][phoenix-site] is a web development framework written in [Elixir][elixir-site], which is a +[Phoenix](https://phoenixframework.org) is a web development framework written in [Elixir](https://elixir-lang.org), which is a functional language designed for productivity and maintainability that runs on the [Erlang VM](https://www.erlang.org). Erlang VM is really really fast and can handle very large numbers of simultaneous users. @@ -27,8 +27,8 @@ and the GitLab UI. ### What is Phoenix? -[Phoenix][phoenix-site] is a web development framework written in [Elixir][elixir-site] very useful - to build fast, reliable, and high-performance applications, as it uses [Erlang VM](https://www.erlang.org). +[Phoenix](https://phoenixframework.org) is a web development framework written in [Elixir](https://elixir-lang.org) it's very useful + for building fast, reliable, and high-performance applications, as it uses [Erlang VM](https://www.erlang.org). Many components and concepts are similar to Ruby on Rails or Python's Django. High developer productivity and high application performance are only a few advantages on learning how to use it. @@ -45,27 +45,27 @@ Phoenix can run in any OS where Erlang is supported: - Fedora - Raspbian -Check the [Phoenix learning guide][phoenix-learning-guide] for more information. +Check the [Phoenix learning guide](https://hexdocs.pm/phoenix/learning.html) for more information. ### What is Elixir? -[Elixir][elixir-site] is a dynamic, functional language created to use all the maturity of Erlang +[Elixir](https://elixir-lang.org) is a dynamic, functional language created to use all the maturity of Erlang (30 years old!) in these days, in an easy way. It has similarities with Ruby, specially on syntax, so Ruby developers are quite excited with the rapid growing of Elixir. A full-stack Ruby developer can learn how to use Elixir and Phoenix in just a few weeks! In Elixir we have a command called `mix`, which is a helper to create projects, testing, run -migrations and [much more][elixir-mix]. We'll use it later on in this tutorial. +migrations and [much more](https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix). We'll use it later on in this tutorial. -Check the [Elixir documentation][elixir-docs] for more information. +Check the [Elixir documentation](https://elixir-lang.org/getting-started/introduction) for more information. ## Requirements To follow this tutorial, you'll need to have installed: -- Elixir [installation instructions][elixir-install] -- Phoenix Framework [installation instructions][phoenix-install] -- PostgreSQL (if you need to use MySQL server, check [Phoenix instructions][phoenix-mysql]) +- Elixir [installation instructions](https://elixir-lang.org/install) +- Phoenix Framework [installation instructions](https://hexdocs.pm/phoenix/installation.html) +- PostgreSQL (if you need to use MySQL server, check [Phoenix instructions](https://hexdocs.pm/phoenix/ecto.html#using-mysql)) ### Create a new Phoenix project @@ -100,7 +100,7 @@ this case, we'll only create an empty database. First, we need to navigate to our recently created project's directory, and then execute again `mix`. This time, `mix` will receive the parameter `ecto.create`, which is the task to create our -new database. [Ecto][ecto] is the database wrapper for Elixir. +new database. [Ecto](https://hexdocs.pm/ecto/Ecto.html) is the database wrapper for Elixir. When we do run `mix` the first time after creating our project, it will compile our files to bytecode, which will be interpreted by Erlang VM. In the next times, it will only compile our @@ -123,7 +123,7 @@ The database for HelloGitlabCi.Repo has been created > **Note:** Phoenix assumes that our PostgreSQL database will have a `postgres` user account with the correct permissions and a password of `postgres`. If it's not your case, check -[Ecto's instructions][ecto-repo]. +[Ecto's instructions](https://hexdocs.pm/ecto/Ecto.html#module-repositories). ### Start Phoenix server @@ -151,7 +151,7 @@ point `localhost` to `127.0.0.1`. Great, now we have a local Phoenix Server running our app. -Locally, our application is running in an `iex` session. [iex][iex] stands for Interactive Elixir. +Locally, our application is running in an `iex` session. [iex](https://elixir-lang.org/getting-started/introduction.html#interactive-mode) stands for Interactive Elixir. In this interactive mode, we can type any Elixir expression and get its result. To exit `iex`, we need to press `Ctrl+C` twice. So, when we need to stop the Phoenix server, we have to hit `Ctrl+C` twice. @@ -245,17 +245,16 @@ Our test was successful. It's time to push our files to GitLab. The first step is to create a new file called `.gitlab-ci.yml` in `hello_gitlab_ci` directory of our project. -- The fastest and easiest way to do this, is to click on **Set up CI** on project's main page: +- The easiest way to do this is to click on **Set up CI/CD** on project's main page: -  +  -- On next screen, we can select a template ready to go. Click on **Apply a GitLab CI/CD Yaml - template** and select **Elixir**: +- On the next screen, we can use a template with Elixir tests already included. Click on **Apply a template** and select **Elixir**: -  +  This template file tells GitLab CI/CD about what we wish to do every time a new commit is made. - However, we have to adapt it to run a Phoenix app. + However, we have to adapt it slightly to run a Phoenix app. - The first line tells GitLab what Docker image will be used. @@ -263,21 +262,21 @@ project. our application? This virtual machine must have all dependencies to run our application. This is where a Docker image is needed. The correct image will provide the entire system for us. - As a suggestion, you can use [trenpixster's elixir image][docker-image], which already has all - dependencies for Phoenix installed, such as Elixir, Erlang, NodeJS and PostgreSQL: + As we are focusing on testing (not deploying), you can use the [elixir:latest](https://hub.docker.com/_/elixir) docker image, which already has the + dependencies for running Phoenix tests installed, such as Elixir and Erlang: ```yml - image: trenpixster/elixir:latest + image: elixir:latest ``` -- At `services` session, we'll only use `postgres`, so we'll delete `mysql` and `redis` lines: +- We'll only use `postgres`, so we can delete the `mysql` and `redis` lines from the `services` section: ```yml services: - postgres:latest ``` -- Now, we'll create a new entry called `variables`, before `before_script` session: +- Now, we'll create a new section called `variables`, before the `before_script` section: ```yml variables: @@ -288,54 +287,56 @@ project. MIX_ENV: "test" ``` - Here, we are setting up the values for GitLab CI/CD authenticate into PostgreSQL, as we did on - `config/test.exs` earlier. + Above, we set up the values for GitLab CI/CD to authenticate into PostgreSQL, like we did in + `config/test.exs` earlier. The `POSTGRES_USER` and `POSTGRES_PASSWORD` values + are used by the `postgres` service to create a user with those credentials. -- In `before_script` session, we'll add some commands to prepare everything to the test: +- In the `before_script` section, we'll add some commands to prepare everything for the test: ```yml before_script: - - apt-get update && apt-get -y install postgresql-client + - mix local.rebar --force - mix local.hex --force - mix deps.get --only test - mix ecto.create - mix ecto.migrate ``` - It's important to install `postgresql-client` to let GitLab CI/CD access PostgreSQL and create our - database with the login information provided earlier. More important is to respect the indentation, - to avoid syntax errors when running the build. + This ensures that [rebar3](https://www.rebar3.org) and [hex](https://hex.pm) are both installed + before attempting to fetch the dependencies that are required to run the tests. Next, the `postgres` db + is created and migrated with `ecto`, to ensure it's up-to-date. -- And finally, we'll let `mix` session intact. +- Finally, we'll leave the `mix` section unchanged. -Let's take a look at the completed file after the editions: +Let's take a look at the updated file after the changes: ```yml -image: trenpixster/elixir:latest +image: elixir:latest services: - postgres:latest variables: - POSTGRES_DB: test_test + POSTGRES_DB: hello_gitlab_ci_test POSTGRES_HOST: postgres POSTGRES_USER: postgres POSTGRES_PASSWORD: "postgres" MIX_ENV: "test" before_script: - - apt-get update && apt-get -y install postgresql-client - - mix deps.get + - mix local.rebar --force + - mix local.hex --force + - mix deps.get --only test - mix ecto.create - mix ecto.migrate mix: script: - - mix test + - mix test ``` For safety, we can check if we get any syntax errors before submitting this file to GitLab. Copy the -contents of `.gitlab-ci.yml` and paste it on [GitLab CI/CD Lint tool][ci-lint]. Please note that +contents of `.gitlab-ci.yml` and paste it on [GitLab CI/CD Lint tool](https://gitlab.com/ci/lint). Please note that this link will only work for logged in users. ## Watching the build @@ -374,7 +375,7 @@ see if our latest code is running without errors. When we finish this edition, GitLab will start another build and show a **build running** badge. It is expected, after all we just configured GitLab CI/CD to do this for every push! But you may think "Why run build and tests for simple things like editing README.md?" and it is a good question. -For changes that don't affect your application, you can add the keyword [`[ci skip]`][skipping-jobs] +For changes that don't affect your application, you can add the keyword [`[ci skip]`](../../yaml/README.md#skipping-jobs) to commit message and the build related to that commit will be skipped. In the end, we finally got our pretty green build succeeded badge! By outputting the result on the @@ -389,34 +390,12 @@ code permanently working. GitLab CI/CD is a time saving powerful tool to help us organized and working. As we could see in this post, GitLab CI/CD is really really easy to configure and use. We have [many -other reasons][ci-reasons] to keep using GitLab CI/CD. The benefits to our teams will be huge! +other reasons](https://about.gitlab.com/blog/2015/02/03/7-reasons-why-you-should-be-using-ci/) to keep +using GitLab CI/CD. The benefits to our teams will be huge! ## References -- [GitLab CI/CD introductory guide][ci-guide] -- [GitLab CI/CD full Documentation][ci-docs] -- [GitLab Runners documentation][gitlab-runners] -- [Using Docker images documentation][using-docker] -- [Example project: Hello GitLab CI/CD on GitLab][hello-gitlab] - -[phoenix-site]: https://phoenixframework.org/ "Phoenix Framework" -[phoenix-learning-guide]: https://hexdocs.pm/phoenix/learning.html "Phoenix Learning Guide" -[phoenix-install]: https://hexdocs.pm/phoenix/installation.html "Phoenix Installation" -[phoenix-mysql]: https://hexdocs.pm/phoenix/ecto.html#using-mysql "Phoenix with MySQL" -[elixir-site]: https://elixir-lang.org/ "Elixir" -[elixir-mix]: https://elixir-lang.org/getting-started/mix-otp/introduction-to-mix.html "Introduction to mix" -[elixir-docs]: https://elixir-lang.org/getting-started/introduction.html "Elixir Documentation" -[elixir-install]: https://elixir-lang.org/install.html "Elixir Installation" -[ecto]: https://hexdocs.pm/ecto/Ecto.html "Ecto" -[ecto-repo]: https://hexdocs.pm/ecto/Ecto.html#module-repositories "Ecto Repositories" -[mix-ecto]: https://hexdocs.pm/ecto/Mix.Tasks.Ecto.Create.html "mix and Ecto" -[iex]: https://elixir-lang.org/getting-started/introduction.html#interactive-mode "Interactive Mode" -[ci-lint]: https://gitlab.com/ci/lint "CI Lint Tool" -[ci-reasons]: https://about.gitlab.com/blog/2015/02/03/7-reasons-why-you-should-be-using-ci/ "7 Reasons Why You Should Be Using CI" -[ci-guide]: https://about.gitlab.com/blog/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/ "Getting Started With GitLab And GitLab CI/CD" -[ci-docs]: ../../README.md "GitLab CI/CD Documentation" -[skipping-jobs]: ../../yaml/README.md#skipping-jobs "Skipping Jobs" -[gitlab-runners]: ../../runners/README.md "GitLab Runners Documentation" -[docker-image]: https://hub.docker.com/r/trenpixster/elixir/ "Elixir Docker Image" -[using-docker]: ../../docker/using_docker_images.md "Using Docker Images" -[hello-gitlab]: https://gitlab.com/Hostert/hello_gitlab_ci "Hello GitLab CI/CD" +- [GitLab CI/CD introductory guide](https://about.gitlab.com/blog/2015/12/14/getting-started-with-gitlab-and-gitlab-ci) +- [GitLab CI/CD full Documentation](../../README.md) +- [GitLab Runners documentation](../../runners/README.md) +- [Using Docker images documentation](../../docker/using_docker_images.md) diff --git a/doc/ci/img/parent_pipeline_graph_expanded_v12_6.png b/doc/ci/img/parent_pipeline_graph_expanded_v12_6.png Binary files differnew file mode 100644 index 00000000000..5c493109a54 --- /dev/null +++ b/doc/ci/img/parent_pipeline_graph_expanded_v12_6.png diff --git a/doc/ci/img/pipeline-delete.png b/doc/ci/img/pipeline-delete.png Binary files differnew file mode 100644 index 00000000000..d9dba1f455d --- /dev/null +++ b/doc/ci/img/pipeline-delete.png diff --git a/doc/ci/jenkins/index.md b/doc/ci/jenkins/index.md index 6e9e723feb5..92fc4de986c 100644 --- a/doc/ci/jenkins/index.md +++ b/doc/ci/jenkins/index.md @@ -26,7 +26,7 @@ There are some high level differences between the products worth mentioning: feature. - The `.gitlab-ci.yml` file is checked in to the root of your repository, much like a Jenkinsfile, but is in the YAML format (see [complete reference](../yaml/README.md)) instead of a Groovy DSL. It's most - analagous to the declarative Jenkinsfile format. + analogous to the declarative Jenkinsfile format. - GitLab comes with a [container registry](../../user/packages/container_registry/index.md), and we recommend using container images to set up your build environment. @@ -207,7 +207,7 @@ Because GitLab is integrated tightly with Git, SCM polling options for triggers #### `tools` -GitLab does not support a separate `tools` directive. Our best-practice reccomendation is to use pre-built +GitLab does not support a separate `tools` directive. Our best-practice recommendation is to use pre-built container images, which can be cached, and can be built to already contain the tools you need for your pipelines. Pipelines can be set up to automatically build these images as needed and deploy them to the [container registry](../../user/packages/container_registry/index.md). diff --git a/doc/ci/junit_test_reports.md b/doc/ci/junit_test_reports.md index f0c3da4358a..8773f712110 100644 --- a/doc/ci/junit_test_reports.md +++ b/doc/ci/junit_test_reports.md @@ -25,7 +25,7 @@ Consider the following workflow: 1. Your `master` branch is rock solid, your project is using GitLab CI/CD and your pipelines indicate that there isn't anything broken. -1. Someone from you team submits a merge request, a test fails and the pipeline +1. Someone from your team submits a merge request, a test fails and the pipeline gets the known red icon. To investigate more, you have to go through the job logs to figure out the cause of the failed test, which usually contain thousands of lines. diff --git a/doc/ci/merge_request_pipelines/index.md b/doc/ci/merge_request_pipelines/index.md index 9ac41f88ff6..8c3c17d2ce1 100644 --- a/doc/ci/merge_request_pipelines/index.md +++ b/doc/ci/merge_request_pipelines/index.md @@ -136,7 +136,7 @@ Review App set up, helping to save resources. ## Excluding certain branches -Pipelines for merge requests require special treatement when +Pipelines for merge requests require special treatment when using [`only`/`except`](../yaml/README.md#onlyexcept-basic). Unlike ordinary branch refs (for example `refs/heads/my-feature-branch`), merge request refs use a special Git reference that looks like `refs/merge-requests/:iid/head`. Because @@ -161,7 +161,7 @@ test: only: [merge_requests] except: variables: - $CI_COMMIT_REF_NAME =~ /^docs-/ + - $CI_COMMIT_REF_NAME =~ /^docs-/ ``` ## Important notes about merge requests from forked projects diff --git a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png Binary files differindex 6f0752bb940..8da2970ab5a 100644 --- a/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png +++ b/doc/ci/merge_request_pipelines/pipelines_for_merged_results/img/merged_result_pipeline_v12_3.png diff --git a/doc/ci/multi_project_pipelines.md b/doc/ci/multi_project_pipelines.md index f13d05716f1..6b84c3d6d12 100644 --- a/doc/ci/multi_project_pipelines.md +++ b/doc/ci/multi_project_pipelines.md @@ -93,8 +93,8 @@ gets created. If you want to display the downstream pipeline's status instead, s NOTE: **Note:** Bridge jobs do not support every configuration entry that a user can use -in the case of regular jobs. Bridge jobs will not to be picked by a Runner, -thus there is no point in adding support for `script`, for example. If a user +in the case of regular jobs. Bridge jobs will not be picked by a Runner, +so there is no point in adding support for `script`, for example. If a user tries to use unsupported configuration syntax, YAML validation will fail upon pipeline creation. @@ -221,6 +221,7 @@ Some features are not implemented yet. For example, support for environments. - `trigger` (to define a downstream pipeline trigger) - `stage` - `allow_failure` +- [`rules`](yaml/README.md#rules) - `only` and `except` - `when` (only with `on_success`, `on_failure`, and `always` values) - `extends` diff --git a/doc/ci/parent_child_pipelines.md b/doc/ci/parent_child_pipelines.md new file mode 100644 index 00000000000..269cbd75a9a --- /dev/null +++ b/doc/ci/parent_child_pipelines.md @@ -0,0 +1,86 @@ +--- +type: reference +--- + +# Parent-child pipelines + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/16094) in GitLab Starter 12.7. + +As pipelines grow more complex, a few related problems start to emerge: + +- The staged structure, where all steps in a stage must be completed before the first + job in next stage begins, causes arbitrary waits, slowing things down. +- Configuration for the single global pipeline becomes very long and complicated, + making it hard to manage. +- Imports with [`include`](yaml/README.md#include) increase the complexity of the configuration, and create the potential + for namespace collisions where jobs are unintentionally duplicated. +- Pipeline UX can become unwieldy with so many jobs and stages to work with. + +Additionally, sometimes the behavior of a pipeline needs to be more dynamic. The ability +to choose to start sub-pipelines (or not) is a powerful ability, especially if the +YAML is dynamically generated. + + + +Similarly to [multi-project pipelines](multi_project_pipelines.md), a pipeline can trigger a +set of concurrently running child pipelines, but within the same project: + +- Child pipelines still execute each of their jobs according to a stage sequence, but + would be free to continue forward through their stages without waiting for unrelated + jobs in the parent pipeline to finish. +- The configuration is split up into smaller child pipeline configurations, which are + easier to understand. This reduces the cognitive load to understand the overall configuration. +- Imports are done at the child pipeline level, reducing the likelihood of collisions. +- Each pipeline has only the steps relevant steps, making it easier to understand what's going on. + +Child pipelines work well with other GitLab CI features: + +- Use [`only: changes`](yaml/README.md#onlychangesexceptchanges) to trigger pipelines only when + certain files change. This is useful for monorepos, for example. +- Since the parent pipeline in `.gitlab-ci.yml` and the child pipeline run as normal + pipelines, they can have their own behaviors and sequencing in relation to triggers. + +All of this will work with [`include:`](yaml/README.md#include) feature so you can compose +the child pipeline configuration. + +## Examples + +The simplest case is [triggering a child pipeline](yaml/README.md#trigger-premium) using a +local YAML file to define the pipeline configuration. In this case, the parent pipeline will +trigger the child pipeline, and continue without waiting: + +```yaml +microservice_a: + trigger: + include: path/to/microservice_a.yml +``` + +You can include multiple files when composing a child pipeline: + +```yaml +microservice_a: + trigger: + include: + - local: path/to/microservice_a.yml + - template: SAST.gitlab-ci.yml +``` + +NOTE: **Note:** +The max number of entries that are accepted for `trigger:include:` is three. + +Similar to [multi-project pipelines](multi_project_pipelines.md#mirroring-status-from-triggered-pipeline), +we can set the parent pipeline to depend on the status of the child pipeline upon completion: + +```yaml +microservice_a: + trigger: + include: + - local: path/to/microservice_a.yml + - template: SAST.gitlab-ci.yml + strategy: depend +``` + +## Limitations + +A parent pipeline can trigger many child pipelines, but a child pipeline cannot trigger +further child pipelines. See the [related issue](https://gitlab.com/gitlab-org/gitlab/issues/29651) for discussion on possible future improvements. diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index d1e50039417..71c4c9ca0ec 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -246,6 +246,13 @@ Pipelines for different projects can be combined and visualized together. For more information, see [Multi-project pipelines](multi_project_pipelines.md). +## Parent-child pipelines + +Complex pipelines can be broken down into one parent pipeline that can trigger +multiple child sub-pipelines, which all run in the same project and with the same SHA. + +For more information, see [Parent-Child pipelines](parent_child_pipelines.md). + ## Working with pipelines In general, pipelines are executed automatically and require no intervention once created. @@ -305,12 +312,14 @@ For example, the query string ### Accessing pipelines You can find the current and historical pipeline runs under your project's -**CI/CD > Pipelines** page. Clicking on a pipeline will show the jobs that were run for -that pipeline. +**CI/CD > Pipelines** page. You can also access pipelines for a merge request by navigating +to its **Pipelines** tab.  -You can also access pipelines for a merge request by navigating to its **Pipelines** tab. +Clicking on a pipeline will bring you to the **Pipeline Details** page and show +the jobs that were run for that pipeline. From here you can cancel a running pipeline, +retry jobs on a failed pipeline, or [delete a pipeline](#deleting-a-single-pipeline). ### Accessing individual jobs @@ -410,6 +419,20 @@ This functionality is only available: - For users with at least Developer access. - If the the stage contains [manual actions](#manual-actions-from-pipeline-graphs). +### Deleting a single pipeline + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24851) in GitLab 12.7. + +Users with [owner permissions](../user/permissions.md) in a project can delete a pipeline +by clicking on the pipeline in the **CI/CD > Pipelines** to get to the **Pipeline Details** +page, then using the **Delete** button. + + + +CAUTION: **Warning:** +Deleting a pipeline will expire all pipeline caches, and delete all related objects, +such as builds, logs, artifacts, and triggers. **This action cannot be undone.** + ## Most Recent Pipeline > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/50499) in GitLab 12.3. diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 68e977c1c98..55710145a95 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -17,34 +17,29 @@ NOTE: **Note:** Coming over to GitLab from Jenkins? Check out our [reference](../jenkins/index.md) for converting your pre-existing pipelines over to our format. -GitLab offers a [continuous integration][ci] service. If you -[add a `.gitlab-ci.yml` file][yaml] to the root directory of your repository, -and configure your GitLab project to use a [Runner], then each commit or -push triggers your CI [pipeline]. +GitLab offers a [continuous integration](https://about.gitlab.com/product/continuous-integration/) service. For each commit or push to trigger your CI +[pipeline](../pipelines.md), you must: -The `.gitlab-ci.yml` file tells the GitLab Runner what to do. By default it runs -a pipeline with three [stages]: `build`, `test`, and `deploy`. You don't need to -use all three stages; stages with no jobs are simply ignored. +- Add a [`.gitlab-ci.yml` file](#creating-a-gitlab-ciyml-file) to your repository's root directory. +- Ensure your project is configured to use a [Runner](#configuring-a-runner). -If everything runs OK (no non-zero return values), you'll get a nice green -checkmark associated with the commit. This makes it -easy to see whether a commit caused any of the tests to fail before -you even look at the code. +The `.gitlab-ci.yml` file tells the GitLab Runner what to do. A simple pipeline commonly has +three [stages](../yaml/README.md#stages): -Most projects use GitLab's CI service to run the test suite so that -developers get immediate feedback if they broke something. +- `build` +- `test` +- `deploy` -There's a growing trend to use continuous delivery and continuous deployment to -automatically deploy tested code to staging and production environments. +You do not need to use all three stages; stages with no jobs are ignored. -So in brief, the steps needed to have a working CI can be summed up to: +The pipeline appears under the project's **CI/CD > Pipelines** page. If everything runs OK (no non-zero +return values), you get a green check mark associated with the commit. This makes it easy to see +whether a commit caused any of the tests to fail before you even look at the job (test) log. Many projects use +GitLab's CI service to run the test suite, so developers get immediate feedback if they broke +something. -1. Add `.gitlab-ci.yml` to the root directory of your repository -1. Configure a Runner - -From there on, on every push to your Git repository, the Runner will -automatically start the pipeline and the pipeline will appear under the -project's **Pipelines** page. +It's also common to use pipelines to automatically deploy +tested code to staging and production environments. --- @@ -237,9 +232,4 @@ CI with various languages. [runner-install]: https://docs.gitlab.com/runner/install/ [blog-ci]: https://about.gitlab.com/blog/2015/05/06/why-were-replacing-gitlab-ci-jobs-with-gitlab-ci-dot-yml/ [examples]: ../examples/README.md -[ci]: https://about.gitlab.com/product/continuous-integration/ -[yaml]: ../yaml/README.md -[runner]: ../runners/README.md [enabled]: ../enable_or_disable_ci.md -[stages]: ../yaml/README.md#stages -[pipeline]: ../pipelines.md diff --git a/doc/ci/review_apps/index.md b/doc/ci/review_apps/index.md index 0da1228aa53..23cb0362867 100644 --- a/doc/ci/review_apps/index.md +++ b/doc/ci/review_apps/index.md @@ -167,7 +167,7 @@ Ensure that the `anonymous_visual_review_feedback` feature flag is enabled. Administrators can enable with a Rails console as follows: ```ruby -Feature.enabled(:anonymous_visual_review_feedback) +Feature.enable(:anonymous_visual_review_feedback) ``` The feedback form is served through a script you add to pages in your Review App. diff --git a/doc/ci/runners/README.md b/doc/ci/runners/README.md index 4011ae4df70..466c6f96d81 100644 --- a/doc/ci/runners/README.md +++ b/doc/ci/runners/README.md @@ -62,13 +62,13 @@ You can only register a shared Runner if you are an admin of the GitLab instance 1. Grab the shared-Runner token on the `admin/runners` page -  +  1. [Register the Runner][register] Shared Runners are enabled by default as of GitLab 8.2, but can be disabled with the **Disable shared Runners** button which is present under each project's -**Settings ➔ CI/CD** page. Previous versions of GitLab defaulted shared +**Settings > CI/CD** page. Previous versions of GitLab defaulted shared Runners to disabled. ## Registering a specific Runner @@ -100,7 +100,7 @@ If you are an admin on your GitLab instance, you can turn any shared Runner into a specific one, but not the other way around. Keep in mind that this is a one way transition. -1. Go to the Runners in the admin area **Overview > Runners** (`/admin/runners`) +1. Go to the Runners in the **Admin Area > Overview > Runners** (`/admin/runners`) and find your Runner 1. Enable any projects under **Restrict projects for this Runner** to be used with the Runner @@ -402,7 +402,7 @@ different places. To view the IP address of a shared Runner you must have admin access to the GitLab instance. To determine this: -1. Visit **Admin area ➔ Overview ➔ Runners** +1. Visit **Admin Area > Overview > Runners** 1. Look for the Runner in the table and you should see a column for "IP Address"  @@ -411,7 +411,7 @@ the GitLab instance. To determine this: You can find the IP address of a Runner for a specific project by: -1. Visit your project's **Settings ➔ CI/CD** +1. Visit your project's **Settings > CI/CD** 1. Find the Runner and click on it's ID which links you to the details page 1. On the details page you should see a row for "IP Address" diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index 384216fed2c..6dc093b6d0f 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -290,6 +290,7 @@ export CI_RUNNER_ID="10" export CI_RUNNER_DESCRIPTION="my runner" export CI_RUNNER_TAGS="docker, linux" export CI_SERVER="yes" +export CI_SERVER_URL="https://example.com" export CI_SERVER_HOST="example.com" export CI_SERVER_NAME="GitLab" export CI_SERVER_REVISION="70606bf" @@ -673,6 +674,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_PROJECT_DIR=/builds/gitlab-examples/ci-debug-trace ++ export CI_SERVER=yes ++ CI_SERVER=yes +++ export CI_SERVER_URL=https://example.com:3000 +++ CI_SERVER_URL=https://example.com:3000 ++ export 'CI_SERVER_HOST=example.com' ++ CI_SERVER_HOST='example.com' ++ export 'CI_SERVER_NAME=GitLab CI' @@ -709,6 +712,8 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ CI_JOB_NAME=debug_trace ++ export CI_JOB_STAGE=test ++ CI_JOB_STAGE=test +++ export CI_SERVER_URL=https://example.com:3000 +++ CI_SERVER_URL=https://example.com:3000 ++ export CI_SERVER_HOST=example.com ++ CI_SERVER_HOST=example.com ++ export CI_SERVER_NAME=GitLab diff --git a/doc/ci/variables/img/inherited_group_variables_v12_5.png b/doc/ci/variables/img/inherited_group_variables_v12_5.png Binary files differindex f9043df051c..fd41859605f 100644 --- a/doc/ci/variables/img/inherited_group_variables_v12_5.png +++ b/doc/ci/variables/img/inherited_group_variables_v12_5.png diff --git a/doc/ci/variables/predefined_variables.md b/doc/ci/variables/predefined_variables.md index e25425b01ae..24a16fe6a70 100644 --- a/doc/ci/variables/predefined_variables.md +++ b/doc/ci/variables/predefined_variables.md @@ -79,13 +79,14 @@ future GitLab releases.** | `CI_MERGE_REQUEST_TARGET_BRANCH_NAME` | 11.6 | all | The target branch name of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | | `CI_MERGE_REQUEST_TARGET_BRANCH_SHA` | 11.9 | all | The HEAD SHA of the target branch of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used, the merge request is created, and the pipeline is a [merged result pipeline](../merge_request_pipelines/pipelines_for_merged_results/index.md). **(PREMIUM)** | | `CI_MERGE_REQUEST_TITLE` | 11.9 | all | The title of the merge request if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Available only if `only: [merge_requests]` is used and the merge request is created. | +| `CI_MERGE_REQUEST_EVENT_TYPE` | 12.3 | all | The event type of the merge request, if [the pipelines are for merge requests](../merge_request_pipelines/index.md). Can be `detached`, `merged_result` or `merge_train`. | | `CI_NODE_INDEX` | 11.5 | all | Index of the job in the job set. If the job is not parallelized, this variable is not set. | | `CI_NODE_TOTAL` | 11.5 | all | Total number of instances of this job running in parallel. If the job is not parallelized, this variable is set to `1`. | | `CI_PAGES_DOMAIN` | 11.8 | all | The configured domain that hosts GitLab Pages. | | `CI_PAGES_URL` | 11.8 | all | URL to GitLab Pages-built pages. Always belongs to a subdomain of `CI_PAGES_DOMAIN`. | | `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`, `pipeline` and `merge_request_event`. For pipelines created before GitLab 9.5, this will show as `unknown` | +| `CI_PIPELINE_SOURCE` | 10.0 | all | Indicates how the pipeline was triggered. Possible options are: `push`, `web`, `trigger`, `schedule`, `api`, `pipeline`, `external`, `chat`, `merge_request_event`, and `external_pull_request_event`. 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](../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. | @@ -111,6 +112,7 @@ future GitLab releases.** | `CI_RUNNER_TAGS` | 8.10 | 0.5 | The defined runner tags | | `CI_RUNNER_VERSION` | all | 10.6 | GitLab Runner version that is executing the current job | | `CI_SERVER` | all | all | Mark that job is executed in CI environment | +| `CI_SERVER_URL` | 12.7 | all | The base URL of the GitLab instance, including protocol and port (like `https://gitlab.example.com:8080`) | | `CI_SERVER_HOST` | 12.1 | all | Host component of the GitLab instance URL, without protocol and port (like `gitlab.example.com`) | | `CI_SERVER_NAME` | all | all | The name of CI server that is used to coordinate jobs | | `CI_SERVER_REVISION` | all | all | GitLab revision that is used to schedule jobs | diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index 84e0bb873a7..aafbe4c9189 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -119,6 +119,7 @@ The following table lists available parameters for jobs: | [`pages`](#pages) | Upload the result of a job to use with GitLab Pages. | | [`variables`](#variables) | Define job variables on a job level. | | [`interruptible`](#interruptible) | Defines if a job can be canceled when made redundant by a newer run. | +| [`resource_group`](#resource_group) | Limit job concurrency. | NOTE: **Note:** Parameters `types` and `type` are [deprecated](#deprecated-parameters). @@ -728,7 +729,18 @@ Learn more about [variables expressions](../variables/README.md#environment-vari Using the `changes` keyword with `only` or `except` makes it possible to define if a job should be created based on files modified by a Git push event. -For example: +This means the `only:changes` policy is useful for pipelines where: + +- `$CI_PIPELINE_SOURCE == 'push'` +- `$CI_PIPELINE_SOURCE == 'merge_request_event'` +- `$CI_PIPELINE_SOURCE == 'external_pull_request_event'` + +If there is no Git push event, such as for pipelines with +[sources other than the three above](../variables/predefined_variables.html#variables-reference), +`changes` cannot determine if a given file is new or old, and will always +return true. + +A basic example of using `only: changes`: ```yaml docker build: @@ -829,7 +841,7 @@ In the example above, a pipeline could fail due to changes to a file in `service A later commit could then be pushed that does not include any changes to this file, but includes changes to the `Dockerfile`, and this pipeline could pass because it is only testing the changes to the `Dockerfile`. GitLab checks the **most recent pipeline**, -that **passed**, and will show the merge request as mergable, despite the earlier +that **passed**, and will show the merge request as mergeable, despite the earlier failed pipeline caused by a change that was not yet corrected. With this configuration, care must be taken to check that the most recent pipeline @@ -909,8 +921,9 @@ at all, the behavior defaults to `job:when`, which continues to default to #### `rules:changes` -`changes` works exactly the same way as [`only`/`except`](#onlychangesexceptchanges), -accepting an array of paths. +`rules: changes` works exactly the same way as `only: changes` and `except: changes`, +accepting an array of paths. Similarly, it will always return true if there is no +Git push event. See [`only/except: changes`](#onlychangesexceptchanges) for more information. For example: @@ -2312,6 +2325,23 @@ This example creates three paths of execution: - Related to the above, stages must be explicitly defined for all jobs that have the keyword `needs:` or are referred to by one. +##### Changing the `needs:` job limit + +The maximum number of jobs that can be defined within `needs:` defaults to 10, but +can be changed to 50 via a feature flag. To change the limit to 50, +[start a Rails console session](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session) +and run: + +```ruby +Feature::disable(:ci_dag_limit_needs) +``` + +To set it back to 10, run the opposite command: + +```ruby +Feature::enable(:ci_dag_limit_needs) +``` + #### Artifact downloads with `needs` > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14311) in GitLab v12.6. @@ -2355,6 +2385,51 @@ rspec: - build_job_3 ``` +#### Cross project artifact downloads with `needs` **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/14311) in GitLab v12.7. + +`needs` can be used to download artifacts from up to five jobs in pipelines on +[other refs in the same project](#artifact-downloads-between-pipelines-in-the-same-project), +or pipelines in different projects: + +```yaml +build_job: + stage: build + script: + - ls -lhR + needs: + - project: group/project-name + job: build-1 + ref: master + artifacts: true +``` + +`build_job` will download the artifacts from the latest successful `build-1` job +on the `master` branch in the `group/project-name` project. + +##### Artifact downloads between pipelines in the same project + +`needs` can be used to download artifacts from different pipelines in the current project +by setting the `project` keyword as the current project's name, and specifying a ref. +In the example below, `build_job` will download the artifacts for the latest successful +`build-1` job with the `other-ref` ref: + +```yaml +build_job: + stage: build + script: + - ls -lhR + needs: + - project: group/same-project-name + job: build-1 + ref: other-ref + artifacts: true +``` + +NOTE: **Note:** +Downloading artifacts from jobs that are run in [`parallel:`](#parallel) is not supported. + ### `coverage` > [Introduced][ce-7447] in GitLab 8.17. @@ -2525,14 +2600,17 @@ job split into three separate jobs. from `trigger` definition is started by GitLab, a downstream pipeline gets created. -Learn more about [multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml). +This keyword allows the creation of two different types of downstream pipelines: + +- [Multi-project pipelines](../multi_project_pipelines.md#creating-multi-project-pipelines-from-gitlab-ciyml) +- [Child pipelines](../parent_child_pipelines.md) NOTE: **Note:** Using a `trigger` with `when:manual` together results in the error `jobs:#{job-name} when should be on_success, on_failure or always`, because `when:manual` prevents triggers being used. -#### Simple `trigger` syntax +#### Simple `trigger` syntax for multi-project pipelines The simplest way to configure a downstream trigger is to use `trigger` keyword with a full path to a downstream project: @@ -2547,7 +2625,7 @@ staging: trigger: my/deployment ``` -#### Complex `trigger` syntax +#### Complex `trigger` syntax for multi-project pipelines It is possible to configure a branch name that GitLab will use to create a downstream pipeline with: @@ -2582,6 +2660,28 @@ upstream_bridge: pipeline: other/project ``` +#### `trigger` syntax for child pipeline + +To create a [child pipeline](../parent_child_pipelines.md), specify the path to the +YAML file containing the CI config of the child pipeline: + +```yaml +trigger_job: + trigger: + include: path/to/child-pipeline.yml +``` + +Similar to [multi-project pipelines](../multi_project_pipelines.md#mirroring-status-from-triggered-pipeline), +it is possible to mirror the status from a triggered pipeline: + +```yaml +trigger_job: + trigger: + include: + - local: path/to/child-pipeline.yml + strategy: depend +``` + ### `interruptible` > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/23464) in GitLab 12.3. @@ -2634,6 +2734,39 @@ In the example above, a new pipeline run will cause an existing running pipeline NOTE: **Note:** Once an uninterruptible job is running, the pipeline will never be canceled, regardless of the final job's state. +### `resource_group` + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/15536) in GitLab 12.7. + +Sometimes running multiples jobs or pipelines at the same time in an environment +can lead to errors during the deployment. + +To avoid these errors, the `resource_group` attribute can be used to ensure that +the Runner will not run certain jobs simultaneously. + +When the `resource_group` key is defined for a job in `.gitlab-ci.yml`, +job executions are mutually exclusive across different pipelines for the same project. +If multiple jobs belonging to the same resource group are enqueued simultaneously, +only one of the jobs will be picked by the Runner, and the other jobs will wait until the +`resource_group` is free. + +Here is a simple example: + +```yaml +deploy-to-production: + script: deploy + resource_group: production +``` + +In this case, if a `deploy-to-production` job is running in a pipeline, and a new +`deploy-to-production` job is created in a different pipeline, it will not run until +the currently running/pending `deploy-to-production` job is finished. As a result, +you can ensure that concurrent deployments will never happen to the production environment. + +There can be multiple `resource_group`s defined per environment. A good use case for this +is when deploying to physical devices. You may have more than one physical device, and each +one can be deployed to, but there can be only one deployment per device at any given time. + ### `include` > - Introduced in [GitLab Premium](https://about.gitlab.com/pricing/) 10.5. @@ -3594,7 +3727,7 @@ having their own custom `script` defined: ```yaml .job_template: &job_definition # Hidden key that defines an anchor named 'job_definition' - image: ruby:2.1 + image: ruby:2.6 services: - postgres - redis @@ -3616,13 +3749,13 @@ given hash into the current one", and `*` includes the named anchor ```yaml .job_template: - image: ruby:2.1 + image: ruby:2.6 services: - postgres - redis test1: - image: ruby:2.1 + image: ruby:2.6 services: - postgres - redis @@ -3630,7 +3763,7 @@ test1: - test1 project test2: - image: ruby:2.1 + image: ruby:2.6 services: - postgres - redis diff --git a/doc/development/README.md b/doc/development/README.md index 3a972c4c588..d551e6f471e 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -17,7 +17,7 @@ description: 'Learn how to contribute to GitLab.' - [GitLab core team & GitLab Inc. contribution process](https://gitlab.com/gitlab-org/gitlab/blob/master/PROCESS.md) - [Generate a changelog entry with `bin/changelog`](changelog.md) - [Code review guidelines](code_review.md) for reviewing code and having code reviewed -- [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries +- [Database review guidelines](database_review.md) for reviewing database-related changes and complex SQL queries, and having them reviewed - [Pipelines for the GitLab project](pipelines.md) - [Guidelines for implementing Enterprise Edition features](ee_features.md) - [Security process for developers](https://gitlab.com/gitlab-org/release/docs/blob/master/general/security/developer.md#security-releases-critical-non-critical-as-a-developer) @@ -71,6 +71,8 @@ description: 'Learn how to contribute to GitLab.' - [Auto DevOps development guide](auto_devops.md) - [Mass Inserting Models](mass_insert.md) - [Cycle Analytics development guide](cycle_analytics.md) +- [Issue types vs first-class types](issue_types.md) +- [Application limits](application_limits.md) ## Performance guides @@ -106,10 +108,10 @@ description: 'Learn how to contribute to GitLab.' ### Debugging - Tracing the source of an SQL query using query comments with [Marginalia](database_query_comments.md) +- Tracing the source of an SQL query in Rails console using [Verbose Query Logs](https://guides.rubyonrails.org/debugging_rails_applications.html#verbose-query-logs) ### Best practices -- [Merge Request checklist](database_merge_request_checklist.md) - [Adding database indexes](adding_database_indexes.md) - [Foreign keys & associations](foreign_keys.md) - [Single table inheritance](single_table_inheritance.md) diff --git a/doc/development/api_graphql_styleguide.md b/doc/development/api_graphql_styleguide.md index 1ef0b928820..053eb55420e 100644 --- a/doc/development/api_graphql_styleguide.md +++ b/doc/development/api_graphql_styleguide.md @@ -210,7 +210,7 @@ class MergeRequestPermissionsType < BasePermissionType abilities :admin_merge_request, :update_merge_request, :create_note ability_field :resolve_note, - description: 'Whether or not the user can resolve disussions on the merge request' + description: 'Indicates the user can resolve discussions on the merge request' permission_field :push_to_source_branch, method: :can_push_to_source_branch? end ``` diff --git a/doc/development/api_styleguide.md b/doc/development/api_styleguide.md index 71963ee0c0a..d5fc24c1ddb 100644 --- a/doc/development/api_styleguide.md +++ b/doc/development/api_styleguide.md @@ -92,6 +92,12 @@ For instance: Model.create(foo: params[:foo]) ``` +## Using HTTP status helpers + +For non-200 HTTP responses, use the provided helpers in `lib/api/helpers.rb` to ensure correct behaviour (`not_found!`, `no_content!` etc.). These will `throw` inside Grape and abort the execution of your endpoint. + +For `DELETE` requests, you should also generally use the `destroy_conditionally!` helper which by default returns a `204 No Content` response on success, or a `412 Precondition Failed` response if the given `If-Unmodified-Since` header is out of range. This helper calls `#destroy` on the passed resource, but you can also implement a custom deletion method by passing a block. + ## Using API path helpers in GitLab Rails codebase Because we support [installing GitLab under a relative URL], one must take this diff --git a/doc/development/application_limits.md b/doc/development/application_limits.md new file mode 100644 index 00000000000..28d1f14b1b3 --- /dev/null +++ b/doc/development/application_limits.md @@ -0,0 +1,89 @@ +# Application limits development + +This document provides a development guide for contributors to add application +limits to GitLab. + +## Documentation + +First of all, you have to gather information and decide which are the different +limits that will be set for the different GitLab tiers. You also need to +coordinate with others to [document](../administration/instance_limits.md) +and communicate those limits. + +There is a guide about [introducing application +limits](https://about.gitlab.com/handbook/product/#introducing-application-limits). + +## Development + +The merge request to [configure maximum number of webhooks per +project](https://gitlab.com/gitlab-org/gitlab/merge_requests/20730/diffs) is a +good example about configuring application limits. + +### Insert database plan limits + +In the `plan_limits` table, you have to create a new column and insert the +limit values. It's recommended to create separate migration script files. + +1. Add new column to the `plan_limits` table with non-null default value 0, eg: + + ```ruby + add_column(:plan_limits, :project_hooks, :integer, default: 0, null: false) + ``` + + NOTE: **Note:** Plan limits entries set to `0` mean that limits are not + enabled. + +1. Insert plan limits values into the database using + `create_or_update_plan_limit` migration helper, eg: + + ```ruby + create_or_update_plan_limit('project_hooks', 'free', 10) + create_or_update_plan_limit('project_hooks', 'bronze', 20) + create_or_update_plan_limit('project_hooks', 'silver', 30) + create_or_update_plan_limit('project_hooks', 'gold', 100) + ``` + +### Plan limits validation + +#### Get current limit + +Access to the current limit can be done through the project or the namespace, +eg: + +```ruby +project.actual_limits.project_hooks +``` + +#### Check current limit + +There is one method `PlanLimits#exceeded?` to check if the current limit is +being exceeded. You can use either an `ActiveRecord` object or an `Integer`. + +Ensures that the count of the records does not exceed the defined limit, eg: + +```ruby +project.actual_limits.exceeded?(:project_hooks, ProjectHook.where(project: project)) +``` + +Ensures that the number does not exceed the defined limit, eg: + +```ruby +project.actual_limits.exceeded?(:project_hooks, 10) +``` + +#### `Limitable` concern + +The [`Limitable` concern](https://gitlab.com/gitlab-org/gitlab/blob/master/ee/app/models/concerns/ee/limitable.rb) +can be used to validate that a model does not exceed the limits. It ensures +that the count of the records for the current model does not exceed the defined +limit. + +NOTE: **Note:** The name (pluralized) of the plan limit introduced in the +database (`project_hooks`) must correspond to the name of the model we are +validating (`ProjectHook`). + +```ruby +class ProjectHook + include Limitable +end +``` diff --git a/doc/development/architecture.md b/doc/development/architecture.md index eff83da523b..778cc1aa1d7 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -625,7 +625,7 @@ Note: It is recommended to log into the `git` user using `sudo -i -u git` or `su ## GitLab.com -We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/handbook/engineering/infrastructure/production-architecture/) but this is probably over the top unless you have millions of users. +We've also detailed [our architecture of GitLab.com](https://about.gitlab.com/handbook/engineering/infrastructure/production/architecture/) but this is probably over the top unless you have millions of users. [alertmanager-omnibus]: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/files/gitlab-config-template/gitlab.rb.template [alertmanager-charts]: https://github.com/helm/charts/tree/master/stable/prometheus diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 326ac7b3a37..4bc963222f2 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -259,24 +259,34 @@ Developers who have capacity can regularly check the list of [merge requests to Since [unblocking others is always a top priority](https://about.gitlab.com/handbook/values/#global-optimization), reviewers are expected to review assigned merge requests in a timely manner, even when this may negatively impact their other tasks and priorities. + Doing so allows everyone involved in the merge request to iterate faster as the -context is fresh in memory, improves contributors' experiences significantly. +context is fresh in memory, and improves contributors' experience significantly. + +#### Review-response SLO + +To ensure swift feedback to ready-to-review code, we maintain a `Review-response` Service-level Objective (SLO). The SLO is defined as: -A turnaround time of two working days is usually acceptable, since engineers -will typically have other things to work on while they're waiting for review, -but don't hesitate to ask the author if it's unclear what time frame would be -acceptable, how urgent the review is, or how significant the blockage. +> - review-response SLO = (time when first review response is provided) - (time MR is assigned to reviewer) < 2 business days -If you don't think you'll be able to review a merge request within a reasonable +If you don't think you'll be able to review a merge request within the `Review-response` SLO time frame, let the author know as soon as possible and try to help them find another reviewer or maintainer who will be able to, so that they can be unblocked -and get on with their work quickly. Of course, if you are out of office and have +and get on with their work quickly. + +If you think you are at capacity and are unable to accept any more reviews until +some have been completed, communicate this through your GitLab status by setting +the `:red_circle:` emoji and mentioning that you are at capacity in the status +text. This will guide contributors to pick a different reviewer, helping us to +meet the SLO. + +Of course, if you are out of office and have [communicated](https://about.gitlab.com/handbook/paid-time-off/#communicating-your-time-off) this through your GitLab.com Status, authors are expected to realize this and find a different reviewer themselves. -When a merge request author feels like they have been blocked for longer than -is reasonable, they are free to remind the reviewer through Slack or assign +When a merge request author has been blocked for longer than +the `Review-response` SLO, they are free to remind the reviewer through Slack or assign another reviewer. ### Reviewing code @@ -304,7 +314,7 @@ experience, refactors the existing code). Then: - Ensure the target branch is not too far behind master. If [master is red](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), it should be no more than 100 commits behind. -- Consider warnings and errors from danger bot, codequality, and other reports. +- Consider warnings and errors from danger bot, code quality, and other reports. Unless a strong case can be made for the violation, these should be resolved before merge. - Ensure a passing CI pipeline or if [master is broken](https://about.gitlab.com/handbook/engineering/workflow/#broken-master), post a comment mentioning the failure happens in master with a diff --git a/doc/development/contributing/issue_workflow.md b/doc/development/contributing/issue_workflow.md index a385a7dc83a..eba650ea22f 100644 --- a/doc/development/contributing/issue_workflow.md +++ b/doc/development/contributing/issue_workflow.md @@ -29,7 +29,7 @@ the affected files to find someone. We also use [GitLab Triage](https://gitlab.com/gitlab-org/gitlab-triage) to automate some triaging policies. This is currently set up as a scheduled pipeline (`https://gitlab.com/gitlab-org/quality/triage-ops/pipeline_schedules/10512/editpipeline_schedules/10512/edit`, -must have at least developer access to the project) running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) +must have at least Developer access to the project) running on [quality/triage-ops](https://gitlab.com/gitlab-org/quality/triage-ops) project. ## Labels @@ -185,9 +185,9 @@ their color is `#428BCA`. `<Category Name>` is the category name as it is in the single source of truth for categories at <https://gitlab.com/gitlab-com/www-gitlab-com/blob/master/data/categories.yml>. -For instance, the "Code Analytics" category is represented by the -~"Category:Code Analytics" label in the `gitlab-org` group since its -`code_analytics.name` value is "Code Analytics". +For instance, the "DevOps Score" category is represented by the +~"Category:DevOps Score" label in the `gitlab-org` group since its +`devops_score.name` value is "DevOps Score". If a category's label doesn't respect this naming convention, it should be specified with [the `label` attribute](https://about.gitlab.com/handbook/marketing/website/#category-attributes) diff --git a/doc/development/cycle_analytics.md b/doc/development/cycle_analytics.md index 284645cdae7..90abafb3e03 100644 --- a/doc/development/cycle_analytics.md +++ b/doc/development/cycle_analytics.md @@ -77,8 +77,8 @@ end Some start/end event pairs are not "compatible" with each other. For example: -- "Issue created" to "Merge Request created": The event classes are defined on different domain models, the `object_type` method is different. -- "Issue closed" to "Issue created": Issue must be created first before it can be closed. +- "Issue created" to "Merge Request created": The event classes are defined on different domain models, the `object_type` method is different. +- "Issue closed" to "Issue created": Issue must be created first before it can be closed. - "Issue closed" to "Issue closed": Duration is always 0. The `StageEvents` module describes the allowed `start_event` and `end_event` pairings (`PAIRING_RULES` constant). If a new event is added, it needs to be registered in this module. diff --git a/doc/development/dangerbot.md b/doc/development/dangerbot.md index 40eb4294617..51f7a18dd08 100644 --- a/doc/development/dangerbot.md +++ b/doc/development/dangerbot.md @@ -119,4 +119,16 @@ at GitLab so far: ## Limitations - [`danger local` does not work on GitLab](https://github.com/danger/danger/issues/458) -- Danger output is not added to a merge request comment if working on a fork. +- Danger output is not added to a merge request comment if working on + a fork. This happens because the secret variable from the canonical + project is not shared to forks. + To work around this, you can add an [environment + variable](../ci/variables/README.md) called + `DANGER_GITLAB_API_TOKEN` with a personal API token to your + fork. That way the danger comments will be made from CI using that + API token instead. + Making the variable + [masked](../ci/variables/README.md#masked-variables) will make sure + it doesn't show up in the job logs. The variable cannot be + [protected](../ci/variables/README.md#protected-environment-variables), + as it needs to be present for all feature branches. diff --git a/doc/development/database_merge_request_checklist.md b/doc/development/database_merge_request_checklist.md deleted file mode 100644 index 09dece27e8d..00000000000 --- a/doc/development/database_merge_request_checklist.md +++ /dev/null @@ -1,15 +0,0 @@ -# Merge Request Checklist - -When creating a merge request that performs database related changes (schema -changes, adjusting queries to optimize performance, etc) you should use the -merge request template called "Database changes". This template contains a -checklist of steps to follow to make sure the changes are up to snuff. - -To use the checklist, create a new merge request and click on the "Choose a -template" dropdown, then click "Database changes". - -An example of this checklist can be found at -<https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12463>. - -The source code of the checklist can be found in at -<https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Database%20changes.md> diff --git a/doc/development/database_review.md b/doc/development/database_review.md index b1c3ed47976..5ca77579eec 100644 --- a/doc/development/database_review.md +++ b/doc/development/database_review.md @@ -32,12 +32,10 @@ for review. ### Roles and process -A Merge Request author's role is to: +A Merge Request **author**'s role is to: - Decide whether a database review is needed. - If database review is needed, add the ~database label. -- Use the [database changes](https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/merge_request_templates/Database%20changes.md) - merge request template, or include the appropriate items in the MR description. - [Prepare the merge request for a database review](#how-to-prepare-the-merge-request-for-a-database-review). A database **reviewer**'s role is to: @@ -78,15 +76,54 @@ make sure you have applied the ~database label and rerun the ### How to prepare the merge request for a database review -In order to make reviewing easier and therefore faster, please consider preparing a comment -and details for a database reviewer: +In order to make reviewing easier and therefore faster, please take +the following preparations into account. -- Provide queries in SQL form rather than ActiveRecord. -- Format any queries with a SQL query formatter, for example with [sqlformat.darold.net](http://sqlformat.darold.net). -- Consider providing query plans via a link to [explain.depesz.com](https://explain.depesz.com) or another tool instead of textual form. -- For query changes, it is best to provide the SQL query along with a plan *before* and *after* the change. This helps to spot differences quickly. -- When providing query plans, make sure to use good parameter values, so that the query executed is a good example and also hits enough data. - - Usually, the `gitlab-org` namespace (`namespace_id = 9970`) and the `gitlab-org/gitlab-foss` (`project_id = 13083`) or the `gitlab-org/gitlab` (`project_id = 278964`) projects provide enough data to serve as a good example. +#### Preparation when adding migrations + +- Ensure `db/schema.rb` is updated. +- Make migrations reversible by using the `change` method or include a `down` method when using `up`. + - Include either a rollback procedure or describe how to rollback changes. +- Add the output of the migration(s) to the MR description. +- Add tests for the migration in `spec/migrations` if necessary. See [Testing Rails migrations at GitLab](testing_guide/testing_migrations_guide.html) for more details. + +#### Preparation when adding or modifying queries + +- Write the raw SQL in the MR description. Preferably formatted + nicely with [sqlformat.darold.net](http://sqlformat.darold.net) or + [paste.depesz.com](https://paste.depesz.com). +- Include the output of `EXPLAIN (ANALYZE, BUFFERS)` of the relevant + queries in the description. If the output is too long, wrap it in + `<details>` blocks, paste it in a GitLab Snippet, or provide the + link to the plan at: [explain.depesz.com](https://explain.depesz.com). +- When providing query plans, make sure it hits enough data: + - You can use a GitLab production replica to test your queries on a large scale, + through the `#database-lab` Slack channel or through [chatops](understanding_explain_plans.md#chatops). + - Usually, the `gitlab-org` namespace (`namespace_id = 9970`) and the + `gitlab-org/gitlab-foss` (`project_id = 13083`) or the `gitlab-org/gitlab` (`project_id = 278964`) + projects provide enough data to serve as a good example. +- For query changes, it is best to provide the SQL query along with a + plan _before_ and _after_ the change. This helps to spot differences + quickly. +- Include data that shows the performance improvement, preferably in + the form of a benchmark. + +#### Preparation when adding foreign keys to existing tables + +- Include a migration to remove orphaned rows in the source table **before** adding the foreign key. +- Remove any instances of `dependent: ...` that may no longer be necessary. + +#### Preparation when adding tables + +- Order columns based on the [Ordering Table Columns](ordering_table_columns.md) guidelines. +- Add foreign keys to any columns pointing to data in other tables, including [an index](migration_style_guide.md#adding-foreign-key-constraints). +- Add indexes for fields that are used in statements such as `WHERE`, `ORDER BY`, `GROUP BY`, and `JOIN`s. + +#### Preparation when removing columns, tables, indexes or other structures + +- Follow the [guidelines on dropping columns](what_requires_downtime.md#dropping-columns). +- Generally it's best practice, but not a hard rule, to remove indexes and foreign keys in a post-deployment migration. + - Exceptions include removing indexes and foreign keys for small tables. ### How to review for database @@ -136,6 +173,7 @@ and details for a database reviewer: (eg indexes, columns), you can use a [one-off instance from the restore pipeline](https://ops.gitlab.net/gitlab-com/gl-infra/gitlab-restore/postgres-gprd) in order to establish a proper testing environment. + - Avoid N+1 problems and minimalize the [query count](merge_request_performance_guidelines.md#query-counts). ### Timing guidelines for migrations diff --git a/doc/development/documentation/index.md b/doc/development/documentation/index.md index 61e42ecfe83..a9d8941488f 100644 --- a/doc/development/documentation/index.md +++ b/doc/development/documentation/index.md @@ -208,7 +208,7 @@ available online on 2018-09-15, but, as the feature freeze date has passed, if the MR does not have a "pick into 11.3" label, the milestone has to be changed to 11.4 and it will be shipped with all GitLab packages only on 2018-10-22, with GitLab 11.4. Meaning, it will only be available under `/help` from GitLab -11.4 onwards, but available on <https://docs.gitlab.com/> on the same day it was merged. +11.4 onward, but available on <https://docs.gitlab.com/> on the same day it was merged. ### Linking to `/help` diff --git a/doc/development/documentation/site_architecture/global_nav.md b/doc/development/documentation/site_architecture/global_nav.md index be4d5b5353f..518850358ff 100644 --- a/doc/development/documentation/site_architecture/global_nav.md +++ b/doc/development/documentation/site_architecture/global_nav.md @@ -86,7 +86,7 @@ The available sections are described on the table below: | Section | Description | | ------------- | ------------------------------------------ | | User | Documentation for the GitLab's user UI. | -| Administrator | Documentation for the GitLab's admin area. | +| Administrator | Documentation for the GitLab's Admin Area. | | Contributor | Documentation for developing GitLab. | The majority of the links available on the nav were added according to the UI. diff --git a/doc/development/documentation/styleguide.md b/doc/development/documentation/styleguide.md index 385569fc8fa..fd591c71e85 100644 --- a/doc/development/documentation/styleguide.md +++ b/doc/development/documentation/styleguide.md @@ -941,7 +941,7 @@ a helpful link back to how the feature was developed. Over time, version text will reference a progressively older version of GitLab. In cases where version text refers to versions of GitLab four or more major versions back, consider removing the text. -For example, if the current major version is 11.x, version text referencing versions of GitLab 7.x +For example, if the current major version is 12.x, version text referencing versions of GitLab 8.x and older are candidates for removal. NOTE: **Note:** diff --git a/doc/development/documentation/workflow.md b/doc/development/documentation/workflow.md index e48c940dc21..0e5da29df94 100644 --- a/doc/development/documentation/workflow.md +++ b/doc/development/documentation/workflow.md @@ -284,7 +284,7 @@ To update GitLab documentation: 1. Follow GitLab's [Merge Request Guidelines](../contributing/merge_request_workflow.md#merge-request-guidelines). TIP: **Tip:** -Work in a fork if you do not have developer access to the GitLab project. +Work in a fork if you do not have Developer access to the GitLab project. Request help from the Technical Writing team if you: @@ -297,8 +297,7 @@ To request help: 1. Locate the the Technical Writer for the relevant [DevOps stage group](https://about.gitlab.com/handbook/product/technical-writing/index.html#assignments). 1. Either: - - If urgent help is required, directly assign the Technical Writer in the issue or - [in the merge request](../../user/project/merge_requests/creating_merge_requests.md#multiple-assignees-starter). + - If urgent help is required, directly assign the Technical Writer in the issue or in the merge request. - If non-urgent help is required, ping the Technical Writer in the issue or merge request. If you are a member of GitLab's Slack workspace, you can request help in `#docs`. diff --git a/doc/development/elasticsearch.md b/doc/development/elasticsearch.md index 1375bd6d56d..bd8a4e1c6d7 100644 --- a/doc/development/elasticsearch.md +++ b/doc/development/elasticsearch.md @@ -37,20 +37,6 @@ brew install elasticsearch@5.6 There is no need to install any plugins -## New repo indexer (beta) - -If you're interested on working with the new beta repo indexer, all you need to do is: - -```sh -git clone git@gitlab.com:gitlab-org/gitlab-elasticsearch-indexer.git -make -make install -``` - -this adds `gitlab-elasticsearch-indexer` to `$GOPATH/bin`, please make sure that is in your `$PATH`. After that GitLab will find it and you'll be able to enable it in the admin settings area. - -**note:** `make` will not recompile the executable unless you do `make clean` beforehand - ## Helpful rake tasks - `gitlab:elastic:test:index_size`: Tells you how much space the current index is using, as well as how many documents are in the index. diff --git a/doc/development/event_tracking/index.md b/doc/development/event_tracking/index.md index ac19053320d..13b08e53768 100644 --- a/doc/development/event_tracking/index.md +++ b/doc/development/event_tracking/index.md @@ -53,7 +53,7 @@ Tracking can be enabled at: We utilize Snowplow for the majority of our tracking strategy, and it can be enabled by navigating to: -- **Admin area > Settings > Integrations** in the UI. +- **Admin Area > Settings > Integrations** in the UI. - `admin/application_settings/integrations` in your browser. The following configuration is required: diff --git a/doc/development/fe_guide/design_patterns.md b/doc/development/fe_guide/design_patterns.md index a7a0f39e2f3..72a7861ffcb 100644 --- a/doc/development/fe_guide/design_patterns.md +++ b/doc/development/fe_guide/design_patterns.md @@ -31,11 +31,11 @@ export default new MyThing(); export default class MyThing { constructor() { - if (!this.prototype.singleton) { + if (!MyThing.prototype.singleton) { this.init(); - this.prototype.singleton = this; + MyThing.prototype.singleton = this; } - return this.prototype.singleton; + return MyThing.prototype.singleton; } init() { diff --git a/doc/development/fe_guide/frontend_faq.md b/doc/development/fe_guide/frontend_faq.md index cbe0a78370d..01ed07f8736 100644 --- a/doc/development/fe_guide/frontend_faq.md +++ b/doc/development/fe_guide/frontend_faq.md @@ -73,3 +73,76 @@ Ensure a [Product Designer](https://about.gitlab.com/company/team/?department=ux reviews the use of the non-conforming component as part of the MR review. Make a follow up issue and attach it to the component implementation epic found within the [Components of Pajamas Design System epic](https://gitlab.com/groups/gitlab-org/-/epics/973). + +### 4. My submit form button becomes disabled after submitting + +If you are using a submit button inside a form and you attach an `onSubmit` event listener on the form element, [this piece of code](https://gitlab.com/gitlab-org/gitlab/blob/794c247a910e2759ce9b401356432a38a4535d49/app/assets/javascripts/main.js#L225) will add a `disabled` class selector to the submit button when the form is submitted. +To avoid this behavior, add the class `js-no-auto-disable` to the button. + +### 5. Should I use a full URL (i.e. `gon.gitlab_url`) or a full path (i.e. `gon.relative_url_root`) when referencing backend endpoints? + +It's preferred to use a **full path** over a **full URL** because the URL will use the hostname configured with +GitLab which may not match the request. This will cause [CORS issues like this Web IDE one](https://gitlab.com/gitlab-org/gitlab/issues/36810). + +Example: + +```javascript +// bad :( +// If gitlab is configured with hostname `0.0.0.0` +// This will cause CORS issues if I request from `localhost` +axios.get(joinPaths(gon.gitlab_url, '-', 'foo')) + +// good :) +axios.get(joinPaths(gon.relative_url_root, '-', 'foo')) +``` + +Also, please try not to hardcode paths in the Frontend, but instead receive them from the Backend (see next section). +When referencing Backend rails paths, avoid using `*_url`, and use `*_path` instead. + +Example: + +```haml +-# Bad :( +#js-foo{ data: { foo_url: some_rails_foo_url } } + +-# Good :) +#js-foo{ data: { foo_path: some_rails_foo_path } } +``` + +### 6. How should the Frontend reference Backend paths? + +We prefer not to add extra coupling by hardcoding paths. If possible, +add these paths as data attributes to the DOM element being referenced in the JavaScript. + +Example: + +```javascript +// Bad :( +// Here's a Vuex action that hardcodes a path :( +export const fetchFoos = ({ state }) => { + return axios.get(joinPaths(gon.relative_url_root, '-', 'foo')); +}; + +// Good :) +function initFoo() { + const el = document.getElementById('js-foo'); + + // Path comes from our root element's data which is used to initialize the store :) + const store = createStore({ + fooPath: el.dataset.fooPath + }); + + Vue.extend({ + store, + el, + render(h) { + return h(Component); + }, + }); +} + +// Vuex action can now reference the path from it's state :) +export const fetchFoos = ({ state }) => { + return axios.get(state.settings.fooPath); +}; +``` diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 40b9fdef76e..1639029d193 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -109,17 +109,16 @@ import createDefaultClient from '~/lib/graphql'; Vue.use(VueApollo); const defaultClient = createDefaultClient({ - Query: { - ... - }, - Mutations: { - ... - }, + resolvers: {} }); defaultClient.cache.writeData({ data: { - isLoading: true, + user: { + name: 'John', + surname: 'Doe', + age: 30 + }, }, }); @@ -128,8 +127,122 @@ const apolloProvider = new VueApollo({ }); ``` +We can query local data with `@client` Apollo directive: + +```javascript +// user.query.graphql + +query User { + user @client { + name + surname + age + } +} +``` + +Along with creating local data, we can also extend existing GraphQL types with `@client` fields. This is extremely useful when we need to mock an API responses for fields not yet added to our GraphQL API. + +#### Mocking API response with local Apollo cache + +Using local Apollo Cache is handy when we have a need to mock some GraphQL API responses, queries or mutations locally (e.g. when they're still not added to our actual API). + +For example, we have a [fragment](#fragments) on `DesignVersion` used in our queries: + +``` +fragment VersionListItem on DesignVersion { + id + sha +} +``` + +We need to fetch also version author and the 'created at' property to display them in the versions dropdown but these changes are still not implemented in our API. We can change the existing fragment to get a mocked response for these new fields: + +``` +fragment VersionListItem on DesignVersion { + id + sha + author @client { + avatarUrl + name + } + createdAt @client +} +``` + +Now Apollo will try to find a _resolver_ for every field marked with `@client` directive. Let's create a resolver for `DesignVersion` type (why `DesignVersion`? because our fragment was created on this type). + +```javascript +// resolvers.js + +const resolvers = { + DesignVersion: { + author: () => ({ + avatarUrl: + 'https://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon', + name: 'Administrator', + __typename: 'User', + }), + createdAt: () => '2019-11-13T16:08:11Z', + }, +}; + +export default resolvers; +``` + +We need to pass resolvers object to our existing Apollo Client: + +```javascript +// graphql.js + +import createDefaultClient from '~/lib/graphql'; +import resolvers from './graphql/resolvers'; + +const defaultClient = createDefaultClient( + {}, + resolvers, +); +``` + +Now every single time on attempt to fetch a version, our client will fetch `id` and `sha` from the remote API endpoint and will assign our hardcoded values to `author` and `createdAt` version properties. With this data, frontend developers are able to work on UI part without being blocked by backend. When actual response is added to the API, a custom local resolver can be removed fast and the only change to query/fragment is `@client` directive removal. + Read more about local state management with Apollo in the [Vue Apollo documentation](https://vue-apollo.netlify.com/guide/local-state.html#local-state). +### Feature flags in queries + +Sometimes it may be useful to have an entity in the GraphQL query behind a feature flag. +For example, when working on a feature where the backend has already been merged but the frontend +hasn't you might want to put the GraphQL entity behind a feature flag to allow for smaller +merge requests to be created and merged. + +To do this we can use the `@include` directive to exclude an entity if the `if` statement passes. + +```graphql +query getAuthorData($authorNameEnabled: Boolean = false) { + username + name @include(if: $authorNameEnabled) +} +``` + +Then in the Vue (or JavaScript) call to the query we can pass in our feature flag. This feature +flag will need to be already setup correctly. See the [feature flag documentation](../feature_flags/development.md) +for the correct way to do this. + +```javascript +export default { + apollo: { + user: { + query: QUERY_IMPORT, + variables() { + return { + authorNameEnabled: gon?.features?.authorNameEnabled, + }; + }, + } + }, +}; +``` + ### Testing #### Mocking response as component data diff --git a/doc/development/fe_guide/img/graphiql_explorer_v12_4.png b/doc/development/fe_guide/img/graphiql_explorer_v12_4.png Binary files differindex 8981b37ba23..b50424f7f8d 100644 --- a/doc/development/fe_guide/img/graphiql_explorer_v12_4.png +++ b/doc/development/fe_guide/img/graphiql_explorer_v12_4.png diff --git a/doc/development/fe_guide/style/vue.md b/doc/development/fe_guide/style/vue.md index 2499623e66a..8f69792287b 100644 --- a/doc/development/fe_guide/style/vue.md +++ b/doc/development/fe_guide/style/vue.md @@ -7,8 +7,8 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) ## Basic Rules -1. The service has it's own file -1. The store has it's own file +1. The service has its own file +1. The store has its own file 1. Use a function in the bundle file to instantiate the Vue component: ```javascript @@ -268,7 +268,7 @@ Please check this [rules](https://github.com/vuejs/eslint-plugin-vue#bulb-rules) ## Closing tags -1. Prefer self closing component tags +1. Prefer self-closing component tags ```javascript // bad @@ -411,8 +411,8 @@ The goal of this accord is to make sure we are all on the same page. 1. You may use a jQuery dependency in Vue.js following [this example from the docs](https://vuejs.org/v2/examples/select2.html). 1. If an outside jQuery Event needs to be listen to inside the Vue application, you may use jQuery event listeners. 1. We will avoid adding new jQuery events when they are not required. Instead of adding new jQuery events take a look at [different methods to do the same task](https://vuejs.org/v2/api/#vm-emit). -1. You may query the `window` object 1 time, while bootstrapping your application for application specific data (e.g. `scrollTo` is ok to access anytime). Do this access during the bootstrapping of your application. -1. You may have a temporary but immediate need to create technical debt by writing code that does not follow our standards, to be refactored later. Maintainers need to be ok with the tech debt in the first place. An issue should be created for that tech debt to evaluate it further and discuss. In the coming months you should fix that tech debt, with it's priority to be determined by maintainers. +1. You may query the `window` object one time, while bootstrapping your application for application specific data (e.g. `scrollTo` is ok to access anytime). Do this access during the bootstrapping of your application. +1. You may have a temporary but immediate need to create technical debt by writing code that does not follow our standards, to be refactored later. Maintainers need to be ok with the tech debt in the first place. An issue should be created for that tech debt to evaluate it further and discuss. In the coming months you should fix that tech debt, with its priority to be determined by maintainers. 1. When creating tech debt you must write the tests for that code before hand and those tests may not be rewritten. e.g. jQuery tests rewritten to Vue tests. 1. You may choose to use VueX as a centralized state management. If you choose not to use VueX, you must use the *store pattern* which can be found in the [Vue.js documentation](https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch). -1. Once you have chosen a centralized state management solution you must use it for your entire application. i.e. Don't mix and match your state management solutions. +1. Once you have chosen a centralized state-management solution you must use it for your entire application. i.e. Don't mix and match your state-management solutions. diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md index c64b14a05a4..4b44c8dadca 100644 --- a/doc/development/feature_flags/process.md +++ b/doc/development/feature_flags/process.md @@ -15,7 +15,9 @@ should be leveraged: - Feature flags should remain in the codebase for as short period as possible to reduce the need for feature flag accounting. - The person operating with feature flags is responsible for clearly communicating - the status of a feature behind the feature flag with responsible stakeholders. + the status of a feature behind the feature flag with responsible stakeholders. The + issue description should be updated with the feature flag name and whether it is + defaulted on or off as soon it is evident that a feature flag is needed. - Merge requests that make changes hidden behind a feature flag, or remove an existing feature flag because a feature is deemed stable must have the ~"feature flag" label assigned. diff --git a/doc/development/foreign_keys.md b/doc/development/foreign_keys.md index 0ab0deb156f..38b60ce6f0b 100644 --- a/doc/development/foreign_keys.md +++ b/doc/development/foreign_keys.md @@ -61,3 +61,29 @@ introduces non database logic to a model, and means we can no longer rely on foreign keys to remove the data as this would result in the filesystem data being left behind. In such a case you should use a service class instead that takes care of removing non database data. + +## Alternative primary keys with has_one associations + +Sometimes a `has_one` association is used to create a one-to-one relationship: + +```ruby +class User < ActiveRecord::Base + has_one :user_config +end + +class UserConfig < ActiveRecord::Base + belongs_to :user +end +``` + +In these cases, there may be an opportunity to remove the unnecessary `id` +column on the associated table, `user_config.id` in this example. Instead, +the originating table ID can be used as the primary key for the associated +table: + +```ruby +create_table :user_configs, id: false do |t| + t.references :users, primary_key: true, default: nil, index: false, foreign_key: { on_delete: :cascade } + ... +end +``` diff --git a/doc/development/gitaly.md b/doc/development/gitaly.md index 1fa555de994..20bba134ef1 100644 --- a/doc/development/gitaly.md +++ b/doc/development/gitaly.md @@ -207,6 +207,21 @@ To use a custom Gitaly repository in CI, for instance if you want your GitLab fork to always use your own Gitaly fork, set `GITALY_REPO_URL` as a [CI environment variable](../ci/variables/README.md#gitlab-cicd-environment-variables). +### Use a locally modified version of Gitaly RPC client + +If you are making changes to the RPC client, such as adding a new endpoint or adding a new +parameter to an existing endpoint, follow the guide for +[Gitaly proto](https://gitlab.com/gitlab-org/gitaly/blob/master/proto/README.md). After pushing +the branch with the changes (`new-feature-branch`, for example): + +1. Change the `gitaly` line in the Rails' `Gemfile` to: + + ```ruby + gem 'gitaly', git: 'https://gitlab.com/gitlab-org/gitaly.git', branch: 'new-feature-branch' + ``` + +1. Run `bundle install` to use the modified RPC client. + --- [Return to Development documentation](README.md) diff --git a/doc/development/go_guide/index.md b/doc/development/go_guide/index.md index 724bc240bc2..f6aae945f62 100644 --- a/doc/development/go_guide/index.md +++ b/doc/development/go_guide/index.md @@ -78,13 +78,27 @@ projects: All Go projects should include these GitLab CI/CD jobs: ```yaml -go lint: - image: golang:1.11 +lint: + image: registry.gitlab.com/gitlab-org/gitlab-build-images:golangci-lint-alpine + stage: test script: - - go get -u golang.org/x/lint/golint - - golint -set_exit_status $(go list ./... | grep -v "vendor/") + # Use default .golangci.yml file from the image if one is not present in the project root. + - '[ -e .golangci.yml ] || cp /golangci/.golangci.yml .' + # Write the code coverage report to gl-code-quality-report.json + # and print linting issues to stdout in the format: path/to/file:line description + - golangci-lint run --out-format code-climate | tee gl-code-quality-report.json | jq -r '.[] | "\(.location.path):\(.location.lines.begin) \(.description)"' + artifacts: + reports: + codequality: gl-code-quality-report.json + paths: + - gl-code-quality-report.json + allow_failure: true ``` +Including a `.golangci.yml` in the root directory of the project allows for +configuration of `golangci-lint`. All options for `golangci-lint` are listed in +this [example](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml). + Once [recursive includes](https://gitlab.com/gitlab-org/gitlab-foss/issues/56836) become available, you will be able to share job templates like this [analyzer](https://gitlab.com/gitlab-org/security-products/ci-templates/raw/master/includes-dev/analyzer.yml). diff --git a/doc/development/gotchas.md b/doc/development/gotchas.md index 7529278f902..09d0d71b3d7 100644 --- a/doc/development/gotchas.md +++ b/doc/development/gotchas.md @@ -26,7 +26,7 @@ describe API::Labels do get api("/projects/#{project.id}/labels", user) - expect(response).to have_http_status(200) + expect(response).to have_gitlab_http_status(:ok) expect(json_response.first['name']).to eq('label1') end @@ -35,7 +35,7 @@ describe API::Labels do get api("/projects/#{project.id}/labels", user) - expect(response).to have_http_status(200) + expect(response).to have_gitlab_http_status(:ok) expect(json_response.first['name']).to eq('label1') end end @@ -77,7 +77,7 @@ describe API::Labels do get api("/projects/#{project.id}/labels", user) - expect(response).to have_http_status(200) + expect(response).to have_gitlab_http_status(:ok) expect(json_response.first['name']).to eq('foo') end @@ -86,7 +86,7 @@ describe API::Labels do get api("/projects/#{project.id}/labels", user) - expect(response).to have_http_status(200) + expect(response).to have_gitlab_http_status(:ok) expect(json_response.first['name']).to eq('bar') end end diff --git a/doc/development/i18n/proofreader.md b/doc/development/i18n/proofreader.md index 8b3a5d893fe..a475f854ab0 100644 --- a/doc/development/i18n/proofreader.md +++ b/doc/development/i18n/proofreader.md @@ -25,7 +25,7 @@ are very appreciative of the work done by translators and proofreaders! - Victor Wu - [GitLab](https://gitlab.com/victorwuky), [Crowdin](https://crowdin.com/profile/victorwu) - Ivan Ip - [GitLab](https://gitlab.com/lifehome), [Crowdin](https://crowdin.com/profile/lifehome) - Czech - - Proofreaders needed. + - Jan Urbanec - [GitLab](https://gitlab.com/TatranskyMedved), [Crowdin](https://crowdin.com/profile/Tatranskymedved) - Danish - Saederup92 - [GitLab](https://gitlab.com/Saederup92), [Crowdin](https://crowdin.com/profile/Saederup92) - Dutch @@ -58,6 +58,7 @@ are very appreciative of the work done by translators and proofreaders! - Japanese - Hiroyuki Sato - [GitLab](https://gitlab.com/hiroponz), [Crowdin](https://crowdin.com/profile/hiroponz) - Tomo Dote - [GitLab](https://gitlab.com/fu7mu4), [Crowdin](https://crowdin.com/profile/fu7mu4) + - Hiromi Nozawa - [GitLab](https://gitlab.com/hir0mi), [Crowdin](https://crowdin.com/profile/hir0mi) - Korean - Chang-Ho Cha - [GitLab](https://gitlab.com/changho-cha), [Crowdin](https://crowdin.com/profile/zzazang) - Ji Hun Oh - [GitLab](https://gitlab.com/Baw-Appie), [Crowdin](https://crowdin.com/profile/BawAppie) @@ -82,6 +83,7 @@ are very appreciative of the work done by translators and proofreaders! - Alexy Lustin - [GitLab](https://gitlab.com/allustin), [Crowdin](https://crowdin.com/profile/lustin) - Mark Minakou - [GitLab](https://gitlab.com/sandzhaj), [Crowdin](https://crowdin.com/profile/sandzhaj) - NickVolynkin - [Crowdin](https://crowdin.com/profile/NickVolynkin) + - Andrey Komarov - [GitLab](https://gitlab.com/elkamarado), [Crowdin](https://crowdin.com/profile/kamarado) - Serbian (Cyrillic) - Proofreaders needed. - Serbian (Latin) diff --git a/doc/development/img/build_package_v12_6.png b/doc/development/img/build_package_v12_6.png Binary files differindex c3d99e6c6ce..32a3ebedba4 100644 --- a/doc/development/img/build_package_v12_6.png +++ b/doc/development/img/build_package_v12_6.png diff --git a/doc/development/img/memory_ruby_heap_fragmentation.png b/doc/development/img/memory_ruby_heap_fragmentation.png Binary files differindex 6567abe58bb..4703da7491d 100644 --- a/doc/development/img/memory_ruby_heap_fragmentation.png +++ b/doc/development/img/memory_ruby_heap_fragmentation.png diff --git a/doc/development/img/trigger_build_package_v12_6.png b/doc/development/img/trigger_build_package_v12_6.png Binary files differindex 6f5879bd8c4..ca6797ebf65 100644 --- a/doc/development/img/trigger_build_package_v12_6.png +++ b/doc/development/img/trigger_build_package_v12_6.png diff --git a/doc/development/issue_types.md b/doc/development/issue_types.md new file mode 100644 index 00000000000..bcd3980c298 --- /dev/null +++ b/doc/development/issue_types.md @@ -0,0 +1,45 @@ +# Issue Types + +Sometimes when a new resource type is added it's not clear if it should be only an +"extension" of Issue (Issue Type) or if it should be a new first-class resource type +(similar to Issue, Epic, Merge Request, Snippet). + +The idea of Issue Types was first proposed in [this +issue](https://gitlab.com/gitlab-org/gitlab/issues/8767) and its usage was +discussed few times since then, for example in [incident +management](https://gitlab.com/gitlab-org/gitlab-foss/issues/55532). + +## What is an Issue Type + +Issue Type is a resource type which extends the existing Issue type and can be +used anywhere where Issue is used - for example when listing or searching +issues or when linking objects of the type from Epics. It should use the same +`issues` table, additional fields can be stored in a separate table. + +## When an Issue Type should be used + +- When the new type only adds new fields to the basic Issue type without + removing existing fields (but it's OK if some fields from the basic Issue + type are hidden in user interface/API). +- When the new type can be used anywhere where the basic Issue type is used. + +## When a first-class resource type should be used + +- When a separate model and table is used for the new resource. +- When some fields of the basic Issue type need to be removed - hiding in the UI + is OK, but not complete removal. +- When the new resource cannot be used instead of the basic Issue type, + for example: + + - You can't add it to an epic. + - You can't close it from a commit or a merge request. + - You can't mark it as related to another issue. + +If an Issue type can not be used you can still define a first-class type and +then include concerns such as `Issuable` or `Noteable` to reuse functionality +which is common for all our issue-related resources. But you still need to +define the interface for working with the new resource and update some other +components to make them work with the new type. + +Usage of the Issue type limits what fields, functionality, or both is available +for the type. However, this functionality is provided by default. diff --git a/doc/development/logging.md b/doc/development/logging.md index 2eb140d3b7e..202c7a5ce9f 100644 --- a/doc/development/logging.md +++ b/doc/development/logging.md @@ -127,6 +127,118 @@ importer progresses. Here's what to do: logger.info(message: "Import error", error_code: 1, error: "I/O failure") ``` +## Multi-destination Logging + +GitLab is transitioning from unstructured/plaintext logs to structured/JSON logs. During this transition period some logs will be recorded in multiple formats through multi-destination logging. + +### How to use multi-destination logging + +Create a new logger class, inheriting from `MultiDestinationLogger` and add an array of loggers to a `LOGGERS` constant. The loggers should be classes that descend from `Gitlab::Logger`. e.g. the user defined loggers in the following examples, could be inheriting from `Gitlab::Logger` and `Gitlab::JsonLogger`, respectively. + +You must specify one of the loggers as the `primary_logger`. The `primary_logger` will be used when information about this multi-destination logger is displayed in the app, e.g. using the `Gitlab::Logger.read_latest` method. + +The following example sets one of the defined `LOGGERS` as a `primary_logger`. + +```ruby +module Gitlab + class FancyMultiLogger < Gitlab::MultiDestinationLogger + LOGGERS = [UnstructuredLogger, StructuredLogger].freeze + + def self.loggers + LOGGERS + end + + def primary_logger + UnstructuredLogger + end + end +end +``` + +You can now call the usual logging methods on this multi-logger, e.g. + +```ruby +FancyMultiLogger.info(message: "Information") +``` + +This message will be logged by each logger registered in `FancyMultiLogger.loggers`. + +### Passing a string or hash for logging + +When passing a string or hash to a `MultiDestinationLogger`, the log lines could be formatted differently, depending on the kinds of `LOGGERS` set. + +e.g. let's partially define the loggers from the previous example: + +```ruby +module Gitlab + # Similar to AppTextLogger + class UnstructuredLogger < Gitlab::Logger + ... + end + + # Similar to AppJsonLogger + class StructuredLogger < Gitlab::JsonLogger + ... + end +end +``` + +Here are some examples of how messages would be handled by both the loggers. + +1. When passing a string + +```ruby +FancyMultiLogger.info("Information") + +# UnstructuredLogger +I, [2020-01-13T18:48:49.201Z #5647] INFO -- : Information + +# StructuredLogger +{:severity=>"INFO", :time=>"2020-01-13T11:02:41.559Z", :correlation_id=>"b1701f7ecc4be4bcd4c2d123b214e65a", :message=>"Information"} +``` + +1. When passing a hash + +```ruby +FancyMultiLogger.info({:message=>"This is my message", :project_id=>123}) + +# UnstructuredLogger +I, [2020-01-13T19:01:17.091Z #11056] INFO -- : {"message"=>"Message", "project_id"=>"123"} + +# StructuredLogger +{:severity=>"INFO", :time=>"2020-01-13T11:06:09.851Z", :correlation_id=>"d7e0886f096db9a8526a4f89da0e45f6", :message=>"This is my message", :project_id=>123} +``` + +### Logging context metadata (through Rails or Grape requests) + +`Gitlab::ApplicationContext` stores metadata in a request +lifecycle, which can then be added to the web request +or Sidekiq logs. + +Entry points can be seen at: + +- [`ApplicationController`](https://gitlab.com/gitlab-org/gitlab/blob/master/app/controllers/application_controller.rb) +- [External API](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/api.rb) +- [Internal API](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/internal/base.rb) + +#### Adding attributes + +When adding new attributes, make sure they're exposed within the context of the entry points above and: + +- Pass them within the hash to the `with_context` (or `push`) method (make sure to pass a Proc if the +method or variable shouldn't be evaluated right away) +- Change `Gitlab::ApplicationContext` to accept these new values +- Make sure the new attributes are accepted at [`Labkit::Context`](https://gitlab.com/gitlab-org/labkit-ruby/blob/master/lib/labkit/context.rb) + +See our [HOWTO: Use Sidekiq metadata logs](https://www.youtube.com/watch?v=_wDllvO_IY0) for further knowledge on +creating visualizations in Kibana. + +**Note:** +The fields of the context are currently only logged for Sidekiq jobs triggered +through web requests. See the +[follow-up work](https://gitlab.com/gitlab-com/gl-infra/scalability/issues/68) +for more information. + ## Exception Handling It often happens that you catch the exception and want to track it. diff --git a/doc/development/merge_request_performance_guidelines.md b/doc/development/merge_request_performance_guidelines.md index ec50b1557d4..6552ed29e98 100644 --- a/doc/development/merge_request_performance_guidelines.md +++ b/doc/development/merge_request_performance_guidelines.md @@ -93,7 +93,7 @@ the following: The query plan can answer the questions whether we need additional indexes, or whether we perform expensive filtering (i.e. using sequential scans). -Each query plan should be run against substantional size of data set. +Each query plan should be run against substantial size of data set. For example if you look for issues with specific conditions, you should consider validating the query against a small number (a few hundred) and a big number (100_000) of issues. @@ -318,7 +318,7 @@ Take into consideration the following when choosing a pagination strategy: 1. It is very inefficient to calculate amount of objects that pass the filtering, this operation usually can take seconds, and can time out, -1. It is very inefficent to get entries for page at higher ordinals, like 1000. +1. It is very inefficient to get entries for page at higher ordinals, like 1000. The database has to sort and iterate all previous items, and this operation usually can result in substantial load put on database. @@ -363,7 +363,7 @@ The intent of quotas could be different: 1. We want to provide higher quotas for higher tiers of features: we want to provide on GitLab.com more capabilities for different tiers, -1. We want to prevent misuse of the feature: someone accidentially creates +1. We want to prevent misuse of the feature: someone accidentally creates 10000 deploy tokens, because of a broken API script, 1. We want to prevent abuse of the feature: someone purposely creates a 10000 pipelines to take advantage of the system. @@ -374,7 +374,7 @@ Examples: more than 50 schedules. In such cases it is rather expected that this is either misuse or abuse of the feature. Lack of the upper limit can result - in service degredation as the system will try to process all schedules + in service degradation as the system will try to process all schedules assigned the the project. 1. GitLab CI includes: We started with the limit of maximum of 50 nested includes. diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index 6301ba778bc..cccea4ee9f4 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -323,7 +323,7 @@ In this particular case, the default value exists and we're just changing the me in the `namespaces` table. Only when creating a new column with a default, all the records are going be rewritten. NOTE: **Note:** A faster [ALTER TABLE ADD COLUMN with a non-null default](https://www.depesz.com/2018/04/04/waiting-for-postgresql-11-fast-alter-table-add-column-with-a-non-null-default/) -was introduced on PostgresSQL 11.0, removing the need of rewritting the table when a new column with a default value is added. +was introduced on PostgresSQL 11.0, removing the need of rewriting the table when a new column with a default value is added. For the reasons mentioned above, it's safe to use `change_column_default` in a single-transaction migration without requiring `disable_ddl_transaction!`. diff --git a/doc/development/packages.md b/doc/development/packages.md index 7ae3cd53e66..980c1869a0a 100644 --- a/doc/development/packages.md +++ b/doc/development/packages.md @@ -21,6 +21,7 @@ The goal of the Package group is to build a set of features that, within three y | Format | Use case | | ------ | ------ | | [Bower](https://gitlab.com/gitlab-org/gitlab/issues/36888) | Boost your front end development by hosting your own Bower components. | +| [Cargo](https://gitlab.com/gitlab-org/gitlab/issues/33060) | Cargo is the Rust package manager. Build, publish and share Rust packages | | [Chef](https://gitlab.com/gitlab-org/gitlab/issues/36889) | Configuration management with Chef using all the benefits of a repository manager. | | [CocoaPods](https://gitlab.com/gitlab-org/gitlab/issues/36890) | Speed up development with Xcode and CocoaPods. | | [Conda](https://gitlab.com/gitlab-org/gitlab/issues/36891) | Secure and private local Conda repositories. | @@ -110,7 +111,7 @@ File uploads should be handled by GitLab Workhorse using object accelerated uplo the workhorse proxy that checks all incoming requests to GitLab will intercept the upload request, upload the file, and forward a request to the main GitLab codebase only containing the metadata and file location rather than the file itself. An overview of this process can be found in the -[development documentation](uploads.md#workhorse-object-storage-acceleration). +[development documentation](uploads.md#direct-upload). In terms of code, this means a route will need to be added to the [GitLab Workhorse project](https://gitlab.com/gitlab-org/gitlab-workhorse) for each level of remote being added @@ -183,7 +184,7 @@ These changes represent all that is needed to deliver a minimally usable package 1. Empty file structure (API file, base service for this package) 1. Authentication system for 'logging in' to the package manager 1. Identify metadata and create applicable tables -1. Workhorse route for [object storage accelerated uploads](uploads.md#workhorse-object-storage-acceleration) +1. Workhorse route for [object storage direct upload](uploads.md#direct-upload) 1. Endpoints required for upload/publish 1. Endpoints required for install/download 1. Endpoints required for remove/delete diff --git a/doc/development/performance.md b/doc/development/performance.md index 786b590ec70..94285efdf1e 100644 --- a/doc/development/performance.md +++ b/doc/development/performance.md @@ -382,7 +382,7 @@ end ## String Freezing In recent Ruby versions calling `freeze` on a String leads to it being allocated -only once and re-used. For example, on Ruby 2.3 this will only allocate the +only once and re-used. For example, on Ruby 2.3 or later this will only allocate the "foo" String once: ```ruby diff --git a/doc/development/pipelines.md b/doc/development/pipelines.md index 99f92e6f39f..7da74ae8b35 100644 --- a/doc/development/pipelines.md +++ b/doc/development/pipelines.md @@ -42,9 +42,9 @@ The current stages are: ## Default image The default image is currently -`registry.gitlab.com/gitlab-org/gitlab-build-images:ruby-2.6.3-golang-1.12-git-2.24-lfs-2.9-chrome-73.0-node-12.x-yarn-1.16-postgresql-9.6-graphicsmagick-1.3.33`. +`registry.gitlab.com/gitlab-org/gitlab-build-images:ruby-2.6.5-golang-1.12-git-2.24-lfs-2.9-chrome-73.0-node-12.x-yarn-1.16-postgresql-9.6-graphicsmagick-1.3.33`. -It includes Ruby 2.6.3, Go 1.12, Git 2.24, Git LFS 2.9, Chrome 73, Node 12, Yarn 1.16, +It includes Ruby 2.6.5, Go 1.12, Git 2.24, Git LFS 2.9, Chrome 73, Node 12, Yarn 1.16, PostgreSQL 9.6, and Graphics Magick 1.3.33. The images used in our pipelines are configured in the @@ -129,6 +129,64 @@ from a commit or MR by extending from the following CI definitions: **See <https://gitlab.com/gitlab-org/gitlab/blob/master/.gitlab/ci/global.gitlab-ci.yml> for the list of exact patterns.** +## Rules conditions and changes patterns + +We're making use of the [`rules` keyword](https://docs.gitlab.com/ee/ci/yaml/#rules) but we're currently +duplicating the `if` conditions and `changes` patterns lists since they cannot be shared across +`include`d files as we do with `extends`. + +**If you update an `if` condition or `changes` +patterns list, make sure to mass-update those across all the CI config files (i.e. `.gitlab/ci/*.yml`).** + +### Canonical commits only + +This condition limits jobs creation to commits under the `gitlab-org/` top-level group +on GitLab.com only. This is similar to the `.only:variables-canonical-dot-com` CI definition: + +```yaml +.if-canonical-gitlab: &if-canonical-gitlab + if: '$CI_SERVER_HOST == "gitlab.com" && $CI_PROJECT_NAMESPACE =~ /^gitlab-org($|\/)/' +``` + +### Canonical merge requests only + +Same as the "Canonical commits only" condition above but further limits jobs creation +to merge requests only (i.e. this won't run for `master`, stable or auto-deploy branches). +This is similar to the `.only:variables-canonical-dot-com` + `.except:refs-master-tags-stable-deploy` +CI definitions: + +```yaml +.if-canonical-gitlab-merge-request: &if-canonical-gitlab-merge-request + if: '$CI_SERVER_HOST == "gitlab.com" && $CI_PROJECT_NAMESPACE =~ /^gitlab-org($|\/)/ && $CI_MERGE_REQUEST_IID' +``` + +### Code changes patterns + +Similar patterns as for `.only:changes-code`: + +```yaml +.code-patterns: &code-patterns + - ... +``` + +### QA changes patterns + +Similar patterns as for `.only:changes-qa`: + +```yaml +.qa-patterns: &qa-patterns + - ... +``` + +### Code and QA changes patterns + +Similar patterns as for `.only:changes-code-qa`: + +```yaml +.code-qa-patterns: &code-qa-patterns + - ... +``` + ## Directed acyclic graph We're using the [`needs:`](../ci/yaml/README.md#needs) keyword to @@ -152,14 +210,14 @@ graph RL; M[coverage]; N[pages]; O[static-analysis]; - P["schedule:package-and-qa<br/>(master schedule only)"]; Q[package-and-qa]; - R[package-and-qa-manual]; S["RSpec<br/>(e.g. rspec unit pg9)"] T[retrieve-tests-metadata]; subgraph "`prepare` stage" A + B + C F K J @@ -167,8 +225,6 @@ subgraph "`prepare` stage" end subgraph "`test` stage" - B --> |needs| A; - C --> |needs| A; D --> |needs| A; H -.-> |needs and depends on| A; H -.-> |needs and depends on| K; @@ -201,10 +257,6 @@ subgraph "`review` stage" subgraph "`qa` stage" Q --> |needs| C; Q --> |needs| F; - R --> |needs| C; - R --> |needs| F; - P --> |needs| C; - P --> |needs| F; review-qa-smoke -.-> |needs and depends on| G; review-qa-all -.-> |needs and depends on| G; review-performance -.-> |needs and depends on| G; @@ -212,11 +264,6 @@ subgraph "`qa` stage" dast -.-> |needs and depends on| G; end -subgraph "`notification` stage" - NOTIFICATION1["schedule:package-and-qa:notify-success<br>(on_success)"] -.-> |needs| P; - NOTIFICATION2["schedule:package-and-qa:notify-failure<br>(on_failure)"] -.-> |needs| P; - end - subgraph "`post-test` stage" M end diff --git a/doc/development/policies.md b/doc/development/policies.md index 8e5ef6e57c0..4d045411156 100644 --- a/doc/development/policies.md +++ b/doc/development/policies.md @@ -95,8 +95,8 @@ Each line represents a rule that was evaluated. There are a few things to note: Here you can see that the first four rules were evaluated `false` for which user and subject. For example, you can see in the last line that -the rule was activated because the user `root` had at reporter access to -the `Project/4`. +the rule was activated because the user `root` had Reporter access to +`Project/4`. When a policy is asked whether a particular ability is allowed (`policy.allowed?(:some_ability)`), it does not necessarily have to diff --git a/doc/development/testing_guide/best_practices.md b/doc/development/testing_guide/best_practices.md index 356e3f7a227..a845b5a26e8 100644 --- a/doc/development/testing_guide/best_practices.md +++ b/doc/development/testing_guide/best_practices.md @@ -67,9 +67,10 @@ When using spring and guard together, use `SPRING=1 bundle exec guard` instead t - Don't supply the `:each` argument to hooks since it's the default. - On `before` and `after` hooks, prefer it scoped to `:context` over `:all` - When using `evaluate_script("$('.js-foo').testSomething()")` (or `execute_script`) which acts on a given element, - use a Capyabara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists. + use a Capybara matcher beforehand (e.g. `find('.js-foo')`) to ensure the element actually exists. - Use `focus: true` to isolate parts of the specs you want to run. - Use [`:aggregate_failures`](https://relishapp.com/rspec/rspec-core/docs/expectation-framework-integration/aggregating-failures) when there is more than one expectation in a test. +- For [empty test description blocks](https://github.com/rubocop-hq/rspec-style-guide#it-and-specify), use `specify` rather than `it do` if the test is self-explanatory. ### System / Feature tests diff --git a/doc/development/testing_guide/end_to_end/best_practices.md b/doc/development/testing_guide/end_to_end/best_practices.md index fc00fcea67e..e060312e05f 100644 --- a/doc/development/testing_guide/end_to_end/best_practices.md +++ b/doc/development/testing_guide/end_to_end/best_practices.md @@ -14,7 +14,7 @@ Now, realize that almost all tests need the user to be logged in, and that we ne Now, multiply the number of tests per 2 seconds, and as your test suite grows, the time to run it grows with it, and this is not sustainable. -An alternative to perform a login in a cheaper way would be having an endpoint (available only for testing) where we could pass the user's credentials as encrypted values as query strings, and then we would be redirected to the logged in home page if the credentials are valid. Let's say that, on average, this process takes only 200 miliseconds. +An alternative to perform a login in a cheaper way would be having an endpoint (available only for testing) where we could pass the user's credentials as encrypted values as query strings, and then we would be redirected to the logged in home page if the credentials are valid. Let's say that, on average, this process takes only 200 milliseconds. You see the point right? diff --git a/doc/development/testing_guide/end_to_end/index.md b/doc/development/testing_guide/end_to_end/index.md index 19885f5756f..96141a5d68d 100644 --- a/doc/development/testing_guide/end_to_end/index.md +++ b/doc/development/testing_guide/end_to_end/index.md @@ -15,27 +15,27 @@ a black-box testing framework for the API and the UI. ### Testing nightly builds -We run scheduled pipeline each night to test nightly builds created by Omnibus. +We run scheduled pipelines each night to test nightly builds created by Omnibus. You can find these nightly pipelines at `https://gitlab.com/gitlab-org/quality/nightly/pipelines` (need Developer access permissions). Results are reported in the `#qa-nightly` Slack channel. ### Testing staging -We run scheduled pipeline each night to test staging. +We run scheduled pipelines each night to test staging. You can find these nightly pipelines at `https://gitlab.com/gitlab-org/quality/staging/pipelines` -(need developer access permissions). Results are reported in the `#qa-staging` Slack channel. +(need Developer access permissions). Results are reported in the `#qa-staging` Slack channel. ### Testing code in merge requests -#### Using the `package-and-qa-manual` job +#### Using the `package-and-qa` job It is possible to run end-to-end tests for a merge request, eventually being run in a pipeline in the [`gitlab-qa`](https://gitlab.com/gitlab-org/gitlab-qa/) project, -by triggering the `package-and-qa-manual` manual action in the `test` stage (not +by triggering the `package-and-qa` manual action in the `test` stage (not available for forks). -**This runs end-to-end tests against a custom Omnibus package built from your -merge request's changes.** +**This runs end-to-end tests against a custom CE and EE (with an Ultimate license) +Omnibus package built from your merge request's changes.** Manual action that starts end-to-end tests is also available in merge requests in [Omnibus GitLab][omnibus-gitlab]. @@ -53,7 +53,7 @@ graph LR B2[`Trigger-qa` stage<br>`Trigger:qa-test` job] -.->|2. Triggers a gitlab-qa pipeline and wait for it to be done| A3 subgraph "gitlab-foss/gitlab pipeline" - A1[`test` stage<br>`package-and-qa-manual` job] + A1[`test` stage<br>`package-and-qa` job] end subgraph "omnibus-gitlab pipeline" @@ -61,7 +61,7 @@ subgraph "omnibus-gitlab pipeline" end subgraph "gitlab-qa pipeline" - A3>QA jobs run] -.->|3. Reports back the pipeline result to the `package-and-qa-manual` job<br>and post the result on the original commit tested| A1 + A3>QA jobs run] -.->|3. Reports back the pipeline result to the `package-and-qa` job<br>and post the result on the original commit tested| A1 end ``` diff --git a/doc/development/testing_guide/end_to_end/page_objects.md b/doc/development/testing_guide/end_to_end/page_objects.md index 554995fa2e2..f1e0de0c792 100644 --- a/doc/development/testing_guide/end_to_end/page_objects.md +++ b/doc/development/testing_guide/end_to_end/page_objects.md @@ -40,7 +40,7 @@ the time it would take to build packages and test everything. That is why when someone changes `t.text_field :login` to `t.text_field :username` in the _new session_ view we won't know about this change until our GitLab QA nightly pipeline fails, or until someone triggers -`package-and-qa-manual` action in their merge request. +`package-and-qa` action in their merge request. Obviously such a change would break all tests. We call this problem a _fragile tests problem_. @@ -171,8 +171,8 @@ and we should prefer the `data-qa-selector` method of definition. > Introduced in GitLab 12.5 -A common occurrence in automated testing is selecting a single "one-of-many" element. -In a list of several items, how do you differentiate what you are selecting on? +A common occurrence in automated testing is selecting a single "one-of-many" element. +In a list of several items, how do you differentiate what you are selecting on? The most common workaround for this is via text matching. Instead, a better practice is by matching on that specific element by a unique identifier, rather than by text. diff --git a/doc/development/testing_guide/end_to_end/quick_start_guide.md b/doc/development/testing_guide/end_to_end/quick_start_guide.md index fb820ac22a2..be00129a2bc 100644 --- a/doc/development/testing_guide/end_to_end/quick_start_guide.md +++ b/doc/development/testing_guide/end_to_end/quick_start_guide.md @@ -445,7 +445,7 @@ end By defining the `resource_web_url(resource)` method, we override the one from the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb#L44) module. We do that to avoid failing the test due to this particular resource not exposing a `web_url` property. -By defining the `api_get_path` method, we **would** allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single label, but since there's no path available for that in the publich API, we raise a `NotImplementedError` instead. +By defining the `api_get_path` method, we **would** allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to get a single label, but since there's no path available for that in the public API, we raise a `NotImplementedError` instead. By defining the `api_post_path` method, we allow for the [`ApiFabricator`](https://gitlab.com/gitlab-org/gitlab/blob/master/qa/qa/resource/api_fabricator.rb) module to know which path to use to create a new label in a specific project. diff --git a/doc/development/testing_guide/end_to_end/style_guide.md b/doc/development/testing_guide/end_to_end/style_guide.md index 9088e9e9bfb..7f4616f394b 100644 --- a/doc/development/testing_guide/end_to_end/style_guide.md +++ b/doc/development/testing_guide/end_to_end/style_guide.md @@ -54,18 +54,20 @@ We follow a simple formula roughly based on hungarian notation. *Formula*: `element :<descriptor>_<type>` - `descriptor`: The natural-language description of what the element is. On the login page, this could be `username`, or `password`. -- `type`: A physical control on the page that can be seen by a user. +- `type`: A generic control on the page that can be seen by a user. - `_button` - - `_link` - - `_tab` - - `_dropdown` - - `_field` - `_checkbox` + - `_container`: an element that includes other elements, but doesn't present visible content itself. E.g., an element that has a third-party editor inside it, but which isn't the editor itself and so doesn't include the editor's content. + - `_content`: any element that contains text, images, or any other content displayed to the user. + - `_dropdown` + - `_field`: a text input element. + - `_link` + - `_modal`: a popup modal dialog, e.g., a confirmation prompt. + - `_placeholder`: a temporary element that appears while content is loading. For example, the elements that are displayed instead of discussions while the discussions are being fetched. - `_radio` - - `_content` + - `_tab` -*Note: This list is a work in progress. This list will eventually be the end-all enumeration of all available types. - I.e., any element that does not end with something in this list is bad form.* +*Note: If none of the listed types are suitable, please open a merge request to add an appropriate type to the list.* ### Examples diff --git a/doc/development/testing_guide/flaky_tests.md b/doc/development/testing_guide/flaky_tests.md index 3a96f8204fc..5628ca633f6 100644 --- a/doc/development/testing_guide/flaky_tests.md +++ b/doc/development/testing_guide/flaky_tests.md @@ -76,7 +76,7 @@ This was originally implemented in: <https://gitlab.com/gitlab-org/gitlab-foss/m ### Feature tests -- [Be sure to create all the data the test need before starting exercize](https://gitlab.com/gitlab-org/gitlab-foss/issues/32622#note_31128195): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12059> +- [Be sure to create all the data the test need before starting exercise](https://gitlab.com/gitlab-org/gitlab-foss/issues/32622#note_31128195): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12059> - [Bis](https://gitlab.com/gitlab-org/gitlab-foss/issues/34609#note_34048715): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12604> - [Bis](https://gitlab.com/gitlab-org/gitlab-foss/issues/34698#note_34276286): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12664> - [Assert against the underlying database state instead of against a page's content](https://gitlab.com/gitlab-org/gitlab-foss/issues/31437): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/10934> @@ -98,6 +98,10 @@ This was originally implemented in: <https://gitlab.com/gitlab-org/gitlab-foss/m - Memory is through the roof! (TL;DR: Load images but block images requests!): <https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/12003> +#### Capybara expectation times out + +- [Test imports a project (via Sidekiq) that is growing over time, leading to timeouts when the import takes longer than 60 seconds](https://gitlab.com/gitlab-org/gitlab/merge_requests/22599) + ## Resources - [Flaky Tests: Are You Sure You Want to Rerun Them?](http://semaphoreci.com/blog/2017/04/20/flaky-tests.html) diff --git a/doc/development/testing_guide/frontend_testing.md b/doc/development/testing_guide/frontend_testing.md index 8934f0d4b65..56b059063e0 100644 --- a/doc/development/testing_guide/frontend_testing.md +++ b/doc/development/testing_guide/frontend_testing.md @@ -315,7 +315,7 @@ export, one is be generated by the babel plugin). The second parameter is the name of the import you wish to change. The result of the function is a Spy object which can be treated like any other Jasmine spy object. -Further documentation on the babel rewire pluign API can be found on +Further documentation on the babel rewire plugin API can be found on [its repository Readme doc](https://github.com/speedskater/babel-plugin-rewire#babel-plugin-rewire). #### Waiting in tests @@ -532,7 +532,7 @@ In order to ensure that a clean wrapper object and DOM are being used in each te }); ``` -See also the [Vue Test Utils documention on `destroy`](https://vue-test-utils.vuejs.org/api/wrapper/#destroy). +See also the [Vue Test Utils documentation on `destroy`](https://vue-test-utils.vuejs.org/api/wrapper/#destroy). #### Migrating flaky Karma tests to Jest @@ -649,7 +649,7 @@ it('uses some HTML element', () => { HTML and JSON fixtures are generated from backend views and controllers using RSpec (see `spec/frontend/fixtures/*.rb`). For each fixture, the content of the `response` variable is stored in the output file. -This variable gets automagically set if the test is marked as `type: :request` or `type: :controller`. +This variable gets automatically set if the test is marked as `type: :request` or `type: :controller`. Fixtures are regenerated using the `bin/rake frontend:fixtures` command but you can also generate them individually, for example `bin/rspec spec/frontend/fixtures/merge_requests.rb`. When creating a new fixture, it often makes sense to take a look at the corresponding tests for the endpoint in `(ee/)spec/controllers/` or `(ee/)spec/requests/`. diff --git a/doc/development/testing_guide/img/k9s.png b/doc/development/testing_guide/img/k9s.png Binary files differindex c4b222f0b64..34585b2a43a 100644 --- a/doc/development/testing_guide/img/k9s.png +++ b/doc/development/testing_guide/img/k9s.png diff --git a/doc/development/uploads.md b/doc/development/uploads.md index e3ff62f1d2f..3eda0667753 100644 --- a/doc/development/uploads.md +++ b/doc/development/uploads.md @@ -42,7 +42,7 @@ We have three challenges here: performance, availability, and scalability. Rails process are expensive in terms of both CPU and memory. Ruby [global interpreter lock](https://en.wikipedia.org/wiki/Global_interpreter_lock) adds to cost too because the ruby process will spend time on I/O operations on step 3 causing incoming requests to pile up. -In order to improve this, [workhorse disk acceleration](#workhorse-disk-acceleration) was implemented. With this, Rails no longer deals with writing uploaded files to disk. +In order to improve this, [disk buffered upload](#disk-buffered-upload) was implemented. With this, Rails no longer deals with writing uploaded files to disk. ```mermaid graph TB @@ -76,13 +76,13 @@ graph TB There's also an availability problem in this setup, NFS is a [single point of failure](https://en.wikipedia.org/wiki/Single_point_of_failure). -To address this problem an HA object storage can be used and it's supported by [workhorse object storage acceleration](#workhorse-object-storage-acceleration) +To address this problem an HA object storage can be used and it's supported by [direct upload](#direct-upload) ### Scalability Scaling NFS is outside of our support scope, and NFS is not a part of cloud native installations. -All features that require Sidekiq and do not use object storage acceleration won't work without NFS. In Kubernetes, machine boundaries translate to PODs, and in this case the uploaded file will be written into the POD private disk. Since Sidekiq POD cannot reach into other pods, the operation will fail to read it. +All features that require Sidekiq and do not use direct upload won't work without NFS. In Kubernetes, machine boundaries translate to PODs, and in this case the uploaded file will be written into the POD private disk. Since Sidekiq POD cannot reach into other pods, the operation will fail to read it. ## How to select the proper level of acceleration? @@ -90,9 +90,9 @@ Selecting the proper acceleration is a tradeoff between speed of development and We can identify three major use-cases for an upload: -1. **storage:** if we are uploading for storing a file (i.e. artifacts, packages, discussion attachments). In this case [object storage acceleration](#workhorse-object-storage-acceleration) is the proper level as it's the less resource-intensive operation. Additional information can be found on [File Storage in GitLab](file_storage.md). -1. **in-controller/synchronous processing:** if we allow processing **small files** synchronously, using [disk acceleration](#workhorse-disk-acceleration) may speed up development. -1. **Sidekiq/asynchronous processing:** Async processing must implement [object storage acceleration](#workhorse-object-storage-acceleration), the reason being that it's the only way to support Cloud Native deployments without a shared NFS. +1. **storage:** if we are uploading for storing a file (i.e. artifacts, packages, discussion attachments). In this case [direct upload](#direct-upload) is the proper level as it's the less resource-intensive operation. Additional information can be found on [File Storage in GitLab](file_storage.md). +1. **in-controller/synchronous processing:** if we allow processing **small files** synchronously, using [disk buffered upload](#disk-buffered-upload) may speed up development. +1. **Sidekiq/asynchronous processing:** Async processing must implement [direct upload](#direct-upload), the reason being that it's the only way to support Cloud Native deployments without a shared NFS. For more details about currently broken feature see [epic &1802](https://gitlab.com/groups/gitlab-org/-/epics/1802). @@ -122,7 +122,7 @@ By uploading technologies we mean how all the involved services interact with ea GitLab supports 3 kinds of uploading technologies, here follows a brief description with a sequence diagram for each one. Diagrams are not meant to be exhaustive. -### Regular rails upload +### Rack Multipart upload This is the default kind of upload, and it's most expensive in terms of resources. @@ -148,7 +148,7 @@ sequenceDiagram deactivate w ``` -### Workhorse disk acceleration +### Disk buffered upload This kind of upload avoids wasting resources caused by handling upload writes to `/tmp` in rails. @@ -202,7 +202,7 @@ sequenceDiagram end ``` -### Workhorse object storage acceleration +### Direct upload This is the more advanced acceleration technique we have in place. @@ -212,9 +212,8 @@ In this setup an extra rails route needs to be implemented in order to handle au you can see an example of this in [`Projects::LfsStorageController`](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/app/controllers/projects/lfs_storage_controller.rb) and [its routes](https://gitlab.com/gitlab-org/gitlab/blob/cc723071ad337573e0360a879cbf99bc4fb7adb9/config/routes/git_http.rb#L31-32). -NOTE: **Note:** -This will fall back to _Workhorse disk acceleration_ when object storage is not enabled -in the GitLab instance. The answer to the `/authorize` call will only contain a file system path. +**note:** this will fallback to _disk buffered upload_ when `direct_upload` is disabled inside the [object storage setting](../administration/uploads.md#object-storage-settings). +The answer to the `/authorize` call will only contain a file system path. ```mermaid sequenceDiagram @@ -262,11 +261,3 @@ sequenceDiagram deactivate sidekiq end ``` - -## What does the `direct_upload` setting mean? - -[Object storage setting](../administration/uploads.md#object-storage-settings) allows instance administators to enable `direct_upload`, this in an option that only affects the behavior of [workhorse object storage acceleration](#workhorse-object-storage-acceleration). - -This option affect the response to the `/authorize` call. When not enabled, the API response will not contain presigned URLs and workhorse will write the file the shared disk, on the path is provided by rails, acting like object storage was disabled. - -Once the request reachs rails, it will schedule an object storage upload as a Sidekiq job. diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index 9e43758a4aa..356feae4eaf 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -34,6 +34,9 @@ blocking access to the table being modified. See ["Adding Columns With Default Values"](migration_style_guide.md#adding-columns-with-default-values) for more information on how to use this method. +Note that usage of `add_column_with_default` with `allow_null: false` to also add +a `NOT NULL` constraint is [discouraged](https://gitlab.com/gitlab-org/gitlab/issues/38060). + ## Dropping Columns Removing columns is tricky because running GitLab processes may still be using diff --git a/doc/gitlab-basics/add-merge-request.md b/doc/gitlab-basics/add-merge-request.md index 28f32fefb95..1ee28183ac8 100644 --- a/doc/gitlab-basics/add-merge-request.md +++ b/doc/gitlab-basics/add-merge-request.md @@ -1,47 +1,5 @@ --- -type: howto +redirect_to: '../user/project/merge_requests/creating_merge_requests.md' --- -# How to create a merge request - -Merge requests are how you integrate separate changes that you've made in a -[branch](create-branch.md) to a [project](create-project.md). - -This is a brief guide on how to create a merge request. For more detailed information, -check the [merge requests documentation](../user/project/merge_requests/index.md), or -you can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for -a quick overview of working with merge requests. - -1. Before you start, you should have already [created a branch](create-branch.md) - and [pushed your changes](start-using-git.md#send-changes-to-gitlabcom) to GitLab. -1. Go to the project where you'd like to merge your changes and click on the - **Merge requests** tab. -1. Click on **New merge request** on the right side of the screen. -1. From there, you have the option to select the source branch and the target - branch you'd like to compare to. The default target project is the upstream - repository, but you can choose to compare across any of its forks. - -  - -1. When ready, click on the **Compare branches and continue** button. -1. At a minimum, add a title and a description to your merge request. Optionally, - select a user to review your merge request. You may also select a milestone and - labels. - -  - -1. When ready, click on the **Submit merge request** button. - -Your merge request will be ready to be reviewed, approved, and merged. - -<!-- ## Troubleshooting - -Include any troubleshooting steps that you can foresee. If you know beforehand what issues -one might have when setting this up, or when something is changed, or on upgrading, it's -important to describe those, too. Think of things that may go wrong and include them here. -This is important to minimize requests for support, and to avoid doc comments with -questions that you know someone might ask. - -Each scenario can be a third-level heading, e.g. `### Getting error message X`. -If you have none to add when creating a doc, leave this section in place -but commented out to help encourage others to add to it in the future. --> +This document was moved to [another location](../user/project/merge_requests/creating_merge_requests.md). diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 8edce515ec8..74b3afbcd98 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -31,7 +31,14 @@ To create a new blank project on the **New project** page: 1. On the **Blank project** tab, provide the following information: - The name of your project in the **Project name** field. You can't use special characters, but you can use spaces, hyphens, underscores or even - emoji. + emoji. When adding the name, the **Project slug** will auto populate. + The slug is what the GitLab instance will use as the URL path to the project. + If you want a different slug, input the project name first, + then change the slug after. + - The path to your project in the **Project slug** field. This is the URL + path for your project that the GitLab instance will use. If the + **Project name** is blank, it will auto populate when you fill in + the **Project slug**. - The **Project description (optional)** field enables you to enter a description for your project's dashboard, which will help others understand what your project is about. Though it's not required, it's a good diff --git a/doc/gitlab-basics/start-using-git.md b/doc/gitlab-basics/start-using-git.md index 097794d39a7..7fa84bf45bd 100644 --- a/doc/gitlab-basics/start-using-git.md +++ b/doc/gitlab-basics/start-using-git.md @@ -313,7 +313,7 @@ git merge master ### Synchronize changes in a forked repository with the upstream -[Forking a repository](../user/project/repository/forking_workflow.md lets you create +[Forking a repository](../user/project/repository/forking_workflow.md) lets you create a copy of a repository in your namespace. Changes made to your copy of the repository are not synchronized automatically with the original. Your local fork (copy) contains changes made by you only, so to keep the project diff --git a/doc/install/README.md b/doc/install/README.md index 441826687aa..6b497763d93 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -87,3 +87,7 @@ the above methods, provided the cloud provider supports it. - [Install GitLab on DigitalOcean](https://about.gitlab.com/blog/2016/04/27/getting-started-with-gitlab-and-digitalocean/): Install Omnibus GitLab on DigitalOcean. - _Testing only!_ [DigitalOcean and Docker Machine](digitaloceandocker.md): Quickly test any version of GitLab on DigitalOcean using Docker Machine. + +## Securing your GitLab installation + +After completing your installation, check out our [recommended practices to secure your GitLab instance](../security/README.md#securing-your-gitlab-installation). diff --git a/doc/install/aws/index.md b/doc/install/aws/index.md index 8165d3edabb..a3b9124a2ba 100644 --- a/doc/install/aws/index.md +++ b/doc/install/aws/index.md @@ -211,7 +211,7 @@ create the actual RDS instance. Now, it's time to create the database: -1. Select **Instances** from the left menu and click **Create database**. +1. Select **Databases** from the left menu and click **Create database**. 1. Select PostgreSQL and click **Next**. 1. Since this is a production server, let's choose "Production". Click **Next**. 1. Let's see the instance specifications: @@ -244,7 +244,7 @@ Once the database is created, connect to your new RDS instance to verify access and to install a required extension. You can find the host or endpoint by selecting the instance you just created and -after the details drop down you'll find it labeled as 'Endpoint'. Do not to +after the details dropdown menu you'll find it labeled as 'Endpoint'. Do not to include the colon and port number: ```sh diff --git a/doc/install/azure/index.md b/doc/install/azure/index.md index c789467175a..5baaec79048 100644 --- a/doc/install/azure/index.md +++ b/doc/install/azure/index.md @@ -226,7 +226,7 @@ connections:  1. Enter **"HTTP"** in the `Name` field -1. Select **HTTP** from the options in the `Service` drop-down +1. Select **HTTP** from the options in the `Service` dropdown list 1. Make sure the `Action` is set to **Allow** 1. Click **"OK"** @@ -238,7 +238,7 @@ accept [SSH] connections:  1. Enter **"SSH"** in the `Name` field -1. Select **SSH** from the options in the `Service` drop-down +1. Select **SSH** from the options in the `Service` dropdown list 1. Make sure the `Action` is set to **Allow** 1. Click **"OK"** diff --git a/doc/install/installation.md b/doc/install/installation.md index d420ac5e952..5cd8f98b2f3 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -224,9 +224,9 @@ Download Ruby and compile it: ```sh mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.3.tar.gz -echo '2347ed6ca5490a104ebd5684d2b9b5eefa6cd33c ruby-2.6.3.tar.gz' | shasum -c - && tar xzf ruby-2.6.3.tar.gz -cd ruby-2.6.3 +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.5.tar.gz +echo '1416ce288fb8bfeae07a12b608540318c9cace71 ruby-2.6.5.tar.gz' | shasum -c - && tar xzf ruby-2.6.5.tar.gz +cd ruby-2.6.5 ./configure --disable-install-rdoc make @@ -250,11 +250,11 @@ page](https://golang.org/dl). # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --progress https://dl.google.com/go/go1.11.10.linux-amd64.tar.gz -echo 'aefaa228b68641e266d1f23f1d95dba33f17552ba132878b65bb798ffa37e6d0 go1.11.10.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.11.10.linux-amd64.tar.gz +curl --remote-name --progress https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz +echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569 go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.11.10.linux-amd64.tar.gz +rm go1.13.5.linux-amd64.tar.gz ``` ## 4. Node diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 106c7714bfe..9bc1658d59c 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -38,14 +38,40 @@ GitLab is developed for Linux-based operating systems. It does **not** run on Microsoft Windows, and we have no plans to support it in the near future. For the latest development status view this [issue](https://gitlab.com/gitlab-org/gitlab/issues/22337). Please consider using a virtual machine to run GitLab. -## Ruby versions +## Software requirements -GitLab requires Ruby (MRI) 2.6. Support for Ruby versions below 2.6 (2.4, 2.5) will stop with GitLab 12.2. +### Ruby versions -You will have to use the standard MRI implementation of Ruby. -We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com) but GitLab +GitLab requires Ruby (MRI) 2.6. Beginning in GitLab 12.2, we no longer support Ruby 2.5 and lower. + +You must use the standard MRI implementation of Ruby. +We love [JRuby](https://www.jruby.org/) and [Rubinius](https://rubinius.com), but GitLab needs several Gems that have native extensions. +### Go versions + +The minimum required Go version is 1.12. + +### Git versions + +GitLab 11.11 and higher only supports Git 2.21.x and newer, and +[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-foss/issues/54255). + +### Node.js versions + +Beginning in GitLab 11.8, we only support Node.js 8.10.0 or higher, and dropped +support for Node.js 6. + +We recommend Node 12.x, as it is faster. + +GitLab uses [webpack](https://webpack.js.org/) to compile frontend assets, which requires a minimum +version of Node.js 8.10.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v8.10.0`, you need to update to a newer version. You +can find instructions to install from community maintained packages or compile +from source at the [Node.js website](https://nodejs.org/en/download). + ## Hardware requirements ### Storage @@ -210,7 +236,7 @@ For reference, GitLab.com's [auto-scaling shared runner](../user/gitlab_com/inde ## Supported web browsers -We support the current and the previous major release of: +GitLab supports the following web browsers: - Firefox - Chrome/Chromium @@ -218,10 +244,11 @@ We support the current and the previous major release of: - Microsoft Edge - Internet Explorer 11 -The browser vendors release regular minor version updates with important bug fixes and security updates. -Support is only provided for the current minor version of the major version you are running. +For the listed web browsers, GitLab supports: -Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version. +- The current and previous major versions of browsers except Internet Explorer. +- Only version 11 of Internet Explorer. +- The current minor version of a supported major version. NOTE: **Note:** We do not support running GitLab with JavaScript disabled in the browser and have no plans of supporting that in the future because we have features such as Issue Boards which require JavaScript extensively. diff --git a/doc/integration/elasticsearch.md b/doc/integration/elasticsearch.md index 62b3de72a3a..44f32343151 100644 --- a/doc/integration/elasticsearch.md +++ b/doc/integration/elasticsearch.md @@ -17,9 +17,10 @@ special searches: | GitLab version | Elasticsearch version | | -------------- | --------------------- | -| GitLab Enterprise Edition 8.4 - 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | +| GitLab Enterprise Edition 8.4 - 8.17 | Elasticsearch 2.4 with [Delete By Query Plugin](https://www.elastic.co/guide/en/elasticsearch/plugins/2.4/plugins-delete-by-query.html) installed | | GitLab Enterprise Edition 9.0 - 11.4 | Elasticsearch 5.1 - 5.5 | -| GitLab Enterprise Edition 11.5+ | Elasticsearch 5.6 - 6.x | +| GitLab Enterprise Edition 11.5 - 12.6 | Elasticsearch 5.6 - 6.x | +| GitLab Enterprise Edition 12.7+ | Elasticsearch 6.x - 7.x | ## Installing Elasticsearch @@ -36,18 +37,20 @@ it yourself or by using the service. Running Elasticsearch on the same server as GitLab is not recommended and it will likely cause performance degradation on the GitLab installation. +NOTE: **Note:** +**For a single node Elasticsearch cluster the functional cluster health status will be yellow** (will never be green) because the primary shard is allocated but replicas can not be as there is no other node to which Elasticsearch can assign a replica. + Once the data is added to the database or repository and [Elasticsearch is -enabled in the admin area](#enabling-elasticsearch) the search index will be +enabled in the Admin Area](#enabling-elasticsearch) the search index will be updated automatically. -## Elasticsearch repository indexer (beta) +## Elasticsearch repository indexer -In order to improve Elasticsearch indexing performance, GitLab has made available a [new indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). -This will replace the included Ruby indexer in the future but should be considered beta software for now, so there may be some bugs. +For indexing Git repository data, GitLab uses an [indexer written in Go](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). -The Elasticsearch Go indexer is included in Omnibus for GitLab 11.8 and newer. - -To use the new Elasticsearch indexer included in Omnibus, check the box "Use the new repository indexer (beta)" when [enabling the Elasticsearch integration](#enabling-elasticsearch). +The Go indexer was included in Omnibus GitLab 11.8 as an optional replacement to a +Ruby-based indexer. [Since GitLab v12.3](https://gitlab.com/gitlab-org/gitlab/issues/6481), +all indexing is done by the Go indexer, and the Ruby indexer is removed. If you would like to use the Elasticsearch Go indexer with a source installation or an older version of GitLab, please follow the instructions below. @@ -139,7 +142,6 @@ The following Elasticsearch settings are available: | Parameter | Description | | ----------------------------------------------------- | ----------- | | `Elasticsearch indexing` | Enables/disables Elasticsearch indexing. You may want to enable indexing but disable search in order to give the index time to be fully completed, for example. Also, keep in mind that this option doesn't have any impact on existing data, this only enables/disables background indexer which tracks data changes. So by enabling this you will not get your existing data indexed, use special rake task for that as explained in [Adding GitLab's data to the Elasticsearch index](#adding-gitlabs-data-to-the-elasticsearch-index). | -| `Use the new repository indexer (beta)` | Perform repository indexing using [GitLab Elasticsearch Indexer](https://gitlab.com/gitlab-org/gitlab-elasticsearch-indexer). | | `Search with Elasticsearch enabled` | Enables/disables using Elasticsearch in search. | | `URL` | The URL to use for connecting to Elasticsearch. Use a comma-separated list to support clustering (e.g., `http://host1, https://host2:9200`). If your Elasticsearch instance is password protected, pass the `username:password` in the URL (e.g., `http://<username>:<password>@<elastic_host>:9200/`). | | `Number of Elasticsearch shards` | Elasticsearch indexes are split into multiple shards for performance reasons. In general, larger indexes need to have more shards. Changes to this value do not take effect until the index is recreated. You can read more about tradeoffs in the [Elasticsearch documentation](https://www.elastic.co/guide/en/elasticsearch/reference/current/indices-create-index.html#create-index-settings) | @@ -200,10 +202,9 @@ To backfill existing data, you can use one of the methods below to index it in b > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/15390) in [GitLab Starter](https://about.gitlab.com/pricing/) 12.3. -To index via the admin area: +To index via the Admin Area: -1. Navigate to the **Admin Area** (wrench icon), then **Settings > Integrations** and expand the **Elasticsearch** section. -1. [Enable **Elasticsearch indexing** and configure your host and port](#enabling-elasticsearch). +1. [Configure your Elasticsearch host and port](#enabling-elasticsearch). 1. Create empty indexes using one of the following commands: ```sh @@ -214,7 +215,8 @@ To index via the admin area: bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production ``` -1. Click **Index all projects**. +1. [Enable **Elasticsearch indexing**](#enabling-elasticsearch). +1. Click **Index all projects** in **Admin Area > Settings > Integrations > Elasticsearch**. 1. Click **Check progress** in the confirmation message to see the status of the background jobs. 1. Personal snippets need to be indexed manually by running one of these commands: @@ -257,7 +259,7 @@ Performing asynchronous indexing will generate a lot of Sidekiq jobs. Make sure to prepare for this task by either [Horizontally Scaling](../administration/high_availability/README.md#basic-scaling) or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq_processes.md) -1. [Enable **Elasticsearch indexing** and configure your host and port](#enabling-elasticsearch). +1. [Configure your Elasticsearch host and port](#enabling-elasticsearch). 1. Create empty indexes using one of the following commands: ```sh @@ -268,6 +270,7 @@ or creating [extra Sidekiq processes](../administration/operations/extra_sidekiq bundle exec rake gitlab:elastic:create_empty_index RAILS_ENV=production ``` +1. [Enable **Elasticsearch indexing**](#enabling-elasticsearch). 1. Indexing large Git repositories can take a while. To speed up the process, you can temporarily disable auto-refreshing and replicating. In our experience, you can expect a 20% decrease in indexing time. We'll enable them when indexing is done. This step is optional! @@ -592,6 +595,23 @@ Here are some common pitfalls and how to overcome them: AWS has [fixed limits](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-limits.html) for this setting ("Maximum Size of HTTP Request Payloads"), based on the size of the underlying instance. + +- **My single node Elasticsearch cluster status never goes from `yellow` to `green` even though everything seems to be running properly** + + **For a single node Elasticsearch cluster the functional cluster health status will be yellow** (will never be green) because the primary shard is allocated but replicas can not be as there is no other node to which Elasticsearch can assign a replica. This also applies if you are using using the +[Amazon Elasticsearch](https://docs.aws.amazon.com/elasticsearch-service/latest/developerguide/aes-handling-errors.html#aes-handling-errors-yellow-cluster-status) service. + + CAUTION: **Warning**: Setting the number of replicas to `0` is not something that we recommend (this is not allowed in the GitLab Elasticsearch Integration menu). If you are planning to add more Elasticsearch nodes (for a total of more than 1 Elasticsearch) the number of replicas will need to be set to an integer value larger than `0`. Failure to do so will result in lack of redundancy (losing one node will corrupt the index). + + If you have a **hard requirement to have a green status for your single node Elasticsearch cluster**, please make sure you understand the risks outlined in the previous paragraph and then simply run the following query to set the number of replicas to `0`(the cluster will no longer try to create any shard replicas): + + ```bash + curl --request PUT localhost:9200/gitlab-production/_settings --header 'Content-Type: application/json' --data '{ + "index" : { + "number_of_replicas" : 0 + } + }' + ``` ### Reverting to basic search diff --git a/doc/integration/img/authorize_vault_with_gitlab_v12_6.png b/doc/integration/img/authorize_vault_with_gitlab_v12_6.png Binary files differindex dc5bc954cd7..2c9810bc9e8 100644 --- a/doc/integration/img/authorize_vault_with_gitlab_v12_6.png +++ b/doc/integration/img/authorize_vault_with_gitlab_v12_6.png diff --git a/doc/integration/img/gitlab_oauth_vault_v12_6.png b/doc/integration/img/gitlab_oauth_vault_v12_6.png Binary files differindex f952abc2c6d..08fc56c8ec9 100644 --- a/doc/integration/img/gitlab_oauth_vault_v12_6.png +++ b/doc/integration/img/gitlab_oauth_vault_v12_6.png diff --git a/doc/integration/img/sign_into_vault_with_gitlab_v12_6.png b/doc/integration/img/sign_into_vault_with_gitlab_v12_6.png Binary files differindex 8afa2c6aabd..474473e334d 100644 --- a/doc/integration/img/sign_into_vault_with_gitlab_v12_6.png +++ b/doc/integration/img/sign_into_vault_with_gitlab_v12_6.png diff --git a/doc/integration/img/signed_into_vault_via_oidc_v12_6.png b/doc/integration/img/signed_into_vault_via_oidc_v12_6.png Binary files differindex 0ad81ef40e6..0a7f86ff5f0 100644 --- a/doc/integration/img/signed_into_vault_via_oidc_v12_6.png +++ b/doc/integration/img/signed_into_vault_via_oidc_v12_6.png diff --git a/doc/integration/img/sourcegraph_admin_v12_5.png b/doc/integration/img/sourcegraph_admin_v12_5.png Binary files differindex 23e38f56619..54511541c87 100644 --- a/doc/integration/img/sourcegraph_admin_v12_5.png +++ b/doc/integration/img/sourcegraph_admin_v12_5.png diff --git a/doc/integration/img/sourcegraph_demo_v12_5.png b/doc/integration/img/sourcegraph_demo_v12_5.png Binary files differindex c70448c0a8a..35a2e2a89e3 100644 --- a/doc/integration/img/sourcegraph_demo_v12_5.png +++ b/doc/integration/img/sourcegraph_demo_v12_5.png diff --git a/doc/integration/img/sourcegraph_popover_v12_5.png b/doc/integration/img/sourcegraph_popover_v12_5.png Binary files differindex 878d6143646..62fa48129b2 100644 --- a/doc/integration/img/sourcegraph_popover_v12_5.png +++ b/doc/integration/img/sourcegraph_popover_v12_5.png diff --git a/doc/integration/img/sourcegraph_user_preferences_v12_5.png b/doc/integration/img/sourcegraph_user_preferences_v12_5.png Binary files differindex 2c0e138e296..7b7f8945431 100644 --- a/doc/integration/img/sourcegraph_user_preferences_v12_5.png +++ b/doc/integration/img/sourcegraph_user_preferences_v12_5.png diff --git a/doc/integration/jira_development_panel.md b/doc/integration/jira_development_panel.md index a3a66cf6cf2..02cfdc32abb 100644 --- a/doc/integration/jira_development_panel.md +++ b/doc/integration/jira_development_panel.md @@ -100,7 +100,7 @@ There are no special requirements if you are using GitLab.com. every 60 minutes. > **Note:** - > In the future, we plan on implementating real-time integration. If you need + > In the future, we plan on implementing real-time integration. If you need > to refresh the data manually, you can do this from the `Applications -> DVCS > accounts` screen where you initially set up the integration: > diff --git a/doc/integration/kerberos.md b/doc/integration/kerberos.md index 2a3e2e43d72..1cdbdb1c40e 100644 --- a/doc/integration/kerberos.md +++ b/doc/integration/kerberos.md @@ -265,7 +265,7 @@ so the client will fall back to attempting to negotiate `IAKERB`, leading to the above error message. To fix this, ensure that the forward and reverse DNS for your GitLab server -match. So for instance, if you acces GitLab as `gitlab.example.com`, resolving +match. So for instance, if you access GitLab as `gitlab.example.com`, resolving to IP address `1.2.3.4`, then `4.3.2.1.in-addr.arpa` must be a PTR record for `gitlab.example.com`. diff --git a/doc/integration/oauth_provider.md b/doc/integration/oauth_provider.md index 36b4836e6b3..6c9b272f35b 100644 --- a/doc/integration/oauth_provider.md +++ b/doc/integration/oauth_provider.md @@ -26,7 +26,7 @@ The 'GitLab Importer' feature is also using the OAuth protocol to give access to repositories without sharing user credentials to your GitLab.com account. GitLab supports two ways of adding a new OAuth2 application to an instance. You -can either add an application as a regular user or add it in the admin area. +can either add an application as a regular user or add it in the Admin Area. What this means is that GitLab can actually have instance-wide and a user-wide applications. There is no difference between them except for the different permission levels they are set (user/admin). The default callback URL is @@ -51,14 +51,14 @@ connects to GitLab.  -## OAuth applications in the admin area +## OAuth applications in the Admin Area To create an application that does not belong to a certain user, you can create -it from the admin area. +it from the Admin Area.  -You're also able to mark an application as _trusted_ when creating it through the admin area. By doing that, +You're also able to mark an application as _trusted_ when creating it through the Admin Area. By doing that, the user authorization step is automatically skipped for this application. ## Authorized applications diff --git a/doc/integration/saml.md b/doc/integration/saml.md index a667c2e84c9..11e768194bc 100644 --- a/doc/integration/saml.md +++ b/doc/integration/saml.md @@ -155,7 +155,7 @@ Identity Provider. ### Requirements First you need to tell GitLab where to look for group information. For this you -need to make sure that your IdP server sends a specific `AttributeStament` along +need to make sure that your IdP server sends a specific `AttributeStatement` along with the regular SAML response. Here is an example: ```xml diff --git a/doc/integration/sourcegraph.md b/doc/integration/sourcegraph.md index 358657ca172..25d1ef457c0 100644 --- a/doc/integration/sourcegraph.md +++ b/doc/integration/sourcegraph.md @@ -100,7 +100,7 @@ When visiting one of these views, you can now hover over a code reference to see - Details on how this reference was defined. - **Go to definition**, which navigates to the line of code where this reference was defined. -- **Find references**, which navigates to the configured Sourcegraph instance, showing a list of references to the hilighted code. +- **Find references**, which navigates to the configured Sourcegraph instance, showing a list of references to the highlighted code.  diff --git a/doc/integration/vault.md b/doc/integration/vault.md index 68803fed35d..8bd0897548a 100644 --- a/doc/integration/vault.md +++ b/doc/integration/vault.md @@ -7,7 +7,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/22323) in GitLab 9.0 [Vault](https://www.vaultproject.io/) is a secrets management application offered by HashiCorp. -It allows you to store and manage sensitive information such secret environment variables, encryption keys, and authentication tokens. +It allows you to store and manage sensitive information such as secret environment variables, encryption keys, and authentication tokens. Vault offers Identity-based Access, which means Vault users can authenticate through several of their preferred cloud providers. In this document, we'll explain how Vault users can authenticate themselves through GitLab by utilizing our OpenID authentication feature. diff --git a/doc/policy/maintenance.md b/doc/policy/maintenance.md index 7617d0c8881..1739c07ccd5 100644 --- a/doc/policy/maintenance.md +++ b/doc/policy/maintenance.md @@ -7,6 +7,11 @@ type: concepts GitLab has strict policies governing version naming, as well as release pace for major, minor, patch and security releases. New releases are usually announced on the [GitLab blog](https://about.gitlab.com/blog/categories/releases/). +Our current policy is: + +- Backporting bug fixes for **only the current stable release** at any given time, see [patch releases](#patch-releases). +- Backporting to **to the previous two monthly releases in addition to the current stable release**, see [security releases](#security-releases). + ## Versioning GitLab uses [Semantic Versioning](https://semver.org/) for its releases: @@ -30,8 +35,6 @@ The following table describes the version types and their release cadence: ## Patch releases -Our current policy is to support **only the current stable release** at any given time. - Patch releases **only include bug fixes** for the current stable released version of GitLab. @@ -97,10 +100,7 @@ To request backporting to more than one stable release for consideration, raise ### Security releases Security releases are a special kind of patch release that only include security -fixes and patches (see below). - -Our current policy is to backport security fixes to the previous two -monthly releases in addition to the current stable release. +fixes and patches (see below) for the previous two monthly releases in addition to the current stable release. For very serious security issues, there is [precedent](https://about.gitlab.com/blog/2016/05/02/cve-2016-4340-patches/) @@ -139,6 +139,11 @@ We cannot guarantee that upgrading between major versions will be seamless. As p We recommend that you first upgrade to the latest available minor version within your major version. By doing this, you can address any deprecation messages that could change behavior in the next major release. + +It's also important to ensure that any background migrations have been fully completed +before upgrading to a new major version. To see the current size of the `background_migration` queue, +[Check for background migrations before upgrading](../update/README.md#checking-for-background-migrations-before-upgrading). + To ensure background migrations are successful, increment by one minor version during the version jump before installing newer releases. For example: `11.11.x` -> `12.0.x` @@ -151,9 +156,6 @@ Please see the table below for some examples: | 11.3.4 | 8.13.4 | `8.13.4` -> `8.17.7` -> `9.5.10` -> `10.8.7` -> `11.3.4` | `8.17.7` is the last version in version `8`, `9.5.10` is the last version in version `9`, `10.8.7` is the last version in version `10` | | 12.5.8 | 11.3.4 | `11.3.4` -> `11.11.8` -> `12.0.9` -> `12.5.8` | `11.11.8` is the last version in version `11` | -To check the size of `background_migration` queue and to learn more about background migrations -see [Upgrading without downtime](../update/README.md#upgrading-without-downtime). - More information about the release procedures can be found in our [release documentation](https://gitlab.com/gitlab-org/release/docs). You may also want to read our [Responsible Disclosure Policy](https://about.gitlab.com/security/disclosure/). diff --git a/doc/public_access/img/project_visibility_confirmation_v12_6.png b/doc/public_access/img/project_visibility_confirmation_v12_6.png Binary files differindex ac4d70ff11a..8fba57f353b 100644 --- a/doc/public_access/img/project_visibility_confirmation_v12_6.png +++ b/doc/public_access/img/project_visibility_confirmation_v12_6.png diff --git a/doc/push_rules/push_rules.md b/doc/push_rules/push_rules.md index d778d6b929c..f26cf0cece0 100644 --- a/doc/push_rules/push_rules.md +++ b/doc/push_rules/push_rules.md @@ -52,7 +52,7 @@ will get rejected. ### Custom Push Rules **(CORE ONLY)** It's possible to create custom push rules rather than the push rules available in -**Admin area > Push Rules** by using more advanced server-side Git hooks. +**Admin Area > Push Rules** by using more advanced server-side Git hooks. See [custom server-side Git hooks](../administration/custom_hooks.md) for more information. @@ -60,7 +60,7 @@ See [custom server-side Git hooks](../administration/custom_hooks.md) for more i NOTE: **Note:** GitLab administrators can set push rules globally under -**Admin area > Push Rules** that all new projects will inherit. You can later +**Admin Area > Push Rules** that all new projects will inherit. You can later override them in a project's settings. 1. Navigate to your project's **Settings > Repository** and expand **Push Rules** diff --git a/doc/raketasks/README.md b/doc/raketasks/README.md index ad86555fc17..a9ba44f82c6 100644 --- a/doc/raketasks/README.md +++ b/doc/raketasks/README.md @@ -14,5 +14,5 @@ comments: false - [Webhooks](web_hooks.md) - [Import](import.md) of Git repositories in bulk - [Rebuild authorized_keys file](../administration/raketasks/maintenance.md#rebuild-authorized_keys-file) task for administrators -- [Migrate Uploads](../administration/raketasks/uploads/migrate.md) -- [Sanitize Uploads](../administration/raketasks/uploads/sanitize.md) +- [Uploads Migrate](../administration/raketasks/uploads/migrate.md) +- [Uploads Sanitize](../administration/raketasks/uploads/sanitize.md) diff --git a/doc/raketasks/generate_sample_prometheus_data.md b/doc/raketasks/generate_sample_prometheus_data.md index 2489a2c2ad3..bb0ed68ec0f 100644 --- a/doc/raketasks/generate_sample_prometheus_data.md +++ b/doc/raketasks/generate_sample_prometheus_data.md @@ -1,11 +1,11 @@ # Generate Sample Prometheus Data This command will run Prometheus queries for each of the metrics of a specific environment -for a default time interval of 7 days ago to now. The results of each of query are stored -under a `sample_metrics` directory as a yaml file named by the metric's `identifier`. -When the environmental variable `USE_SAMPLE_METRICS` is set, the Prometheus API query is -re-routed to `Projects::Environments::SampleMetricsController` which loads the appropriate -data set if it is present within the `sample_metrics` directory. +for a series of time intervals: 30 minutes, 3 hours, 8 hours, 24 hours, 72 hours, and 7 days +to now. The results of each of query are stored under a `sample_metrics` directory as a yaml +file named by the metric's `identifier`. When the environmental variable `USE_SAMPLE_METRICS` +is set, the Prometheus API query is re-routed to `Projects::Environments::SampleMetricsController` +which loads the appropriate data set if it is present within the `sample_metrics` directory. - This command requires an id from an Environment with an available Prometheus installation. diff --git a/doc/security/README.md b/doc/security/README.md index fe96f7f2846..20da1a2c77c 100644 --- a/doc/security/README.md +++ b/doc/security/README.md @@ -19,3 +19,9 @@ type: index - [Send email confirmation on sign-up](user_email_confirmation.md) - [Security of running jobs](https://docs.gitlab.com/runner/security/) - [Proxying images](asset_proxy.md) + +## Securing your GitLab installation + +To make sure your GitLab instance is safe and secure, please consider implementing +[Sign up restrictions](../user/admin_area/settings/sign_up_restrictions.md) to avoid +malicious users creating accounts. diff --git a/doc/security/asset_proxy.md b/doc/security/asset_proxy.md index 6e615028e8b..5522a41ff01 100644 --- a/doc/security/asset_proxy.md +++ b/doc/security/asset_proxy.md @@ -30,22 +30,22 @@ To install a Camo server as an asset proxy: 1. Make sure your instance of GitLab is running, and that you have created a private API token. Using the API, configure the asset proxy settings on your GitLab instance. For example: - ```sh - curl --request "PUT" "https://gitlab.example.com/api/v4/application/settings?\ - asset_proxy_enabled=true&\ - asset_proxy_url=https://proxy.gitlab.example.com&\ - asset_proxy_secret_key=<somekey>" \ - --header 'PRIVATE-TOKEN: <my_private_token>' - ``` - - The following settings are supported: - - | Attribute | Description | - |:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------| - | `asset_proxy_enabled` | Enable proxying of assets. If enabled, requires: `asset_proxy_url`). | - | `asset_proxy_secret_key` | Shared secret with the asset proxy server. | - | `asset_proxy_url` | URL of the asset proxy server. | - | `asset_proxy_whitelist` | Assets that match these domain(s) will NOT be proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. | + ```sh + curl --request "PUT" "https://gitlab.example.com/api/v4/application/settings?\ + asset_proxy_enabled=true&\ + asset_proxy_url=https://proxy.gitlab.example.com&\ + asset_proxy_secret_key=<somekey>" \ + --header 'PRIVATE-TOKEN: <my_private_token>' + ``` + + The following settings are supported: + + | Attribute | Description | + |:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------| + | `asset_proxy_enabled` | Enable proxying of assets. If enabled, requires: `asset_proxy_url`). | + | `asset_proxy_secret_key` | Shared secret with the asset proxy server. | + | `asset_proxy_url` | URL of the asset proxy server. | + | `asset_proxy_whitelist` | Assets that match these domain(s) will NOT be proxied. Wildcards allowed. Your GitLab installation URL is automatically whitelisted. | 1. Restart the server for the changes to take effect. Each time you change any values for the asset proxy, you need to restart the server. diff --git a/doc/security/password_length_limits.md b/doc/security/password_length_limits.md index 235730eb825..c00fd78c4d3 100644 --- a/doc/security/password_length_limits.md +++ b/doc/security/password_length_limits.md @@ -49,7 +49,7 @@ From GitLab 12.6, the minimum password length set in this configuration file wil The user password length is set to a minimum of 8 characters by default. To change that using GitLab UI: -In the Admin area under **Settings** (`/admin/application_settings`), go to section **Sign-up Restrictions**. +In **Admin Area > Settings** (`/admin/application_settings`), go to the section **Sign-up restrictions**. [Minimum password length settings](../user/admin_area/img/minimum_password_length_settings_v12_6.png) diff --git a/doc/security/ssh_keys_restrictions.md b/doc/security/ssh_keys_restrictions.md index 4c60daf77f4..176b09168c4 100644 --- a/doc/security/ssh_keys_restrictions.md +++ b/doc/security/ssh_keys_restrictions.md @@ -17,8 +17,8 @@ algorithms. GitLab allows you to restrict the allowed SSH key technology as well as specify the minimum key length for each technology. -In the Admin area under **Settings** (`/admin/application_settings`), look for -the "Visibility and Access Controls" area: +In **Admin Area > Settings** (`/admin/application_settings`), expand the +**Visibility and access controls** section:  diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index defc4669e69..39f92f95ba1 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -25,7 +25,7 @@ won't be able to leave the 2FA configuration area at `/profile/two_factor_auth`. To enable 2FA for all users: -1. Navigate to **Admin area > Settings > General** (`/admin/application_settings`). +1. Navigate to **Admin Area > Settings > General** (`/admin/application_settings`). 1. Expand the **Sign-in restrictions** section, where you can configure both. If you want 2FA enforcement to take effect on next login, change the grace diff --git a/doc/security/user_email_confirmation.md b/doc/security/user_email_confirmation.md index 7ba50acbb06..3abfbe96a59 100644 --- a/doc/security/user_email_confirmation.md +++ b/doc/security/user_email_confirmation.md @@ -8,7 +8,7 @@ GitLab can be configured to require confirmation of a user's email address when the user signs up. When this setting is enabled, the user is unable to sign in until they confirm their email address. -In the Admin area under **Settings** (`/admin/application_settings`), go to section +In **Admin Area > Settings** (`/admin/application_settings`), go to the section **Sign-up Restrictions** and look for the **Send confirmation email on sign-up** option. <!-- ## Troubleshooting diff --git a/doc/security/webhooks.md b/doc/security/webhooks.md index cb9ad2b694c..010f5aa2d43 100644 --- a/doc/security/webhooks.md +++ b/doc/security/webhooks.md @@ -35,13 +35,12 @@ to endpoints like `http://localhost:123/some-resource/delete`. To prevent this type of exploitation from happening, starting with GitLab 10.6, all Webhook requests to the current GitLab instance server address and/or in a private network will be forbidden by default. That means that all requests made -to 127.0.0.1, ::1 and 0.0.0.0, as well as IPv4 10.0.0.0/8, 172.16.0.0/12, -192.168.0.0/16 and IPv6 site-local (ffc0::/10) addresses won't be allowed. +to `127.0.0.1`, `::1` and `0.0.0.0`, as well as IPv4 `10.0.0.0/8`, `172.16.0.0/12`, +`192.168.0.0/16` and IPv6 site-local (`ffc0::/10`) addresses won't be allowed. This behavior can be overridden by enabling the option *"Allow requests to the local network from web hooks and services"* in the *"Outbound requests"* section -inside the Admin area under **Settings** -(`/admin/application_settings/network`): +inside the **Admin Area > Settings** (`/admin/application_settings/network`):  @@ -61,7 +60,7 @@ and expand **Outbound requests**:  -The whilelist entries can be separated by semicolons, commas or whitespaces +The whitelist entries can be separated by semicolons, commas or whitespaces (including newlines) and be in different formats like hostnames, IP addresses and/or IP ranges. IPv6 is supported. Hostnames that contain unicode characters should use IDNA encoding. diff --git a/doc/ssh/README.md b/doc/ssh/README.md index 80b8db84bed..5a3f97de77d 100644 --- a/doc/ssh/README.md +++ b/doc/ssh/README.md @@ -183,7 +183,7 @@ Now, it's time to add the newly created public key to your GitLab account. 1. Add your **public** SSH key to your GitLab account by: 1. Clicking your avatar in the upper right corner and selecting **Settings**. - 1. Navigating to **SSH Keys** and pasting your **public** key in the **Key** field. If you: + 1. Navigating to **SSH Keys** and pasting your **public** key from the clipboard into the **Key** field. If you: - Created the key with a comment, this will appear in the **Title** field. - Created the key without a comment, give your key an identifiable title like _Work Laptop_ or _Home Workstation_. 1. Click the **Add key** button. @@ -376,7 +376,7 @@ Global Shared Keys can provide greater security compared to Per-Project Deploy Keys since an administrator of the target integrated system is the only one who needs to know and configure the private key. -GitLab administrators set up Global Deploy keys in the Admin area under the +GitLab administrators set up Global Deploy keys in the Admin Area under the section **Deploy Keys**. Ensure keys have a meaningful title as that will be the primary way for project maintainers and owners to identify the correct Global Deploy key to add. For instance, if the key gives access to a SaaS CI instance, diff --git a/doc/tools/email.md b/doc/tools/email.md index 3088b0b63e7..e9ff88152ba 100644 --- a/doc/tools/email.md +++ b/doc/tools/email.md @@ -5,7 +5,7 @@ type: howto, reference # Email from GitLab **(STARTER ONLY)** GitLab provides a simple tool to administrators for emailing all users, or users of -a chosen group or project, right from the admin area. Users will receive the email +a chosen group or project, right from the Admin Area. Users will receive the email at their primary email address. ## Use-cases @@ -16,8 +16,8 @@ at their primary email address. ## Sending emails to users from within GitLab -1. Go to the admin area using the wrench icon in the top right corner and - navigate to **Overview > Users > Send email to users**. +1. Navigate to the **Admin Area > Overview > Users** and press the + **Send email to users** button.  diff --git a/doc/topics/autodevops/img/autodevops_banner_v12_6.png b/doc/topics/autodevops/img/autodevops_banner_v12_6.png Binary files differindex 51ccdeeaa52..abf492c5247 100644 --- a/doc/topics/autodevops/img/autodevops_banner_v12_6.png +++ b/doc/topics/autodevops/img/autodevops_banner_v12_6.png diff --git a/doc/topics/autodevops/img/guide_base_domain_v12_3.png b/doc/topics/autodevops/img/guide_base_domain_v12_3.png Binary files differindex 0c8ab9b26e4..7d3b6a2f905 100644 --- a/doc/topics/autodevops/img/guide_base_domain_v12_3.png +++ b/doc/topics/autodevops/img/guide_base_domain_v12_3.png diff --git a/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png b/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png Binary files differindex f903ae40c02..9be414434c7 100644 --- a/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png +++ b/doc/topics/autodevops/img/guide_cluster_apps_v12_3.png diff --git a/doc/topics/autodevops/img/guide_create_project_v12_3.png b/doc/topics/autodevops/img/guide_create_project_v12_3.png Binary files differindex 68ab7f23f3c..a22730520ef 100644 --- a/doc/topics/autodevops/img/guide_create_project_v12_3.png +++ b/doc/topics/autodevops/img/guide_create_project_v12_3.png diff --git a/doc/topics/autodevops/img/guide_enable_autodevops_v12_3.png b/doc/topics/autodevops/img/guide_enable_autodevops_v12_3.png Binary files differindex 7f0e7c60086..a3bcaeb99ae 100644 --- a/doc/topics/autodevops/img/guide_enable_autodevops_v12_3.png +++ b/doc/topics/autodevops/img/guide_enable_autodevops_v12_3.png diff --git a/doc/topics/autodevops/img/guide_environments_metrics_v12_3.png b/doc/topics/autodevops/img/guide_environments_metrics_v12_3.png Binary files differindex 74f997a5122..47bf3fda53a 100644 --- a/doc/topics/autodevops/img/guide_environments_metrics_v12_3.png +++ b/doc/topics/autodevops/img/guide_environments_metrics_v12_3.png diff --git a/doc/topics/autodevops/img/guide_environments_v12_3.png b/doc/topics/autodevops/img/guide_environments_v12_3.png Binary files differindex 0ad282cfe4e..87253f9929d 100644 --- a/doc/topics/autodevops/img/guide_environments_v12_3.png +++ b/doc/topics/autodevops/img/guide_environments_v12_3.png diff --git a/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png b/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png Binary files differindex 7654b4f0934..9b51b5cfdd8 100644 --- a/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png +++ b/doc/topics/autodevops/img/guide_first_pipeline_v12_3.png diff --git a/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png b/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png Binary files differindex ba2b00dd984..2f3f8259316 100644 --- a/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png +++ b/doc/topics/autodevops/img/guide_gitlab_gke_details_v12_3.png diff --git a/doc/topics/autodevops/img/guide_google_signin_v12_3.png b/doc/topics/autodevops/img/guide_google_signin_v12_3.png Binary files differindex ac8a325dde6..58bcc5e67b6 100644 --- a/doc/topics/autodevops/img/guide_google_signin_v12_3.png +++ b/doc/topics/autodevops/img/guide_google_signin_v12_3.png diff --git a/doc/topics/autodevops/img/guide_ide_commit_v12_3.png b/doc/topics/autodevops/img/guide_ide_commit_v12_3.png Binary files differindex c40658e9ba9..afea0dc8fb4 100644 --- a/doc/topics/autodevops/img/guide_ide_commit_v12_3.png +++ b/doc/topics/autodevops/img/guide_ide_commit_v12_3.png diff --git a/doc/topics/autodevops/img/guide_merge_request_review_app_v12_3.png b/doc/topics/autodevops/img/guide_merge_request_review_app_v12_3.png Binary files differindex e1a4f181744..e94654f4e50 100644 --- a/doc/topics/autodevops/img/guide_merge_request_review_app_v12_3.png +++ b/doc/topics/autodevops/img/guide_merge_request_review_app_v12_3.png diff --git a/doc/topics/autodevops/img/guide_merge_request_v12_3.png b/doc/topics/autodevops/img/guide_merge_request_v12_3.png Binary files differindex 8c70620162c..5565be701cd 100644 --- a/doc/topics/autodevops/img/guide_merge_request_v12_3.png +++ b/doc/topics/autodevops/img/guide_merge_request_v12_3.png diff --git a/doc/topics/autodevops/img/guide_pipeline_stages_v12_3.png b/doc/topics/autodevops/img/guide_pipeline_stages_v12_3.png Binary files differindex f55a985f543..b9bab112a9f 100644 --- a/doc/topics/autodevops/img/guide_pipeline_stages_v12_3.png +++ b/doc/topics/autodevops/img/guide_pipeline_stages_v12_3.png diff --git a/doc/topics/autodevops/img/guide_project_landing_page_v12_3.png b/doc/topics/autodevops/img/guide_project_landing_page_v12_3.png Binary files differindex 4d62588ed90..7eb2ee3692f 100644 --- a/doc/topics/autodevops/img/guide_project_landing_page_v12_3.png +++ b/doc/topics/autodevops/img/guide_project_landing_page_v12_3.png diff --git a/doc/topics/autodevops/img/guide_project_template_v12_3.png b/doc/topics/autodevops/img/guide_project_template_v12_3.png Binary files differindex 9ce730518d0..2b8d7224747 100644 --- a/doc/topics/autodevops/img/guide_project_template_v12_3.png +++ b/doc/topics/autodevops/img/guide_project_template_v12_3.png diff --git a/doc/topics/autodevops/index.md b/doc/topics/autodevops/index.md index 33b13935de3..c52c5832591 100644 --- a/doc/topics/autodevops/index.md +++ b/doc/topics/autodevops/index.md @@ -19,12 +19,20 @@ For an introduction to Auto DevOps, watch [AutoDevOps in GitLab 11.0](https://yo ## Enabled by default -Starting with GitLab 11.3, the Auto DevOps pipeline is enabled by default for all -projects. If it has not been explicitly enabled for the project, Auto DevOps will be automatically -disabled on the first pipeline failure. Your project will continue to use an alternative -[CI/CD configuration file](../../ci/yaml/README.md) if one is found. A GitLab -administrator can [change this setting](../../user/admin_area/settings/continuous_integration.md#auto-devops-core-only) -in the admin area. +> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41729) in GitLab 11.3. + +Auto DevOps is enabled by default for all projects and will attempt to run on all pipelines +in each project. This default can be enabled or disabled by an instance administrator in the +[Auto DevOps settings](../../user/admin_area/settings/continuous_integration.md#auto-devops-core-only). +It will be automatically disabled in individual projects on their first pipeline failure, +if it has not been explicitly enabled for the project. + +Since [GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/issues/26655), Auto DevOps +will run on pipelines automatically only if a [`Dockerfile` or matching buildpack](#auto-build) +exists. + +If a [CI/CD configuration file](../../ci/yaml/README.md) is present in the project, +it will continue to be used, whether or not Auto DevOps is enabled. ## Quick start @@ -176,7 +184,7 @@ The Auto DevOps base domain is required if you want to make use of places: - either under the cluster's settings, whether for [projects](../../user/project/clusters/index.md#base-domain) or [groups](../../user/group/clusters/index.md#base-domain) -- or in instance-wide settings in the **admin area > Settings** under the "Continuous Integration and Delivery" section +- or in instance-wide settings in the **Admin Area > Settings** under the "Continuous Integration and Delivery" section - or at the project level as a variable: `KUBE_INGRESS_BASE_DOMAIN` - or at the group level as a variable: `KUBE_INGRESS_BASE_DOMAIN`. @@ -255,7 +263,7 @@ the subgroup or project. Even when disabled at the instance level, group owners and project maintainers can still enable Auto DevOps at the group and project level, respectively. -1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Go to **Admin Area > Settings > Continuous Integration and Deployment**. 1. Toggle the checkbox labeled **Default to Auto DevOps pipeline for all projects**. 1. If enabling, optionally set up the Auto DevOps [base domain](#auto-devops-base-domain) which will be used for Auto Deploy and Auto Review Apps. 1. Click **Save changes** for the changes to take effect. diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index ce3a3dd5ca6..32dcd60624f 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -30,7 +30,7 @@ Google Kubernetes Engine Integration. All you have to do is [follow this link](h ## Creating a new project from a template We will use one of GitLab's project templates to get started. As the name suggests, -those projects provide a barebones application built on some well-known frameworks. +those projects provide a bare-bones application built on some well-known frameworks. 1. In GitLab, click the plus icon (**+**) at the top of the navigation bar and select **New project**. diff --git a/doc/topics/git/useful_git_commands.md b/doc/topics/git/useful_git_commands.md index abd06b95b1e..68b4c772b8b 100644 --- a/doc/topics/git/useful_git_commands.md +++ b/doc/topics/git/useful_git_commands.md @@ -74,7 +74,7 @@ message. git stash save ``` -The default behavor of `stash` is to save, so you can also use just: +The default behavior of `stash` is to save, so you can also use just: ```sh git stash diff --git a/doc/update/README.md b/doc/update/README.md index 6834deb1a85..f23716f3df8 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -69,13 +69,8 @@ before continuing the upgrading procedure. While this won't require downtime between upgrading major/minor releases, allowing the background migrations to finish. The time necessary to complete these migrations can be reduced by increasing the number of Sidekiq workers that can process jobs in the -`background_migration` queue. To check the size of this queue, -[start a Rails console session](https://docs.gitlab.com/omnibus/maintenance/#starting-a-rails-console-session) -and run the command below: - -```ruby -Sidekiq::Queue.new('background_migration').size -``` +`background_migration` queue. To see the size of this queue, +[Check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). As a rule of thumb, any database smaller than 10 GB won't take too much time to upgrade; perhaps an hour at most per minor release. Larger databases however may @@ -112,6 +107,36 @@ meet the other online upgrade requirements mentioned above. Steps to [upgrade without downtime][omni-zero-downtime]. +## Checking for background migrations before upgrading + +Certain major/minor releases may require a set of background migrations to be +finished. The number of remaining migrations jobs can be found by running the +following command: + +**For Omnibus installations** + +```bash +sudo gitlab-rails runner -e production 'puts Sidekiq::Queue.new("background_migration").size' +``` + +**For installations from source** + +``` +cd /home/git/gitlab +sudo -u git -H bundle exec rails runner -e production 'puts Sidekiq::Queue.new("background_migration").size' +``` + +## Upgrading to a new major version + +Major versions are reserved for backwards incompatible changes. We recommend that +you first upgrade to the latest available minor version within your major version. +Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations) +to identify the ideal upgrade path. + +Before upgrading to a new major version, you should ensure that any background +migration jobs from previous releases have been completed. To see the current size +of the `background_migration` queue, [check for background migrations before upgrading](#checking-for-background-migrations-before-upgrading). + ## Upgrading between editions GitLab comes in two flavors: [Community Edition][ce] which is MIT licensed, diff --git a/doc/update/patch_versions.md b/doc/update/patch_versions.md index b00fc5d90cf..5aa97d82fd1 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -94,11 +94,9 @@ sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_PAGES_VERSION) sudo -u git -H make ``` -### 8. Install/Update `gitlab-elasticsearch-indexer` (optional) **(STARTER ONLY)** +### 8. Install/Update `gitlab-elasticsearch-indexer` **(STARTER ONLY)** -If you're interested in using GitLab's new [Elasticsearch repository indexer](../integration/elasticsearch.md#elasticsearch-repository-indexer-beta) (currently in beta) -please follow the instructions on the document linked above and enable the -indexer usage in the GitLab admin settings. +Please follow the [install instruction](../integration/elasticsearch.md#installation). ### 9. Start application diff --git a/doc/update/upgrading_from_ce_to_ee.md b/doc/update/upgrading_from_ce_to_ee.md index 52a65a89cbf..d1853466e30 100644 --- a/doc/update/upgrading_from_ce_to_ee.md +++ b/doc/update/upgrading_from_ce_to_ee.md @@ -77,11 +77,9 @@ sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:c sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production ``` -### 4. Install `gitlab-elasticsearch-indexer` (optional) **(STARTER ONLY)** +### 4. Install `gitlab-elasticsearch-indexer` **(STARTER ONLY)** -If you're interested in using GitLab's new [Elasticsearch repository indexer](../integration/elasticsearch.md) -(currently in beta) please follow the instructions on the -document linked above and enable the indexer usage in the GitLab admin settings. +Please follow the [install instruction](../integration/elasticsearch.md#installation). ### 5. Start application diff --git a/doc/update/upgrading_from_source.md b/doc/update/upgrading_from_source.md index 662701dbb56..48f8052cbb8 100644 --- a/doc/update/upgrading_from_source.md +++ b/doc/update/upgrading_from_source.md @@ -23,6 +23,17 @@ guide links by version. If you are changing from GitLab Community Edition to GitLab Enterprise Edition, see the [Upgrading from CE to EE](upgrading_from_ce_to_ee.md) documentation. +## Upgrading to a new major version + +Major versions are reserved for backwards incompatible changes. We recommend that +you first upgrade to the latest available minor version within your major version. +Please follow the [Upgrade Recommendations](../policy/maintenance.md#upgrade-recommendations) +to identify the ideal upgrade path. + +Before upgrading to a new major version, you should ensure that any background +migration jobs from previous releases have been completed. To see the current size of the `background_migration` queue, +[Check for background migrations before upgrading](README.md#checking-for-background-migrations-before-upgrading). + ## Guidelines for all versions This section contains all the steps necessary to upgrade Community Edition or @@ -56,9 +67,9 @@ Download Ruby and compile it: ```bash mkdir /tmp/ruby && cd /tmp/ruby -curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.3.tar.gz -echo '2347ed6ca5490a104ebd5684d2b9b5eefa6cd33c ruby-2.6.3.tar.gz' | shasum -c - && tar xzf ruby-2.6.3.tar.gz -cd ruby-2.6.3 +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.6/ruby-2.6.5.tar.gz +echo '1416ce288fb8bfeae07a12b608540318c9cace71 ruby-2.6.5.tar.gz' | shasum -c - && tar xzf ruby-2.6.5.tar.gz +cd ruby-2.6.5 ./configure --disable-install-rdoc make @@ -71,24 +82,15 @@ Install Bundler: sudo gem install bundler --no-document --version '< 2' ``` -### 4. Update Node - -NOTE: Beginning in GitLab 11.8, we only support node 8 or higher, and dropped -support for node 6. Be sure to upgrade if necessary. - -GitLab utilizes [webpack](https://webpack.js.org/) to compile frontend assets. -This requires a minimum version of node v8.10.0. - -You can check which version you are running with `node -v`. If you are running -a version older than `v8.10.0` you will need to update to a newer version. You -can find instructions to install from community maintained packages or compile -from source at the nodejs.org website. +### 4. Update Node.js -<https://nodejs.org/en/download/> +NOTE: To check the minimum required Node.js version, see [Node.js versions](../install/requirements.md#nodejs-versions). -GitLab also requires the use of yarn `>= v1.10.0` to manage JavaScript +GitLab also requires the use of Yarn `>= v1.10.0` to manage JavaScript dependencies. +In Debian or Ubuntu: + ```bash curl --silent --show-error https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list @@ -96,34 +98,33 @@ sudo apt-get update sudo apt-get install yarn ``` -More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). +More information can be found on the [Yarn website](https://yarnpkg.com/en/docs/install). ### 5. Update Go -NOTE: GitLab 11.4 and higher only supports Go 1.10.x and newer, and dropped support for Go -1.9.x. Be sure to upgrade your installation if necessary. +NOTE: To check the minimum required Go version, see [Go versions](../install/requirements.md#go-versions). You can check which version you are running with `go version`. -Download and install Go: +Download and install Go (for Linux, 64-bit): ```bash # Remove former Go installation folder sudo rm -rf /usr/local/go -curl --remote-name --progress https://dl.google.com/go/go1.11.10.linux-amd64.tar.gz -echo 'aefaa228b68641e266d1f23f1d95dba33f17552ba132878b65bb798ffa37e6d0 go1.11.10.linux-amd64.tar.gz' | shasum -a256 -c - && \ - sudo tar -C /usr/local -xzf go1.11.10.linux-amd64.tar.gz +curl --remote-name --progress https://dl.google.com/go/go1.13.5.linux-amd64.tar.gz +echo '512103d7ad296467814a6e3f635631bd35574cab3369a97a323c9a585ccaa569 go1.13.5.linux-amd64.tar.gz' | shasum -a256 -c - && \ + sudo tar -C /usr/local -xzf go1.13.5.linux-amd64.tar.gz sudo ln -sf /usr/local/go/bin/{go,godoc,gofmt} /usr/local/bin/ -rm go1.11.10.linux-amd64.tar.gz +rm go1.13.5.linux-amd64.tar.gz + ``` ### 6. Update Git -NOTE: **Note:** -GitLab 11.11 and higher only supports Git 2.21.x and newer, and -[dropped support for older versions](https://gitlab.com/gitlab-org/gitlab-foss/issues/54255). -Be sure to upgrade your installation if necessary. +NOTE: To check the minimum required Git version, see [Git versions](../install/requirements.md#git-versions). + +In Debian or Ubuntu: ```bash # Make sure Git is version 2.21.0 or higher @@ -243,9 +244,8 @@ sudo -u git -H make #### New configuration options for `gitlab.yml` -There might be configuration options available for [`gitlab.yml`][yaml]. View -them with the command below and apply them manually to your current -`gitlab.yml`: +There might be configuration options available for [`gitlab.yml`](https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example)). +View them with the command below and apply them manually to your current `gitlab.yml`: ```sh cd /home/git/gitlab @@ -271,7 +271,7 @@ If you are using Strict-Transport-Security in your installation to continue using it you must enable it in your NGINX configuration as GitLab application no longer handles setting it. -If you are using Apache instead of NGINX please see the updated [Apache templates]. +If you are using Apache instead of NGINX see the updated [Apache templates](https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache). Also note that because Apache does not support upstreams behind Unix sockets you will need to let GitLab Workhorse listen on a TCP port. You can do this via [`/etc/default/gitlab`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example#L38). @@ -285,13 +285,13 @@ add the following line to `config/initializers/smtp_settings.rb`: ActionMailer::Base.delivery_method = :smtp ``` -See [smtp_settings.rb.sample] as an example. +See [smtp_settings.rb.sample](https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/smtp_settings.rb.sample#L13) as an example. #### Init script There might be new configuration options available for -[`gitlab.default.example`][gl-example]. View them with the command below and -apply them manually to your current `/etc/default/gitlab`: +[`gitlab.default.example`](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example). +View them with the command below and apply them manually to your current `/etc/default/gitlab`: ```sh cd /home/git/gitlab @@ -378,17 +378,19 @@ Example: Additional instructions here. --> -## Things went south? Revert to previous version +## Troubleshooting ### 1. Revert the code to the previous version -To revert to a previous version, you'll need to following the upgrading guides -for the previous version. If you upgraded to 11.8 and want to revert back to -11.7, you'll need to follow the guides for upgrading from 11.6 to 11.7. You can +To revert to a previous version, you need to follow the upgrading guides +for the previous version. + +For example, if you have upgraded to GitLab 12.6 and want to revert back to +12.5, you need to follow the guides for upgrading from 12.4 to 12.5. You can use the version dropdown at the top of the page to select the right version. -When reverting, you should _not_ follow the database migration guides, as the -backup is already migrated to the previous version. +When reverting, you should **not** follow the database migration guides, as the +backup has already been migrated to the previous version. ### 2. Restore from the backup @@ -398,9 +400,4 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:backup:restore RAILS_ENV=production ``` -If you have more than one backup `*.tar` file(s) please add `BACKUP=timestamp_of_backup` to the command above. - -[yaml]: https://gitlab.com/gitlab-org/gitlab/blob/master/config/gitlab.yml.example -[gl-example]: https://gitlab.com/gitlab-org/gitlab/blob/master/lib/support/init.d/gitlab.default.example -[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab/blob/master/config/initializers/smtp_settings.rb.sample#L13 -[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +If you have more than one backup `*.tar` file, add `BACKUP=timestamp_of_backup` to the above. diff --git a/doc/user/admin_area/custom_project_templates.md b/doc/user/admin_area/custom_project_templates.md index 8a0cc95ade0..f9a4dad2500 100644 --- a/doc/user/admin_area/custom_project_templates.md +++ b/doc/user/admin_area/custom_project_templates.md @@ -28,7 +28,7 @@ see [Custom group-level project templates](../group/custom_project_templates.md) GitLab administrators can configure a GitLab group that serves as template source for an entire GitLab instance by: -1. Navigating to **Admin area > Settings > Templates**. +1. Navigating to **Admin Area > Settings > Templates**. 1. Expanding **Custom project templates**. 1. Selecting a group to use. 1. Pressing **Save changes**. diff --git a/doc/user/admin_area/diff_limits.md b/doc/user/admin_area/diff_limits.md index 4e24c25de8f..bc6f93891df 100644 --- a/doc/user/admin_area/diff_limits.md +++ b/doc/user/admin_area/diff_limits.md @@ -24,7 +24,7 @@ CAUTION: **Caution:** This setting is experimental. An increased maximum will increase resource consumption of your instance. Keep this in mind when adjusting the maximum. -1. Go to **Admin area > Settings > General**. +1. Go to **Admin Area > Settings > General**. 1. Expand **Diff limits**. 1. Enter a value for **Maximum diff patch size**, measured in bytes. 1. Click on **Save changes**. diff --git a/doc/user/admin_area/geo_nodes.md b/doc/user/admin_area/geo_nodes.md index bbdb9cb07a6..250956beb63 100644 --- a/doc/user/admin_area/geo_nodes.md +++ b/doc/user/admin_area/geo_nodes.md @@ -2,12 +2,12 @@ type: howto --- -# Geo nodes admin area **(PREMIUM ONLY)** +# Geo nodes Admin Area **(PREMIUM ONLY)** You can configure various settings for GitLab Geo nodes. For more information, see [Geo documentation](../../administration/geo/replication/index.md). -On the primary node, go to **Admin area > Geo**. On secondary nodes, go to **Admin area > Geo > Nodes**. +On the primary node, go to **Admin Area > Geo**. On secondary nodes, go to **Admin Area > Geo > Nodes**. ## Common settings @@ -59,7 +59,7 @@ The **primary** node's Internal URL is used by **secondary** nodes to contact it which is used by users. Internal URL does not need to be a private address. Internal URL defaults to External URL, but you can customize it under -**Admin area > Geo Nodes**. +**Admin Area > Geo > Nodes**. CAUTION: **Warning:** We recommend using an HTTPS connection while configuring the Geo nodes. To avoid diff --git a/doc/user/admin_area/img/appearance_favicon_v12_3.png b/doc/user/admin_area/img/appearance_favicon_v12_3.png Binary files differindex b464c9087e9..0bab0638265 100644 --- a/doc/user/admin_area/img/appearance_favicon_v12_3.png +++ b/doc/user/admin_area/img/appearance_favicon_v12_3.png diff --git a/doc/user/admin_area/img/appearance_header_footer_v12_3.png b/doc/user/admin_area/img/appearance_header_footer_v12_3.png Binary files differindex aed0ff820fb..da68ddcf166 100644 --- a/doc/user/admin_area/img/appearance_header_footer_v12_3.png +++ b/doc/user/admin_area/img/appearance_header_footer_v12_3.png diff --git a/doc/user/admin_area/img/appearance_header_logo_v12_3.png b/doc/user/admin_area/img/appearance_header_logo_v12_3.png Binary files differindex 0da56d196c0..414301b8efa 100644 --- a/doc/user/admin_area/img/appearance_header_logo_v12_3.png +++ b/doc/user/admin_area/img/appearance_header_logo_v12_3.png diff --git a/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png b/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png Binary files differindex 621e62e787b..92593399843 100644 --- a/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png +++ b/doc/user/admin_area/img/appearance_new_project_preview_v12_3.png diff --git a/doc/user/admin_area/img/appearance_new_project_v12_3.png b/doc/user/admin_area/img/appearance_new_project_v12_3.png Binary files differindex ae1a8ca0f85..120a191de27 100644 --- a/doc/user/admin_area/img/appearance_new_project_v12_3.png +++ b/doc/user/admin_area/img/appearance_new_project_v12_3.png diff --git a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png Binary files differindex 64bd62c2d32..59c190393d1 100644 --- a/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png +++ b/doc/user/admin_area/img/appearance_sign_in_preview_v12_3.png diff --git a/doc/user/admin_area/img/appearance_sign_in_v12_3.png b/doc/user/admin_area/img/appearance_sign_in_v12_3.png Binary files differindex 6abe10f8bea..7e2337bbae8 100644 --- a/doc/user/admin_area/img/appearance_sign_in_v12_3.png +++ b/doc/user/admin_area/img/appearance_sign_in_v12_3.png diff --git a/doc/user/admin_area/img/credentials_inventory_v12_6.png b/doc/user/admin_area/img/credentials_inventory_v12_6.png Binary files differindex ff46db61cdb..5c16781cb2d 100644 --- a/doc/user/admin_area/img/credentials_inventory_v12_6.png +++ b/doc/user/admin_area/img/credentials_inventory_v12_6.png diff --git a/doc/user/admin_area/img/minimum_password_length_settings_v12_6.png b/doc/user/admin_area/img/minimum_password_length_settings_v12_6.png Binary files differindex f75d9e9bb29..27634a02a8a 100644 --- a/doc/user/admin_area/img/minimum_password_length_settings_v12_6.png +++ b/doc/user/admin_area/img/minimum_password_length_settings_v12_6.png diff --git a/doc/user/admin_area/index.md b/doc/user/admin_area/index.md index 35cb2b42c56..7d710e3b2c1 100644 --- a/doc/user/admin_area/index.md +++ b/doc/user/admin_area/index.md @@ -18,22 +18,24 @@ Only admin users can access the Admin Area. The Admin Area is made up of the following sections: -| Section | Description | -|:------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [Runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | -| Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log-premium-only). | -| Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | -| System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | -| Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | -| Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | -| License **(STARTER ONLY)** | Upload, display, and remove [licenses](license.md). | -| Push Rules **(STARTER)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. | -| Geo **(PREMIUM ONLY)** | Configure and maintain [Geo nodes](geo_nodes.md). | -| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | -| Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | -| Labels | Create and maintain [labels](labels.md) for your GitLab instance. | -| Appearance | Customize [GitLab's appearance](appearance.md). | -| Settings | Modify the [settings](settings/index.md) for your GitLab instance. | +| Section | Description | +|:--------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Overview](#overview-section) | View your GitLab [Dashboard](#admin-dashboard), and administer [projects](#administering-projects), [users](#administering-users), [groups](#administering-groups), [jobs](#administering-jobs), [Runners](#administering-runners), and [Gitaly servers](#administering-gitaly-servers). | +| Monitoring | View GitLab [system information](#system-info), and information on [background jobs](#background-jobs), [logs](#logs), [health checks](monitoring/health_check.md), [requests profiles](#requests-profiles), and [audit logs](#audit-log-premium-only). | +| Messages | Send and manage [broadcast messages](broadcast_messages.md) for your users. | +| System Hooks | Configure [system hooks](../../system_hooks/system_hooks.md) for many events. | +| Applications | Create system [OAuth applications](../../integration/oauth_provider.md) for integrations with other services. | +| Abuse Reports | Manage [abuse reports](abuse_reports.md) submitted by your users. | +| License **(STARTER ONLY)** | Upload, display, and remove [licenses](license.md). | +| Kubernetes | Create and manage instance-level [Kubernetes clusters](../instance/clusters/index.md). | +| Push Rules **(STARTER)** | Configure pre-defined Git [push rules](../../push_rules/push_rules.md) for projects. | +| Geo **(PREMIUM ONLY)** | Configure and maintain [Geo nodes](geo_nodes.md). | +| Deploy Keys | Create instance-wide [SSH deploy keys](../../ssh/README.md#deploy-keys). | +| Credentials **(ULTIMATE ONLY)** | View [credentials](credentials_inventory.md) that can be used to access your instance. | +| Service Templates | Create [service templates](../project/integrations/services_templates.md) for projects. | +| Labels | Create and maintain [labels](labels.md) for your GitLab instance. | +| Appearance | Customize [GitLab's appearance](appearance.md). | +| Settings | Modify the [settings](settings/index.md) for your GitLab instance. | ## Admin Dashboard diff --git a/doc/user/admin_area/license.md b/doc/user/admin_area/license.md index fe8903a9f01..c9d8a457a51 100644 --- a/doc/user/admin_area/license.md +++ b/doc/user/admin_area/license.md @@ -24,17 +24,17 @@ will be locked. The very first time you visit your GitLab EE installation signed in as an admin, you should see a note urging you to upload a license with a link that takes you -straight to the License admin area. +straight to **Admin Area > License**. Otherwise, you can: 1. Navigate manually to the **Admin Area** by clicking the wrench icon in the menu bar. -  +  1. And then going to the **License** tab and click on **Upload New License**. -  +  1. If you've received a `.gitlab-license` file, you should have already downloaded it in your local machine. You can then upload it directly by choosing the @@ -69,7 +69,7 @@ gitlab_rails['license_file'] = "/path/to/license/file" CAUTION: **Caution:** These methods will only add a license at the time of installation. Use the -admin area in the web ui to renew or upgrade licenses. +Admin Area in the web ui to renew or upgrade licenses. --- diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index 68767efc72a..fe38c350f19 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -141,7 +141,7 @@ This check is being exempt from Rack Attack. > Access token has been deprecated in GitLab 9.4 in favor of [IP whitelist](#ip-whitelist). An access token needs to be provided while accessing the probe endpoints. The current -accepted token can be found under the **Admin area ➔ Monitoring ➔ Health check** +accepted token can be found under the **Admin Area > Monitoring > Health check** (`admin/health_check`) page of your GitLab instance.  diff --git a/doc/user/admin_area/settings/account_and_limit_settings.md b/doc/user/admin_area/settings/account_and_limit_settings.md index 9d82b3b4292..131ff949cd1 100644 --- a/doc/user/admin_area/settings/account_and_limit_settings.md +++ b/doc/user/admin_area/settings/account_and_limit_settings.md @@ -106,7 +106,7 @@ To set a limit on how long personal access tokens are valid: 1. Navigate to **Admin Area > Settings > General**. 1. Expand the **Account and limit** section. -1. Fill in the **Maximun allowable lifetime for personal access tokens (days)** field. +1. Fill in the **Maximum allowable lifetime for personal access tokens (days)** field. 1. Click **Save changes**. Once a lifetime for personal access tokens is set, GitLab will: @@ -116,3 +116,17 @@ Once a lifetime for personal access tokens is set, GitLab will: - After three hours, revoke old tokens with no expiration date or with a lifetime longer than the allowed lifetime. Three hours is given to allow administrators to change the allowed lifetime, or remove it, before revocation takes place. + +## Disabling user profile name changes **(PREMIUM ONLY)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/24605) in GitLab 12.7. + +To maintain integrity of user details in [Audit Events](../../../administration/audit_events.md), GitLab administrators can choose to disable a user's ability to change their profile name. + +To do this: + +1. Navigate to **Admin Area > Settings > General**, then expand **Account and Limit**. +1. Check the **Prevent users from changing their profile name** checkbox. + +NOTE: **Note:** +When this ability is disabled, GitLab administrators will still be able to update the name of any user in their instance via the [Admin UI](../index.md#administering-users) or the [API](../../../api/users.md#user-modification) diff --git a/doc/user/admin_area/settings/continuous_integration.md b/doc/user/admin_area/settings/continuous_integration.md index 79deda73d34..43b0671d9e0 100644 --- a/doc/user/admin_area/settings/continuous_integration.md +++ b/doc/user/admin_area/settings/continuous_integration.md @@ -5,16 +5,16 @@ type: reference # Continuous Integration and Deployment Admin settings **(CORE ONLY)** In this area, you will find settings for Auto DevOps, Runners and job artifacts. -You can find it in the admin area, under **Settings > Continuous Integration and Deployment**. +You can find it in the **Admin Area > Settings > CI/CD**. - + ## Auto DevOps **(CORE ONLY)** To enable (or disable) [Auto DevOps](../../../topics/autodevops/index.md) for all projects: -1. Go to **Admin area > Settings > Continuous Integration and Deployment** +1. Go to **Admin Area > Settings > CI/CD** 1. Check (or uncheck to disable) the box that says "Default to Auto DevOps pipeline for all projects" 1. Optionally, set up the [Auto DevOps base domain](../../../topics/autodevops/index.md#auto-devops-base-domain) which is going to be used for Auto Deploy and Auto Review Apps. @@ -43,7 +43,7 @@ To change it at the: - Instance level: - 1. Go to **Admin area > Settings > Continuous Integration and Deployment**. + 1. Go to **Admin Area > Settings > CI/CD**. 1. Change the value of maximum artifacts size (in MB). 1. Hit **Save changes** for the changes to take effect. @@ -65,12 +65,12 @@ The setting at all levels is only available to GitLab administrators. ## Default artifacts expiration **(CORE ONLY)** The default expiration time of the [job artifacts](../../../administration/job_artifacts.md) -can be set in the Admin area of your GitLab instance. The syntax of duration is +can be set in the Admin Area of your GitLab instance. The syntax of duration is described in [`artifacts:expire_in`](../../../ci/yaml/README.md#artifactsexpire_in) and the default value is `30 days`. On GitLab.com they [never expire](../../gitlab_com/index.md#gitlab-cicd). -1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Go to **Admin Area > Settings > CI/CD**. 1. Change the value of default expiration time. 1. Hit **Save changes** for the changes to take effect. @@ -78,6 +78,12 @@ This setting is set per job and can be overridden in [`.gitlab-ci.yml`](../../../ci/yaml/README.md#artifactsexpire_in). To disable the expiration, set it to `0`. The default unit is in seconds. +NOTE: **Note** +Any changes to this setting will apply to new artifacts only. The expiration time will not +be updated for artifacts created before this setting was changed. +The administrator may need to manually search for and expire previously-created +artifacts, as described in the [troubleshooting documentation](../../../administration/troubleshooting/gitlab_rails_cheat_sheet.md#remove-artifacts-more-than-a-week-old). + ## Shared Runners pipeline minutes quota **(STARTER ONLY)** > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/1078) @@ -93,17 +99,17 @@ On GitLab.com, the quota is calculated based on your To change the pipelines minutes quota: -1. Go to **Admin area > Settings > Continuous Integration and Deployment** +1. Go to **Admin Area > Settings > CI/CD** 1. Set the pipeline minutes quota limit. 1. Hit **Save changes** for the changes to take effect --- -While the setting in the Admin area has a global effect, as an admin you can +While the setting in the Admin Area has a global effect, as an admin you can also change each group's pipeline minutes quota to override the global value. -1. Navigate to the **Groups** admin area and hit the **Edit** button for the - group you wish to change the pipeline minutes quota. +1. Navigate to the **Admin Area > Overview > Groups** and hit the **Edit** + button for the group you wish to change the pipeline minutes quota. 1. Set the pipeline minutes quota to the desired value 1. Hit **Save changes** for the changes to take effect. @@ -126,8 +132,9 @@ but persisting the traces and artifacts for auditing purposes. To set the duration for which the jobs will be considered as old and expired: -1. Go to **Admin area > Settings > CI/CD > Continuous Integration and Deployment**. -1. Change the value of "Archive jobs". +1. Go to **Admin Area > Settings > CI/CD**. +1. Expand the **Continuous Integration and Deployment** section. +1. Set the value of **Archive jobs**. 1. Hit **Save changes** for the changes to take effect. Once that time passes, the jobs will be archived and no longer able to be @@ -139,9 +146,9 @@ for example: <code>15 days</code>, <code>1 month</code>, <code>2 years</code>. > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/18073) in GitLab 12.5. The default CI configuration file path for new projects can be set in the Admin -area of your GitLab instance (`.gitlab-ci.yml` if not set): +Area of your GitLab instance (`.gitlab-ci.yml` if not set): -1. Go to **Admin area > Settings > Continuous Integration and Deployment**. +1. Go to **Admin Area > Settings > CI/CD**. 1. Input the new path in the **Default CI configuration path** field. 1. Hit **Save changes** for the changes to take effect. @@ -162,9 +169,10 @@ but commented out to help encourage others to add to it in the future. --> ## Required pipeline configuration **(PREMIUM ONLY)** CAUTION: **Caution:** -The Required Pipeline Configuration feature is deprecated and will be removed when an -[improved compliance solution](https://gitlab.com/gitlab-org/gitlab/issues/34830) -is added to GitLab. It is recommended to avoid using this feature. +This feature is being re-evaluated in favor of a different +[compliance solution](https://gitlab.com/gitlab-org/gitlab/issues/34830). +We recommend that users who haven't yet implemented this feature wait for +the new solution. GitLab administrators can force a pipeline configuration to run on every pipeline. @@ -177,7 +185,7 @@ sourced from: To set required pipeline configuration: -1. Go to **Admin area > Settings > CI/CD**. +1. Go to **Admin Area > Settings > CI/CD**. 1. Expand the **Required pipeline configuration** section. 1. Select the required configuration from the provided dropdown. 1. Click **Save changes**. diff --git a/doc/user/admin_area/settings/external_authorization.md b/doc/user/admin_area/settings/external_authorization.md index d11f672ca5c..da464ac1bf9 100644 --- a/doc/user/admin_area/settings/external_authorization.md +++ b/doc/user/admin_area/settings/external_authorization.md @@ -40,7 +40,7 @@ Read more about logs GitLab keeps in the [omnibus documentation][omnibus-log-doc ## Configuration The external authorization service can be enabled by an admin on the GitLab's -admin area under the settings page: +**Admin Area > Settings > General** page:  @@ -62,7 +62,7 @@ The available required properties are: requesting authorization if no specific label is defined on the project When using TLS Authentication with a self signed certificate, the CA certificate -needs to be trused by the openssl installation. When using GitLab installed using +needs to be trusted by the openssl installation. When using GitLab installed using Omnibus, learn to install a custom CA in the [omnibus documentation][omnibus-ssl-docs]. Alternatively learn where to install custom certificates using `openssl version -d`. diff --git a/doc/user/admin_area/settings/help_page.md b/doc/user/admin_area/settings/help_page.md index a2c99f94d8b..ca983edd4fa 100644 --- a/doc/user/admin_area/settings/help_page.md +++ b/doc/user/admin_area/settings/help_page.md @@ -13,7 +13,7 @@ to go for help. You can customize and display this information on the GitLab ser You can add a help message, which will be shown on the GitLab `/help` page (e.g., <https://gitlab.com/help>) in a new section at the top of the `/help` page: -1. Navigate to **Admin area > Settings > Preferences**, then expand **Help page**. +1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. 1. Under **Help page text**, fill in the information you wish to display on `/help`.  @@ -27,7 +27,7 @@ You can add a help message, which will be shown on the GitLab `/help` page (e.g. You can add a help message, which will be shown on the GitLab login page in a new section titled `Need Help?`, located below the login page message: -1. Navigate to **Admin area > Settings > Preferences**, then expand **Help page**. +1. Navigate to **Admin Area > Settings > Preferences**, then expand **Help page**. 1. Under **Help text**, fill in the information you wish to display on the login page.  diff --git a/doc/user/admin_area/settings/img/bulk_push_event_v12_4.png b/doc/user/admin_area/settings/img/bulk_push_event_v12_4.png Binary files differindex 38e666e32ac..114e87a61f1 100644 --- a/doc/user/admin_area/settings/img/bulk_push_event_v12_4.png +++ b/doc/user/admin_area/settings/img/bulk_push_event_v12_4.png diff --git a/doc/user/admin_area/settings/img/clone_panel_v12_4.png b/doc/user/admin_area/settings/img/clone_panel_v12_4.png Binary files differindex 8aa0bd2f7d8..427224f5b78 100644 --- a/doc/user/admin_area/settings/img/clone_panel_v12_4.png +++ b/doc/user/admin_area/settings/img/clone_panel_v12_4.png diff --git a/doc/user/admin_area/settings/img/disable_signup_v12_7.png b/doc/user/admin_area/settings/img/disable_signup_v12_7.png Binary files differnew file mode 100644 index 00000000000..be1a070a804 --- /dev/null +++ b/doc/user/admin_area/settings/img/disable_signup_v12_7.png diff --git a/doc/user/admin_area/settings/img/email_confirmation.png b/doc/user/admin_area/settings/img/email_confirmation.png Binary files differdeleted file mode 100644 index 987aa10c3ce..00000000000 --- a/doc/user/admin_area/settings/img/email_confirmation.png +++ /dev/null diff --git a/doc/user/admin_area/settings/img/email_confirmation_v12_7.png b/doc/user/admin_area/settings/img/email_confirmation_v12_7.png Binary files differnew file mode 100644 index 00000000000..6bcadb63b9a --- /dev/null +++ b/doc/user/admin_area/settings/img/email_confirmation_v12_7.png diff --git a/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png b/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png Binary files differindex 9dc7ef28149..421fa2977f9 100644 --- a/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png +++ b/doc/user/admin_area/settings/img/help_page_help_page_text_ex_v12_3.png diff --git a/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png b/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png Binary files differindex 59d3343db34..13c17fb118a 100644 --- a/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png +++ b/doc/user/admin_area/settings/img/help_page_help_page_text_v12_3.png diff --git a/doc/user/admin_area/settings/img/help_page_help_text_ex_v12_3.png b/doc/user/admin_area/settings/img/help_page_help_text_ex_v12_3.png Binary files differindex 9de26ac0758..973be2e8b6e 100644 --- a/doc/user/admin_area/settings/img/help_page_help_text_ex_v12_3.png +++ b/doc/user/admin_area/settings/img/help_page_help_text_ex_v12_3.png diff --git a/doc/user/admin_area/settings/img/help_page_help_text_v12_3.png b/doc/user/admin_area/settings/img/help_page_help_text_v12_3.png Binary files differindex 1b6aad5753a..8848ea55cf3 100644 --- a/doc/user/admin_area/settings/img/help_page_help_text_v12_3.png +++ b/doc/user/admin_area/settings/img/help_page_help_text_v12_3.png diff --git a/doc/user/admin_area/settings/img/protected_paths.png b/doc/user/admin_area/settings/img/protected_paths.png Binary files differindex 7aa9124b845..2233a71a139 100644 --- a/doc/user/admin_area/settings/img/protected_paths.png +++ b/doc/user/admin_area/settings/img/protected_paths.png diff --git a/doc/user/admin_area/settings/img/push_event_activities_limit_v12_4.png b/doc/user/admin_area/settings/img/push_event_activities_limit_v12_4.png Binary files differindex fd3775ac4d7..ea618ad4c50 100644 --- a/doc/user/admin_area/settings/img/push_event_activities_limit_v12_4.png +++ b/doc/user/admin_area/settings/img/push_event_activities_limit_v12_4.png diff --git a/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png b/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png Binary files differindex c32eb93c8a8..c59f67df1ce 100644 --- a/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png +++ b/doc/user/admin_area/settings/img/rate_limits_on_raw_endpoints.png diff --git a/doc/user/admin_area/settings/index.md b/doc/user/admin_area/settings/index.md index 42f496bfbfa..07d614b449b 100644 --- a/doc/user/admin_area/settings/index.md +++ b/doc/user/admin_area/settings/index.md @@ -27,9 +27,9 @@ include: NOTE: **Note:** You can change the [first day of the week](../../profile/preferences.md) for the entire GitLab instance -in the **Localization** section of **Admin area > Settings > Preferences**. +in the **Localization** section of **Admin Area > Settings > Preferences**. -## GitLab.com admin area settings +## GitLab.com Admin Area settings Most of the settings under the Admin Area change the behavior of the whole GitLab instance. For GitLab.com, the admin settings are available only for the diff --git a/doc/user/admin_area/settings/instance_template_repository.md b/doc/user/admin_area/settings/instance_template_repository.md index b3a861cac45..1338352fcb1 100644 --- a/doc/user/admin_area/settings/instance_template_repository.md +++ b/doc/user/admin_area/settings/instance_template_repository.md @@ -17,10 +17,10 @@ while the project remains secure. ## Configuration -As an administrator, navigate to **Admin area > Settings > Templates** and +As an administrator, navigate to **Admin Area > Settings > Templates** and select the project to serve as the custom template repository. - + Once a project has been selected, you can add custom templates to the repository, and they will appear in the appropriate places in the diff --git a/doc/user/admin_area/settings/sign_in_restrictions.md b/doc/user/admin_area/settings/sign_in_restrictions.md index 0975766400f..1da93c7005f 100644 --- a/doc/user/admin_area/settings/sign_in_restrictions.md +++ b/doc/user/admin_area/settings/sign_in_restrictions.md @@ -40,7 +40,7 @@ this message after logging-in. To access this feature: -1. Navigate to the **Settings > General** in the Admin area. +1. Navigate to the **Admin Area > Settings > General**. 1. Expand the **Sign-in restrictions** section. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/sign_up_restrictions.md b/doc/user/admin_area/settings/sign_up_restrictions.md index 851a984c285..0686044b9e3 100644 --- a/doc/user/admin_area/settings/sign_up_restrictions.md +++ b/doc/user/admin_area/settings/sign_up_restrictions.md @@ -4,20 +4,42 @@ type: reference # Sign-up restrictions **(CORE ONLY)** -You can use sign-up restrictions to require user email confirmation, as well as -to blacklist or whitelist email addresses belonging to specific domains. +You can use sign-up restrictions to: ->**Note**: These restrictions are only applied during sign-up. An admin is +- Disable new signups. +- Require user email confirmation. +- Blacklist or whitelist email addresses belonging to specific domains. + +NOTE: **Note:** +These restrictions are only applied during sign-up from an external user. An admin is able to add a user through the admin panel with a disallowed domain. Also note that the users can change their email addresses after signup to disallowed domains. +## Disable new signups + +When this setting is enabled, any user visiting your GitLab domain will be able to sign up for an account. + + + +You can restrict new users from signing up by themselves for an account in your instance by disabling this setting. + +### Recommendations + +For customers running public facing GitLab instances, we highly recommend that you +consider disabling new signups if you do not expect public users to sign up for an +account. + +Alternatively, you could also consider setting up a +[whitelist](#whitelist-email-domains) or [blacklist](#blacklist-email-domains) on +email domains to prevent malicious users from creating accounts. + ## Require email confirmation You can send confirmation emails during sign-up and require that users confirm their email address before they are allowed to sign in. - + ## Minimum password length limit @@ -46,7 +68,7 @@ addresses. To access this feature: -1. Navigate to the **Settings > General** in the Admin area. +1. Navigate to the **Admin Area > Settings > General**. 1. Expand the **Sign-up restrictions** section. For the blacklist, you can enter the list manually or upload a `.txt` file that diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md index 81edd9eac34..eae6925d073 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -7,10 +7,10 @@ type: reference GitLab Inc. will periodically collect information about your instance in order to perform various actions. -All statistics are opt-out, you can enable/disable them from the admin panel -under **Admin area > Settings > Metrics and profiling > Usage statistics**. +All statistics are opt-out. You can enable/disable them in the +**Admin Area > Settings > Metrics and profiling** section **Usage statistics**. -## Version check **(CORE ONLY)** +## Version Check **(CORE ONLY)** If enabled, version check will inform you if a new version is available and the importance of it through a status. This is shown on the help page (i.e. `/help`) @@ -31,9 +31,25 @@ patches will need to be backported, making sure active GitLab instances remain secure. If you disable version check, this information will not be collected. Enable or -disable the version check at **Admin area > Settings > Metrics and profiling > Usage statistics**. +disable the version check in **Admin Area > Settings > Metrics and profiling > Usage statistics**. + +### Request flow example + +The following example shows a basic request/response flow between the self-managed GitLab instance +and the GitLab Version Application: + +```mermaid +sequenceDiagram + participant GitLab instance + participant Version Application + GitLab instance->>Version Application: Is there a version update? + loop Version Check + Version Application->>Version Application: Record version info + end + Version Application->>GitLab instance: Response (PNG/SVG) +``` -## Usage ping **(CORE ONLY)** +## Usage Ping **(CORE ONLY)** > [Introduced][ee-557] in GitLab Enterprise Edition 8.10. More statistics [were added][ee-735] in GitLab Enterprise Edition @@ -48,11 +64,36 @@ of the instance. You can view the exact JSON payload in the administration panel. To view the payload: -1. Go to the **Admin area** (spanner symbol on the top bar). -1. Expand **Settings** in the left sidebar and click on **Metrics and profiling**. -1. Expand **Usage statistics** and click on the **Preview payload** button. - -You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/ping_metrics_to_stage_mapping_data.csv). +1. Navigate to the **Admin Area > Settings > Metrics and profiling**. +1. Expand the **Usage statistics** section. +1. Click the **Preview payload** button. + +You can see how [the usage ping data maps to different stages of the product](https://gitlab.com/gitlab-data/analytics/blob/master/transform/snowflake-dbt/data/version_usage_stats_to_stage_mappings.csv). + +### Request flow example + +The following example shows a basic request/response flow between the self-managed GitLab instance, GitLab Version Application, +GitLab License Application and Salesforce: + +```mermaid +sequenceDiagram + participant GitLab instance + participant Version Application + participant License Application + participant Salesforce + GitLab instance->>Version Application: Usage Ping data + loop Process Usage Data + Version Application->>Version Application: Parse Usage Data + Version Application->>Version Application: Record Usage Data + Version Application->>Version Application: Update license ping time + end + Version Application-xLicense Application: Request Zuora subscription id + License Application-xVersion Application: Zuora subscription id + Version Application-xSalesforce: Request Zuora account id by Zuora subscription id + Salesforce-xVersion Application: Zuora account id + Version Application-xSalesforce: Usage data for the Zuora account + Version Application->>GitLab instance: Conversational Development Index +``` ### Deactivate the usage ping @@ -84,8 +125,8 @@ Once usage ping is enabled, GitLab will gather data from other instances and will be able to show [usage statistics](../../instance_statistics/index.md) of your instance to your users. -This can be restricted to admins by selecting "Only admins" in the Instance -Statistics visibility section under **Admin area > Settings > Metrics and profiling > Usage statistics**. +To make this visible only to admins, go to **Admin Area > Settings > Metrics and profiling**, expand +**Usage statistics**, and set the **Instance Statistics visibility** option to **Only admins**. <!-- ## Troubleshooting diff --git a/doc/user/admin_area/settings/visibility_and_access_controls.md b/doc/user/admin_area/settings/visibility_and_access_controls.md index 74398128593..b5d708b5e04 100644 --- a/doc/user/admin_area/settings/visibility_and_access_controls.md +++ b/doc/user/admin_area/settings/visibility_and_access_controls.md @@ -16,7 +16,6 @@ To access the visibility and access control options: This global option defines the branch protection that applies to every repository's default branch. [Branch protection](../../project/protected_branches.md) specifies which roles can push to branches and which roles can delete branches. In this case _Default_ refers to a repository's default branch, which in most cases is _master_. -branches. "Default" in this case refers to a repository's default branch, which in most cases would be "master". This setting applies only to each repositories' default branch. To protect other branches, you must configure branch protection in repository. For details, see [Protected Branches](../../project/protected_branches.md). diff --git a/doc/user/analytics/code_review_analytics.md b/doc/user/analytics/code_review_analytics.md new file mode 100644 index 00000000000..87c29c265bf --- /dev/null +++ b/doc/user/analytics/code_review_analytics.md @@ -0,0 +1,35 @@ +--- +description: "Learn how long your open merge requests have spent in code review, and what distinguishes the longest-running." # Up to ~200 chars long. They will be displayed in Google Search snippets. It may help to write the page intro first, and then reuse it here. +--- + +# Code Review Analytics **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/38062) in GitLab ([Starter](https://about.gitlab.com/pricing/)) 12.7. + +Want to learn how long your open merge requests have spent in code review? Or what distinguishes your longest-running code reviews? These are some of the questions Code Review Analytics is designed to answer. + +NOTE: **Note:** +Initially no data will appear. Data will populate as users comment on open merge requests. + +## Overview + +Code Review Analytics displays a collection of merge requests in a table. These are all the open merge requests that are considered to be in code review. This feature considers code review to begin when a merge request receives its first comment from someone other than the author. The rows of the table are sorted by review time so the longest reviews appear at the top. There are also columns to display the author, approvers, comment count, and line -/+ counts. + +This feature is designed for [development team leaders](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#delaney-development-team-lead) and others who want to understand broad code review dynamics, and identify patterns to help explain them. You can use Code Review Analytics to expose your team's unique challenges with code review, and identify improvements that might substantially accelerate your development cycle. + +## Use cases + +Perhaps your team agrees that code review is moving too slow, or the [Cycle Analytics feature](https://docs.gitlab.com/ee/user/analytics/cycle_analytics.html) shows that "Review" is your team's most time-consuming step. You can use Code Review Analytics to see what is currently moving slowest, and analyze the patterns and trends between them. Lots of comments or commits? Maybe the code is too complex. A particular author is involved? Maybe more training is advisable. Few comments and approvers? Maybe your team is understaffed. + +## Permissions + +- On [Starter or Bronze tier](https://about.gitlab.com/pricing/) and above. +- By users with [Reporter access] and above. + +## Feature flag + +Code Review Analytics is [currently protected by a feature flag](https://gitlab.com/gitlab-org/gitlab/issues/194165) that defaults to "enabled" - meaning the feature is available. If you experience performance problems or otherwise wish to disable the feature, a GitLab administrator can execute a command in a Rails console: + +```ruby +Feature.disable(:code_review_analytics) +``` diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md index 796cae70803..dfc0f488ff9 100644 --- a/doc/user/analytics/cycle_analytics.md +++ b/doc/user/analytics/cycle_analytics.md @@ -44,8 +44,8 @@ There are seven stages that are tracked as part of the Cycle Analytics calculati - Time spent on code review - **Staging** (Continuous Deployment) - Time between merging and deploying to production -- **Production** (Total) - - Total lifecycle time; i.e. the velocity of the project or team +- **Total** (Total) + - Total lifecycle time. That is, the velocity of the project or team. [Previously known](https://gitlab.com/gitlab-org/gitlab/issues/38317) as **Production**. ## Date ranges @@ -60,12 +60,12 @@ GitLab provides the ability to filter analytics based on a date range. To filter ## How the data is measured Cycle Analytics records cycle time and data based on the project issues with the -exception of the staging and production stages, where only data deployed to +exception of the staging and total stages, where only data deployed to production are measured. Specifically, if your CI is not set up and you have not defined a `production` or `production/*` [environment](../../ci/yaml/README.md#environment), then you will not have any -data for those stages. +data for this stage. Each stage of Cycle Analytics is further described in the table below. @@ -77,7 +77,7 @@ Each stage of Cycle Analytics is further described in the table below. | Test | Measures the median time to run the entire pipeline for that project. It's related to the time GitLab CI takes to run every job for the commits pushed to that merge request defined in the previous stage. It is basically the start->finish time for all pipelines. | | Review | Measures the median time taken to review the merge request that has closing issue pattern, between its creation and until it's merged. | | Staging | Measures the median time between merging the merge request with closing issue pattern until the very first deployment to production. It's tracked by the environment set to `production` or matching `production/*` (case-sensitive, `Production` won't work) in your GitLab CI configuration. If there isn't a production environment, this is not tracked. | -| Production| The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. | +| Total | The sum of all time (medians) taken to run the entire process, from issue creation to deploying the code to production. [Previously known](https://gitlab.com/gitlab-org/gitlab/issues/38317) as **Production**. | How this works, behind the scenes: @@ -124,7 +124,7 @@ environments is configured. 1. Now that the merge request is merged, a deployment to the `production` environment starts and finishes at 19:30 (stop of **Staging** stage). 1. The cycle completes and the sum of the median times of the previous stages - is recorded to the **Production** stage. That is the time between creating an + is recorded to the **Total** stage. That is the time between creating an issue and deploying its relevant merge request to production. From the above example you can conclude the time it took each stage to complete @@ -136,10 +136,10 @@ as long as their total time: - **Test**: 5min - **Review**: 5h (19:00 - 14:00) - **Staging**: 30min (19:30 - 19:00) -- **Production**: Since this stage measures the sum of median time off all +- **Total**: Since this stage measures the sum of median time of all previous stages, we cannot calculate it if we don't know the status of the stages before. In case this is the very first cycle that is run in the project, - then the **Production** time is 10h 30min (19:30 - 09:00) + then the **Total** time is 10h 30min (19:30 - 09:00) A few notes: diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md index 8e88d8fd7b6..707ba01eb79 100644 --- a/doc/user/analytics/index.md +++ b/doc/user/analytics/index.md @@ -15,6 +15,8 @@ Once enabled, click on **Analytics** from the top navigation bar. From the centralized analytics workspace, the following analytics are available: +- [Code Review Analytics](code_review_analytics.md), enabled with the `code_review_analytics` + [feature flag](../../development/feature_flags/development.html#enabling-a-feature-flag-in-development). **(STARTER)** - [Cycle Analytics](cycle_analytics.md), enabled with the `cycle_analytics` [feature flag](../../development/feature_flags/development.html#enabling-a-feature-flag-in-development). **(PREMIUM)** - [Productivity Analytics](productivity_analytics.md), enabled with the `productivity_analytics` diff --git a/doc/user/application_security/container_scanning/index.md b/doc/user/application_security/container_scanning/index.md index 08242b3c65b..de8854bda0a 100644 --- a/doc/user/application_security/container_scanning/index.md +++ b/doc/user/application_security/container_scanning/index.md @@ -269,6 +269,15 @@ it highlighted: } ], "remediations": [ + { + "fixes": [ + { + "cve": "debian:9:apt:CVE-2019-3462" + } + ], + "summary": "Upgrade apt from 1.4.8 to 1.4.9", + "diff": "YXB0LWdldCB1cGRhdGUgJiYgYXB0LWdldCB1cGdyYWRlIC15IGFwdA==" + } ] } ``` @@ -296,7 +305,7 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].location.dependency.package.name` | Name of the package where the vulnerability is located. | | `vulnerabilities[].location.dependency.version` | Version of the vulnerable package. Optional. | | `vulnerabilities[].location.operating_system` | The operating system that contains the vulnerable package. | -| `vulnerabilities[].location.image` | The Docker image that was analyzed. Optional. | +| `vulnerabilities[].location.image` | The Docker image that was analyzed. | | `vulnerabilities[].identifiers` | An ordered array of references that identify a vulnerability on internal or external DBs. | | `vulnerabilities[].identifiers[].type` | Type of the identifier. Possible values: common identifier types (among `cve`, `cwe`, `osvdb`, and `usn`). | | `vulnerabilities[].identifiers[].name` | Name of the identifier for display purpose. | @@ -305,7 +314,11 @@ the report JSON unless stated otherwise. Presence of optional fields depends on | `vulnerabilities[].links` | An array of references to external documentation pieces or articles that describe the vulnerability further. Optional. | | `vulnerabilities[].links[].name` | Name of the vulnerability details link. Optional. | | `vulnerabilities[].links[].url` | URL of the vulnerability details document. Optional. | -| `remediations` | Not supported yet. | +| `remediations` | An array of objects containing information on cured vulnerabilities along with patch diffs to apply. Empty if no remediations provided by an underlying analyzer. | +| `remediations[].fixes` | An array of strings that represent references to vulnerabilities fixed by this particular remediation. | +| `remediations[].fixes[].cve` | A string value that describes a fixed vulnerability occurrence in the same format as `vulnerabilities[].cve`. | +| `remediations[].summary` | Overview of how the vulnerabilities have been fixed. | +| `remediations[].diff` | base64-encoded remediation code diff, compatible with [`git apply`](https://git-scm.com/docs/git-format-patch#_discussion). | ## Troubleshooting diff --git a/doc/user/application_security/dast/index.md b/doc/user/application_security/dast/index.md index 3a8a81f5f57..9678ff4de5a 100644 --- a/doc/user/application_security/dast/index.md +++ b/doc/user/application_security/dast/index.md @@ -103,6 +103,10 @@ always take the latest DAST artifact available. Behind the scenes, the [GitLab DAST Docker image](https://gitlab.com/gitlab-org/security-products/dast) is used to run the tests on the specified URL and scan it for possible vulnerabilities. +By default, the DAST template will use the latest major version of the DAST Docker image. Using the `DAST_VERSION` variable, +you can choose to automatically update DAST with new features and fixes by pinning to a major version (e.g. 1), only update fixes by pinning to a minor version (e.g. 1.6) or prevent all updates by pinning to a specific version (e.g. 1.6.4). +Find the latest DAST versions on the [Releases](https://gitlab.com/gitlab-org/security-products/dast/-/releases) page. + ### Authenticated scan It's also possible to authenticate the user before performing the DAST checks: @@ -312,6 +316,15 @@ variable value. | `DAST_FULL_SCAN_ENABLED` | no | Switches the tool to execute [ZAP Full Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Full-Scan) instead of [ZAP Baseline Scan](https://github.com/zaproxy/zaproxy/wiki/ZAP-Baseline-Scan). Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | | `DAST_FULL_SCAN_DOMAIN_VALIDATION_REQUIRED` | no | Requires [domain validation](#domain-validation) when running DAST full scans. Boolean. `true`, `True`, or `1` are considered as true value, otherwise false. Defaults to `false`. | +## Reports JSON format + +CAUTION: **Caution:** +The JSON report artifacts are not a public API of DAST and their format may change in the future. + +The DAST tool emits a JSON report report file. Sample report files can be found in the [DAST repository](https://gitlab.com/gitlab-org/security-products/dast/tree/master/test/end-to-end/expect). + +There are two formats of data in the JSON document that are used side by side: the proprietary ZAP format which will be eventually deprecated, and a "common" format which will be the default in the future. + ## Security Dashboard The Security Dashboard is a good place to get an overview of all the security diff --git a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png b/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png Binary files differindex 1ae44687ed5..8eeadb34504 100644 --- a/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png +++ b/doc/user/application_security/dependency_list/img/dependency_list_v12_3.png diff --git a/doc/user/application_security/dependency_scanning/index.md b/doc/user/application_security/dependency_scanning/index.md index 01feaaac423..c47fd6f1ff1 100644 --- a/doc/user/application_security/dependency_scanning/index.md +++ b/doc/user/application_security/dependency_scanning/index.md @@ -65,6 +65,7 @@ The following languages and dependency managers are supported. | Python ([poetry](https://poetry.eustace.io/)) | not currently ([issue](https://gitlab.com/gitlab-org/gitlab/issues/7006 "Support Poetry in Dependency Scanning")) | not available | | Ruby ([gem](https://rubygems.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium), [bundler-audit](https://github.com/rubysec/bundler-audit) | | Scala ([sbt](https://www.scala-sbt.org/)) | yes | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | +| Go ([go](https://golang.org/)) | yes (alpha) | [gemnasium](https://gitlab.com/gitlab-org/security-products/gemnasium) | ## Configuration @@ -136,6 +137,9 @@ using environment variables. | `DS_PYTHON_VERSION` | Version of Python. If set to 2, dependencies are installed using Python 2.7 instead of Python 3.6. ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12296) in GitLab 12.1)| | `DS_PIP_VERSION` | Force the install of a specific pip version (example: `"19.3"`), otherwise the pip installed in the docker image is used. | | `DS_PIP_DEPENDENCY_PATH` | Path to load Python pip dependencies from. ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12412) in GitLab 12.2) | +| `GEMNASIUM_DB_LOCAL_PATH` | Path to local gemnasium database (default `/gemnasium-db`). +| `GEMNASIUM_DB_REMOTE_URL` | Repository URL for fetching the gemnasium database (default `https://gitlab.com/gitlab-org/security-products/gemnasium-db.git`). +| `GEMNASIUM_DB_REF_NAME` | Branch name for remote repository database (default `master`). `GEMNASIUM_DB_REMOTE_URL` is required. | `DS_DEFAULT_ANALYZERS` | Override the names of the official default images. Read more about [customizing analyzers](analyzers.md). | | `DS_DISABLE_DIND` | Disable Docker in Docker and run analyzers [individually](#disabling-docker-in-docker-for-dependency-scanning).| | `DS_PULL_ANALYZER_IMAGES` | Pull the images from the Docker registry (set to `0` to disable). | @@ -146,7 +150,7 @@ using environment variables. | `PIP_INDEX_URL` | Base URL of Python Package Index (default `https://pypi.org/simple`). | | `PIP_EXTRA_INDEX_URL` | Array of [extra URLs](https://pip.pypa.io/en/stable/reference/pip_install/#cmdoption-extra-index-url) of package indexes to use in addition to `PIP_INDEX_URL`. Comma separated. | | `PIP_REQUIREMENTS_FILE` | Pip requirements file to be scanned. | -| `MAVEN_CLI_OPTS` | List of command line arguments that will be passed to the maven analyzer during the project's build phase (see example for [using private repos](#using-private-maven-repos)). | +| `MAVEN_CLI_OPTS` | List of command line arguments that will be passed to `maven` by the analyzer. The default is `"-DskipTests --batch-mode"`. See an example for [using private repos](#using-private-maven-repos). | | `BUNDLER_AUDIT_UPDATE_DISABLED` | Disable automatic updates for the `bundler-audit` analyzer (default: `"false"`). Useful if you're running Dependency Scanning in an offline, air-gapped environment.| ### Using private Maven repos diff --git a/doc/user/application_security/license_compliance/img/license_list_v12_6.png b/doc/user/application_security/license_compliance/img/license_list_v12_6.png Binary files differnew file mode 100644 index 00000000000..8f2b510be0d --- /dev/null +++ b/doc/user/application_security/license_compliance/img/license_list_v12_6.png diff --git a/doc/user/application_security/license_compliance/index.md b/doc/user/application_security/license_compliance/index.md index 3cf8301adca..97804a451b9 100644 --- a/doc/user/application_security/license_compliance/index.md +++ b/doc/user/application_security/license_compliance/index.md @@ -253,3 +253,25 @@ 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. --> + +## License list + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/13582) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. + +The License list allows you to see your project's licenses and key +details about them. + +In order for the licenses to appear under the license list, the following +requirements must be met: + +1. The License Compliance CI job must be [configured](#configuration) for your project. +1. Your project must use at least one of the + [supported languages and package managers](#supported-languages-and-package-managers). + +Once everything is set, navigate to **Security & Compliance > License Compliance** +in your project's sidebar, and you'll see the licenses displayed, where: + +- **Name:** The name of the license. +- **Component:** The components which have this license. + + diff --git a/doc/user/application_security/sast/index.md b/doc/user/application_security/sast/index.md index 95027e99c00..2672b0f3461 100644 --- a/doc/user/application_security/sast/index.md +++ b/doc/user/application_security/sast/index.md @@ -100,7 +100,7 @@ Add the following to your `.gitlab-ci.yml` file: ```yaml include: - template: SAST.gitlab-ci.yml + - template: SAST.gitlab-ci.yml ``` The included template will create a `sast` job in your CI/CD pipeline and scan @@ -124,7 +124,7 @@ set the `SAST_GOSEC_LEVEL` variable to `2`: ```yaml include: - template: SAST.gitlab-ci.yml + - template: SAST.gitlab-ci.yml variables: SAST_GOSEC_LEVEL: 2 @@ -141,7 +141,7 @@ template inclusion and specify any additional keys under it. For example: ```yaml include: - template: SAST.gitlab-ci.yml + - template: SAST.gitlab-ci.yml sast: variables: @@ -178,7 +178,7 @@ This does not require running the executor in privileged mode. For example: ```yaml include: - template: SAST.gitlab-ci.yml + - template: SAST.gitlab-ci.yml variables: SAST_DISABLE_DIND: "true" @@ -196,12 +196,63 @@ kubesec analyzer. In `.gitlab-ci.yml`, define: ```yaml include: - template: SAST.gitlab-ci.yml + - template: SAST.gitlab-ci.yml variables: + SAST_DISABLE_DIND: "true" SCAN_KUBERNETES_MANIFESTS: "true" ``` +#### Pre-compilation + +If your project requires custom build configurations, it can be preferable to avoid +compilation during your SAST execution and instead pass all job artifacts from an +earlier stage within the pipeline. + +To pass your project's dependencies as artifacts, the dependencies must be included +in the project's working directory and specified using the `artifacts:path` configuration. +If all dependencies are present, the `-compile=false` flag can be provided to the +analyzer and compilation will be skipped: + +```yaml +image: maven:3.6-jdk-8-alpine + +stages: + - build + - test + +include: + template: SAST.gitlab-ci.yml + +variables: + SAST_DISABLE_DIND: "true" + +build: + stage: build + script: + - mvn package -Dmaven.repo.local=./.m2/repository + artifacts: + paths: + - .m2/ + - target/ + +spotbugs-sast: + dependencies: build + script: + - /analyzer run -compile=false + variables: + MAVEN_REPO_PATH: ./.m2/repository + artifacts: + reports: + sast: gl-sast-report.json +``` + +NOTE: **Note:** +The path to the vendored directory must be specified explicitly to allow +the analyzer to recognize the compiled artifacts. This configuration can vary per +analyzer but in the case of Java above, `MAVEN_REPO_PATH` can be used. +See [Analyzer settings](#analyzer-settings) for the complete list of available options. + ### Available variables SAST can be [configured](#customizing-the-sast-settings) using environment variables. diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png Binary files differnew file mode 100644 index 00000000000..e0e80810b08 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_link_v12_4.png diff --git a/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v12_7.png b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v12_7.png Binary files differnew file mode 100644 index 00000000000..ffd6b0bfae6 --- /dev/null +++ b/doc/user/application_security/security_dashboard/img/instance_security_dashboard_with_projects_v12_7.png diff --git a/doc/user/application_security/security_dashboard/index.md b/doc/user/application_security/security_dashboard/index.md index bb2bf0b7806..e9ae87ab44e 100644 --- a/doc/user/application_security/security_dashboard/index.md +++ b/doc/user/application_security/security_dashboard/index.md @@ -26,7 +26,7 @@ The Security Dashboard supports the following reports: ## Requirements -To use the group, project or pipeline security dashboard: +To use the instance, group, project or pipeline security dashboard: 1. At least one project inside a group must be configured with at least one of the [supported reports](#supported-reports). @@ -110,6 +110,31 @@ vulnerabilities are not included either. Read more on how to [interact with the vulnerabilities](../index.md#interacting-with-the-vulnerabilities). +## Instance Security Dashboard + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/6953) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.7. + +At the instance level, the Security Dashboard displays the vulnerabilities +present in all of the projects that you have added to it. + +You can access the Instance Security Dashboard from the menu +bar at the top of the page. Under **More**, select **Security**. + + + +### Adding projects to the dashboard + +To add projects to the dashboard: + +1. Click the **Edit dashboard** button on the Instance Security Dashboard page. +1. Search for and add one or more projects using the **Search your projects** field. +1. Click the **Add projects** button. + +Once added, the dashboard will display the vulnerabilities found in your chosen +projects. + + + ## Keeping the dashboards up to date The Security Dashboard displays information from the results of the most recent diff --git a/doc/user/clusters/applications.md b/doc/user/clusters/applications.md index 95dbe7d3b51..47d835a1622 100644 --- a/doc/user/clusters/applications.md +++ b/doc/user/clusters/applications.md @@ -35,12 +35,13 @@ The following applications can be installed: - [Helm](#helm) - [Ingress](#ingress) -- [Cert-Manager](#cert-manager) +- [cert-manager](#cert-manager) - [Prometheus](#prometheus) - [GitLab Runner](#gitlab-runner) - [JupyterHub](#jupyterhub) - [Knative](#knative) - [Crossplane](#crossplane) +- [Elastic Stack](#elastic-stack) With the exception of Knative, the applications will be installed in a dedicated namespace called `gitlab-managed-apps`. @@ -73,13 +74,13 @@ Installing Helm as a GitLab-managed App behind a proxy is not supported, but a [workaround](../../topics/autodevops/index.md#installing-helm-behind-a-proxy) is available. -### Cert-Manager +### cert-manager > Introduced in GitLab 11.6 for project- and group-level clusters. -[Cert-Manager](https://docs.cert-manager.io/en/latest/) is a native +[cert-manager](https://docs.cert-manager.io/en/latest/) is a native Kubernetes certificate management controller that helps with issuing -certificates. Installing Cert-Manager on your cluster will issue a +certificates. Installing cert-manager on your cluster will issue a certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up-to-date. @@ -91,13 +92,13 @@ The chart used to install this application depends on the version of GitLab used - GitLab 12.2 and older, the [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) chart was used. -If you have installed Cert-Manager prior to GitLab 12.3, Let's Encrypt will -[block requests from older versions of Cert-Manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753). +If you have installed cert-manager prior to GitLab 12.3, Let's Encrypt will +[block requests from older versions of cert-manager](https://community.letsencrypt.org/t/blocking-old-cert-manager-versions/98753). To resolve this: -1. Uninstall Cert-Manager (consider [backing up any additional configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html)). -1. Install Cert-Manager again. +1. Uninstall cert-manager (consider [backing up any additional configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html)). +1. Install cert-manager again. ### GitLab Runner @@ -248,10 +249,10 @@ use an A record. If your external endpoint is a hostname, use a CNAME record. #### Web Application Firewall (ModSecurity) -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/65192) in GitLab 12.3 (enabled using `ingress_modsecurity` [feature flag](../../development/feature_flags/development.md#enabling-a-feature-flag-in-development)). +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/21966) in GitLab 12.7. Out of the box, GitLab provides you real-time security monitoring with -[`modsecurity`](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity) +[ModSecurity](https://kubernetes.github.io/ingress-nginx/user-guide/nginx-configuration/annotations/#modsecurity). Modsecurity is a toolkit for real-time web application monitoring, logging, and access control. With GitLab's offering, the [OWASP's Core Rule Set](https://www.modsecurity.org/CRS/Documentation/), which provides generic attack detection capabilities, @@ -264,25 +265,21 @@ This feature: For example: ```sh - kubectl -n gitlab-managed-apps exec -it $(kubectl get pods -n gitlab-managed-apps | grep 'ingress-controller' | awk '{print $1}') -- tail -f /var/log/modsec/audit.log + kubectl logs -n gitlab-managed-apps $(kubectl get pod -n gitlab-managed-apps -l app=nginx-ingress,component=controller --no-headers=true -o custom-columns=:metadata.name) modsecurity-log -f ``` -There is a small performance overhead by enabling `modsecurity`. If this is -considered significant for your application, you can either: +To enable ModSecurity, check the **Enable Web Application Firewall** checkbox +when installing your [Ingress application](#ingress). -- Disable ModSecurity's rule engine for your deployed application by setting - [the deployment variable](../../topics/autodevops/index.md) - `AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off`. This will prevent ModSecurity from - processing any requests for the given application or environment. -- Toggle the feature flag to false by running the following command within your - instance's Rails console: +There is a small performance overhead by enabling ModSecurity. If this is +considered significant for your application, you can disable ModSecurity's +rule engine for your deployed application by setting +[the deployment variable](../../topics/autodevops/index.md) +`AUTO_DEVOPS_MODSECURITY_SEC_RULE_ENGINE` to `Off`. This will prevent ModSecurity +from processing any requests for the given application or environment. - ```ruby - Feature.disable(:ingress_modsecurity) - ``` - -Once disabled, you must [uninstall](#uninstalling-applications) and reinstall your Ingress -application for the changes to take effect. +To permanently disable it, you must [uninstall](#uninstalling-applications) and +reinstall your Ingress application for the changes to take effect. ### JupyterHub @@ -423,18 +420,45 @@ install Crossplane using the [`values.yaml`](https://github.com/crossplaneio/crossplane/blob/master/cluster/charts/crossplane/values.yaml.tmpl) file. -#### Enabling installation +### Elastic Stack + +> Introduced in GitLab 12.7 for project- and group-level clusters. + +[Elastic Stack](https://www.elastic.co/products/elastic-stack) is a complete end-to-end +log analysis solution which helps in deep searching, analyzing and visualizing the logs +generated from different machines. + +GitLab is able to gather logs from pods in your cluster automatically. +Filebeat will run as a DaemonSet on each node in your cluster, and it will ship container logs to Elasticsearch for querying. +GitLab will then connect to Elasticsearch for logs instead of the Kubernetes API, +and you will have access to more advanced querying capabilities. + +Log data is automatically deleted after 15 days using [Curator](https://www.elastic.co/guide/en/elasticsearch/client/curator/5.5/about.html). -This is a preliminary release of Crossplane as a GitLab-managed application. By default, +This is a preliminary release of Elastic Stack as a GitLab-managed application. By default, the ability to install it is disabled. -To allow installation of Crossplane as a GitLab-managed application, ask a GitLab +To allow installation of Elastic Stack as a GitLab-managed application, ask a GitLab administrator to run following command within a Rails console: ```ruby -Feature.enable(:enable_cluster_application_crossplane) +Feature.enable(:enable_cluster_application_elastic_stack) ``` +Once the feature flag is set, to enable log shipping, install Elastic Stack into the cluster with the +**Install** button. + +NOTE: **Note:** +The [`stable/elastic-stack`](https://github.com/helm/charts/tree/master/stable/elastic-stack) +chart is used to install this application with a +[`values.yaml`](https://gitlab.com/gitlab-org/gitlab/blob/master/vendor/elastic_stack/values.yaml) +file. + +NOTE: **Note:** +The chart will deploy 4 Elasticsearch nodes: 2 masters, 1 data and 1 client node, +with resource requests totalling 0.1 CPU and 3GB RAM. Each data node requests 1.5GB of memory, +which makes it incompatible with clusters of `f1-micro` and `g1-small` instance types. + ## Install using GitLab CI (alpha) > [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/20822) in GitLab 12.6. @@ -450,10 +474,16 @@ install using Helm `values.yaml` files. Supported applications: - [Ingress](#install-ingress-using-gitlab-ci) +- [cert-manager](#install-cert-manager-using-gitlab-ci) - [Sentry](#install-sentry-using-gitlab-ci) +- [GitLab Runner](#install-gitlab-runner-using-gitlab-ci) ### Usage +You can find and import all the files referenced below +in the [example cluster applications +project](https://gitlab.com/gitlab-org/cluster-integration/example-cluster-applications/). + To install applications using GitLab CI: 1. Connect the cluster to a [cluster management project](management_project.md). @@ -478,7 +508,10 @@ To install applications using GitLab CI: customize values for the installed application. A GitLab CI pipeline will then run on the `master` branch to install the -applications you have configured. +applications you have configured. In case of pipeline failure, the +output of the [Helm +Tiller](https://v2.helm.sh/docs/install/#running-tiller-locally) binary +will be saved as a [CI job artifact](../project/pipelines/job_artifacts.md). ### Install Ingress using GitLab CI @@ -499,6 +532,43 @@ management project. Refer to the [chart](https://github.com/helm/charts/tree/master/stable/nginx-ingress) for the available configuration options. +### Install cert-manager using GitLab CI + +cert-manager is installed using GitLab CI by defining configuration in +`.gitlab/managed-apps/config.yaml`. + +cert-manager: + +- Is installed into the `gitlab-managed-apps` namespace of your cluster. +- Can be installed with or without a default [Let's Encrypt `ClusterIssuer`](https://cert-manager.io/docs/configuration/acme/), which requires an + email address to be specified. The email address is used by Let's Encrypt to + contact you about expiring certificates and issues related to your account. + +The following configuration is required to install cert-manager using GitLab CI: + +```yaml +certManager: + installed: true + letsEncryptClusterIssuer: + installed: true + email: "user@example.com" +``` + +The following installs cert-manager using GitLab CI without the default `ClusterIssuer`: + +```yaml +certManager: + installed: true + letsEncryptClusterIssuer: + installed: false +``` + +You can customize the installation of cert-manager by defining +`.gitlab/managed-apps/cert-manager/values.yaml` file in your cluster +management project. Refer to the +[chart](https://hub.helm.sh/charts/jetstack/cert-manager) for the +available configuration options. + ### Install Sentry using GitLab CI NOTE: **Note:** @@ -560,6 +630,37 @@ postgresql: postgresqlPassword: example-postgresql-password ``` +### Install GitLab Runner using GitLab CI + +GitLab Runner is installed using GitLab CI by defining configuration in +`.gitlab/managed-apps/config.yaml`. + +The following configuration is required to install GitLab Runner using GitLab CI: + +```yaml +gitlabRunner: + installed: true +``` + +GitLab Runner is installed into the `gitlab-managed-apps` namespace of your cluster. + +In order for GitLab Runner to function, you **must** specify the following: + +- `gitlabUrl` - the GitLab server full URL (e.g., `https://example.gitlab.com`) to register the Runner against. +- `runnerRegistrationToken` - The registration token for adding new Runners to GitLab. This must be + [retrieved from your GitLab instance](../../ci/runners/README.md). + +These values can be specifed using [CI variables](../../ci/variables/README.md): + +- `GITLAB_RUNNER_GITLAB_URL` will be used for `gitlabUrl`. +- `GITLAB_RUNNER_REGISTRATION_TOKEN` will be used for `runnerRegistrationToken` + +You can customize the installation of GitLab Runner by defining +`.gitlab/managed-apps/gitlab-runner/values.yaml` file in your cluster +management project. Refer to the +[chart](https://gitlab.com/gitlab-org/charts/gitlab-runner) for the +available configuration options. + ## Upgrading applications > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/24789) in GitLab 11.8. @@ -593,7 +694,7 @@ The applications below can be uninstalled. | Application | GitLab version | Notes | | ----------- | -------------- | ----- | -| Cert-Manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). | +| cert-manager | 12.2+ | The associated private key will be deleted and cannot be restored. Deployed applications will continue to use HTTPS, but certificates will not be renewed. Before uninstalling, you may wish to [back up your configuration](https://docs.cert-manager.io/en/latest/tasks/backup-restore-crds.html) or [revoke your certificates](https://letsencrypt.org/docs/revoking/). | | GitLab Runner | 12.2+ | Any running pipelines will be canceled. | | Helm | 12.2+ | The associated Tiller pod, the `gitlab-managed-apps` namespace, and all of its resources will be deleted and cannot be restored. | | Ingress | 12.1+ | The associated load balancer and IP will be deleted and cannot be restored. Furthermore, it can only be uninstalled if JupyterHub is not installed. | @@ -601,6 +702,7 @@ The applications below can be uninstalled. | Knative | 12.1+ | The associated IP will be deleted and cannot be restored. | | Prometheus | 11.11+ | All data will be deleted and cannot be restored. | | Crossplane | 12.5+ | All data will be deleted and cannot be restored. | +| Elastic Stack | 12.7+ | All data will be deleted and cannot be restored. | | Sentry | 12.6+ | The PostgreSQL persistent volume will remain and should be manually removed for complete uninstall. | To uninstall an application: diff --git a/doc/user/clusters/crossplane.md b/doc/user/clusters/crossplane.md index ee0bd4c33db..247a373301f 100644 --- a/doc/user/clusters/crossplane.md +++ b/doc/user/clusters/crossplane.md @@ -222,7 +222,7 @@ The Auto DevOps pipeline can be run with the following options: The Environment variables, `AUTO_DEVOPS_POSTGRES_MANAGED` and `AUTO_DEVOPS_POSTGRES_MANAGED_CLASS_SELECTOR` need to be set to provision PostgreSQL using Crossplane -Alertnatively, the following options can be overridden from the values for the Helm chart. +Alternatively, the following options can be overridden from the values for the Helm chart. - `postgres.managed` set to true which will select a default resource class. The resource class needs to be marked with the annotation @@ -235,7 +235,7 @@ Alertnatively, the following options can be overridden from the values for the H will select the CloudSQLInstance class `cloudsqlinstancepostgresql-standard` to satisfy the claim request. -The Auto DevOps pipeline should provision a PostgresqlInstance when it runs succesfully. +The Auto DevOps pipeline should provision a PostgresqlInstance when it runs successfully. Verify creation of the PostgreSQL Instance. diff --git a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png Binary files differindex 63e2d1cd4e8..5fd1bac5e05 100644 --- a/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png +++ b/doc/user/clusters/img/advanced-settings-cluster-management-project-v12_5.png diff --git a/doc/user/clusters/img/cluster_environments_table_v12_3.png b/doc/user/clusters/img/cluster_environments_table_v12_3.png Binary files differindex 52f232e2eb3..9e419efe4c5 100644 --- a/doc/user/clusters/img/cluster_environments_table_v12_3.png +++ b/doc/user/clusters/img/cluster_environments_table_v12_3.png diff --git a/doc/user/discussions/img/apply_suggestion_v12_7.png b/doc/user/discussions/img/apply_suggestion_v12_7.png Binary files differnew file mode 100644 index 00000000000..c8c44149fd0 --- /dev/null +++ b/doc/user/discussions/img/apply_suggestion_v12_7.png diff --git a/doc/user/discussions/img/insert_suggestion.png b/doc/user/discussions/img/insert_suggestion.png Binary files differdeleted file mode 100644 index 4bf293b8297..00000000000 --- a/doc/user/discussions/img/insert_suggestion.png +++ /dev/null diff --git a/doc/user/discussions/img/make_suggestion.png b/doc/user/discussions/img/make_suggestion.png Binary files differdeleted file mode 100644 index a24e29770aa..00000000000 --- a/doc/user/discussions/img/make_suggestion.png +++ /dev/null diff --git a/doc/user/discussions/img/make_suggestion_v12_7.png b/doc/user/discussions/img/make_suggestion_v12_7.png Binary files differnew file mode 100644 index 00000000000..7eb84186b0a --- /dev/null +++ b/doc/user/discussions/img/make_suggestion_v12_7.png diff --git a/doc/user/discussions/img/suggestion.png b/doc/user/discussions/img/suggestion.png Binary files differdeleted file mode 100644 index f7962305a15..00000000000 --- a/doc/user/discussions/img/suggestion.png +++ /dev/null diff --git a/doc/user/discussions/img/suggestion_button_v12_7.png b/doc/user/discussions/img/suggestion_button_v12_7.png Binary files differnew file mode 100644 index 00000000000..3b7a4d625a3 --- /dev/null +++ b/doc/user/discussions/img/suggestion_button_v12_7.png diff --git a/doc/user/discussions/img/suggestions_custom_commit_messages_v12_7.png b/doc/user/discussions/img/suggestions_custom_commit_messages_v12_7.png Binary files differnew file mode 100644 index 00000000000..8bbc0fcb99b --- /dev/null +++ b/doc/user/discussions/img/suggestions_custom_commit_messages_v12_7.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md index d4e485d7c32..6016837a769 100644 --- a/doc/user/discussions/index.md +++ b/doc/user/discussions/index.md @@ -4,12 +4,12 @@ The ability to contribute conversationally is offered throughout GitLab. You can leave a comment in the following places: -- issues -- epics **(ULTIMATE)** -- merge requests -- snippets -- commits -- commit diffs +- Issues +- Epics **(ULTIMATE)** +- Merge requests +- Snippets +- Commits +- Commit diffs There are standard comments, and you also have the option to create a comment in the form of a thread. A comment can also be [turned into a thread](#start-a-thread-by-replying-to-a-standard-comment) @@ -29,9 +29,7 @@ There is a limit of 5,000 comments for every object, for example: issue, epic, a ## Resolvable comments and threads -> **Notes:** -> -> - The main feature was [introduced][ce-5022] in GitLab 8.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/5022) in GitLab 8.11. > - Resolvable threads can be added only to merge request diffs. Thread resolution helps keep track of progress during planning or code review. @@ -352,7 +350,10 @@ bottom of the screen with two buttons: Clicking **Submit review** will publish all comments. Any quick actions submitted are performed at this time. -Alternatively, every pending comment has a button to finish the entire review. +Alternatively, to finish the entire review from a pending comment: + +- Click the **Finish review** button on the comment. +- Use the `/submit_review` [quick action](../project/quick_actions.md) in the text of non-review comment.  @@ -389,47 +390,45 @@ As a reviewer, you're able to suggest code changes with a simple Markdown syntax in Merge Request Diff threads. Then, the Merge Request author (or other users with appropriate [permission](../permissions.md)) is able to apply these -suggestions with a click, which will generate a commit in -the Merge Request authored by the user that applied them. +Suggestions with a click, which will generate a commit in +the merge request authored by the user that applied them. 1. Choose a line of code to be changed, add a new comment, then click on the **Insert suggestion** icon in the toolbar: -  +  1. In the comment, add your suggestion to the pre-populated code block: -  +  1. Click **Comment**. - The suggestions in the comment can be applied by the merge request author + NOTE: **Note:** + If you're using GitLab Premium, GitLab.com Silver, and higher tiers, the thread will display [Review](#merge-request-reviews-premium) options. Click either **Start a review**, **Add comment now**, or **Add to review** to obtain the same result. + + The Suggestion in the comment can be applied by the merge request author directly from the merge request: -  +  -Once the author applies a suggestion, it will be marked with the **Applied** label, +Once the author applies a Suggestion, it will be marked with the **Applied** label, the thread will be automatically resolved, and GitLab will create a new commit -with the message `Apply suggestion to <file-name>` and push the suggested change -directly into the codebase in the merge request's branch. -[Developer permission](../permissions.md) is required to do so. - -> **Note:** -Custom commit messages will be introduced by -[#54404](https://gitlab.com/gitlab-org/gitlab-foss/issues/54404). +and push the suggested change directly into the codebase in the merge request's +branch. [Developer permission](../permissions.md) is required to do so. -### Multi-line suggestions +### Multi-line Suggestions > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/53310) in GitLab 11.10. -Reviewers can also suggest changes to multiple lines with a single suggestion -within Merge Request diff threads by adjusting the range offsets. The +Reviewers can also suggest changes to multiple lines with a single Suggestion +within merge request diff threads by adjusting the range offsets. The offsets are relative to the position of the diff thread, and specify the range to be replaced by the suggestion when it is applied.  -In the example above, the suggestion covers three lines above and four lines +In the example above, the Suggestion covers three lines above and four lines below the commented line. When applied, it would replace from 3 lines _above_ to 4 lines _below_ the commented line, with the suggested change. @@ -440,6 +439,37 @@ Suggestions covering multiple lines are limited to 100 lines _above_ and 100 lines _below_ the commented diff line, allowing up to 200 changed lines per suggestion. +### Configure the commit message for applied Suggestions + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13086) in GitLab 12.7. + +GitLab uses `Apply suggestion to %{file_path}` by default as commit messages +when applying Suggestions. This commit message can be customized to +follow any guidelines you might have. To do so, expand the **Merge requests** +tab within your project's **General** settings and change the +**Merge suggestions** text: + + + +You can also use following variables besides static text: + +| Variable | Description | Output example | +|---|---|---| +| `%{project_path}` | The project path. | `my-group/my-project` | +| `%{project_name}` | The human-readable name of the project. | **My Project** | +| `%{file_path}` | The path of the file the Suggestion is applied to. | `docs/index.md` | +| `%{branch_name}` | The name of the branch the Suggestion is applied on. | `my-feature-branch` | +| `%{username}` | The username of the user applying the Suggestion. | `user_1` | +| `%{user_full_name}` | The full name of the user applying the Suggestion. | **User 1** | + +For example, to customize the commit message to output +**Addresses user_1's review**, set the custom text to +`Addresses %{username}'s review`. + +NOTE: **Note:** +Custom commit messages for each applied Suggestion will be +introduced by [#25381](https://gitlab.com/gitlab-org/gitlab/issues/25381). + ## Start a thread by replying to a standard comment > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/30299) in GitLab 11.9 @@ -461,7 +491,6 @@ to the original comment, so a note about when it was last edited will appear und This feature only exists for Issues, Merge requests, and Epics. Commits, Snippets and Merge request diff threads are not supported yet. -[ce-5022]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/5022 [ce-7125]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7125 [ce-7527]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7527 [ce-7180]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/7180 diff --git a/doc/user/group/clusters/index.md b/doc/user/group/clusters/index.md index 2b36c3bdf5b..83d1fc672df 100644 --- a/doc/user/group/clusters/index.md +++ b/doc/user/group/clusters/index.md @@ -53,8 +53,8 @@ differentiate the new cluster from the rest. ## GitLab-managed clusters -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5. -> Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5. +> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11. You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects will be automatically created. See the @@ -170,6 +170,11 @@ For important information about securely configuring GitLab Runners, see Runners](../../project/clusters/add_remove_clusters.md#security-of-gitlab-runners) documentation for project-level clusters. +## More information + +For information on integrating GitLab and Kubernetes, see +[Kubernetes clusters](../../project/clusters/index.md). + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/group/epics/img/epics_list_view_v12.5.png b/doc/user/group/epics/img/epics_list_view_v12.5.png Binary files differindex 2520ee67abc..6e3c39009be 100644 --- a/doc/user/group/epics/img/epics_list_view_v12.5.png +++ b/doc/user/group/epics/img/epics_list_view_v12.5.png diff --git a/doc/user/group/epics/index.md b/doc/user/group/epics/index.md index 01e277d5559..d8cb49d0e9f 100644 --- a/doc/user/group/epics/index.md +++ b/doc/user/group/epics/index.md @@ -40,14 +40,19 @@ An epic's page contains the following tabs: - **Epics and Issues**: epics and issues added to this epic. Child epics, and their issues, are shown in a tree view. - Click on the <kbd>></kbd> beside a parent epic to reveal the child epics and issues. + - Hover over the total counts to see a breakdown of open and closed items. - **Roadmap**: a roadmap view of child epics which have start and due dates.  ## Adding an issue to an epic -Any issue that belongs to a project in the epic's group, or any of the epic's -subgroups, are eligible to be added. New issues appear at the top of the list of issues in the **Epics and Issues** tab. +You can add an existing issue to an epic, or, from an epic's page, create a new issue that is automatically added to the epic. + +### Adding an existing issue to an epic + +Existing issues that belong to a project in an epic's group, or any of the epic's +subgroups, are eligible to be added to the epic. Newly added issues appear at the top of the list of issues in the **Epics and Issues** tab. An epic contains a list of issues and an issue can be associated with at most one epic. When you add an issue that is already linked to an epic, @@ -63,6 +68,19 @@ To add an issue to an epic: If there are multiple issues to be added, press <kbd>Spacebar</kbd> and repeat this step. 1. Click **Add**. +### Creating an issue from an epic + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/5419) in GitLab 12.7. + +Creating an issue from an epic enables you to maintain focus on the broader context of the epic while dividing work into smaller parts. + +To create an issue from an epic: + +1. On the epic's page, under **Epics and Issues**, click the arrow next to **Add an issue** and select **Create new issue**. +1. Under **Title**, enter the title for the new issue. +1. From the **Project** dropdown, select the project in which the issue should be created. +1. Click **Create issue**. + To remove an issue from an epic: 1. Click on the <kbd>x</kbd> button in the epic's issue list. @@ -218,7 +236,9 @@ link in the issue sidebar. If you have [permissions](../../permissions.md) to close an issue and create an epic in the parent group, you can promote an issue to an epic with the `/promote` [quick action](../../project/quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). -Only issues from projects that are in groups can be promoted. +Only issues from projects that are in groups can be promoted. When attempting to promote a confidential +issue, a warning will display. Promoting a confidential issue to an epic will make all information +related to the issue public as epics are public to group members. When the quick action is executed: diff --git a/doc/user/group/img/select_group_dropdown.png b/doc/user/group/img/select_group_dropdown.png Binary files differindex 8c03ffffbde..4948cefb65f 100644 --- a/doc/user/group/img/select_group_dropdown.png +++ b/doc/user/group/img/select_group_dropdown.png diff --git a/doc/user/group/index.md b/doc/user/group/index.md index ad16aaa34ff..bf0a8c6bfbd 100644 --- a/doc/user/group/index.md +++ b/doc/user/group/index.md @@ -204,6 +204,25 @@ and give all group members access to the project at once. Alternatively, you can [lock the sharing with group feature](#share-with-group-lock). +## Sharing a group with another group + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18328) in GitLab 12.7. + +Similarly to [sharing a project with a group](#sharing-a-project-with-a-group), +you can share a group with another group to give direct group members access +to the shared group. This is not valid for inherited members. + +To share a given group, for example, 'Frontend' with another group, for example, +'Engineering': + +1. Navigate to your 'Frontend' group page and use the left navigation menu to go + to your group **Members**. +1. Select the **Invite group** tab. +1. Add 'Engineering' with the maximum access level of your choice. +1. Click **Invite**. + +All the members of the 'Engineering' group will have been added to 'Frontend'. + ## Manage group memberships via LDAP In GitLab Enterprise Edition, it is possible to manage GitLab group memberships using LDAP groups. diff --git a/doc/user/group/subgroups/img/group_members_filter_v12_6.png b/doc/user/group/subgroups/img/group_members_filter_v12_6.png Binary files differindex 0207515ded0..692fdfe00a1 100644 --- a/doc/user/group/subgroups/img/group_members_filter_v12_6.png +++ b/doc/user/group/subgroups/img/group_members_filter_v12_6.png diff --git a/doc/user/incident_management/img/incident_management_settings.png b/doc/user/incident_management/img/incident_management_settings.png Binary files differindex 25ad4fd08b7..761a782ce61 100644 --- a/doc/user/incident_management/img/incident_management_settings.png +++ b/doc/user/incident_management/img/incident_management_settings.png diff --git a/doc/user/instance/clusters/index.md b/doc/user/instance/clusters/index.md index 3d9a1eb219e..7b5ba14a5ae 100644 --- a/doc/user/instance/clusters/index.md +++ b/doc/user/instance/clusters/index.md @@ -12,11 +12,12 @@ projects. ## Cluster precedence -GitLab will try match to clusters in the following order: +GitLab will try [to match](../../../ci/environments.md#scoping-environments-with-specs) clusters in +the following order: -- Project-level clusters -- Group-level clusters -- Instance level +- Project-level clusters. +- Group-level clusters. +- Instance-level clusters. To be selected, the cluster must be enabled and match the [environment selector](../../../ci/environments.md#scoping-environments-with-specs). @@ -26,3 +27,8 @@ match the [environment selector](../../../ci/environments.md#scoping-environment For a consolidated view of which CI [environments](../../../ci/environments.md) are deployed to the Kubernetes cluster, see the documentation for [cluster environments](../../clusters/environments.md). + +## More information + +For information on integrating GitLab and Kubernetes, see +[Kubernetes clusters](../../project/clusters/index.md). diff --git a/doc/user/instance_statistics/dev_ops_score.md b/doc/user/instance_statistics/dev_ops_score.md index fbe4cc3c6df..68c5bb48c3c 100644 --- a/doc/user/instance_statistics/dev_ops_score.md +++ b/doc/user/instance_statistics/dev_ops_score.md @@ -16,7 +16,7 @@ of top-performing instances based on [usage ping data](../admin_area/settings/us collected. Your score is compared to the lead score of each feature and then expressed as a percentage at the bottom of said feature. Your overall index score is an average of all your feature score percentages - this percentage value is presented above all the of features on the page. - + The page also provides helpful links to articles and GitLab docs, to help you improve your scores. diff --git a/doc/user/instance_statistics/img/cohorts.png b/doc/user/instance_statistics/img/cohorts.png Binary files differindex 4d070fdb654..19250e385aa 100644 --- a/doc/user/instance_statistics/img/cohorts.png +++ b/doc/user/instance_statistics/img/cohorts.png diff --git a/doc/user/instance_statistics/img/dev_ops_score.png b/doc/user/instance_statistics/img/dev_ops_score.png Binary files differdeleted file mode 100644 index bee1317438d..00000000000 --- a/doc/user/instance_statistics/img/dev_ops_score.png +++ /dev/null diff --git a/doc/user/instance_statistics/img/dev_ops_score_v12_6.png b/doc/user/instance_statistics/img/dev_ops_score_v12_6.png Binary files differnew file mode 100644 index 00000000000..af07e9323d6 --- /dev/null +++ b/doc/user/instance_statistics/img/dev_ops_score_v12_6.png diff --git a/doc/user/instance_statistics/img/instance_statistics_button.png b/doc/user/instance_statistics/img/instance_statistics_button.png Binary files differdeleted file mode 100644 index 6104321b1a6..00000000000 --- a/doc/user/instance_statistics/img/instance_statistics_button.png +++ /dev/null diff --git a/doc/user/instance_statistics/img/instance_statistics_button_v12_6.png b/doc/user/instance_statistics/img/instance_statistics_button_v12_6.png Binary files differnew file mode 100644 index 00000000000..e5f033141ca --- /dev/null +++ b/doc/user/instance_statistics/img/instance_statistics_button_v12_6.png diff --git a/doc/user/instance_statistics/index.md b/doc/user/instance_statistics/index.md index 53bf85b6e13..c31da8d86f1 100644 --- a/doc/user/instance_statistics/index.md +++ b/doc/user/instance_statistics/index.md @@ -5,10 +5,10 @@ in GitLab 11.2. Instance statistics gives users or admins access to instance-wide analytics. They are accessible to all users by default (GitLab admins can restrict its -visibility in the [admin area](../admin_area/settings/usage_statistics.md)), +visibility in the [Admin Area](../admin_area/settings/usage_statistics.md)), and can be accessed via the top bar. - + There are two kinds of statistics: diff --git a/doc/user/markdown.md b/doc/user/markdown.md index fdf6cb3c7be..913a4332b1d 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -160,7 +160,7 @@ It is possible to generate diagrams and flowcharts from text in GitLab using [Me > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/15107) in GitLab 10.3. -Visit the [official page](https://mermaidjs.github.io/) for more details. +Visit the [official page](https://mermaidjs.github.io/) for more details. If you are new to using Mermaid or need help identifying issues in your Mermaid code, the [Mermaid Live Editor](https://mermaid-js.github.io/mermaid-live-editor/) is a helpful tool for creating and resolving issues within Mermaid diagrams. In order to generate a diagram or flowchart, you should write your text inside the `mermaid` block: @@ -275,7 +275,7 @@ In GitLab, front matter is only used in Markdown files and wiki pages, not the o places where Markdown formatting is supported. It must be at the very top of the document, and must be between delimiters, as explained below. -The following delimeters are supported: +The following delimiters are supported: - YAML (`---`): @@ -407,6 +407,7 @@ GFM will recognize the following: | merge request | `!123` | `namespace/project!123` | `project!123` | | snippet | `$123` | `namespace/project$123` | `project$123` | | epic **(ULTIMATE)** | `&123` | `group1/subgroup&123` | | +| design **(PREMIUM)** | `#123[file.jpg]` or `#123["file.png"]` | `group1/subgroup#123[file.png]` | `project#123[file.png]` | | label by ID | `~123` | `namespace/project~123` | `project~123` | | one-word label by name | `~bug` | `namespace/project~bug` | `project~bug` | | multi-word label by name | `~"feature request"` | `namespace/project~"feature request"` | `project~"feature request"` | @@ -601,7 +602,7 @@ Inline `code` has `back-ticks around` it. --- Similarly, a whole block of code can be fenced with triple backticks ```` ``` ````, -triple tildes (`~~~`), or indended 4 or more spaces to achieve a similar effect for +triple tildes (`~~~`), or indented 4 or more spaces to achieve a similar effect for a larger body of code. ~~~ @@ -773,17 +774,33 @@ do*this*and*do*that*and*another thing ### Footnotes -Footnotes add a link to a note rendered at the end of a Markdown file: +Footnotes add a link to a note that will be rendered at the end of a Markdown file. + +To make a footnote, you need both a reference tag and a separate line (anywhere in the file) with the note content. + +Regardless of the tag names, the relative order of the reference tags determines the rendered numbering. ```markdown -You can add footnotes to your text as follows.[^1] +A footnote reference tag looks like this:[^1] + +[^1]: This is the contents of a footnote. -[^1]: This is my awesome footnote (later in file). +Reference tags can use letters and other characters.[^footnote-note] + +[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`) +in your footnote tag name until an +[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. ``` -You can add footnotes to your text as follows.[^1] +A footnote reference tag looks like this:[^1] + +[^1]: This is the contents of a footnote. + +Reference tags can use letters and other characters.[^footnote-note] -[^1]: This is my awesome footnote (later in file). +[^footnote-note]: Avoid using lowercase `w` or an underscore (`_`) +in your footnote tag name until an +[upstream bug](https://gitlab.com/gitlab-org/gitlab/issues/24423) is resolved. ### Headers diff --git a/doc/user/packages/conan_repository/img/conan_package_view.png b/doc/user/packages/conan_repository/img/conan_package_view.png Binary files differindex 79a188d7856..742fb4195da 100644 --- a/doc/user/packages/conan_repository/img/conan_package_view.png +++ b/doc/user/packages/conan_repository/img/conan_package_view.png diff --git a/doc/user/packages/conan_repository/index.md b/doc/user/packages/conan_repository/index.md index 2366d1ccc0d..bcf2fea24e3 100644 --- a/doc/user/packages/conan_repository/index.md +++ b/doc/user/packages/conan_repository/index.md @@ -22,46 +22,134 @@ by default. To enable it for existing projects, or if you want to disable it: You should then be able to see the **Packages** section on the left sidebar. -Before proceeding to authenticating with the GitLab Conan Repository, you should -get familiar with the package naming convention. +## Getting started -## Authenticating to the GitLab Conan Repository +This section will cover installing Conan and building a package for your C/C++ project. This is a quickstart if you are new +to Conan. If you already are using Conan and understand how to build your own packages, move on to the [next section](#adding-the-gitlab-package-registry-as-a-conan-remote). -You will need to generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. +### Installing Conan + +Follow the instructions at [conan.io](https://conan.io/downloads.html) to download the Conan package manager to your local development environment. + +Once installation is complete, verify you can use Conan in your terminal by running + +```sh +conan --version +``` + +You should see the Conan version printed in the output: + +``` +Conan version 1.20.5 +``` + +### Installing CMake -Now you can run conan commands using your token. +When developing with C++ and Conan, you have a wide range of options for compilers. This tutorial walks through using the cmake +compiler. In your terminal, run the command -`CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload Hello/0.2@user/channel --remote=gitlab` -`CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search Hello* --all --remote=gitlab` +```sh +cmake --version +``` + +You should see the cmake version printed in the output. If you see something else, you may have to install cmake. + +On a Mac, you can use [homebrew](https://brew.sh/) to install cmake by running `brew install cmake`. Otherwise, follow +instructions at [cmake.org](https://cmake.org/install/) for your operating system. + +### Creating a project + +Understanding what is needed to create a valid and compilable C++ project is out of the scope of this guide, but if you are new to C++ and want to try out the GitLab +package registry, Conan.io has a great [hello world starter project](https://github.com/conan-io/hello) that you can clone to get started. -Alternatively, you can set the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` in your local conan config to be used when connecting to the `gitlab` remote. The examples here show the username and password inline. +Clone the repo and it can be used for the rest of the tutorial if you don't have your own C++ project. -Next, you'll need to set your Conan remote to point to the GitLab Package Registry. +### Building a package -## Setting the Conan remote to the GitLab Package Registry +In your terminal, navigate to the root folder of your project. Generate a new recipe by running `conan new` and providing it with a +package name and version: -After you authenticate to the [GitLab Conan Repository](#authenticating-to-the-gitlab-conan-repository), -you can set the Conan remote: +```sh +conan new Hello/0.1 -t +``` + +Next, you will create a package for that recipe by running `conan create` providing the Conan user and channel: + +```sh +conan create . my-org+my-group+my-project/beta +``` + +NOTE: **Note** +Current [naming restrictions](#package-recipe-naming-convention) require you to name the `user` value as the `+` separated path of your project on GitLab. + +The example above would create a package belonging to this project: `https://gitlab.com/my-org/my-group/my-project` with a channel of `beta`. + +These two example commands will generate a final package with the recipe `Hello/0.1@my-org+my-group+my-project/beta`. + +For more advanced details on creating and managing your packages, refer to the [Conan docs](https://docs.conan.io/en/latest/creating_packages.html). + +You are now ready to upload your package to the GitLab registry. To get started, first you will need to set GitLab as a remote, then you will need to add a Conan user for that remote to authenticate your requests. + +## Adding the GitLab Package Registry as a Conan remote + +Add a new remote to your Conan configuration: ```sh conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan ``` -Once the remote is set, you can use the remote when running Conan commands: +Once the remote is set, you can use the remote when running Conan commands by adding `--remote=gitlab` to the end of your commands. + +For example: ```sh conan search Hello* --all --remote=gitlab ``` -## Supported CLI commands +## Authenticating to the GitLab Conan Repository -The GitLab Conan repository supports the following Conan CLI commands: +You will need to generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. -- `conan upload`: Upload your recipe and package files to the GitLab Package Registry. -- `conan install`: Install a conan package from the GitLab Package Registry, this includes using the `conan.txt` file. -- `conan search`: Search the GitLab Package Registry for public packages, and private packages you have permission to view. -- `conan info`: View the info on a given package from the GitLab Package Registry. -- `conan remove`: Delete the package from the GitLab Package Registry. +### Adding a Conan user to the GitLab remote + +Once you have a personal access token and have [set your Conan remote](#adding-the-gitlab-package-registry-as-a-conan-remote), you can associate the token with the remote so you do not have to explicitly add them to each Conan command you run: + +```sh +conan user <gitlab-username> -r gitlab -p <personal_access_token> +``` + +Note: **Note** +If you named your remote something other than `gitlab`, your remote name should be used in this command instead of `gitlab`. + +From now on, when you run commands using `--remote=gitlab`, your username and password will automatically be included in the requests. + +Note: **Note** +The personal access token is not stored locally at any moment. Conan uses JWT, so when you run this command, Conan will request an expirable token from GitLab using your token. The JWT does expire on a regular basis, so you will need to re-enter your personal access token when that happens. + +Alternatively, you could explicitly include your credentials in any given command. +For example: + +```sh +CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload Hello/0.1@my-group+my-project/beta --all --remote=gitlab +``` + +### Setting a default remote to your project (optional) + +If you'd like Conan to always use GitLab as the registry for your package, you can tell Conan to always reference the GitLab remote for a given package recipe: + +```sh +conan remote add_ref Hello/0.1@my-group+my-project/beta gitlab +``` + +NOTE: **Note** +The package recipe does include the version, so setting the default remote for `Hello/0.1@user/channel` will not work for `Hello/0.2@user/channel`. +This functionality is best suited for when you want to consume or install packages from the GitLab registry without having to specify a remote. + +The rest of the example commands in this documentation assume that you have added a Conan user with your credentials to the `gitlab` remote and will not include the explicit credentials or remote option, but be aware that any of the commands could be run without having added a user or default remote: + +```sh +`CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> <conan command> --remote=gitlab +``` ## Uploading a package @@ -72,14 +160,14 @@ Ensure you have a project created on GitLab and that the personal access token y You can upload your package to the GitLab Package Registry using the `conan upload` command: ```sh -CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload Hello/0.1@my-group+my-project/beta --all --remote=gitlab +conan upload Hello/0.1@my-group+my-project/beta --all ``` ### Package recipe naming convention -Standard Conan recipe convention looks like `package_name/version@username/channel`. +Standard Conan recipe convention looks like `package_name/version@user/channel`. -**Recipe usernames must be the `+` separated project path**. The package +**The recipe user must be the `+` separated project path**. The package name may be anything, but it is preferred that the project name be used unless it is not possible due to a naming collision. For example: @@ -95,7 +183,36 @@ A future iteration will extend support to [project and group level](https://gitl ## Installing a package -Add the conan package to the `[requires]` section of your `conan.txt` file and they will be installed when you run `conan install` within your project. +Conan packages are commonly installed as dependencies using the `conanfile.txt` file. + +In your project where you would like to install the Conan package as a dependency, open `conanfile.txt` or create +an empty file named `conanfile.txt` in the root of your project. + +Add the Conan recipe to the `[requires]` section of the file: + +```ini + [requires] + Hello/0.1@my-group+my-project/beta + + [generators] + cmake +``` + +Next, from the root of your project, create a build directory and navigate to it: + +```sh +mkdir build && cd build +``` + +Now you can install the dependencies listed in `conanfile.txt`: + +```sh +conan install .. +``` + +NOTE: **Note:** +If you are trying to install the package you just created in this tutorial, not much will happen since that package +already exists on your local machine. ## Removing a package @@ -104,9 +221,12 @@ There are two ways to remove a Conan package from the GitLab Package Registry. - **Using the Conan client in the command line:** ```sh - CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan remove Hello/0.2@user/channel -r gitlab + conan remove Hello/0.2@user/channel --remote=gitlab ``` + You need to explicitly include the remote in this command, otherwise the package will only be removed from your + local system cache. + NOTE: **Note:** This command will remove all recipe and binary package files from the Package Registry. @@ -119,9 +239,9 @@ The `conan search` command can be run searching by full or partial package name, To search using a partial name, use the wildcard symbol `*`, which should be placed at the end of your search (e.g., `my-packa*`): ```sh -CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search Hello --all --remote=gitlab -CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search He* --all --remote=gitlab -CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan search Hello/1.0.0@my-group+my-project/stable --all --remote=gitlab +conan search Hello --all --remote=gitlab +conan search He* --all --remote=gitlab +conan search Hello/0.1@my-group+my-project/beta --all --remote=gitlab ``` The scope of your search will include all projects you have permission to access, this includes your private projects as well as all public projects. @@ -131,5 +251,37 @@ The scope of your search will include all projects you have permission to access The `conan info` command will return info about a given package: ```sh -CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan info Hello/1.0.0@my-group+my-project/stable -r gitlab +conan info Hello/0.1@my-group+my-project/beta ``` + +## List of supported CLI commands + +The GitLab Conan repository supports the following Conan CLI commands: + +- `conan upload`: Upload your recipe and package files to the GitLab Package Registry. +- `conan install`: Install a conan package from the GitLab Package Registry, this includes using the `conanfile.txt` file. +- `conan search`: Search the GitLab Package Registry for public packages, and private packages you have permission to view. +- `conan info`: View the info on a given package from the GitLab Package Registry. +- `conan remove`: Delete the package from the GitLab Package Registry. + +## Using GitLab CI with Conan packages + +To work with Conan commands within [GitLab CI](./../../../ci/README.md), you can use +`CI_JOB_TOKEN` in place of the personal access token in your commands. + +It is easiest to provide the `CONAN_LOGIN_USERNAME` and `CONAN_PASSWORD` with each +Conan command in your `.gitlab-ci.yml` file: + +```yml +image: conanio/gcc7 + +create_package: + stage: deploy + script: + - conan remote add gitlab https://gitlab.example.com/api/v4/packages/conan + - conan create . my-group+my-project/beta + - CONAN_LOGIN_USERNAME=ci_user CONAN_PASSWORD=${CI_JOB_TOKEN} conan upload Hello/0.1@root+ci-conan/beta1 --all --remote=gitlab +``` + +You can find additional Conan images to use as the base of your CI file +in the [Conan docs](https://docs.conan.io/en/latest/howtos/run_conan_in_docker.html#available-docker-images). diff --git a/doc/user/packages/container_registry/index.md b/doc/user/packages/container_registry/index.md index 9c1a9d5a41a..877379705de 100644 --- a/doc/user/packages/container_registry/index.md +++ b/doc/user/packages/container_registry/index.md @@ -20,6 +20,9 @@ You can read more about Docker Registry at <https://docs.docker.com/registry/int ## Enable the Container Registry for your project +CAUTION: **Warning:** +The Container Registry follows the visibility settings of the project. If the project is public, so is the Container Registry. + If you cannot find the **Packages > Container Registry** entry under your project's sidebar, it is not enabled in your GitLab instance. Ask your administrator to enable GitLab Container Registry following the diff --git a/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png b/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png Binary files differindex 035aff0b6c4..0b94efdd83e 100644 --- a/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png +++ b/doc/user/packages/dependency_proxy/img/group_dependency_proxy.png diff --git a/doc/user/packages/dependency_proxy/index.md b/doc/user/packages/dependency_proxy/index.md index 60f4dbc0abb..05934212a12 100644 --- a/doc/user/packages/dependency_proxy/index.md +++ b/doc/user/packages/dependency_proxy/index.md @@ -12,7 +12,7 @@ receiving a request and returning the upstream image from a registry, acting as a pull-through cache. The dependency proxy is available in the group level. To access it, navigate to -a group's **Overview > Dependency Proxy**. +a group's **Packages > Dependency Proxy**.  @@ -33,7 +33,7 @@ The following dependency proxies are supported. With the Docker dependency proxy, you can use GitLab as a source for a Docker image. To get a Docker image into the dependency proxy: -1. Find the proxy URL on your group's page under **Overview > Dependency Proxy**, +1. Find the proxy URL on your group's page under **Packages > Dependency Proxy**, for example `gitlab.com/groupname/dependency_proxy/containers`. 1. Trigger GitLab to pull the Docker image you want (e.g., `alpine:latest` or `linuxserver/nextcloud:latest`) and store it in the proxy storage by using diff --git a/doc/user/packages/index.md b/doc/user/packages/index.md index ecaad960340..c58effac59d 100644 --- a/doc/user/packages/index.md +++ b/doc/user/packages/index.md @@ -10,15 +10,21 @@ The Packages feature allows GitLab to act as a repository for the following: | ------------------- | ----------- | --------------------------- | | [Container Registry](container_registry/index.md) | The GitLab Container Registry enables every project in GitLab to have its own space to store [Docker](https://www.docker.com/) images. | 8.8+ | | [Dependency Proxy](dependency_proxy/index.md) **(PREMIUM)** | The GitLab Dependency Proxy sets up a local proxy for frequently used upstream images/packages. | 11.11+ | -| [Conan Repository](conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.4+ | +| [Conan Repository](conan_repository/index.md) **(PREMIUM)** | The GitLab Conan Repository enables every project in GitLab to have its own space to store [Conan](https://conan.io/) packages. | 12.6+ | | [Maven Repository](maven_repository/index.md) **(PREMIUM)** | The GitLab Maven Repository enables every project in GitLab to have its own space to store [Maven](https://maven.apache.org/) packages. | 11.3+ | | [NPM Registry](npm_registry/index.md) **(PREMIUM)** | The GitLab NPM Registry enables every project in GitLab to have its own space to store [NPM](https://www.npmjs.com/) packages. | 11.7+ | -| [NuGet Repository](https://gitlab.com/gitlab-org/gitlab/issues/20050) **(PREMIUM)** | *COMING SOON* The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.7 (planned) | +| [NuGet Repository](nuget_repository/index.md) **(PREMIUM)** | *PLANNED* The GitLab NuGet Repository will enable every project in GitLab to have its own space to store [NuGet](https://www.nuget.org/) packages. | 12.8+ | TIP: **Tip:** Don't you see your package management system supported yet? Consider contributing to GitLab. This [development documentation](../../development/packages.md) will -guide you through the process. Or check out how other members of the commmunity +guide you through the process. Or check out how other members of the community are adding support for [PHP](https://gitlab.com/gitlab-org/gitlab/merge_requests/17417) or [Terraform](https://gitlab.com/gitlab-org/gitlab/merge_requests/18834). NOTE: **Note** We are especially interested in adding support for [PyPi](https://gitlab.com/gitlab-org/gitlab/issues/10483), [RubyGems](https://gitlab.com/gitlab-org/gitlab/issues/803), [Debian](https://gitlab.com/gitlab-org/gitlab/issues/5835), and [RPM](https://gitlab.com/gitlab-org/gitlab/issues/5932). + +## Package workflows + +Learning how to use the GitLab Package Registry will help you build your own custom package workflow. + +[Use a project as a package registry](./workflows/project_registry.md) to publish all of your packages to one project. diff --git a/doc/user/packages/npm_registry/index.md b/doc/user/packages/npm_registry/index.md index 7d5db5a60ef..5fdbbcedfc9 100644 --- a/doc/user/packages/npm_registry/index.md +++ b/doc/user/packages/npm_registry/index.md @@ -73,20 +73,20 @@ If you have 2FA enabled, you need to use a [personal access token](../../profile ### Authenticating with an OAuth token To authenticate with an [OAuth token](../../../api/oauth2.md#resource-owner-password-credentials-flow) -or [personal access token](../../profile/personal_access_tokens.md), add a corresponding section to your `.npmrc` file: +or [personal access token](../../profile/personal_access_tokens.md), set your NPM configuration: -```ini -; Set URL for your scoped packages. -; For example package with name `@foo/bar` will use this URL for download -@foo:registry=https://gitlab.com/api/v4/packages/npm/ +```bash +# Set URL for your scoped packages. +# For example package with name `@foo/bar` will use this URL for download +npm config set @foo:registry https://gitlab.com/api/v4/packages/npm/ -; Add the token for the scoped packages URL. This will allow you to download -; `@foo/` packages from private projects. -//gitlab.com/api/v4/packages/npm/:_authToken=<your_token> +# Add the token for the scoped packages URL. This will allow you to download +# `@foo/` packages from private projects. +npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "<your_token>" -; Add token for uploading to the registry. Replace <your_project_id> -; with the project you want your package to be uploaded to. -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=<your_token> +# Add token for uploading to the registry. Replace <your_project_id> +# with the project you want your package to be uploaded to. +npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "<your_token>" ``` Replace `<your_project_id>` with your project ID which can be found on the home page @@ -103,13 +103,11 @@ If you encounter an error message with [Yarn](https://yarnpkg.com/en/), see the ### Using variables to avoid hard-coding auth token values -To avoid hard-coding the `authToken` value, you may use a variables in its place. -In your `.npmrc` file, you would add: +To avoid hard-coding the `authToken` value, you may use a variables in its place: -```ini -@foo:registry=https://gitlab.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken=${NPM_TOKEN} -//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken=${NPM_TOKEN} +```bash +npm config set '//gitlab.com/api/v4/projects/<your_project_id>/packages/npm/:_authToken' "${NPM_TOKEN}" +npm config set '//gitlab.com/api/v4/packages/npm/:_authToken' "${NPM_TOKEN}" ``` Then, you could run `npm publish` either locally or via GitLab CI/CD: @@ -134,8 +132,8 @@ Add a corresponding section to your `.npmrc` file: ```ini @foo:registry=https://gitlab.com/api/v4/packages/npm/ -//gitlab.com/api/v4/packages/npm/:_authToken=${env.CI_JOB_TOKEN} -//gitlab.com/api/v4/projects/{env.CI_PROJECT_ID>/packages/npm/:_authToken=${env.CI_JOB_TOKEN} +//gitlab.com/api/v4/packages/npm/:_authToken=${CI_JOB_TOKEN} +//gitlab.com/api/v4/projects/${CI_PROJECT_ID}/packages/npm/:_authToken=${CI_JOB_TOKEN} ``` ## Uploading packages @@ -195,7 +193,7 @@ info Visit https://yarnpkg.com/en/docs/cli/install for documentation about this ``` In this case, try adding this to your `.npmrc` file (and replace `<your_oauth_token>` -with your with your OAuth or personal access token): +with your OAuth or personal access token): ```text //gitlab.com/api/v4/projects/:_authToken=<your_oauth_token> @@ -227,6 +225,14 @@ And the `.npmrc` file should look like: @foo:registry=https://gitlab.com/api/v4/packages/npm/ ``` +### `npm install` returns `Error: Failed to replace env in config: ${NPM_TOKEN}` + +You do not need a token to run `npm install` unless your project is private (the token is only required to publish). If the `.npmrc` file was checked in with a reference to `$NPM_TOKEN`, you can remove it. If you prefer to leave the reference in, you'll need to set a value prior to running `npm install` or set the value using [GitLab environment variables](./../../../ci/variables/README.md): + +```bash +NPM_TOKEN=<your_token> npm install +``` + ## NPM dependencies metadata > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11867) in GitLab Premium 12.6. @@ -242,3 +248,27 @@ Starting from GitLab 12.6, new packages published to the GitLab NPM Registry exp - bundleDependencies - peerDependencies - deprecated + +## NPM distribution tags + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9425) in GitLab Premium 12.7. + +Dist Tags for newly published packages are supported, and they follow NPM's convention where they are optional, and each tag can only be assigned to 1 package at +You can add [distribution tags](https://docs.npmjs.com/cli/dist-tag) for newly +published packages. They follow NPM's convention where they are optional, and +each tag can only be assigned to one package at a time. The latest tag is added +by default when a package is published without a tag. The same goes to installing +a package without specifying the tag or version. + +Examples of the supported `dist-tag` commands and using tags in general: + +```sh +npm publish @scope/package --tag # Publish new package with new tag +npm dist-tag add @scope/package@version my-tag # Add a tag to an existing package +npm dist-tag ls @scope/package # List all tags under the package +npm dist-tag rm @scope/package@version my-tag # Delete a tag from the package +npm install @scope/package@my-tag # Install a specific tag +``` + +CAUTION: **Warning:** +Due to a bug in NPM 6.9.0, deleting dist tags fails. Make sure your NPM version is greater than 6.9.1. diff --git a/doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png b/doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png Binary files differnew file mode 100644 index 00000000000..94b037ced42 --- /dev/null +++ b/doc/user/packages/nuget_repository/img/visual_studio_adding_nuget_source.png diff --git a/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png Binary files differnew file mode 100644 index 00000000000..d2f4791a25a --- /dev/null +++ b/doc/user/packages/nuget_repository/img/visual_studio_nuget_source_added.png diff --git a/doc/user/packages/nuget_repository/index.md b/doc/user/packages/nuget_repository/index.md new file mode 100644 index 00000000000..212641222f8 --- /dev/null +++ b/doc/user/packages/nuget_repository/index.md @@ -0,0 +1,104 @@ +# GitLab NuGet Repository **(PREMIUM)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/20050) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.8. + +CAUTION: **Work in progress** +This feature is in development, sections on uploading and installing packages will be coming soon, please follow along and help us make sure we're building the right solution for you in the [NuGet issue](https://gitlab.com/gitlab-org/gitlab/issues/20050). + +With the GitLab NuGet Repository, every project can have its own space to store NuGet packages. + +The GitLab NuGet Repository works with either [nuget CLI](https://www.nuget.org/) or [Visual Studio](https://visualstudio.microsoft.com/vs/). + +## Setting up your development environment + +You will need [nuget CLI](https://www.nuget.org/) 5.2 or above. Previous versions have not been tested against the GitLab NuGet Repository and might not work. You can install it by visiting the [downloads page](https://www.nuget.org/downloads). + +If you have [Visual Studio](https://visualstudio.microsoft.com/vs/), [nuget CLI](https://www.nuget.org/) is probably already installed. + +You can confirm that [nuget CLI](https://www.nuget.org/) is properly installed with: + +```sh +nuget help +``` + +You should see something similar to: + +``` +NuGet Version: 5.2.0.6090 +usage: NuGet <command> [args] [options] +Type 'NuGet help <command>' for help on a specific command. + +Available commands: + +[output truncated] +``` + +## Enabling the NuGet Repository + +NOTE: **Note:** +This option is available only if your GitLab administrator has +[enabled support for the NuGet Repository](../../../administration/packages/index.md).**(PREMIUM ONLY)** + +After the NuGet Repository is enabled, it will be available for all new projects +by default. To enable it for existing projects, or if you want to disable it: + +1. Navigate to your project's **Settings > General > Permissions**. +1. Find the Packages feature and enable or disable it. +1. Click on **Save changes** for the changes to take effect. + +You should then be able to see the **Packages** section on the left sidebar. + +## Adding the GitLab NuGet Repository as a source to nuget + +You will need the following: + +- Your GitLab username. +- A personal access token. You can generate a [personal access token](../../../user/profile/personal_access_tokens.md) with the scope set to `api` for repository authentication. +- A suitable name for your source. +- Your project ID which can be found on the home page of your project. + +You can now add a new source to nuget either using [nuget CLI](https://www.nuget.org/) or [Visual Studio](https://visualstudio.microsoft.com/vs/). + +### Using nuget CLI + +To add the GitLab NuGet Repository as a source with `nuget`: + +```sh +nuget source Add -Name <source_name> -Source "https://example.gitlab.com/api/v4/projects/<your_project_id>/packages/nuget/index.json" -UserName <gitlab_username> -Password <gitlab_token> +``` + +Replace: + +- `<source_name>` with your desired source name. +- `<your_project_id>` with your project ID. +- `<gitlab-username>` with your GitLab username. +- `<gitlab-token>` with your personal access token. +- `example.gitlab.com` with the URL of the GitLab instance you're using. + +For example: + +```sh +nuget source Add -Name "GitLab" -Source "https//gitlab.example/api/v4/projects/10/packages/nuget/index.json" -UserName carol -Password 12345678asdf +``` + +### Using Visual Studio + +1. Open [Visual Studio](https://visualstudio.microsoft.com/vs/). +1. Open the **FILE > OPTIONS** (Windows) or **Visual Studio > Preferences** (Mac OS). +1. In the **NuGet** section, open **Sources**. You will see a list of all your NuGet sources. +1. Click **Add**. +1. Fill the fields with: + - **Name**: Desired name for the source + - **Location**: `https://gitlab.com/api/v4/projects/<your_project_id>/packages/nuget/index.json` + - Replace `<your_project_id>` with your project ID. + - If you have a self-hosted GitLab installation, replace `gitlab.com` with your domain name. + - **Username**: Your GitLab username + - **Password**: Your personal access token + +  + +1. Click **Save**. + +  + +In case of any warning, please make sure that the **Location**, **Username** and **Password** are correct. diff --git a/doc/user/packages/workflows/project_registry.md b/doc/user/packages/workflows/project_registry.md new file mode 100644 index 00000000000..d8c1c7c2861 --- /dev/null +++ b/doc/user/packages/workflows/project_registry.md @@ -0,0 +1,85 @@ +# Project as a package registry + +Using the features of the package registry, it is possible to use one project to store all of your packages. + +This guide mirrors the creation of [this package registry](https://gitlab.com/sabrams/my-package-registry). + +For the video version, see [Single Project Package Registry Demo](https://youtu.be/ui2nNBwN35c). + +## How does this work? + +You might be wondering "how is it possible to upload two packages from different codebases to the same project on GitLab?". + +It is easy to forget that a package on GitLab belongs to a project, but a project does not have to be a code repository. +The code used to build your packages can be stored anywhere - maybe it is another project on GitLab, or maybe a completely +different system altogether. All that matters is that when you configure your remote repositories for those packages, you +point them at the same project on GitLab. + +## Why would I do this? + +There are a few reasons you might want to publish all your packages to one project on GitLab: + +1. You want to publish your packages on GitLab, but to a project that is different from where your code is stored. +1. You would like to group packages together in ways that make sense for your usage (all NPM packages in one project, + all packages being used by a specific department in one project, all private packages in one project, etc.) +1. You want to use one remote for all of your packages when installing them into other projects. +1. You would like to migrate your packages to a single place on GitLab from a third-party package registry and do not + want to worry about setting up separate projects for each package. +1. You want to have your CI pipelines build all of your packages to one project so the individual responsible for +validating packages can manage them all in one place. + +## Example walkthrough + +There is no functionality specific to this feature. All we are doing is taking advantage of functionality available in each +of the package management systems to publish packages of different types to the same place. + +Let's take a look at how you might create a public place to hold all of your public packages. + +### Create a project + +First, create a new project on GitLab. It does not have to have any code or content. Make note of the project ID +displayed on the project overview page, as you will need this later. + +### Create an access token + +All of the package repositories available on the GitLab package registry are accessible using [GitLab personal access +tokens](../../profile/personal_access_tokens.md). + +While using CI, you can alternatively use CI job tokens (`CI_JOB_TOKEN`) to authenticate. + +### Configure your local project for the GitLab registry and upload + +There are many ways to use this feature. You can upload all types of packages to the same project, +split things up based on package type, or package visibility level. + +The purpose of this tutorial is to demonstrate the root idea that one project can hold many unrelated +packages, and to allow you to discover the best way to use this functionality yourself. + +#### NPM + +If you are using NPM, this involves creating an `.npmrc` file and adding the appropriate URL for uploading packages +to your project using your project ID, then adding a section to your `package.json` file with a similar URL. + +Follow +the instructions in the [GitLab NPM Registry documentation](../npm_registry/index.md#authenticating-to-the-gitlab-npm-registry). Once +you do this, you will be able to push your NPM package to your project using `npm publish`, as described in the +[uploading packages](../npm_registry/index.md#uploading-packages) section of the docs. + +#### Maven + +If you are using Maven, this involves updating your `pom.xml` file with distribution sections, including the +appropriate URL for your project, as described in the [GitLab Maven Repository documentation](../maven_repository/index.md#project-level-maven-endpoint). +Then, you need to add a `settings.xml` file and [include your access token](../maven_repository/index.md#authenticating-with-a-personal-access-token). +Now you can [deploy Maven packages](../maven_repository/index.md#uploading-packages) to your project. + +#### Conan + +For Conan, first you need to add GitLab as a Conan registry remote. Follow the instructions in the [GitLab Conan Repository docs](../conan_repository/index.md#adding-the-gitlab-package-registry-as-a-conan-remote) +to do so. Then, create your package using the plus-separated (`+`) project path as your Conan user. For example, +if your project is located at `https://gitlab.com/foo/bar/my-proj`, then you can [create your Conan package](../conan_repository/index.md) +using `conan create . foo+bar+my-proj/channel`, where `channel` is your package channel (`stable`, `beta`, etc.). Once your package +is created, you are ready to [upload your package](../conan_repository/index.md#uploading-a-package) depending on your final package recipe. For example: + +```sh +CONAN_LOGIN_USERNAME=<gitlab-username> CONAN_PASSWORD=<personal_access_token> conan upload MyPackage/1.0.0@foo+bar+my-proj/channel --all --remote=gitlab +``` diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 9cbf4fd6192..985c1babdb5 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -66,6 +66,7 @@ The following table depicts the various user permission levels in a project. | View confidential issues | (*2*) | ✓ | ✓ | ✓ | ✓ | | Assign issues | | ✓ | ✓ | ✓ | ✓ | | Label issues | | ✓ | ✓ | ✓ | ✓ | +| Set issue weight | | ✓ | ✓ | ✓ | ✓ | | Lock issue threads | | ✓ | ✓ | ✓ | ✓ | | Manage issue tracker | | ✓ | ✓ | ✓ | ✓ | | Manage related issues **(STARTER)** | | ✓ | ✓ | ✓ | ✓ | @@ -274,14 +275,14 @@ External users still count towards a license seat. An administrator can flag a user as external by either of the following methods: - Either [through the API](../api/users.md#user-modification). -- Or by navigating to the **Admin area > Overview > Users** to create a new user +- Or by navigating to the **Admin Area > Overview > Users** to create a new user or edit an existing one. There, you will find the option to flag the user as external. ### Setting new users to external By default, new users are not set as external users. This behavior can be changed -by an administrator under the **Admin Area > Settings > General > Account and limit** page. +by an administrator on the **Admin Area > Settings > General** page, under **Account and limit**. If you change the default behavior of creating new users as external, you will have the option to narrow it down by defining a set of internal users. diff --git a/doc/user/profile/account/create_accounts.md b/doc/user/profile/account/create_accounts.md index c0a887d0779..27aa57e7f99 100644 --- a/doc/user/profile/account/create_accounts.md +++ b/doc/user/profile/account/create_accounts.md @@ -15,7 +15,7 @@ If you have [sign-up enabled](../../admin_area/settings/sign_up_restrictions.md)  -## Create users in admin area +## Create users in Admin Area As an admin user, you can manually create users by: diff --git a/doc/user/profile/account/img/admin_user_button.png b/doc/user/profile/account/img/admin_user_button.png Binary files differindex 6be9c1e266a..506e16bb8ca 100644 --- a/doc/user/profile/account/img/admin_user_button.png +++ b/doc/user/profile/account/img/admin_user_button.png diff --git a/doc/user/profile/account/img/admin_user_form.png b/doc/user/profile/account/img/admin_user_form.png Binary files differindex ede96373c73..aebc31ee3ff 100644 --- a/doc/user/profile/account/img/admin_user_form.png +++ b/doc/user/profile/account/img/admin_user_form.png diff --git a/doc/user/profile/account/img/register_tab.png b/doc/user/profile/account/img/register_tab.png Binary files differindex 73faa3edd1c..4bbb4e62687 100644 --- a/doc/user/profile/account/img/register_tab.png +++ b/doc/user/profile/account/img/register_tab.png diff --git a/doc/user/profile/active_sessions.md b/doc/user/profile/active_sessions.md index f68b11a57ec..11e5ef293e4 100644 --- a/doc/user/profile/active_sessions.md +++ b/doc/user/profile/active_sessions.md @@ -24,6 +24,11 @@ review the sessions, and revoke any you don't recognize. GitLab allows users to have up to 100 active sessions at once. If the number of active sessions exceeds 100, the oldest ones are deleted. +## Revoking a session + +1. Use the previous steps to navigate to **Active Sessions**. +1. Click on **Revoke** besides a session. The current session cannot be revoked, as this would sign you out of GitLab. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/profile/img/active_sessions_list.png b/doc/user/profile/img/active_sessions_list.png Binary files differindex 41173c7eee5..5d94dca69cc 100644 --- a/doc/user/profile/img/active_sessions_list.png +++ b/doc/user/profile/img/active_sessions_list.png diff --git a/doc/user/profile/personal_access_tokens.md b/doc/user/profile/personal_access_tokens.md index 980a7d5968d..09825bd5ff8 100644 --- a/doc/user/profile/personal_access_tokens.md +++ b/doc/user/profile/personal_access_tokens.md @@ -6,15 +6,13 @@ type: concepts, howto > [Introduced][ce-3749] in GitLab 8.8. -Personal access tokens are the preferred way for third party applications and scripts to -authenticate with the [GitLab API][api], if using [OAuth2](../../api/oauth2.md) is not practical. +If you're unable to use [OAuth2](../../api/oauth2.md), you can use a personal access token to authenticate with the [GitLab API][api]. -You can also use personal access tokens to authenticate against Git over HTTP or SSH. They must be used when you have [Two-Factor Authentication (2FA)][2fa] enabled. Authenticate with a token in place of your password. +You can also use personal access tokens with Git to authenticate over HTTP or SSH. Personal access tokens are required when [Two-Factor Authentication (2FA)][2fa] is enabled. In both cases, you can authenticate with a token in place of your password. -To make [authenticated requests to the API][usage], use either the `private_token` parameter or the `Private-Token` header. +Personal access tokens expire on the date you define, at midnight UTC. -The expiration of personal access tokens happens on the date you define, -at midnight UTC. +For examples of how you can use a personal access token to authenticate with the API, see the following section from our [API Docs](../../api/README.md#personal-access-tokens). ## Creating a personal access token diff --git a/doc/user/project/clusters/add_remove_clusters.md b/doc/user/project/clusters/add_remove_clusters.md index 6a0377f118d..a77584c0485 100644 --- a/doc/user/project/clusters/add_remove_clusters.md +++ b/doc/user/project/clusters/add_remove_clusters.md @@ -10,6 +10,74 @@ Every new Google Cloud Platform (GCP) account receives [$300 in credit upon sign and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's Google Kubernetes Engine Integration. All you have to do is [follow this link](https://cloud.google.com/partners/partnercredit/?pcn_code=0014M00001h35gDQAQ#contact-form) and apply for credit. +## Before you begin + +Before [adding a Kubernetes cluster](#add-new-cluster) using GitLab, you need: + +- GitLab itself. Either: + - A GitLab.com [account](https://about.gitlab.com/pricing/#gitlab-com). + - A [self-managed installation](https://about.gitlab.com/pricing/#self-managed) with GitLab version + 12.5 or later. This will ensure the GitLab UI can be used for cluster creation. +- The following GitLab access: + - [Maintainer access to a project](../../permissions.md#project-members-permissions) for a + project-level cluster. + - [Maintainer access to a group](../../permissions.md#group-members-permissions) for a + group-level cluster. + - [Admin Area access](../../admin_area/index.md) for a self-managed instance-level + cluster. **(CORE ONLY)** + +### GKE requirements + +Before creating your first cluster on Google GKE with GitLab's integration, make sure the following +requirements are met: + +- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) + set up with access. +- The Kubernetes Engine API and related service are enabled. It should work immediately but may + take up to 10 minutes after you create a project. For more information see the + ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). + +### EKS requirements + +Before creating your first cluster on Amazon EKS with GitLab's integration, make sure the following +requirements are met: + +- An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. +- You have permissions to manage IAM resources. +- If you want to use an [existing EKS cluster](#existing-eks-cluster): + - An Amazon EKS cluster with worker nodes properly configured. + - `kubectl` [installed and configured](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl) + for access to the EKS cluster. + +#### Additional requirements for self-managed instances **(CORE ONLY)** + +If you are using a self-managed GitLab instance, GitLab must first be configured with a set of +Amazon credentials. These credentials will be used to assume an Amazon IAM role provided by the user +creating the cluster. Create an IAM user and ensure it has permissions to assume the role(s) that +your users will use to create EKS clusters. + +For example, the following policy document allows assuming a role whose name starts with +`gitlab-eks-` in account `123456789012`: + +```json +{ + "Version": "2012-10-17", + "Statement": { + "Effect": "Allow", + "Action": "sts:AssumeRole", + "Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*" + } +} +``` + +Generate an access key for the IAM user, and configure GitLab with the credentials: + +1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section. +1. Check **Enable Amazon EKS integration**. +1. Enter the account ID and access key credentials into the respective + `Account ID`, `Access key ID` and `Secret access key` fields. +1. Click **Save changes**. + ## Access controls When creating a cluster in GitLab, you will be asked if you would like to create either: @@ -116,57 +184,39 @@ New clusters can be added using GitLab for: - Google Kubernetes Engine. - Amazon Elastic Kubernetes Service. -### GKE cluster - -GitLab supports: - -- Creating a new GKE cluster using the GitLab UI. -- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster). - -Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). +### New GKE cluster -NOTE: **Note:** -The [Google authentication integration](../../../integration/google.md) must -be enabled in GitLab at the instance level. If that's not the case, ask your -GitLab administrator to enable it. On GitLab.com, this is enabled. - -#### GKE Requirements +Starting from [GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/25925), all the GKE clusters +provisioned by GitLab are [VPC-native](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips). -Before creating your first cluster on Google Kubernetes Engine with GitLab's -integration, make sure the following requirements are met: - -- A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) - is set up and you have permissions to access it. -- The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the - ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). +#### Important notes -Also note the following: +Note the following: +- The [Google authentication integration](../../../integration/google.md) must be enabled in GitLab + at the instance level. If that's not the case, ask your GitLab administrator to enable it. On + GitLab.com, this is enabled. - Starting from [GitLab 12.1](https://gitlab.com/gitlab-org/gitlab-foss/issues/55902), all GKE clusters created by GitLab are RBAC-enabled. Take a look at the [RBAC section](#rbac-cluster-resources) for more information. - Starting from [GitLab 12.5](https://gitlab.com/gitlab-org/gitlab/merge_requests/18341), the cluster's pod address IP range will be set to /16 instead of the regular /14. /16 is a CIDR notation. - -NOTE: **Note:** -GitLab requires basic authentication enabled and a client certificate issued for the cluster in -order to setup an [initial service account](#access-controls). Starting from [GitLab -11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will -explicitly request that basic authentication and client certificate is enabled. +- GitLab requires basic authentication enabled and a client certificate issued for the cluster to + set up an [initial service account](#access-controls). Starting from [GitLab + 11.10](https://gitlab.com/gitlab-org/gitlab-foss/issues/58208), the cluster creation process will + explicitly request that basic authentication and client certificate is enabled. #### Creating the cluster on GKE -If all of the above requirements are met, you can proceed to create and add a -new Kubernetes cluster to your project: - -1. Navigate to your project's **Operations > Kubernetes** page. - - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. +To create and add a new Kubernetes cluster to your project, group, or instance: +1. Navigate to your: + - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Group's **Kubernetes** page, for a group-level cluster. + - **Admin Area > Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Click **Create with Google Kubernetes Engine**. +1. Under the **Create new cluster** tab, click **Google GKE**. 1. Connect your Google account if you haven't done already by clicking the **Sign in with Google** button. 1. Choose your cluster's settings: @@ -198,64 +248,19 @@ separately after the cluster has been created. This means that Cloud Run (Knative), Istio, and HTTP Load Balancing will be enabled on the cluster at create time and cannot be [installed or uninstalled](../../clusters/applications.md) separately. -### EKS Cluster - -GitLab supports: - -- Creating a new EKS cluster using the GitLab UI - ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5). -- Providing credentials to add an [existing Kubernetes cluster](#add-existing-cluster). - -#### EKS Requirements - -Before creating your first cluster on Amazon EKS with GitLab's integration, -make sure the following requirements are met: - -- An [Amazon Web Services](https://aws.amazon.com/) account is set up and you are able to log in. -- You have permissions to manage IAM resources. - -##### Additional requirements for self-managed instances - -If you are using a self-managed GitLab instance, GitLab must first -be configured with a set of Amazon credentials. These credentials -will be used to assume an Amazon IAM role provided by the user -creating the cluster. Create an IAM user and ensure it has permissions -to assume the role(s) that your users will use to create EKS clusters. - -For example, the following policy document allows assuming a role whose name starts with -`gitlab-eks-` in account `123456789012`: - -```json -{ - "Version": "2012-10-17", - "Statement": { - "Effect": "Allow", - "Action": "sts:AssumeRole", - "Resource": "arn:aws:iam::123456789012:role/gitlab-eks-*" - } -} -``` - -Generate an access key for the IAM user, and configure GitLab with the credentials: - -1. Navigate to **Admin Area > Settings > Integrations** and expand the **Amazon EKS** section. -1. Check **Enable Amazon EKS integration**. -1. Enter the account ID and access key credentials into the respective - `Account ID`, `Access key ID` and `Secret access key` fields. -1. Click **Save changes**. - -#### Creating the cluster on EKS - -If all of the above requirements are met, you can proceed to create and add a -new Kubernetes cluster to your project: +### New EKS cluster -1. Navigate to your project's **Operations > Kubernetes** page. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/22392) in GitLab 12.5. - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. +To create and add a new Kubernetes cluster to your project, group, or instance: +1. Navigate to your: + - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Group's **Kubernetes** page, for a group-level cluster. + - **Admin Area > Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Click **Amazon EKS**. You will be provided with an `Account ID` and `External ID` to use in the next step. +1. Under the **Create new cluster** tab, click **Amazon EKS**. You will be provided with an + `Account ID` and `External ID` to use in the next step. 1. In the [IAM Management Console](https://console.aws.amazon.com/iam/home), create an IAM role: 1. From the left panel, select **Roles**. 1. Click **Create role**. @@ -331,8 +336,9 @@ new Kubernetes cluster to your project: - **Kubernetes cluster name** - The name you wish to give the cluster. - **Environment scope** - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. - **Kubernetes version** - The Kubernetes version to use. Currently the only version supported is 1.14. - - **Role name** - Select the [IAM role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) - to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. + - **Role name** - Select the [IAM role](https://docs.aws.amazon.com/eks/latest/userguide/service_IAM_role.html) + to allow Amazon EKS and the Kubernetes control plane to manage AWS resources on your behalf. This IAM role is separate + to the IAM role created above, you will need to create it if it does not yet exist. - **Region** - The [region](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html) in which the cluster will be created. - **Key pair name** - Select the [key pair](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-key-pairs.html) @@ -356,24 +362,23 @@ to install some [pre-defined applications](index.md#installing-applications). If you have either of the following types of clusters already, you can add them to a project: -- [Google Kubernetes Engine cluster](#add-existing-gke-cluster). -- [Amazon Elastic Kubernetes Service](#add-existing-eks-cluster). +- [Google Kubernetes Engine cluster](#existing-gke-cluster). +- [Amazon Elastic Kubernetes Service](#existing-eks-cluster). NOTE: **Note:** Kubernetes integration is not supported for arm64 clusters. See the issue [Helm Tiller fails to install on arm64 cluster](https://gitlab.com/gitlab-org/gitlab-foss/issues/64044) for details. -### Add existing GKE cluster - -To add an existing Kubernetes cluster to your project: - -1. Navigate to your project's **Operations > Kubernetes** page. +### Existing GKE cluster - NOTE: **Note:** - You need Maintainer [permissions](../../permissions.md) and above to access the Kubernetes page. +To add an existing GKE cluster to your project, group, or instance: +1. Navigate to your: + - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Group's **Kubernetes** page, for a group-level cluster. + - **Admin Area > Kubernetes** page, for an instance-level cluster. 1. Click **Add Kubernetes cluster**. -1. Click **Add an existing Kubernetes cluster** and fill in the details: +1. Click the **Add existing cluster** tab and fill in the details: - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - **Environment scope** (required) - The [associated environment](index.md#setting-the-environment-scope-premium) to this cluster. @@ -389,7 +394,7 @@ To add an existing Kubernetes cluster to your project: ``` - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should named similar to + - List the secrets with `kubectl get secrets`, and one should be named similar to `default-token-xxxxx`. Copy that token name for use below. - Get the certificate by running this command: @@ -508,136 +513,110 @@ To add an existing Kubernetes cluster to your project: After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](index.md#installing-applications). -### Add existing EKS cluster - -In this section, we will show how to integrate an [Amazon EKS](https://aws.amazon.com/eks/) cluster with GitLab and begin -deploying applications. - -#### Requirements - -To integrate with with EKS, you will need: - -- An account on GitLab, like [GitLab.com](https://gitlab.com). -- An Amazon EKS cluster (with worker nodes properly configured). -- `kubectl` [installed and configured for access to the EKS cluster](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html#get-started-kubectl). - -If you don't have an Amazon EKS cluster, one can be created by following the -[EKS getting started guide](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html). - -#### Configuring and connecting the EKS cluster - -From the left side bar, hover over **Operations > Kubernetes > Add Kubernetes cluster**, -then click **Add an existing Kubernetes cluster**. - -A few details from the EKS cluster will be required to connect it to GitLab: - -1. **Retrieve the certificate**: A valid Kubernetes certificate is needed to - authenticate to the EKS cluster. We will use the certificate created by default. - Open a shell and use `kubectl` to retrieve it: - - - List the secrets with `kubectl get secrets`, and one should named similar to - `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate with: - - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` - -1. **Create admin token**: A `cluster-admin` token is required to install and - manage Helm Tiller. GitLab establishes mutual SSL auth with Helm Tiller - and creates limited service accounts for each application. To create the - token we will create an admin service account as follows: - - 1. Create a file called `eks-admin-service-account.yaml` with contents: - - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the service account to your cluster: - - ```bash - kubectl apply -f eks-admin-service-account.yaml - ``` - - Output: - - ```bash - serviceaccount "eks-admin" created - ``` - - 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: eks-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: eks-admin - namespace: kube-system - ``` - - 1. Apply the cluster role binding to your cluster: - - ```bash - kubectl apply -f eks-admin-cluster-role-binding.yaml - ``` - - Output: - - ```bash - clusterrolebinding "eks-admin" created - ``` - - 1. Retrieve the token for the `eks-admin` service account: - - ```bash - kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') - ``` - - Copy the `<authentication_token>` value from the output: - - ```yaml - Name: eks-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=eks-admin +### Existing EKS cluster + +To add an existing EKS cluster to your project, group, or instance: + +1. Perform the following steps on the EKS cluster: + 1. Retrieve the certificate. A valid Kubernetes certificate is needed to authenticate to the + EKS cluster. We will use the certificate created by default. + Open a shell and use `kubectl` to retrieve it: + + 1. List the secrets with `kubectl get secrets`, and one should named similar to + `default-token-xxxxx`. Copy that token name for use below. + 1. Get the certificate with: + + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` + + 1. Create admin token. A `cluster-admin` token is required to install and manage Helm Tiller. + GitLab establishes mutual SSL authentication with Helm Tiller and creates limited service + accounts for each application. To create the token we will create an admin service account as + follows: + + 1. Create a file called `eks-admin-service-account.yaml` with contents: + + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: eks-admin + namespace: kube-system + ``` + + 1. Apply the service account to your cluster: + + ```shell + $ kubectl apply -f eks-admin-service-account.yaml + serviceaccount "eks-admin" created + ``` + + 1. Create a file called `eks-admin-cluster-role-binding.yaml` with contents: + + ```yaml + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: eks-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: eks-admin + namespace: kube-system + ``` + + 1. Apply the cluster role binding to your cluster: + + ```shell + $ kubectl apply -f eks-admin-cluster-role-binding.yaml + clusterrolebinding "eks-admin" created + ``` + + 1. Retrieve the token for the `eks-admin` service account: + + ```bash + kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep eks-admin | awk '{print $1}') + ``` + + Copy the `<authentication_token>` value from the output: + + ```yaml + Name: eks-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=eks-admin kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - Type: kubernetes.io/service-account-token - - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - -1. The API server endpoint is also required, so GitLab can connect to the cluster. - This is displayed on the AWS EKS console, when viewing the EKS cluster details. - -You now have all the information needed to connect the EKS cluster: - -- Kubernetes cluster name: Provide a name for the cluster to identify it within GitLab. -- Environment scope: Leave this as `*` for now, since we are only connecting a single cluster. -- API URL: Paste in the API server endpoint retrieved above. -- CA Certificate: Paste the certificate data from the earlier step, as-is. -- Paste the admin token value. -- Project namespace: This can be left blank to accept the default namespace, based on the project name. - - + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` + + 1. Locate the the API server endpoint so GitLab can connect to the cluster. This is displayed on + the AWS EKS console, when viewing the EKS cluster details. +1. Navigate to your: + - Project's **Operations > Kubernetes** page, for a project-level cluster. + - Group's **Kubernetes** page, for a group-level cluster. + - **Admin Area > Kubernetes** page, for an instance-level cluster. +1. Click **Add Kubernetes cluster**. +1. Click the **Add existing cluster** tab and fill in the details: + - **Kubernetes cluster name**: A name for the cluster to identify it within GitLab. + - **Environment scope**: Leave this as `*` for now, since we are only connecting a single cluster. + - **API URL**: The API server endpoint retrieved earlier. + - **CA Certificate**: The certificate data from the earlier step, as-is. + - **Service Token**: The admin token value. + - For project-level clusters, **Project namespace prefix**: This can be left blank to accept the + default namespace, based on the project name. +1. Click on **Add Kubernetes cluster**. The cluster is now connected to GitLab. -Click on **Add Kubernetes cluster**, the cluster is now connected to GitLab. At this point, [Kubernetes deployment variables](index.md#deployment-variables) will automatically be available during CI/CD jobs, making it easy to interact with the cluster. @@ -719,16 +698,19 @@ To disable the Kubernetes cluster integration, follow the same procedure. ## Removing integration -To remove the Kubernetes cluster integration from your project, simply click the -**Remove integration** button. You will then be able to follow the procedure -and add a Kubernetes cluster again. +To remove the Kubernetes cluster integration from your project, either: + +- Select **Remove integration**, to remove only the Kubernetes integration. +- [From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/26815), select + **Remove integration and resources**, to also remove all related GitLab cluster resources (for + example, namespaces, roles, and bindings) when removing the integration. When removing the cluster integration, note: - You need Maintainer [permissions](../../permissions.md) and above to remove a Kubernetes cluster integration. - When you remove a cluster, you only remove its relationship to GitLab, not the cluster itself. To - remove the cluster, you can do so by visiting the GKE dashboard or using `kubectl`. + remove the cluster, you can do so by visiting the GKE or EKS dashboard, or using `kubectl`. ## Learn more diff --git a/doc/user/project/clusters/eks_and_gitlab/index.md b/doc/user/project/clusters/eks_and_gitlab/index.md index fda8cd6340e..9bb8f6cb83c 100644 --- a/doc/user/project/clusters/eks_and_gitlab/index.md +++ b/doc/user/project/clusters/eks_and_gitlab/index.md @@ -1,5 +1,5 @@ --- -redirect_to: '../add_remove_clusters.md#add-existing-eks-cluster' +redirect_to: '../add_remove_clusters.md#existing-eks-cluster' --- -This document was moved to [another location](../add_remove_clusters.md#add-existing-eks-cluster). +This document was moved to [another location](../add_remove_clusters.md#existing-eks-cluster). diff --git a/doc/user/project/clusters/img/add_cluster.png b/doc/user/project/clusters/img/add_cluster.png Binary files differdeleted file mode 100644 index 94ec83f1514..00000000000 --- a/doc/user/project/clusters/img/add_cluster.png +++ /dev/null diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index 6d863a8b888..895cc6c4b57 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -30,9 +30,6 @@ Using the GitLab project Kubernetes integration, you can: - View [Pod logs](#pod-logs-ultimate). **(ULTIMATE)** - Run serverless workloads on [Kubernetes with Knative](serverless/index.md). -See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to -set up integrations. - ### Deploy Boards **(PREMIUM)** GitLab's Deploy Boards offer a consolidated view of the current health and @@ -79,10 +76,7 @@ Kubernetes clusters can be used without Auto DevOps. ### Web terminals -NOTE: **Note:** -Introduced in GitLab 8.15. You must be the project owner or have `maintainer` permissions -to use terminals. Support is limited to the first container in the -first pod of your environment. +> Introduced in GitLab 8.15. When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals) support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in @@ -97,6 +91,14 @@ pods are annotated with: `$CI_ENVIRONMENT_SLUG` and `$CI_PROJECT_PATH_SLUG` are the values of the CI variables. +You must be the project owner or have `maintainer` permissions to use terminals. Support is limited +to the first container in the first pod of your environment. + +## Adding and removing clusters + +See [Adding and removing Kubernetes clusters](add_remove_clusters.md) for details on how to +set up integrations with Google Cloud Platform (GCP) and Amazon Elastic Kubernetes Service (EKS). + ## Cluster configuration After [adding a Kubernetes cluster](add_remove_clusters.md) to GitLab, read this section that covers @@ -115,8 +117,8 @@ applications running on the cluster. ### GitLab-managed clusters -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5. -> Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11. +> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/22011) in GitLab 11.5. +> - Became [optional](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/26565) in GitLab 11.11. You can choose to allow GitLab to manage your cluster for you. If your cluster is managed by GitLab, resources for your projects will be automatically created. See the diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md index 797ddf784cc..7cd5d99ef67 100644 --- a/doc/user/project/clusters/kubernetes_pod_logs.md +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -41,9 +41,37 @@ Logs can be displayed by clicking on a specific pod from [Deploy Boards](../depl 1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). 1. When mousing over the list of pods, a tooltip will appear with the exact pod name and status.  -1. Click on the desired pod to bring up the logs view, which will contain the last 500 lines for that pod. - You may switch between the following in this view: - - Pods. - - [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. +1. Click on the desired pod to bring up the logs view. - Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/6502). +### Logs view + +The logs view will contain the last 500 lines for a pod, and has control to filter via: + +- Pods. +- [From GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/issues/5769), environments. +- [From GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/merge_requests/21656), [full text search](#full-text-search). + +Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/13404). + +Support for historical data is coming [in a future release](https://gitlab.com/gitlab-org/gitlab/issues/196191). + +### Full text search + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/21656) in GitLab 12.7. + +When you enable [Elastic Stack](../../clusters/applications.md#elastic-stack) on your cluster, +you can search the content of your logs via a search bar. + +The search is passed on to Elasticsearch using the [simple_query_string](https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html) +Elasticsearch function, which supports the following operators: + +``` ++ signifies AND operation +| signifies OR operation +- negates a single token +" wraps a number of tokens to signify a phrase for searching +* at the end of a term signifies a prefix query +( and ) signify precedence +~N after a word signifies edit distance (fuzziness) +~N after a phrase signifies slop amount +``` diff --git a/doc/user/project/clusters/serverless/aws.md b/doc/user/project/clusters/serverless/aws.md index 0b74f1e73eb..220ce2593bb 100644 --- a/doc/user/project/clusters/serverless/aws.md +++ b/doc/user/project/clusters/serverless/aws.md @@ -121,7 +121,6 @@ This example code does the following: - Installs the Serverless Framework. - Deploys the serverless function to your AWS account using the AWS credentials defined above. - - Deploys the serverless function to your AWS account using the AWS credentials defined above ### Setting up your AWS credentials with your GitLab account diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 9aaf046e78b..1dc543c3b83 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -43,7 +43,7 @@ To run Knative on GitLab, you will need: clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](../add_remove_clusters.md#gke-cluster). + The simplest way to get started is to add a cluster using GitLab's [GKE integration](../add_remove_clusters.md). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. 1. **Helm Tiller:** Helm is a package manager for Kubernetes and is required to install Knative. diff --git a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png Binary files differindex f813b60dcd9..fc2893aa4d5 100644 --- a/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png +++ b/doc/user/project/img/code_owners_approval_new_protected_branch_v12_4.png diff --git a/doc/user/project/img/deploy_boards_landing_page.png b/doc/user/project/img/deploy_boards_landing_page.png Binary files differindex c9621a06860..73b3724d657 100644 --- a/doc/user/project/img/deploy_boards_landing_page.png +++ b/doc/user/project/img/deploy_boards_landing_page.png diff --git a/doc/user/project/img/description_templates_issue_settings.png b/doc/user/project/img/description_templates_issue_settings.png Binary files differindex 53328108835..657b6ae1269 100644 --- a/doc/user/project/img/description_templates_issue_settings.png +++ b/doc/user/project/img/description_templates_issue_settings.png diff --git a/doc/user/project/img/description_templates_merge_request_settings.png b/doc/user/project/img/description_templates_merge_request_settings.png Binary files differindex eda264f7f37..587367bf2fe 100644 --- a/doc/user/project/img/description_templates_merge_request_settings.png +++ b/doc/user/project/img/description_templates_merge_request_settings.png diff --git a/doc/user/project/img/issue_boards_multi_select.png b/doc/user/project/img/issue_boards_multi_select.png Binary files differindex 34ec0c1c58e..eebe06b04ae 100644 --- a/doc/user/project/img/issue_boards_multi_select.png +++ b/doc/user/project/img/issue_boards_multi_select.png diff --git a/doc/user/project/img/protected_branches_list_v12_3.png b/doc/user/project/img/protected_branches_list_v12_3.png Binary files differindex 2353ddd23be..995a294b85c 100644 --- a/doc/user/project/img/protected_branches_list_v12_3.png +++ b/doc/user/project/img/protected_branches_list_v12_3.png diff --git a/doc/user/project/img/protected_branches_page_v12_3.png b/doc/user/project/img/protected_branches_page_v12_3.png Binary files differindex 9a194c85c41..60aa3c4d251 100644 --- a/doc/user/project/img/protected_branches_page_v12_3.png +++ b/doc/user/project/img/protected_branches_page_v12_3.png diff --git a/doc/user/project/img/service_desk_disabled.png b/doc/user/project/img/service_desk_disabled.png Binary files differdeleted file mode 100644 index ba11b508682..00000000000 --- a/doc/user/project/img/service_desk_disabled.png +++ /dev/null diff --git a/doc/user/project/img/service_desk_enabled.png b/doc/user/project/img/service_desk_enabled.png Binary files differindex aee2b53a680..33d51227e5f 100644 --- a/doc/user/project/img/service_desk_enabled.png +++ b/doc/user/project/img/service_desk_enabled.png diff --git a/doc/user/project/img/service_desk_nav_item.png b/doc/user/project/img/service_desk_nav_item.png Binary files differindex 3420e355f67..fdf8fa024c3 100644 --- a/doc/user/project/img/service_desk_nav_item.png +++ b/doc/user/project/img/service_desk_nav_item.png diff --git a/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png Binary files differindex 1f1febd9068..bbc72a0b4b7 100644 --- a/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png +++ b/doc/user/project/import/img/bitbucket_import_select_project_v12_3.png diff --git a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png Binary files differindex 1c344853cc8..3f94dd83dd6 100644 --- a/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png +++ b/doc/user/project/import/img/bitbucket_server_import_select_project_v12_3.png diff --git a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png Binary files differindex e79c27f32c0..ff6e5dbf4a1 100644 --- a/doc/user/project/import/img/gitlab_new_project_page_v12_2.png +++ b/doc/user/project/import/img/gitlab_new_project_page_v12_2.png diff --git a/doc/user/project/import/img/import_projects_from_gitea_importer_v12_3.png b/doc/user/project/import/img/import_projects_from_gitea_importer_v12_3.png Binary files differindex d8ae1a54851..0f99f74871b 100644 --- a/doc/user/project/import/img/import_projects_from_gitea_importer_v12_3.png +++ b/doc/user/project/import/img/import_projects_from_gitea_importer_v12_3.png diff --git a/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png b/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png Binary files differindex 6a53d9e6d1d..3ac03c0ecc5 100644 --- a/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png +++ b/doc/user/project/import/img/import_projects_from_github_importer_v12_3.png diff --git a/doc/user/project/import/img/import_projects_from_repo_url.png b/doc/user/project/import/img/import_projects_from_repo_url.png Binary files differindex 90bcff5d31b..fd3eae98ebf 100644 --- a/doc/user/project/import/img/import_projects_from_repo_url.png +++ b/doc/user/project/import/img/import_projects_from_repo_url.png diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md index a08488a4baf..cbcef7a2fb0 100644 --- a/doc/user/project/import/perforce.md +++ b/doc/user/project/import/perforce.md @@ -19,7 +19,7 @@ Git: said 'You need to stop work on that new feature and fix this security vulnerability' you can do so very easily in Git. 1. Having a complete copy of the project and its history on your local machine - means every transaction is superfast and Git provides that. You can branch/merge + means every transaction is very fast and Git provides that. You can branch/merge and experiment in isolation, then clean up your mess before sharing your new cool stuff with everyone. 1. Git also made code review simple because you could share your changes without diff --git a/doc/user/project/import/phabricator.md b/doc/user/project/import/phabricator.md index 5015c5390de..46438c81d35 100644 --- a/doc/user/project/import/phabricator.md +++ b/doc/user/project/import/phabricator.md @@ -32,4 +32,4 @@ we can gain early feedback before releasing it for everyone. To enable it: Feature.enable(:phabricator_import) ``` -1. Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin area. +1. Enable Phabricator as an [import source](../../admin_area/settings/visibility_and_access_controls.md#import-sources) in the Admin Area. diff --git a/doc/user/project/integrations/generic_alerts.md b/doc/user/project/integrations/generic_alerts.md index 62310dd9177..8c509f30c4f 100644 --- a/doc/user/project/integrations/generic_alerts.md +++ b/doc/user/project/integrations/generic_alerts.md @@ -30,7 +30,7 @@ You can customize the payload by sending the following parameters. All fields ar | `start_time` | DateTime | The time of the incident. If none is provided, a timestamp of the issue will be used. | | `service` | String | The affected service. | | `monitoring_tool` | String | The name of the associated monitoring tool. | -| `hosts` | String or Array | One or more hosts, as to where this incident ocurred. | +| `hosts` | String or Array | One or more hosts, as to where this incident occurred. | Example request: diff --git a/doc/user/project/integrations/img/emails_on_push_service.png b/doc/user/project/integrations/img/emails_on_push_service.png Binary files differindex 84e42eca9a2..43cef167369 100644 --- a/doc/user/project/integrations/img/emails_on_push_service.png +++ b/doc/user/project/integrations/img/emails_on_push_service.png diff --git a/doc/user/project/integrations/img/embed_metrics_issue_template.png b/doc/user/project/integrations/img/embed_metrics_issue_template.png Binary files differindex 3c6a243e5c1..ca39a738d5f 100644 --- a/doc/user/project/integrations/img/embed_metrics_issue_template.png +++ b/doc/user/project/integrations/img/embed_metrics_issue_template.png diff --git a/doc/user/project/integrations/img/hangouts_chat_configuration.png b/doc/user/project/integrations/img/hangouts_chat_configuration.png Binary files differindex c40c9b92edb..1104f20ce2f 100644 --- a/doc/user/project/integrations/img/hangouts_chat_configuration.png +++ b/doc/user/project/integrations/img/hangouts_chat_configuration.png diff --git a/doc/user/project/integrations/img/mattermost_configuration.png b/doc/user/project/integrations/img/mattermost_configuration.png Binary files differindex d196b1fc8e4..18c0036846d 100644 --- a/doc/user/project/integrations/img/mattermost_configuration.png +++ b/doc/user/project/integrations/img/mattermost_configuration.png diff --git a/doc/user/project/integrations/img/microsoft_teams_configuration.png b/doc/user/project/integrations/img/microsoft_teams_configuration.png Binary files differindex 8794991f2ec..22ad28e3f73 100644 --- a/doc/user/project/integrations/img/microsoft_teams_configuration.png +++ b/doc/user/project/integrations/img/microsoft_teams_configuration.png diff --git a/doc/user/project/integrations/img/slack_configuration.png b/doc/user/project/integrations/img/slack_configuration.png Binary files differindex 6922c70f253..4d5e6ae7856 100644 --- a/doc/user/project/integrations/img/slack_configuration.png +++ b/doc/user/project/integrations/img/slack_configuration.png diff --git a/doc/user/project/integrations/img/unify_circuit_configuration.png b/doc/user/project/integrations/img/unify_circuit_configuration.png Binary files differindex 285d4f92030..adba065347f 100644 --- a/doc/user/project/integrations/img/unify_circuit_configuration.png +++ b/doc/user/project/integrations/img/unify_circuit_configuration.png diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 3b7309ea7e4..17e64f1692d 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -139,7 +139,10 @@ GitLab supports a limited set of [CI variables](../../../ci/variables/README.htm - CI_ENVIRONMENT_SLUG - KUBE_NAMESPACE -To specify a variable in a query, enclose it in quotation marks with curly braces with a leading percent. For example: `"%{ci_environment_slug}"`. +There are 2 methods to specify a variable in a query or dashboard: + +1. Variables can be specified using the [Liquid template format](https://help.shopify.com/en/themes/liquid/basics), for example `{{ci_environment_slug}}` ([added](https://gitlab.com/gitlab-org/gitlab/merge_requests/20793) in GitLab 12.6). +1. You can also enclose it in quotation marks with curly braces with a leading percent, for example `"%{ci_environment_slug}"`. This method is deprecated though and support will be [removed in the next major release](https://gitlab.com/gitlab-org/gitlab/issues/37990). ### Defining custom dashboards per project @@ -152,12 +155,13 @@ NOTE: **Note:** The custom metrics as defined below do not support alerts, unlike [additional metrics](#adding-additional-metrics-premium). -Dashboards have several components: +#### Adding a new dashboard to your project -- Panel groups, which comprise panels. -- Panels, which support one or more metrics. +You can configure a custom dashboard by adding a new `.yml` file into a project's repository. Only `.yml` files present in the projects **default** branch are displayed on the project's **Operations > Metrics** section. + +You may create a new file from scratch or duplicate a GitLab-defined dashboard. -To configure a custom dashboard: +**Add a `.yml` file manually** 1. Create a YAML file with the `.yml` extension under your repository's root directory inside `.gitlab/dashboards/`. For example, create @@ -182,7 +186,7 @@ To configure a custom dashboard: define the layout of the dashboard and the Prometheus queries used to populate data. -1. Save the file, commit, and push to your repository. +1. Save the file, commit, and push to your repository. The file must be present in your **default** branch. 1. Navigate to your project's **Operations > Metrics** and choose the custom dashboard from the dropdown. @@ -190,6 +194,28 @@ NOTE: **Note:** Configuration files nested under subdirectories of `.gitlab/dashboards` are not supported and will not be available in the UI. +**Duplicate a GitLab-defined dashboard as a new `.yml` file** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/37238) in GitLab 12.7. + +You can save a copy of a GitLab defined dashboard that can be customized and adapted to your project. You can decide to save the dashboard new `.yml` file in the project's **default** branch or in a newly created branch with a name of your choosing. + +1. Click on the "Duplicate dashboard" in the dashboard dropdown. + + NOTE:**Note:** + Only GitLab-defined dashboards can be duplicated. + +1. Input the file name and other information, such as a new commit message, and click on "Duplicate". + +If you select your **default** branch, the new dashboard will become immediately available. If you select another branch, this branch should be merged to your **default** branch first. + +#### Dashboard YAML properties + +Dashboards have several components: + +- Panel groups, which comprise of panels. +- Panels, which support one or more metrics. + The following tables outline the details of expected properties. **Dashboard properties:** diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index cf46456ca42..eda8cf35091 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -20,7 +20,7 @@ NGINX server metrics are detected, which tracks the pages and content directly s ## Configuring Prometheus to monitor for NGINX metrics -To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts)) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. +To get started with NGINX monitoring, you should first enable the [VTS statistics](https://github.com/vozlt/nginx-module-vts) module for your NGINX server. This will capture and display statistics in an HTML readable form. Next, you should install and configure the [NGINX VTS exporter](https://github.com/hnlq715/nginx-vts-exporter) which parses these statistics and translates them into a Prometheus monitoring endpoint. If you are using NGINX as your Kubernetes Ingress, GitLab will [automatically detect](nginx_ingress.md) the metrics once enabled in 0.9.0 and later releases. diff --git a/doc/user/project/integrations/services_templates.md b/doc/user/project/integrations/services_templates.md index a0bf31c526f..8a88df88629 100644 --- a/doc/user/project/integrations/services_templates.md +++ b/doc/user/project/integrations/services_templates.md @@ -8,8 +8,8 @@ for new projects only. ## Enable a service template -In GitLab's Admin area, navigate to **Service Templates** and choose the -service template you wish to create. +Navigate to the **Admin Area > Service Templates** and choose the service +template you wish to create. ## Services for external issue trackers diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index bb946574371..79cda9a045e 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -56,9 +56,9 @@ tier](https://about.gitlab.com/pricing/), as shown in the following table: | Tier | Number of webhooks per project | |----------|--------------------------------| -| Free | 10 | -| Bronze | 20 | -| Silver | 30 | +| Free | 100 | +| Bronze | 100 | +| Silver | 100 | | Gold | 100 | ## Use-cases diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md index 403972941b2..b1334f0b0b0 100644 --- a/doc/user/project/issue_board.md +++ b/doc/user/project/issue_board.md @@ -281,6 +281,17 @@ As on another list types, click on the trash icon to remove it.  +## Work In Progress limits **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11403) in GitLab 12.7 + +You can set Work In Progress (WIP) limits per issues list. When a limit is set, the list's header shows the number of issues in the list and the soft limit of issues. For example, for a list with 4 issues, and a limit of 5, the header will show `4/5`. If you exceed the limit, the current number of issues is shown in red. For example, you have a list with 5 issues with a limit of 5. When you move another issue to that list, the list's header displays `6/5`, with the `6` shown in red. + +To set a WIP limit for a list: + +1. Navigate to a Project or Group board for which you have membership and click on the Settings icon (gear) in a list's header. +1. Next to **Work In Progress Limit**, click **Edit** and enter the maximum number of issues. Press `Enter` to save. + ### Summary of features per tier Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table: diff --git a/doc/user/project/issues/csv_export.md b/doc/user/project/issues/csv_export.md index b97bcd47f61..13f0c11399f 100644 --- a/doc/user/project/issues/csv_export.md +++ b/doc/user/project/issues/csv_export.md @@ -69,6 +69,8 @@ Data will be encoded with a comma as the column delimiter, with `"` used to quot | Labels | Title of any labels joined with a `,` | | Time Estimate | [Time estimate](../time_tracking.md#estimates) in seconds | | Time Spent | [Time spent](../time_tracking.md#time-spent) in seconds | +| Epic ID | Id of the parent epic **(ULTIMATE)**, introduced in 12.7 | +| Epic Title | Title of the parent epic **(ULTIMATE)**, introduced in 12.7 | ## Limitations diff --git a/doc/user/project/issues/design_management.md b/doc/user/project/issues/design_management.md index 594f73dbfbe..c5358f338a5 100644 --- a/doc/user/project/issues/design_management.md +++ b/doc/user/project/issues/design_management.md @@ -37,6 +37,13 @@ Design Management requires that projects are using [hashed storage](../../../administration/repository_storage_types.html#hashed-storage) (the default storage type since v10.0). +### Feature Flags + +- Reference Parsing + + Designs support short references in Markdown, but this needs to be enabled by setting + the `:design_management_reference_filter_gfm_pipeline` feature flag. + ## Limitations - Files uploaded must have a file extension of either `png`, `jpg`, `jpeg`, `gif`, `bmp`, `tiff` or `ico`. @@ -71,6 +78,8 @@ Designs cannot be added if the issue has been moved, or its ## Viewing designs Images on the Design Management page can be enlarged by clicking on them. +You can navigate through designs by clicking on the navigation buttons on the +top-right corner or with <kbd>Left</kbd>/<kbd>Right</kbd> keyboard buttons. The number of comments on a design — if any — is listed to the right of the design filename. Clicking on this number enlarges the design @@ -84,6 +93,14 @@ to help summarize changes between versions. | Modified (in the selected version) |  | | Added (in the selected version) |  | +### Exploring designs by zooming + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/13217) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. + +Designs can be explored in greater detail by zooming in and out of the image. Control the amount of zoom with the `+` and `-` buttons at the bottom of the image. While zoomed, you can still [add new annotations](#adding-annotations-to-designs) to the image, and see any existing ones. + + + ## Deleting designs > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/11089) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.4. @@ -127,3 +144,32 @@ Different discussions have different badge numbers: From GitLab 12.5 on, new annotations will be outputted to the issue activity, so that everyone involved can participate in the discussion. + +## References + +GitLab Flavored Markdown supports references to designs. The syntax for this is: + + `#123[file.jpg]` - the issue reference, with the filename in square braces + +File names may contain a variety of odd characters, so two escaping mechanisms are supported: + +### Quoting + +File names may be quoted with double quotation marks, eg: + + `#123["file.jpg"]` + +This is useful if, for instance, your filename has square braces in its name. In this scheme, all +double quotation marks in the file name need to be escaped with backslashes, and backslashes need +to be escaped likewise: + + `#123["with with \"quote\" marks and a backslash \\.png"]` + +### Base64 Encoding + +In the case of file names that include HTML elements, you will need to escape these names to avoid +them being processed as HTML literals. To do this, we support base64 encoding, eg. + + The file `<a>.jpg` can be referenced as `#123[base64:PGE+LmpwZwo=]` + +Obviously we would advise against using such filenames. diff --git a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png Binary files differindex b1a55c639ca..447d3907122 100644 --- a/doc/user/project/issues/img/confirm_design_deletion_v12_4.png +++ b/doc/user/project/issues/img/confirm_design_deletion_v12_4.png diff --git a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png Binary files differindex b421a5577df..75cbdf77c24 100644 --- a/doc/user/project/issues/img/delete_multiple_designs_v12_4.png +++ b/doc/user/project/issues/img/delete_multiple_designs_v12_4.png diff --git a/doc/user/project/issues/img/delete_single_design_v12_4.png b/doc/user/project/issues/img/delete_single_design_v12_4.png Binary files differindex 0ca03b48e76..158b4949ce4 100644 --- a/doc/user/project/issues/img/delete_single_design_v12_4.png +++ b/doc/user/project/issues/img/delete_single_design_v12_4.png diff --git a/doc/user/project/issues/img/design_zooming_v12_7.png b/doc/user/project/issues/img/design_zooming_v12_7.png Binary files differnew file mode 100644 index 00000000000..4acb4e10913 --- /dev/null +++ b/doc/user/project/issues/img/design_zooming_v12_7.png diff --git a/doc/user/project/issues/img/disable_issue_auto_close.png b/doc/user/project/issues/img/disable_issue_auto_close.png Binary files differnew file mode 100644 index 00000000000..5894d39622a --- /dev/null +++ b/doc/user/project/issues/img/disable_issue_auto_close.png diff --git a/doc/user/project/issues/img/select_designs_v12_4.png b/doc/user/project/issues/img/select_designs_v12_4.png Binary files differindex a53bd516300..532a79fce65 100644 --- a/doc/user/project/issues/img/select_designs_v12_4.png +++ b/doc/user/project/issues/img/select_designs_v12_4.png diff --git a/doc/user/project/issues/img/zoom-quickaction-button.png b/doc/user/project/issues/img/zoom-quickaction-button.png Binary files differindex c95a56b43e8..3be4f36f88f 100644 --- a/doc/user/project/issues/img/zoom-quickaction-button.png +++ b/doc/user/project/issues/img/zoom-quickaction-button.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 6abd6fd7047..f540dfe0e51 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -97,7 +97,7 @@ and modify them if you have the necessary [permissions](../../permissions.md). On the Issues List, you can view all issues in the current project, or from multiple projects when opening the Issues List from the higher-level group context. Filter the -issue list with a [search query](../../search/index.md#issues-and-merge-requests-per-project), +issue list with a [search query](../../search/index.md#filtering-issue-and-merge-request-lists), 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. diff --git a/doc/user/project/issues/managing_issues.md b/doc/user/project/issues/managing_issues.md index 38649b05593..ff360e973aa 100644 --- a/doc/user/project/issues/managing_issues.md +++ b/doc/user/project/issues/managing_issues.md @@ -66,7 +66,7 @@ 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. +contact in your email client for easy access. CAUTION: **Caution:** This is a private email address, generated just for you. **Keep it to yourself**, @@ -207,10 +207,23 @@ 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 +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`. +#### Disabling automatic issue closing + +The automatic issue closing feature can be disabled on a per-project basis +within the [project's repository settings](../settings/index.md). Referenced +issues will still be displayed as such but won't be closed automatically. + + + +This only applies to issues affected by new merge requests or commits. Already +closed issues remain as-is. Disabling automatic issue closing only affects merge +requests *within* the project and won't prevent other projects from closing it +via cross-project issues. + #### Customizing the issue closing pattern **(CORE ONLY)** In order to change the default issue closing pattern, GitLab administrators must edit the diff --git a/doc/user/project/members/img/project_members.png b/doc/user/project/members/img/project_members.png Binary files differindex 5d44b5d957e..218f5a24d2e 100644 --- a/doc/user/project/members/img/project_members.png +++ b/doc/user/project/members/img/project_members.png diff --git a/doc/user/project/members/img/project_members_filter_v12_6.png b/doc/user/project/members/img/project_members_filter_v12_6.png Binary files differindex 0207515ded0..692fdfe00a1 100644 --- a/doc/user/project/members/img/project_members_filter_v12_6.png +++ b/doc/user/project/members/img/project_members_filter_v12_6.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md index c069882e38f..27a5701e6c2 100644 --- a/doc/user/project/members/index.md +++ b/doc/user/project/members/index.md @@ -27,8 +27,8 @@ From the image above, we can deduce the following things: - Administrator is the Owner and member of **all** groups and for that reason, there is an indication of an ancestor group and inherited Owner permissions. -[From](https://gitlab.com/gitlab-org/gitlab/issues/21727), you can filter this list -using dropdown on the right side: +[From GitLab 12.6](https://gitlab.com/gitlab-org/gitlab/issues/21727), you can filter this list +using the dropdown on the right side:  diff --git a/doc/user/project/merge_requests/code_quality.md b/doc/user/project/merge_requests/code_quality.md index 69bdfe10e3f..9d44f416696 100644 --- a/doc/user/project/merge_requests/code_quality.md +++ b/doc/user/project/merge_requests/code_quality.md @@ -66,6 +66,19 @@ will scan your source code for code quality issues. The report will be saved as that you can later download and analyze. Due to implementation limitations we always take the latest Code Quality artifact available. +It is also possible to override the URL to the Code Quality image by +setting the `CODE_QUALITY_IMAGE` variable. This is particularly useful if you want +to lock in a specific version of Code Quality, or use a fork of it: + +```yaml +include: + - template: Code-Quality.gitlab-ci.yml + +code_quality: + variables: + CODE_QUALITY_IMAGE: "registry.example.com/codequality-fork:latest" +``` + By default, report artifacts are not downloadable. If you need them downloadable on the job details page, you can add `gl-code-quality-report.json` to the artifact paths like so: @@ -125,6 +138,33 @@ code_quality: codequality: gl-code-quality-report.json ``` +In GitLab 12.6, Code Quality switched to the +[new versioning scheme](https://gitlab.com/gitlab-org/security-products/codequality/merge_requests/38). +It is highly recommended to include the Code Quality template as shown in the +[example configuration](#example-configuration), which uses the new versioning scheme. +If not using the template, the `SP_VERSION` variable can be hardcoded to use the +new image versions: + +```yaml +code_quality: + image: docker:stable + variables: + DOCKER_DRIVER: overlay2 + SP_VERSION: 0.85.6 + allow_failure: true + services: + - docker:stable-dind + script: + - docker run + --env SOURCE_CODE="$PWD" + --volume "$PWD":/code + --volume /var/run/docker.sock:/var/run/docker.sock + "registry.gitlab.com/gitlab-org/security-products/codequality:$SP_VERSION" /code + artifacts: + reports: + codequality: gl-code-quality-report.json +``` + For GitLab 11.4 and earlier, the job should look like: ```yaml diff --git a/doc/user/project/merge_requests/creating_merge_requests.md b/doc/user/project/merge_requests/creating_merge_requests.md index 1dec58a8bb0..5b4c6d22c80 100644 --- a/doc/user/project/merge_requests/creating_merge_requests.md +++ b/doc/user/project/merge_requests/creating_merge_requests.md @@ -1,124 +1,165 @@ --- -type: index, reference +type: howto +description: "How to create Merge Requests in GitLab." +disqus_identifier: 'https://docs.gitlab.com/ee/gitlab-basics/add-merge-request.html' --- -# Creating merge requests +# How to create a merge request -Merge requests are the primary method of making changes to files in a GitLab project. -Changes are proposed by creating and submitting a merge request, which is then -[reviewed, and accepted (or rejected)](reviewing_and_managing_merge_requests.md), -all within GitLab. +Before creating a merge request, read through an +[introduction to Merge Requests](getting_started.md) +to familiarize yourself with the concept, the terminology, +and to learn what you can do with them. -## Creating new merge requests +Every merge request starts by creating a branch. You can either +do it locally through the command line, via a Git CLI application, +or through the GitLab UI. -You can start creating a new merge request by clicking the **New merge request** button -on the **Merge Requests** page in a project. Then you must choose the source project and -branch that contain your changes, and the target project and branch where you want to merge -the changes into. Click on **Compare branches and continue** to go to the next step -and start filling in the merge request details. +This document describes the several ways to create a merge request. -When viewing the commits on a branch other than master in **Repository > Commits**, you -can click on the **Create merge request** button, and a new merge request will be started -using the current branch as the source, and `master` in the current project as the target. +When you start a new merge request, regarless of the method, +you'll be taken to the [**New Merge Request** page](#new-merge-request-page) +to fill it with information about the merge request. -If you have recently pushed changes to GitLab, the **Create merge request** button will -also appear in the top right of the: +If you push a new branch to GitLab, also regardless of the method, +you can click the [**Create Merge Request**](#create-merge-request-button) +button and start a merge request from there. + +## New Merge Request page + +On the **New Merge Request** page, start by filling in the title +and description for the merge request. If there are are already +commits on the branch, the title will be pre-filled with the first +line of the first commit message, and the description will be +pre-filled with any additional lines in the commit message. +The title is the only field that is mandatory in all cases. + +From there, you can fill it with information (title, description, +assignee(s), milestone, labels, approvers) and click **Create Merge Request**. + +From that initial screen, you can also see all the commits, +pipelines, and file changes pushed to your branch before submitting +the merge request. + + + +TIP: **Tip:** +You can push one or more times to your branch in GitLab before +creating the merge request. + +## Create Merge Request button + +Once you have pushed a new branch to GitLab, visit your repository +in GitLab and to see a call-to-action at the top of your screen +from which you can click the button **Create Merge Request**. + + + +You can also see the **Create merge request** button in the top-right of the: - **Project** page. - **Repository > Files** page. - **Merge Requests** page. -In this case, the merge request will use the most recent branch you pushed changes -to as the source branch, and `master` in the current project as the target. +In this case, GitLab will use the most recent branch you pushed +changes to as the source branch, and the default branch in the current +project as the target. -You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). +## New merge request by adding, editing, and uploading a file -## Workflow for new merge requests +When you choose to edit, add, or upload a file through the GitLab UI, +at the end of the file you'll see the option to add the **Commit message**, +to select the **Target branch** of that commit, and the checkbox to +**Start new a merge request with these changes**. -On the **New Merge Request** page, you can start by filling in the title and description -for the merge request. If there are are already commits on the branch, the title will -be pre-filled with the first line of the first commit message, and the description will -be pre-filled with any additional lines in the commit message. The title is the only -field that is mandatory in all cases. +Similarly, if you change files through the Web IDE, when you navigate to **Commit** on the left-hand sidebar, you'll see these same options. -From here, you can also: +Once you have added, edited, or uploaded the file: -- Set the merge request as a [work in progress](work_in_progress_merge_requests.md). -- Select the [assignee](#assignee), or [assignees](#multiple-assignees-starter). **(STARTER)** -- Select a [milestone](../milestones/index.md). -- Select [labels](../labels.md). -- Add any [merge request dependencies](merge_request_dependencies.md). **(PREMIUM)** -- Select [approval options](merge_request_approvals.md). **(STARTER)** -- Verify the source and target branches are correct. -- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option. -- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option. -- If the merge request is from a fork, enable [Allow collaboration on merge requests across forks](allow_collaboration.md). +1. Describe your changes in the commit message. +1. Select an existing branch to add your commit into, or, if you'd like to create a new branch, type the new branch name (without spaces, capital letters, or special chars). +1. Keep the checkbox checked to start a new merge request straightaway, or, uncheck it to add more changes to that branch before starting the merge request. +1. Click **Commit changes**. -Many of these can be set when pushing changes from the command line, with -[Git push options](../push_options.md). +If you chose to start a merge request, you'll be taken to the +[**New Merge Request** page](#new-merge-request-page), from +which you can fill it in with information and submit the merge request. -### Merge requests to close issues +The merge request will target the default branch of the repository. +If you want to change it, you can do it later by editing the merge request. -If the merge request is being created to resolve an issue, you can add a note in the -description which will set it to [automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) -when merged. +## New merge request from a new branch created through the UI -If the issue is [confidential](../issues/confidential_issues.md), you may want to -use a different workflow for [merge requests for confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues), -to prevent confidential information from being exposed. +To quickly start working on files through the GitLab UI, +navigate to your project's **Repository > Branches** and click +**New branch**. A new branch will be created and you can start +editing files. -## Assignee +Once committed and pushed, you can click on the [**Create Merge Request**](#create-merge-request-button) +button to open the [**New Merge Request** page](#new-merge-request-page). +A new merge request will be started using the current branch as the source, +and the default branch in the current project as the target. -Choose an assignee to designate someone as the person responsible for the first -[review of the merge request](reviewing_and_managing_merge_requests.md). Open the -drop down box to search for the user you wish to assign, and the merge request will be -added to their [assigned merge request list](../../search/index.md#issues-and-merge-requests). +## New merge request from you local environment -### Multiple assignees **(STARTER)** +Assuming you have your repository cloned into your computer and you'd +like to start working on changes to files, start by creating and +checking out a new branch: -> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). +```bash +git checkout -b my-new-branch +``` -Multiple people often review merge requests at the same time. GitLab allows you to -have multiple assignees for merge requests to indicate everyone that is reviewing or -accountable for it. +Work on your file changes, stage, and commit them: - +```bash +git add . +git commit -m "My commit message" +``` -To assign multiple assignees to a merge request: +Once you're done, [push your branch to GitLab](../../../gitlab-basics/start-using-git.md#send-changes-to-gitlabcom): -1. From a merge request, expand the right sidebar and locate the **Assignees** section. -1. Click on **Edit** and from the dropdown menu, select as many users as you want - to assign the merge request to. +```bash +git push origin my-new-branch +``` -Similarly, assignees are removed by deselecting them from the same dropdown menu. +In the output, GitLab will prompt you with a direct link for creating +a merge request: -It's also possible to manage multiple assignees: +```bash +... +remote: To create a merge request for docs-new-merge-request, visit: +remote: https://gitlab-instance.com/my-group/my-project/merge_requests/new?merge_request%5Bsource_branch%5D=my-new-branch +``` -- When creating a merge request. -- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). +Copy that link and paste it in your browser, and the [**New Merge Request page**](#new-merge-request-page) +will be displayed. -## Deleting the source branch +There is also a number of [flags you can add to commands when pushing through the command line](../push_options.md) to reduce the need for editing merge requests manually through the UI. -When creating a merge request, select the "Delete source branch when merge -request accepted" option and the source branch will be deleted when the merge -request is merged. To make this option enabled by default for all new merge -requests, enable it in the [project's settings](../settings/index.md#merge-request-settings). +If you didn't push your branch to GitLab through the command line +(for example, you used a Git CLI application to push your changes), +you can create a merge request through the GitLab UI by clicking +the [**Create Merge Request**](#create-merge-request-button) button. -This option is also visible in an existing merge request next to the merge -request button and can be selected/deselected before merging. It's only visible -to users with [Maintainer permissions](../../permissions.md) in the source project. +## New merge request from an issue -If the user viewing the merge request does not have the correct permissions to -delete the source branch and the source branch is set for deletion, the merge -request widget will show the "Deletes source branch" text. +You can also [create a new merge request directly from an issue](../repository/web_editor.md#create-a-new-branch-from-an-issue). - +## New merge request from the Merge Requests page -## Create new merge requests by email +You can start creating a new merge request by clicking the +**New merge request** button on the **Merge Requests** page in a project. +Then choose the source project and branch that contain your changes, +and the target project and branch where you want to merge the changes into. +Click on **Compare branches and continue** to go to the +[**New Merge Request** page](#new-merge-request-page) and fill in the details. + +## New merge request by email **(CORE ONLY)** _This feature needs [incoming email](../../../administration/incoming_email.md) -to be configured by a GitLab administrator to be available for CE/EE users, and -it's available on GitLab.com._ +to be configured by a GitLab administrator to be available._ It isn't +available in GitLab.com. You can create a new merge request by sending an email to a user-specific email address. The address can be obtained on the merge requests page by clicking on @@ -131,7 +172,7 @@ this feature. If it's not enabled to your instance, you may ask your GitLab administrator to do so. 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. +as anyone who has it can create issues or merge requests as if they were you. You can add this address to your contact list for easy access.  @@ -156,3 +197,7 @@ created from the repository's HEAD or the specified target branch to apply the patches. The target branch can be specified using the [`/target_branch` quick action](../quick_actions.md). If the source branch already exists, the patches will be applied on top of it. + +## Reviewing and managing Merge Requests + +Once you have submitted a merge request, it can be [reviewed and managed](reviewing_and_managing_merge_requests.md) through GitLab. diff --git a/doc/user/project/merge_requests/getting_started.md b/doc/user/project/merge_requests/getting_started.md new file mode 100644 index 00000000000..0ab8d31403e --- /dev/null +++ b/doc/user/project/merge_requests/getting_started.md @@ -0,0 +1,151 @@ +--- +type: index, reference +description: "Getting started with Merge Requests." +--- + +# Getting started with Merge Requests + +A Merge Request (**MR**) is the basis of GitLab as a code +collaboration and version control. + +When working in a Git-based platform, you can use branching +strategies to collaborate on code. + +A repository is composed by its _default branch_, which contains +the major version of the codebase, from which you create minor +branches, also called _feature branches_, to propose changes to +the codebase without introducing them directly into the major +version of the codebase. + +Branching is especially important when collaborating with others, +avoiding changes to be pushed directly to the default branch +without prior reviews, tests, and approvals. + +When you create a new feature branch, change the files, and push +it to GitLab, you have the option to create a **Merge Request**, +which is essentially a _request_ to merge one branch into another. + +The branch you added your changes into is called _source branch_ +while the branch you request to merge your changes into is +called _target branch_. + +The target branch can be the default or any other branch, depending +on the branching strategies you choose. + +In a merge request, beyond visualizing the differences between the +original content and your proposed changes, you can execute a +[significant number of tasks](#what-you-can-do-with-merge-requests) +before concluding your work and merging the merge request. + +You can watch our [GitLab Flow video](https://www.youtube.com/watch?v=InKNIvky2KE) for +a quick overview of working with merge requests. + +## How to create a merge request + +Learn the various ways to [create a merge request](creating_merge_requests.md). + +## What you can do with merge requests + +When you start a new merge request, you can immediately include the following +options, or add them later by clicking the **Edit** button on the merge +request's page at the top-right side: + +- [Assign](#assignee) the merge request to a colleague for review. With GitLab Starter and higher tiers, you can [assign it to more than one person at a time](#multiple-assignees-starter). +- Set a [milestone](../milestones/index.md) to track time-sensitive changes. +- Add [labels](../labels.md) to help contextualize and filter your merge requests over time. +- Require [approval](merge_request_approvals.md) from your team. **(STARTER)** +- [Close issues automatically](#merge-requests-to-close-issues) when they are merged. +- Enable the [delete source branch when merge request is accepted](#deleting-the-source-branch) option to keep your repository clean. +- Enable the [squash commits when merge request is accepted](squash_and_merge.md) option to combine all the commits into one before merging, thus keep a clean commit history in your repository. +- Set the merge request as a [Work In Progress (WIP)](work_in_progress_merge_requests.md) to avoid accidental merges before it is ready. + +Once you have created the merge request, you can also: + +- [Discuss](../../discussions/index.md) your implementation with your team in the merge request thread. +- [Perform inline code reviews](reviewing_and_managing_merge_requests.md#perform-inline-code-reviews). +- Add [merge request dependencies](merge_request_dependencies.md) to restrict it to be merged only when other merge requests have been merged. **(PREMIUM)** +- Preview continuous integration [pipelines on the merge request widget](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests-widgets). +- Preview how your changes look directly on your deployed application with [Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps). +- [Allow collaboration on merge requests across forks](allow_collaboration.md). +- Perform a [Review](../../discussions/index.md#merge-request-reviews-premium) in order to create multiple comments on a diff and publish them once you're ready. **(PREMIUM)** +- Add [code suggestions](../../discussions/index.md#suggest-changes) to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. +- Add a time estimation and the time spent with that merge request with [Time Tracking](../time_tracking.md#time-tracking). + +Many of these can be set when pushing changes from the command line, +with [Git push options](../push_options.md). + +See also other [features associated to merge requests](reviewing_and_managing_merge_requests.md#associated-features). + +### Assignee + +Choose an assignee to designate someone as the person responsible +for the first [review of the merge request](reviewing_and_managing_merge_requests.md). +Open the drop down box to search for the user you wish to assign, +and the merge request will be added to their +[assigned merge request list](../../search/index.md#issues-and-merge-requests). + +#### Multiple assignees **(STARTER)** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2004) in [GitLab Starter 11.11](https://about.gitlab.com/pricing/). + +Multiple people often review merge requests at the same time. +GitLab allows you to have multiple assignees for merge requests +to indicate everyone that is reviewing or accountable for it. + + + +To assign multiple assignees to a merge request: + +1. From a merge request, expand the right sidebar and locate the **Assignees** section. +1. Click on **Edit** and from the dropdown menu, select as many users as you want + to assign the merge request to. + +Similarly, assignees are removed by deselecting them from the same +dropdown menu. + +It is also possible to manage multiple assignees: + +- When creating a merge request. +- Using [quick actions](../quick_actions.md#quick-actions-for-issues-merge-requests-and-epics). + +### Merge requests to close issues + +If the merge request is being created to resolve an issue, you can +add a note in the description which sets it to +[automatically close the issue](../issues/managing_issues.md#closing-issues-automatically) +when merged. + +If the issue is [confidential](../issues/confidential_issues.md), +you may want to use a different workflow for +[merge requests for confidential issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) +to prevent confidential information from being exposed. + +### Deleting the source branch + +When creating a merge request, select the +**Delete source branch when merge request accepted** option, and the source +branch is deleted when the merge request is merged. To make this option +enabled by default for all new merge requests, enable it in the +[project's settings](../settings/index.md#merge-request-settings). + +This option is also visible in an existing merge request next to +the merge request button and can be selected or deselected before merging. +It is only visible to users with [Maintainer permissions](../../permissions.md) +in the source project. + +If the user viewing the merge request does not have the correct +permissions to delete the source branch and the source branch +is set for deletion, the merge request widget displays the +**Deletes source branch** text. + + + +## Recommendations and best practices for Merge Requests + +- When working locally in your branch, add multiple commits and only push when + you're done, so GitLab runs only one pipeline for all the commits pushed + at once. By doing so, you save pipeline minutes. +- Delete feature branches on merge or after merging them to keep your repository clean. +- Take one thing at a time and ship the smallest changes possible. By doing so, + you'll have faster reviews and your changes will be less prone to errors. +- Do not use capital letters nor special chars in branch names. diff --git a/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png b/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png Binary files differnew file mode 100644 index 00000000000..bcbee10e1b7 --- /dev/null +++ b/doc/user/project/merge_requests/img/create_merge_request_button_v12_6.png diff --git a/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png b/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png Binary files differindex 3699ffd16b4..5ced2fa812f 100644 --- a/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png +++ b/doc/user/project/merge_requests/img/dependencies_edit_inaccessible_v12_4.png diff --git a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png b/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png Binary files differindex beb452e80cf..4edf0648794 100644 --- a/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png +++ b/doc/user/project/merge_requests/img/dependencies_edit_v12_4.png diff --git a/doc/user/project/merge_requests/img/dependencies_view_v12_2.png b/doc/user/project/merge_requests/img/dependencies_view_v12_2.png Binary files differindex e00231c839b..3dde15292c4 100644 --- a/doc/user/project/merge_requests/img/dependencies_view_v12_2.png +++ b/doc/user/project/merge_requests/img/dependencies_view_v12_2.png diff --git a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png Binary files differindex ee94dbdea5c..e3a2ff7960c 100644 --- a/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png +++ b/doc/user/project/merge_requests/img/incrementally_expand_merge_request_diffs_v12_2.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png b/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png Binary files differindex e56fbb9750f..7e23b7db309 100644 --- a/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png +++ b/doc/user/project/merge_requests/img/merge_request_diff_v12_2.png diff --git a/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png b/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png Binary files differnew file mode 100644 index 00000000000..c0f2ba261cb --- /dev/null +++ b/doc/user/project/merge_requests/img/new_merge_request_page_v12_6.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 203a2949243..0617e6bc74d 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -50,6 +50,8 @@ collaborating with that MR. MRs also contain navigation tabs from which you can see the discussion happening on the thread, the list of commits, the list of pipelines and jobs, the code changes and inline code reviews. +To get started, read the [introduction to merge requests](getting_started.md). + ## Merge request navigation tabs at the top > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/33813) in GitLab 12.6. This positioning is experimental. @@ -76,72 +78,11 @@ Feature.disable(:mr_tabs_position) ## Creating merge requests -While making changes to files in the `master` branch of a repository is possible, it is not -the common workflow. In most cases, a user will make changes in a [branch](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell#_git_branching), -then [create a merge request](creating_merge_requests.md) to request that the changes -be merged into another branch (often the `master` branch). - -It is then [reviewed](#reviewing-and-managing-merge-requests), possibly updated after -discussions and suggestions, and finally approved and merged into the target branch. -Creating and reviewing merge requests is one of the most fundamental parts of working -with GitLab. - -When [creating merge requests](creating_merge_requests.md), there are a number of features -to be aware of: - -| Feature | Description | -|-----------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Adding patches when creating a merge request via e-mail](creating_merge_requests.md#adding-patches-when-creating-a-merge-request-via-e-mail) | Add commits to a merge request created by e-mail, by adding patches as e-mail attachments. | -| [Allow collaboration on merge requests across forks](allow_collaboration.md) | Allows the maintainers of an upstream project to collaborate on a fork, to make fixes or rebase branches before merging, reducing the back and forth of accepting community contributions. | -| [Assignee](creating_merge_requests.md#assignee) | Add an assignee to indicate who is reviewing or accountable for it. | -| [Automatic issue closing](../../project/issues/managing_issues.md#closing-issues-automatically) | Set a merge request to close defined issues automatically as soon as it is merged. | -| [Create new merge requests by email](creating_merge_requests.md#create-new-merge-requests-by-email) | Create new merge requests by sending an email to a user-specific email address. | -| [Deleting the source branch](creating_merge_requests.md#deleting-the-source-branch) | Select the "Delete source branch when merge request accepted" option and the source branch will be deleted when the merge request is merged. | -| [Git push options](../push_options.md) | Use Git push options to create or update merge requests when pushing changes to GitLab with Git, without needing to use the GitLab interface. | -| [Labels](../../project/labels.md) | Organize your issues and merge requests consistently throughout the project. | -| [Merge request approvals](merge_request_approvals.md) **(STARTER)** | Set the number of necessary approvals and predefine a list of approvers that will need to approve every merge request in a project. | -| [Merge Request dependencies](merge_request_dependencies.md) **(PREMIUM)** | Specify that a merge request depends on other merge requests, enforcing a desired order of merging. | -| [Merge Requests for Confidential Issues](../issues/confidential_issues.md#merge-requests-for-confidential-issues) | Create merge requests to resolve confidential issues for preventing leakage or early release of sensitive data through regular merge requests. | -| [Milestones](../../project/milestones/index.md) | Track merge requests to achieve a broader goal in a certain period of time. | -| [Multiple assignees](creating_merge_requests.md#multiple-assignees-starter) **(STARTER)** | Have multiple assignees for merge requests to indicate everyone that is reviewing or accountable for it. | -| [Squash and merge](squash_and_merge.md) | Squash all changes present in a merge request into a single commit when merging, to allow for a neater commit history. | -| [Work In Progress merge requests](work_in_progress_merge_requests.md) | Prevent the merge request from being merged before it's ready | +Learn [how to create a merge request](creating_merge_requests.md). ## Reviewing and managing merge requests -Once a merge request has been [created](#creating-merge-requests) and submitted, there -are many powerful features that you can use during the review process to make sure only -the changes you want are merged into the repository. - -For managers and administrators, it is also important to be able to view and manage -all the merge requests in a group or project. When [reviewing or managing merge requests](reviewing_and_managing_merge_requests.md), -there are a number of features to be aware of: - -| Feature | Description | -|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| -| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | -| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | -| [Commenting on any file line in merge requests](reviewing_and_managing_merge_requests.md#commenting-on-any-file-line-in-merge-requests) | Make comments directly on the exact line of a file you want to talk about. | -| [Discuss changes in threads in merge requests reviews](../../discussions/index.md) | Keep track of the progress during a code review by making and resolving comments. | -| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | -| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | -| [Ignore whitespace changes in Merge Request diff view](reviewing_and_managing_merge_requests.md#ignore-whitespace-changes-in-Merge-Request-diff-view) | Hide whitespace changes from the diff view for a to focus on more important changes. | -| [Incrementally expand merge request diffs](reviewing_and_managing_merge_requests.md#incrementally-expand-merge-request-diffs) | View the content directly above or below a change, to better understand the context of that change. | -| [Live preview with Review Apps](reviewing_and_managing_merge_requests.md#live-preview-with-review-apps) | Live preview the changes when Review Apps are configured for your project | -| [Merge request diff file navigation](reviewing_and_managing_merge_requests.md#merge-request-diff-file-navigation) | Quickly jump to any changed file within the diff view. | -| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | -| [Merge when pipeline succeeds](merge_when_pipeline_succeeds.md) | Set a merge request that looks ready to merge to merge automatically when CI pipeline succeeds. | -| [Perform a Review](../../discussions/index.md#merge-request-reviews-premium) **(PREMIUM)** | Start a review in order to create multiple comments on a diff and publish them once you're ready. | -| [Pipeline status in merge requests](reviewing_and_managing_merge_requests.md#pipeline-status-in-merge-requests) | If using [GitLab CI/CD](../../../ci/README.md), see pre and post-merge pipelines information, and which deployments are in progress. | -| [Post-merge pipeline status](reviewing_and_managing_merge_requests.md#post-merge-pipeline-status) | When a merge request is merged, see the post-merge pipeline status of the branch the merge request was merged into. | -| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | -| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | -| [Semi-linear history merge requests](reviewing_and_managing_merge_requests.md#semi-linear-history-merge-requests) | Enable semi-linear history merge requests as another security layer to guarantee the pipeline is passing in the target branch | -| [Suggest changes](../../discussions/index.md#suggest-changes) | Add suggestions to change the content of merge requests directly into merge request threads, and easily apply them to the codebase directly from the UI. | -| [Time Tracking](../time_tracking.md#time-tracking) | Add a time estimation and the time spent with that merge request. | -| [View changes between file versions](reviewing_and_managing_merge_requests.md#view-changes-between-file-versions) | View what will be changed when a merge request is merged. | -| [View group merge requests](reviewing_and_managing_merge_requests.md#view-merge-requests-for-all-projects-in-a-group) | List and view the merge requests within a group. | -| [View project merge requests](reviewing_and_managing_merge_requests.md#view-project-merge-requests) | List and view the merge requests within a project. | +See the features at your disposal to [review and manage merge requests](reviewing_and_managing_merge_requests.md). ## Testing and reports in merge requests diff --git a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md index 97c16a9794d..21c8b5c682b 100644 --- a/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md +++ b/doc/user/project/merge_requests/reviewing_and_managing_merge_requests.md @@ -13,7 +13,7 @@ which is then reviewed, and accepted (or rejected). View all the merge requests within a project by navigating to **Project > Merge Requests**. When you access your project's merge requests, GitLab will present them in a list, -and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project). +and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists).  @@ -21,7 +21,7 @@ and you can use the tabs available to quickly filter by open and closed. You can View merge requests in all projects in the group, including all projects of all descendant subgroups of the group. Navigate to **Group > Merge Requests** to view these merge requests. This view also has the open and closed merge requests tabs. -You can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group) from here. +You can [search and filter the results](../../search/index.md#filtering-issue-and-merge-request-lists) from here.  @@ -85,7 +85,7 @@ specific commit page. You can append `?w=1` while on the diffs page of a merge request to ignore any whitespace changes. -## Commenting on any file line in merge requests +## Perform inline code reviews > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/13950) in GitLab 11.5. @@ -94,20 +94,7 @@ in a Merge Request. To do so, click the **...** button in the gutter of the Merg  -## Live preview with Review Apps - -If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project, -you can preview the changes submitted to a feature-branch through a merge request -in a per-branch basis. No need to checkout the branch, install and preview locally; -all your changes will be available to preview by anyone with the Review Apps link. - -With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the -merge request widget takes you directly to the pages changed, making it easier and -faster to preview proposed modifications. - -[Read more about Review Apps](../../../ci/review_apps/index.md). - -## Pipeline status in merge requests +## Pipeline status in merge requests widgets If you've set up [GitLab CI/CD](../../../ci/README.md) in your project, you will be able to see: @@ -135,6 +122,37 @@ be disabled. If the pipeline fails to deploy, the deployment info will be hidden For more information, [read about pipelines](../../../ci/pipelines.md). +### Merge when pipeline succeeds (MWPS) + +Set a merge request that looks ready to merge to [merge automatically when CI pipeline succeeds](merge_when_pipeline_succeeds.md). + +### Live preview with Review Apps + +If you configured [Review Apps](https://about.gitlab.com/product/review-apps/) for your project, +you can preview the changes submitted to a feature-branch through a merge request +in a per-branch basis. No need to checkout the branch, install and preview locally; +all your changes will be available to preview by anyone with the Review Apps link. + +With GitLab's [Route Maps](../../../ci/review_apps/index.md#route-maps) set, the +merge request widget takes you directly to the pages changed, making it easier and +faster to preview proposed modifications. + +[Read more about Review Apps](../../../ci/review_apps/index.md). + +## Associated features + +There is also a large number of features to associated to merge requests: + +| Feature | Description | +|-------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Bulk editing merge requests](../../project/bulk_editing.md) | Update the attributes of multiple merge requests simultaneously. | +| [Cherry-pick changes](cherry_pick_changes.md) | Cherry-pick any commit in the UI by simply clicking the **Cherry-pick** button in a merged merge requests or a commit. | +| [Fast-forward merge requests](fast_forward_merge.md) | For a linear Git history and a way to accept merge requests without creating merge commits | +| [Find the merge request that introduced a change](versions.md) | When viewing the commit details page, GitLab will link to the merge request(s) containing that commit. | +| [Merge requests versions](versions.md) | Select and compare the different versions of merge request diffs | +| [Resolve conflicts](resolve_conflicts.md) | GitLab can provide the option to resolve certain merge request conflicts in the GitLab UI. | +| [Revert changes](revert_changes.md) | Revert changes from any commit from within a merge request. | + ## Troubleshooting Sometimes things don't go as expected in a merge request, here are some diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md index eacc1fd12dc..82a63b07d6b 100644 --- a/doc/user/project/milestones/index.md +++ b/doc/user/project/milestones/index.md @@ -20,7 +20,7 @@ Milestones can be used as Agile sprints so that you can track all issues and mer ## Milestones as releases -Similarily, milestones can be used as releases. To do so: +Similarly, milestones can be used as releases. To do so: 1. Set the milestone due date to represent the release date of your release and leave the milestone start date blank. 1. Set the milestone title to the version of your release, such as `Version 9.4`. diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index 5f3bb83df70..d1bb23396e4 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -48,7 +48,7 @@ It is important to note that we have a few types of users: via another project's job. - **External users**: CI jobs created by [external users](../permissions.md#external-users-core-only) will have - access only to projects to which user has at least reporter access. This + access only to projects to which the user has at least Reporter access. This rules out accessing all internal projects by default. This allows us to make the CI and permission system more trustworthy. @@ -114,7 +114,7 @@ docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.gitlab.com Using single token had multiple security implications: -- The token would be readable to anyone who had developer access to a project +- The token would be readable to anyone who had Developer access to a project that could run CI jobs, allowing the developer to register any specific Runner for that project. - The token would allow to access only the project's sources, forbidding from diff --git a/doc/user/project/operations/error_tracking.md b/doc/user/project/operations/error_tracking.md index 912d7fdbef5..447d294bef8 100644 --- a/doc/user/project/operations/error_tracking.md +++ b/doc/user/project/operations/error_tracking.md @@ -53,12 +53,31 @@ From error list, users can navigate to the error details page by clicking the ti This page has: - A link to the Sentry issue. +- A link to the GitLab commit if the Sentry [release id/version](https://docs.sentry.io/workflow/releases/?platform=javascript#configure-sdk) on the Sentry Issue's first release matches a commit SHA in your GitLab hosted project. - Other details about the issue, including a full stack trace. -If the error has not been linked to an existing GitLab issue, a 'Create Issue' button will be visible: +By default, a **Create issue** button is displayed. Once you have used it to create an issue, the button is hidden. - + -If a link does exist, it will be shown in the details and the 'Create Issue' button will be hidden: +If a link does exist, it will be shown in the details and the 'Create issue' button will change to a 'View issue' button: - + + +## Taking Action on errors + +You can take action on Sentry Errors from within the GitLab UI. + +### Ignoring errors + +> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/39665) in GitLab 12.7. + +From within the [Error Details](#error-details) page you can ignore a Sentry error by simply clicking the **Ignore** button near the top of the page. + +Ignoring an error will prevent it from appearing in the [Error Tracking List](#error-tracking-list), and will silence notifications that were set up within Sentry. + +### Resolving errors + +From within the [Error Details](#error-details) page you can resolve a Sentry error by simply clicking the **Resolve** button near the top of the page. + +Marking an error as resolved indicates that the error has stopped firing events. If another event occurs, the error reverts to unresolved. diff --git a/doc/user/project/operations/feature_flags.md b/doc/user/project/operations/feature_flags.md index 723f9d69995..4d372721d72 100644 --- a/doc/user/project/operations/feature_flags.md +++ b/doc/user/project/operations/feature_flags.md @@ -1,6 +1,6 @@ # Feature Flags **(PREMIUM)** -> [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/11845) in GitLab 11.4. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/merge_requests/7433) in GitLab 11.4. Feature flags allow you to ship a project in different flavors by dynamically toggling certain functionality. @@ -51,7 +51,10 @@ with ability to edit or remove them. To make a feature flag active or inactive, click the pencil icon to edit it, and toggle the status for each [spec](#define-environment-specs). - +The toggles next to each feature flag on the list page function as global shutoff switches. +If a toggle is off, that feature flag is disabled for every environment. + + ## Define environment specs diff --git a/doc/user/project/operations/img/error_details_v12_5.png b/doc/user/project/operations/img/error_details_v12_5.png Binary files differindex 5e3e6300640..f4866141948 100644 --- a/doc/user/project/operations/img/error_details_v12_5.png +++ b/doc/user/project/operations/img/error_details_v12_5.png diff --git a/doc/user/project/operations/img/error_details_v12_6.png b/doc/user/project/operations/img/error_details_v12_6.png Binary files differindex b9152bd2c11..3194d8284d7 100644 --- a/doc/user/project/operations/img/error_details_v12_6.png +++ b/doc/user/project/operations/img/error_details_v12_6.png diff --git a/doc/user/project/operations/img/error_details_v12_7.png b/doc/user/project/operations/img/error_details_v12_7.png Binary files differnew file mode 100644 index 00000000000..1c7ace35e2a --- /dev/null +++ b/doc/user/project/operations/img/error_details_v12_7.png diff --git a/doc/user/project/operations/img/error_details_with_issue_v12_7.png b/doc/user/project/operations/img/error_details_with_issue_v12_7.png Binary files differnew file mode 100644 index 00000000000..aa846ee7220 --- /dev/null +++ b/doc/user/project/operations/img/error_details_with_issue_v12_7.png diff --git a/doc/user/project/operations/img/feature_flags_list.png b/doc/user/project/operations/img/feature_flags_list.png Binary files differdeleted file mode 100644 index f3e85b9ce44..00000000000 --- a/doc/user/project/operations/img/feature_flags_list.png +++ /dev/null diff --git a/doc/user/project/operations/img/feature_flags_list_v12_7.png b/doc/user/project/operations/img/feature_flags_list_v12_7.png Binary files differnew file mode 100644 index 00000000000..a28a844b46d --- /dev/null +++ b/doc/user/project/operations/img/feature_flags_list_v12_7.png diff --git a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md index 2f16606c5a8..c427a5dcca8 100644 --- a/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md +++ b/doc/user/project/pages/custom_domains_ssl_tls_certification/index.md @@ -134,7 +134,7 @@ If you're using CloudFlare, check `domain.com` to your GitLab Pages site. Use an `A` record instead. > - **Do not** add any special chars after the default Pages domain. E.g., don't point `subdomain.domain.com` to - or `namespace.gitlab.io/`. Some domain hosting providers may request a trailling dot (`namespace.gitlab.io.`), though. + or `namespace.gitlab.io/`. Some domain hosting providers may request a trailing dot (`namespace.gitlab.io.`), though. > - GitLab Pages IP on GitLab.com [was changed](https://about.gitlab.com/blog/2017/03/06/we-are-changing-the-ip-of-gitlab-pages-on-gitlab-com/) in 2017. > - GitLab Pages IP on GitLab.com [has changed](https://about.gitlab.com/blog/2018/07/19/gcp-move-update/#gitlab-pages-and-custom-domains) from `52.167.214.135` to `35.185.44.232` in 2018. diff --git a/doc/user/project/pages/getting_started/new_or_existing_website.md b/doc/user/project/pages/getting_started/new_or_existing_website.md index 62b5fa33117..49a330ea202 100644 --- a/doc/user/project/pages/getting_started/new_or_existing_website.md +++ b/doc/user/project/pages/getting_started/new_or_existing_website.md @@ -17,7 +17,7 @@ To do so, follow the steps below. [Pages domain names](../getting_started_part_one.md#gitlab-pages-default-domain-names). 1. Clone it to your local computer, add your website files to your project, add, commit and push to GitLab. - Alternativelly, you can run `git init` in your local directory, + Alternatively, you can run `git init` in your local directory, add the remote URL: `git remote add origin git@gitlab.com:namespace/project-name.git`, then add, commit, and push to GitLab. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 27bd9da8d18..263b20ea224 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -1,5 +1,5 @@ --- -last_updated: 2019-06-04 +last_updated: 2020-01-06 type: reference, howto --- @@ -158,7 +158,7 @@ first thing GitLab Runner will look for in your `.gitlab-ci.yml` is a your container to run that script: ```yaml -image: ruby:2.3 +image: ruby:2.7 pages: script: @@ -170,9 +170,9 @@ pages: ``` In this case, you're telling the Runner to pull this image, which -contains Ruby 2.3 as part of its file system. When you don't specify +contains Ruby 2.7 as part of its file system. When you don't specify this image in your configuration, the Runner will use a default -image, which is Ruby 2.1. +image, which is Ruby 2.6. If your SSG needs [NodeJS](https://nodejs.org/) to build, you'll need to specify which image you want to use, and this image should @@ -198,7 +198,7 @@ To do that, we need to add another line to our CI, telling the Runner to only perform that _job_ called `pages` on the `master` branch `only`: ```yaml -image: ruby:2.3 +image: ruby:2.6 pages: script: @@ -221,7 +221,7 @@ and deploy. To specify which stage your _job_ is running, simply add another line to your CI: ```yaml -image: ruby:2.3 +image: ruby:2.6 pages: stage: deploy @@ -244,7 +244,7 @@ let's add another task (_job_) to our CI, telling it to test every push to other branches, `except` the `master` branch: ```yaml -image: ruby:2.3 +image: ruby:2.6 pages: stage: deploy @@ -294,7 +294,7 @@ every single _job_. In our example, notice that we run We don't need to repeat it: ```yaml -image: ruby:2.3 +image: ruby:2.6 before_script: - bundle install @@ -329,7 +329,7 @@ cache Jekyll dependencies in a `vendor` directory when we run `bundle install`: ```yaml -image: ruby:2.3 +image: ruby:2.6 cache: paths: diff --git a/doc/user/project/pages/introduction.md b/doc/user/project/pages/introduction.md index 01e1909f6d6..37b5e77c062 100644 --- a/doc/user/project/pages/introduction.md +++ b/doc/user/project/pages/introduction.md @@ -1,6 +1,6 @@ --- type: reference -last_updated: 2018-06-04 +last_updated: 2020-01-06 --- # Exploring GitLab Pages @@ -156,7 +156,7 @@ Below is a copy of `.gitlab-ci.yml` where the most significant line is the last one, specifying to execute everything in the `pages` branch: ``` -image: ruby:2.1 +image: ruby:2.6 pages: script: diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index 97ae429a33f..a038dadd7e7 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -68,7 +68,8 @@ The following quick actions are applicable to descriptions, discussions and thre | `/remove_zoom` | ✓ | | | Remove Zoom meeting from this issue. ([Introduced in GitLab 12.4](https://gitlab.com/gitlab-org/gitlab/merge_requests/16609)) | | `/target_branch <local branch name>` | | ✓ | | Set target branch | | `/wip` | | ✓ | | Toggle the Work In Progress status | -| `/approve` | | ✓ | | Approve the merge request | +| `/approve` | | ✓ | | Approve the merge request **(STARTER)** | +| `/submit_review` | | ✓ | | Submit a pending review. ([Introduced in GitLab 12.7](https://gitlab.com/gitlab-org/gitlab/issues/8041)) **(PREMIUM)** | | `/merge` | | ✓ | | Merge (when pipeline succeeds) | | `/child_epic <epic>` | | | ✓ | Add child epic to `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/issues/7330)) **(ULTIMATE)** | | `/remove_child_epic <epic>` | | | ✓ | Remove child epic from `<epic>`. The `<epic>` value should be in the format of `&epic`, `group&epic`, or a URL to an epic. ([Introduced in GitLab 12.0](https://gitlab.com/gitlab-org/gitlab/issues/7330)) **(ULTIMATE)** | diff --git a/doc/user/project/releases/img/custom_notifications_dropdown_v12_5.png b/doc/user/project/releases/img/custom_notifications_dropdown_v12_5.png Binary files differnew file mode 100644 index 00000000000..879599a71f5 --- /dev/null +++ b/doc/user/project/releases/img/custom_notifications_dropdown_v12_5.png diff --git a/doc/user/project/releases/img/custom_notifications_new_release_v12_4.png b/doc/user/project/releases/img/custom_notifications_new_release_v12_4.png Binary files differdeleted file mode 100644 index 6b4231d5804..00000000000 --- a/doc/user/project/releases/img/custom_notifications_new_release_v12_4.png +++ /dev/null diff --git a/doc/user/project/releases/img/custom_notifications_new_release_v12_5.png b/doc/user/project/releases/img/custom_notifications_new_release_v12_5.png Binary files differnew file mode 100644 index 00000000000..d136aa710b2 --- /dev/null +++ b/doc/user/project/releases/img/custom_notifications_new_release_v12_5.png diff --git a/doc/user/project/releases/img/edit_release_page_v12_6.png b/doc/user/project/releases/img/edit_release_page_v12_6.png Binary files differindex 8b9c502a2ef..ae7641ac8a5 100644 --- a/doc/user/project/releases/img/edit_release_page_v12_6.png +++ b/doc/user/project/releases/img/edit_release_page_v12_6.png diff --git a/doc/user/project/releases/img/new_tag_12_5.png b/doc/user/project/releases/img/new_tag_12_5.png Binary files differindex 6137ad2ee56..9a6145d71c7 100644 --- a/doc/user/project/releases/img/new_tag_12_5.png +++ b/doc/user/project/releases/img/new_tag_12_5.png diff --git a/doc/user/project/releases/img/release_edit_button_v12_6.png b/doc/user/project/releases/img/release_edit_button_v12_6.png Binary files differindex f60b0ecb1be..8cc080621cf 100644 --- a/doc/user/project/releases/img/release_edit_button_v12_6.png +++ b/doc/user/project/releases/img/release_edit_button_v12_6.png diff --git a/doc/user/project/releases/img/tags_12_5.png b/doc/user/project/releases/img/tags_12_5.png Binary files differindex 4c032f96125..c9673a5232d 100644 --- a/doc/user/project/releases/img/tags_12_5.png +++ b/doc/user/project/releases/img/tags_12_5.png diff --git a/doc/user/project/releases/index.md b/doc/user/project/releases/index.md index 58e028c89be..c253210af46 100644 --- a/doc/user/project/releases/index.md +++ b/doc/user/project/releases/index.md @@ -6,7 +6,7 @@ type: reference, howto > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/issues/41766) in GitLab 11.7. -It's typical to create a [Git tag](../../../university/training/topics/tags.md) at +It is typical to create a [Git tag](../../../university/training/topics/tags.md) at the moment of release to introduce a checkpoint in your source code history, but in most cases your users will need compiled objects or other assets output by your CI system to use them, not just the raw source @@ -16,8 +16,12 @@ GitLab's **Releases** are a way to track deliverables in your project. Consider a snapshot in time of the source, build output, and other metadata or artifacts associated with a released version of your code. -At the moment, you can create Release entries via the [Releases API](../../../api/releases/index.md); -we recommend doing this as one of the last steps in your CI/CD release pipeline. +There are several ways to create a Release: + +- In the interface, when you create a new Git tag. +- In the interface, by adding a release note to an existing Git tag. +- Using the [Releases API](../../../api/releases/index.md): we recommend doing this as one of the last + steps in your CI/CD release pipeline. ## Getting started with Releases @@ -38,7 +42,7 @@ Release descriptions are unrelated. Description supports [Markdown](../../markdo You can currently add the following types of assets to each Release: -- [Source code](#source-code): state of the repo at the time of the Release +- [Source code](#source-code): state of the repository at the time of the Release - [Links](#links): to content such as built binaries or documentation GitLab will support more asset types in the future, including objects such @@ -117,11 +121,14 @@ of GitLab. You can be notified by email when a new Release is created for your project. -To subscribe to these notifications, navigate to your **Project**'s landing page, then click on the -bell icon. Choose **Custom** from the dropdown menu. The -following modal window will be then displayed, from which you can select **New release** to complete your subscription to new Releases notifications. +To subscribe to Release notifications: - +1. Navigate to your **Project**'s landing page. +1. Click the bell icon (**Notification setting**). +1. Select **Custom** from the dropdown menu. +  +1. Select **New release**. +  ## Add release notes to Git tags @@ -132,8 +139,9 @@ drag and drop files to it. Release notes are stored in GitLab's database. There are several ways to add release notes: - In the interface, when you create a new Git tag. -- In the interface, by adding a note to an existing Git tag. -- Using the GitLab API. +- In the interface, by adding a release note to an existing Git tag. +- Using the [Releases API](../../../api/releases/index.md): (we recommend doing this as one of the last + steps in your CI/CD release pipeline). To create a new tag, navigate to your project's **Repository > Tags** and click **New tag**. From there, you can fill the form with all the information @@ -154,11 +162,11 @@ parallel. This dataset will be a snapshot this new release (including linked milestones and issues) at moment of creation. Such collection of data will provide a chain of custody and facilitate processes like external audits, for example. -The gathered Evidence data is stored in the database upon creation of a new +The gathered evidence data is stored in the database upon creation of a new release as a JSON object. In GitLab 12.6, a link to -the Evidence data is provided for [each Release](#releases-list). +the evidence data is provided for [each Release](#releases-list). -Here's what this object can look like: +Here is what this object can look like: ```json { @@ -208,6 +216,22 @@ Here's what this object can look like: } ``` +### Enabling Release Evidence display **(CORE ONLY)** + +This feature comes with the `:release_evidence_collection` feature flag +disabled by default in GitLab self-managed instances. To turn it on, +ask a GitLab administrator with Rails console access to run the following +command: + +```ruby +Feature.enable(:release_evidence_collection) +``` + +NOTE: **Note:** +Please note that Release Evidence's data is collected regardless of this +feature flag, which only enables or disables the display of the data on the +Releases page. + <!-- ## Troubleshooting Include any troubleshooting steps that you can foresee. If you know beforehand what issues diff --git a/doc/user/project/repository/file_finder.md b/doc/user/project/repository/file_finder.md index 576001d4305..91e6d2912d1 100644 --- a/doc/user/project/repository/file_finder.md +++ b/doc/user/project/repository/file_finder.md @@ -37,7 +37,7 @@ the `app/controllers/admin/deploy_keys_controller.rb` file. Using fuzzy search, we start by typing letters that get us closer to the file. -**Protip:** To narrow down your search, include `/` in your search terms. +**Tip:** To narrow down your search, include `/` in your search terms.  diff --git a/doc/user/project/repository/forking_workflow.md b/doc/user/project/repository/forking_workflow.md index 4cf0e458a53..dddabfce4b3 100644 --- a/doc/user/project/repository/forking_workflow.md +++ b/doc/user/project/repository/forking_workflow.md @@ -14,7 +14,7 @@ document more information about using branches to work together. Forking a project is in most cases a two-step process. -1. Click on the fork button located located in between the star and clone buttons on the project's home page. +1. Click on the fork button located in between the star and clone buttons on the project's home page.  @@ -41,6 +41,10 @@ CAUTION: **CAUTION:** From GitLab 12.6 onwards, if the [visibility of an upstream project is reduced](../../../public_access/public_access.md#reducing-visibility) in any way, the fork relationship with all its forks will be removed. +CAUTION: **Caution:** +[Repository mirroring](repository_mirroring.md) will help to keep your fork synced with the original repository. +Before approving a merge request you'll likely to be asked to sync before getting approval, hence automating it is recommend. + ## Merging upstream Once you are ready to send your code back to the main project, you need diff --git a/doc/user/project/repository/git_blame.md b/doc/user/project/repository/git_blame.md index 454b3f86df9..4b645e4c4bc 100644 --- a/doc/user/project/repository/git_blame.md +++ b/doc/user/project/repository/git_blame.md @@ -23,6 +23,11 @@ noted information: If you hover over a commit in the UI, you'll see a precise date and time for that commit. + + +To see earlier revisions of a specific line, click **View blame prior to this change** +until you've found the changes you're interested in viewing. + ## Associated `git` command If you're running `git` from the command line, the equivalent command is diff --git a/doc/user/project/repository/img/file_blame_button_v12_6.png b/doc/user/project/repository/img/file_blame_button_v12_6.png Binary files differindex b5a18e6726f..e7aa0d1ea3f 100644 --- a/doc/user/project/repository/img/file_blame_button_v12_6.png +++ b/doc/user/project/repository/img/file_blame_button_v12_6.png diff --git a/doc/user/project/repository/img/file_blame_output_v12_6.png b/doc/user/project/repository/img/file_blame_output_v12_6.png Binary files differindex 4aca40353d5..c1186429917 100644 --- a/doc/user/project/repository/img/file_blame_output_v12_6.png +++ b/doc/user/project/repository/img/file_blame_output_v12_6.png diff --git a/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png b/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png Binary files differnew file mode 100644 index 00000000000..2da9e28c84f --- /dev/null +++ b/doc/user/project/repository/img/file_blame_previous_commit_v12_7.png diff --git a/doc/user/project/repository/img/file_history_button_v12_6.png b/doc/user/project/repository/img/file_history_button_v12_6.png Binary files differindex b5a18e6726f..e7aa0d1ea3f 100644 --- a/doc/user/project/repository/img/file_history_button_v12_6.png +++ b/doc/user/project/repository/img/file_history_button_v12_6.png diff --git a/doc/user/project/repository/img/file_history_output_v12_6.png b/doc/user/project/repository/img/file_history_output_v12_6.png Binary files differindex 9e9855203af..1a84f347a93 100644 --- a/doc/user/project/repository/img/file_history_output_v12_6.png +++ b/doc/user/project/repository/img/file_history_output_v12_6.png diff --git a/doc/user/project/repository/img/repository_mirroring_push_settings.png b/doc/user/project/repository/img/repository_mirroring_push_settings.png Binary files differindex 3c0eacaa2df..d055cc580c4 100644 --- a/doc/user/project/repository/img/repository_mirroring_push_settings.png +++ b/doc/user/project/repository/img/repository_mirroring_push_settings.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png Binary files differindex f40cc187b46..1ef210240d4 100644 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png +++ b/doc/user/project/repository/img/web_editor_new_branch_from_issue_create_button_v12_6.png diff --git a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png Binary files differindex d5a92546d40..02cadd5de4c 100644 --- a/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png +++ b/doc/user/project/repository/img/web_editor_new_branch_from_issue_v_12_6.png diff --git a/doc/user/project/repository/repository_mirroring.md b/doc/user/project/repository/repository_mirroring.md index 993c96d2ae4..6da745a8772 100644 --- a/doc/user/project/repository/repository_mirroring.md +++ b/doc/user/project/repository/repository_mirroring.md @@ -22,7 +22,7 @@ There are two kinds of repository mirroring supported by GitLab: When the mirror repository is updated, all new branches, tags, and commits will be visible in the project's activity feed. -Users with at least [developer access](../../permissions.md) to the project can also force an +Users with at least [Developer access](../../permissions.md) to the project can also force an immediate update, unless: - The mirror is already being updated. diff --git a/doc/user/project/service_desk.md b/doc/user/project/service_desk.md index fad4af7102a..e9fce474040 100644 --- a/doc/user/project/service_desk.md +++ b/doc/user/project/service_desk.md @@ -48,43 +48,65 @@ users will only see the thread through email. ## Configuring Service Desk -> **Note:** -Service Desk is enabled on GitLab.com. If you're a -[Silver subscriber](https://about.gitlab.com/pricing/#gitlab-com), -you can skip the step 1 below; you only need to enable it per project. - -1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. This must - support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). -1. Navigate to your project's **Settings > General** and scroll down to the **Service Desk** - section. -1. If you have the correct access and a Premium license, - you will see an option to set up Service Desk: - -  - -1. Checking that box will enable Service Desk for the project, and show a - unique email address to email issues to the project. These issues will be - [confidential](issues/confidential_issues.md), so they will only be visible to project members. - - **Warning**: this email address can be used by anyone to create an issue on - this project, whether or not they have access to your GitLab instance. - We recommend **putting this behind an alias** so that it can be changed if - needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab instance to add spam - checking to this service. Unblocked email spam would result in many spam +NOTE: **Note:** +Service Desk is enabled on GitLab.com. If you're a [Silver subscriber](https://about.gitlab.com/pricing/#gitlab-com), +you can skip step 1 below; you only need to enable it per project. + +If you have the correct access and a Premium license, you have the option to set up Service Desk. +Follow these steps to do so: + +1. [Set up incoming email](../../administration/incoming_email.md#set-it-up) for the GitLab instance. + This must support [email sub-addressing](../../administration/incoming_email.md#email-sub-addressing). +1. Navigate to your project's **Settings > General** and locate the **Service Desk** section. +1. Enable the **Activate Service Desk** toggle. This reveals a unique email address to email issues + to the project. These issues will be [confidential](issues/confidential_issues.md), so they will + only be visible to project members. Note that in GitLab 11.7, we updated the generated email + address's format. The older format is still supported, however, allowing existing aliases or + contacts to continue working. + + DANGER: **Danger:** + This email address can be used by anyone to create an issue on this project, whether or not they + have access to your GitLab instance. We recommend **putting this behind an alias** so it can be + changed if needed, and **[enabling Akismet](../../integration/akismet.md)** on your GitLab + instance to add spam checking to this service. Unblocked email spam would result in many spam issues being created, and may disrupt your GitLab service. + If you have [templates](description_templates.md) in your repository, you can optionally select + one from the selector menu to append it to all Service Desk issues. +  - _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._ +Service Desk is now enabled for this project! You should be able to access it from your project +navigation's **Issues** menu. + + + +### Using customized email templates + + > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/2460) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.7. + +When a user submits a new issue using Service Desk, or when a new note is created on a Service Desk issue, an email is sent to the author. + +The body of these email messages can customized by using templates. To create a new customized template, +create a new Markdown (`.md`) file inside the `.gitlab/service_desk_templates/` +directory in your repository. Commit and push to your default branch. + +#### Thank you email -1. If you have [templates](description_templates.md) in your repository, then you can optionally - select one of these templates from the dropdown to append it to all Service Desk issues. +The **Thank you email** is the email sent to a user after they submit an issue. +The file name of the template has to be `thank_you.md`. +You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue iid in the email and +`%{ISSUE_PATH}` placeholder which will be replaced by project path and the issue iid. +As the service desk issues are created as confidential (only project members can see them) +the response email doesn't provide the issue link. -1. Service Desk is now enabled for this project! You should be able to access it from your project's navigation **Issue submenu**: +#### New note email -  +The **New note email** is the email sent to a user when the issue they submitted has a new comment. +The file name of the template has to be `new_note.md`. +You can use `%{ISSUE_ID}` placeholder which will be replaced by an issue iid +in the email, `%{ISSUE_PATH}` placeholder which will be replaced by + project path and the issue iid and `%{NOTE_TEXT}` placeholder which will be replaced by the note text. ## Using Service Desk diff --git a/doc/user/project/settings/img/sharing_and_permissions_settings_v12_3.png b/doc/user/project/settings/img/sharing_and_permissions_settings_v12_3.png Binary files differdeleted file mode 100644 index cf7fdfe4cce..00000000000 --- a/doc/user/project/settings/img/sharing_and_permissions_settings_v12_3.png +++ /dev/null diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 9449ab6d10f..f5cfa256f5d 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -100,7 +100,7 @@ For more details on the specific data persisted in a project export, see the  1. Alternatively, you can come back to the project settings and download the - file from there, or generate a new export. Once the file available, the page + file from there, or generate a new export. Once the file is available, the page should show the **Download export** button:  diff --git a/doc/user/project/settings/index.md b/doc/user/project/settings/index.md index 2c7a24da8f9..4e55f55dd28 100644 --- a/doc/user/project/settings/index.md +++ b/doc/user/project/settings/index.md @@ -22,31 +22,65 @@ The project description also partially supports [standard Markdown](../../markdo ### Sharing and permissions -Set up your project's access, [visibility](../../../public_access/public_access.md), and enable [Container Registry](../../packages/container_registry/index.md) for your projects: +For your repository, you can set up features such as public access, repository features, +documentation, access permissions, and more. To do so from your project, +go to **Settings** > **General**, and expand the **Visibility, project features, permissions** +section. - +You can now change the [Project visibility](../../../public_access/public_access.md). +If you set **Project Visibility** to public, you can limit access to some features +to **Only Project Members**. In addition, you can select the option to +[Allow users to request access](../members/index.md#project-membership-and-requesting-access). CAUTION: **Caution:** -[Reducing a project's visibility level](../../../public_access/public_access.md#reducing-visibility) -will remove the fork relationship between the project and any forked project. - -If Issues are disabled, or you can't access Issues because you're not a project member, then Labels and Milestones -links will be missing from the sidebar UI. - -You can still access them with direct links if you can access Merge Requests. This is deliberate, if you can see -Issues or Merge Requests, both of which use Labels and Milestones, then you shouldn't be denied access to Labels and Milestones pages. - -Project [Snippets](../../snippets.md) are enabled by default. +If you [reduce a project's visibility level](../../../public_access/public_access.md#reducing-visibility), +that action unlinks all forks of that project. + +Use the switches to enable or disable the following features: + +| Option | More access limit options | Description | +|:----------------------------------|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Issues** | ✓ | Activates the GitLab issues tracker | +| **Repository** | ✓ | Enables [repository](../repository/) functionality | +| **Merge Requests** | ✓ | Enables [merge request](../merge_requests/) functionality; also see [Merge request settings](#merge-request-settings) | +| **Forks** | ✓ | Enables [forking](../index.md#fork-a-project) functionality | +| **Pipelines** | ✓ | Enables [CI/CD](../../../ci/README.md) functionality | +| **Container Registry** | | Activates a [registry](../../packages/container_registry/) for your docker images | +| **Git Large File Storage** | | Enables the use of [large files](../../../administration/lfs/manage_large_binaries_with_git_lfs.md#git-lfs) | +| **Packages** | | Supports configuration of a [package registry](../../../administration/packages/index.md#gitlab-package-registry-administration-premium-only) functionality | +| **Wiki** | ✓ | Enables a separate system for [documentation](../wiki/) | +| **Snippets** | ✓ | Enables [sharing of code and text](../../snippets.md) | +| **Pages** | ✓ | Allows you to [publish static websites](../pages/) | + +Some features depend on others: + +- If you disable the **Issues** option, GitLab also removes the following + features: + - **Issue Boards** + - [**Service Desk**](#service-desk-premium) **(PREMIUM)** + + NOTE: **Note:** + When the **Issues** option is disabled, you can still access **Milestones** + from merge requests. + +- Additionally, if you disable both **Issues** and **Merge Requests**, you will no + longer have access to: + - **Labels** + - **Milestones** + +- If you disable **Repository** functionality, GitLab also disables the following + features for your project: + + - **Merge Requests** + - **Pipelines** + - **Container Registry** + - **Git Large File Storage** + - **Packages** #### Disabling email notifications -You can disable all email notifications related to the project by selecting the -**Disable email notifications** checkbox. Only the project owner is allowed to change -this setting. - -### Issue settings - -Add an [issue description template](../description_templates.md#description-templates) to your project, so that every new issue will start with a custom template. +Project owners can disable all [email notifications](../../profile/notifications.md#gitlab-notification-emails) +related to the project by selecting the **Disable email notifications** checkbox. ### Merge request settings @@ -57,7 +91,8 @@ Set up your project's merge request settings: - Enable [merge request approvals](../merge_requests/merge_request_approvals.md). **(STARTER)** - Enable [merge only if pipeline succeeds](../merge_requests/merge_when_pipeline_succeeds.md). - Enable [merge only when all threads are resolved](../../discussions/index.md#only-allow-merge-requests-to-be-merged-if-all-threads-are-resolved). -- Enable [`delete source branch after merge` option by default](../merge_requests/creating_merge_requests.md#deleting-the-source-branch) +- Enable [`delete source branch after merge` option by default](../merge_requests/getting_started.md#deleting-the-source-branch) +- Configure [suggested changes commit messages](../../discussions/index.md#configure-the-commit-message-for-applied-suggestions)  diff --git a/doc/user/project/web_ide/img/commit_changes_v12_3.png b/doc/user/project/web_ide/img/commit_changes_v12_3.png Binary files differindex 0ee7da26d1a..e7dffbc7655 100644 --- a/doc/user/project/web_ide/img/commit_changes_v12_3.png +++ b/doc/user/project/web_ide/img/commit_changes_v12_3.png diff --git a/doc/user/project/web_ide/img/review_changes_v12_3.png b/doc/user/project/web_ide/img/review_changes_v12_3.png Binary files differdeleted file mode 100644 index cbc96e3dcd9..00000000000 --- a/doc/user/project/web_ide/img/review_changes_v12_3.png +++ /dev/null diff --git a/doc/user/project/web_ide/index.md b/doc/user/project/web_ide/index.md index ee96fca7fd1..8f2314bf31f 100644 --- a/doc/user/project/web_ide/index.md +++ b/doc/user/project/web_ide/index.md @@ -46,12 +46,16 @@ Single file editing is based on the [Ace Editor](https://ace.c9.io). ## Stage and commit changes After making your changes, click the **Commit** button in the bottom left to -review the list of changed files. Click on each file to review the changes and -click the tick icon to stage the file. +review the list of changed files. If you're using GitLab 12.6 or older versions, +click on each file to review the changes and tick the item to stage a file. - +From [GitLab 12.7 onwards](https://gitlab.com/gitlab-org/gitlab/issues/33441), +all your files will be automatically staged. You still have the option to unstage +changes in case you want to submit them in multiple smaller commits. To unstage +a change, simply click the **Unstage** button when a staged file is open, or click +the undo icon next to **Staged changes** to unstage all changes. -Once you have staged some changes, you can add a commit message, commit the +Once you have finalized your changes, you can add a commit message, commit the staged changes and directly create a merge request. In case you don't have write access to the selected branch, you will see a warning, but still be able to create a new branch and start a merge request. diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index 687e1850289..80f5823c095 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -38,7 +38,7 @@ automatically. For example, a title of `docs/my-page` will create a wiki page with a path `/wikis/docs/my-page`. Once you enter the page name, it's time to fill in its content. GitLab wikis -support Markdown, RDoc and AsciiDoc. For Markdown based pages, all the +support Markdown, RDoc, AsciiDoc and Org. For Markdown based pages, all the [Markdown features](../../markdown.md) are supported and for links there is some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. diff --git a/doc/user/search/img/group_issues_filter.png b/doc/user/search/img/group_issues_filter.png Binary files differdeleted file mode 100644 index 45eced79b99..00000000000 --- a/doc/user/search/img/group_issues_filter.png +++ /dev/null diff --git a/doc/user/search/img/issue_search_filter_v12_5.png b/doc/user/search/img/issue_search_filter_v12_5.png Binary files differdeleted file mode 100644 index 1e2dd3d98a3..00000000000 --- a/doc/user/search/img/issue_search_filter_v12_5.png +++ /dev/null diff --git a/doc/user/search/img/issue_search_filter_v12_7.png b/doc/user/search/img/issue_search_filter_v12_7.png Binary files differnew file mode 100644 index 00000000000..102a2e0859c --- /dev/null +++ b/doc/user/search/img/issue_search_filter_v12_7.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md index bc31052b758..d7ca43b1164 100644 --- a/doc/user/search/index.md +++ b/doc/user/search/index.md @@ -17,8 +17,8 @@ When you click **Issues**, you'll see the opened issues assigned to you straight You can search through **Open**, **Closed**, or **All** issues. -You can also filter the results using the search and filter field. This works in the same way as the ones found in the -per project pages described below. +You can also filter the results using the search and filter field, as described below in +[Filtering issue and merge request lists](#filtering-issue-and-merge-request-lists). ### Issues and MRs assigned to you or created by you @@ -27,19 +27,26 @@ on the search field on the top-right of your screen:  -### Issues and merge requests per project +### Filtering issue and merge request lists -If you want to search for issues present in a specific project, navigate to -a project's **Issues** tab, and click on the field **Search or filter results...**. It will -display a dropdown menu, from which you can add filters per author, assignee, milestone, -release, label, weight, confidentiality, and "my-reaction" (based on your emoji votes). -When done, press **Enter** on your keyboard to filter the issues. +Follow these steps to filter the **Issues** and **Merge Requests** list pages within projects and +groups: - +1. Click in the field **Search or filter results...**. +1. In the dropdown menu that appears, select the attribute you wish to filter by (for example, + author, assignee, milestone, and so on). +1. Select or type the operator to use for filtering the attribute. The following operators are + available: + - `=`: Is + - `!=`: Is not ([Introduced](https://gitlab.com/gitlab-org/gitlab/issues/18059) in GitLab 12.7) +1. Enter the text to filter the attribute by. +1. Repeat this process to filter by multiple attributes. Multiple attributes are joined by a logical + `AND`. -The same process is valid for merge requests. Navigate to your project's **Merge Requests** tab, -and click **Search or filter results...**. Merge requests can be filtered by author, assignee, -approver, milestone, release, label, "my-reaction", "work in progess" status, and target branch. +For example, filtering by Author `=` Jane and Milestone `!=` 12.6 filters for the issues where Jane +is the author and the milestone is not 12.6. + + ### Filtering by **None** / **Any** @@ -62,19 +69,10 @@ You can filter issues and merge requests by specific terms included in titles or - Limitation - For performance reasons, terms shorter than 3 chars are ignored. E.g.: searching issues for `included in titles` is same as `included titles` + - Search is limited to 4096 characters and 64 terms per query.  -### Issues and merge requests per group - -Similar to **Issues and merge requests per project**, you can also search for issues -within a group. Navigate to a group's **Issues** tab and query search results in -the same way as you do for projects. - - - -The same process is valid for merge requests. Navigate to your project's **Merge Requests** tab. - ## Search history You can view recent searches by clicking on the little arrow-clock icon, which is to the left of the search input. Click the search entry to run that search again. This feature is available for issues and merge requests. Searches are stored locally in your browser. |
