diff options
Diffstat (limited to 'doc')
293 files changed, 7252 insertions, 1582 deletions
diff --git a/doc/README.md b/doc/README.md index df11d5e49a8..7bab42bc135 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,81 +1,192 @@ # GitLab Community Edition -All technical content published by GitLab lives in the documentation, including: - -- **General Documentation** - - [User docs](#user-documentation): general documentation dedicated to regular users of GitLab - - [Admin docs](#administrator-documentation): general documentation dedicated to administrators of GitLab instances - - [Contributor docs](#contributor-documentation): general documentation on how to develop and contribute to GitLab -- [Topics](topics/index.md): pages organized per topic, gathering all the - resources already published by GitLab related to a specific subject, including - general docs, [technical articles](development/writing_documentation.md#technical-articles), - blog posts and video tutorials. -- [GitLab University](university/README.md): guides to learn Git and GitLab - through courses and videos. - -## User documentation - -- [Account Security](user/profile/account/two_factor_authentication.md) Securing your account via two-factor authentication, etc. -- [API](api/README.md) Automate GitLab via a simple and powerful API. -- [CI/CD](ci/README.md) GitLab Continuous Integration (CI) and Continuous Delivery (CD) getting started, `.gitlab-ci.yml` options, and examples. -- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab. -- [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry. -- [GitLab basics](gitlab-basics/README.md) Find step by step how to start working on your commandline and on GitLab. -- [GitLab Pages](user/project/pages/index.md) Using GitLab Pages. -- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. +[GitLab](https://about.gitlab.com/) is a Git-based fully featured platform +for software development. + +**GitLab Community Edition (CE)** is an opensource product, self-hosted, free to use. +All [GitLab products](https://about.gitlab.com/products/) contain the features +available in GitLab CE. Premium features are available in +[GitLab Enterprise Edition (EE)](https://about.gitlab.com/gitlab-ee/). + +---- + +Shortcuts to GitLab's most visited docs: + +| [GitLab CI](ci/README.md) | Other | +| :----- | :----- | +| [Quick start guide](ci/quick_start/README.md) | [API](api/README.md) | +| [Configuring `.gitlab-ci.yml`](ci/yaml/README.md) | [SSH authentication](ssh/README.md) | +| [Using Docker images](ci/docker/using_docker_images.md) | [GitLab Pages](user/project/pages/index.md) | + +## Getting started with GitLab + +- [GitLab Basics](gitlab-basics/README.md): Start working on your command line and on GitLab. +- [GitLab Workflow](workflow/README.md): Enhance your workflow with the best of GitLab Workflow. + - See also [GitLab Workflow - an overview](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/). +- [GitLab Markdown](user/markdown.md): GitLab's advanced formatting system (GitLab Flavored Markdown). +- [GitLab Slash Commands](user/project/slash_commands.md): Textual shortcuts for common actions on issues or merge requests that are usually done by clicking buttons or dropdowns in GitLab's UI. + +### User account + +- [Authentication](topics/authentication/index.md): Account security with two-factor authentication, setup your ssh keys and deploy keys for secure access to your projects. +- [Profile settings](profile/README.md): Manage your profile settings, two factor authentication and more. +- [User permissions](user/permissions.md): Learn what each role in a project (external/guest/reporter/developer/master/owner) can do. + +### Projects and groups + +- [Create a project](gitlab-basics/create-project.md) +- [Fork a project](gitlab-basics/fork-project.md) - [Importing and exporting projects between instances](user/project/settings/import_export.md). -- [Markdown](user/markdown.md) GitLab's advanced formatting system. -- [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab. -- [Permissions](user/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do. -- [Profile Settings](profile/README.md) -- [Project Services](user/project/integrations/project_services.md) Integrate a project with external services, such as CI and chat. -- [Public access](public_access/public_access.md) Learn how you can allow public and internal access to projects. -- [Snippets](user/snippets.md) Snippets allow you to create little bits of code. -- [SSH](ssh/README.md) Setup your ssh keys and deploy keys for secure access to your projects. -- [Webhooks](user/project/integrations/webhooks.md) Let GitLab notify you when new code has been pushed to your project. -- [Workflow](workflow/README.md) Using GitLab functionality and importing projects from GitHub and SVN. -- [Git Attributes](user/project/git_attributes.md) Managing Git attributes using a `.gitattributes` file. -- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf) Download a PDF describing the most used Git operations. +- [Project access](public_access/public_access.md): Setting up your project's visibility to public, internal, or private. +- [Groups](workflow/groups.md): Organize your projects in groups. + - [Create a group](gitlab-basics/create-group.md) + - [GitLab Subgroups](user/group/subgroups/index.md) +- [Search through GitLab](user/search/index.md): Search for issues, merge requests, projects, groups, todos, and issues in Issue Boards. + +### Repository + +Manage files and branches from the UI (user interface): + +- Files + - [Create a file](user/project/repository/web_editor.md#create-a-file) + - [Upload a file](user/project/repository/web_editor.md#upload-a-file) + - [File templates](user/project/repository/web_editor.md#template-dropdowns) + - [Create a directory](user/project/repository/web_editor.md#create-a-directory) + - [Start a merge request](user/project/repository/web_editor.md#tips) (when committing via UI) +- Branches + - [Create a branch](user/project/repository/web_editor.md#create-a-new-branch) + - [Protected branches](user/project/protected_branches.md#protected-branches) + +### Issues and Merge Requests (MRs) + +- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and merge requests. +- [Issues](user/project/issues/index.md) +- [Issue Board](user/project/issue_board.md) +- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests. +- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles. +- [Merge Requests](user/project/merge_requests/index.md) + - [Work In Progress Merge Requests](user/project/merge_requests/work_in_progress_merge_requests.md) + - [Merge Request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue): Resolve discussions, move discussions in a merge request to an issue, only allow merge requests to be merged if all discussions are resolved. + - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally) + - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md) +- [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date. +- [Todos](workflow/todos.md): A chronological list of to-dos that are waiting for your input, all in a simple dashboard. + +### Git and GitLab + +- [Git](topics/git/index.md): Getting started with Git, branching strategies, Git LFS, advanced use. +- [Git cheatsheet](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf): Download a PDF describing the most used Git operations. +- [GitLab Flow](workflow/gitlab_flow.md): explore the best of Git with the GitLab Flow strategy. + +### Migrate and import your projects from other platforms + +- [Importing to GitLab](workflow/importing/README.md): Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. +- [Migrating from SVN](workflow/importing/migrating_from_svn.md): Convert a SVN repository to Git and GitLab. + +## GitLab's superpowers + +Take a step ahead and dive into GitLab's advanced features. + +- [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages. +- [Snippets](user/snippets.md): Snippets allow you to create little bits of code. +- [Wikis](user/project/wiki/index.md): Enhance your repository documentation with built-in wikis. + +### Continuous Integration, Delivery, and Deployment + +- [GitLab CI](ci/README.md): Explore the features and capabilities of Continuous Integration, Continuous Delivery, and Continuous Deployment with GitLab. + - [Auto Deploy](ci/autodeploy/index.md): Configure GitLab CI for the deployment of your application. + - [Review Apps](ci/review_apps/index.md): Preview changes to your app right from a merge request. +- [GitLab Cycle Analytics](user/project/cycle_analytics.md): Cycle Analytics measures the time it takes to go from an [idea to production](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab) for each project you have. +- [GitLab Container Registry](user/project/container_registry.md): Learn how to use GitLab's built-in Container Registry. + +### Automation + +- [API](api/README.md): Automate GitLab via a simple and powerful API. +- [GitLab Webhooks](user/project/integrations/webhooks.md): Let GitLab notify you when new code has been pushed to your project. + +### Integrations + +- [Project Services](user/project/integrations/project_services.md): Integrate a project with external services, such as CI and chat. +- [GitLab Integration](integration/README.md): Integrate with multiple third-party services with GitLab to allow external issue trackers and external authentication. + +---- ## Administrator documentation -- [Access restrictions](user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols) Define which Git access protocols can be used to talk to GitLab -- [Authentication/Authorization](administration/auth/README.md) Configure - external authentication with LDAP, SAML, CAS and additional Omniauth providers. -- [Custom Git hooks](administration/custom_hooks.md) Custom Git hooks (on the filesystem) for when webhooks aren't enough. -- [Install](install/README.md) Requirements, directory structures and installation from source. -- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components. -- [Integration](integration/README.md) How to integrate with systems such as JIRA, Redmine, Twitter. -- [Issue closing pattern](administration/issue_closing_pattern.md) Customize how to close an issue from commit messages. -- [Koding](administration/integration/koding.md) Set up Koding to use with GitLab. -- [Web terminals](administration/integration/terminal.md) Provide terminal access to environments from within GitLab. -- [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars. -- [Log system](administration/logs.md) Log system. -- [Environment Variables](administration/environment_variables.md) to configure GitLab. -- [Operations](administration/operations.md) Keeping GitLab up and running. -- [Raketasks](raketasks/README.md) Backups, maintenance, automatic webhook setup and the importing of projects. -- [Repository checks](administration/repository_checks.md) Periodic Git repository checks. -- [Repository storage paths](administration/repository_storage_paths.md) Manage the paths used to store repositories. -- [Security](security/README.md) Learn what you can do to further secure your GitLab instance. -- [System hooks](system_hooks/system_hooks.md) Notifications when users, projects and keys are changed. -- [Update](update/README.md) Update guides to upgrade your installation. -- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page. -- [Header logo](customization/branded_page_and_email_header.md) Change the logo on the overall page and email header. -- [Reply by email](administration/reply_by_email.md) Allow users to comment on issues and merge requests by replying to notification emails. -- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md) Follow this guide to migrate your existing GitLab CI data to GitLab CE/EE. -- [Git LFS configuration](workflow/lfs/lfs_administration.md) -- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast. -- [GitLab Pages configuration](administration/pages/index.md) Configure GitLab Pages. -- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md) Configure GitLab and InfluxDB for measuring performance metrics. -- [GitLab performance monitoring with Prometheus](administration/monitoring/prometheus/index.md) Configure GitLab and Prometheus for measuring performance metrics. -- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests. -- [Monitoring uptime](user/admin_area/monitoring/health_check.md) Check the server status using the health check endpoint. -- [Debugging Tips](administration/troubleshooting/debug.md) Tips to debug problems when things go wrong -- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs. -- [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability. -- [Container Registry](administration/container_registry.md) Configure Docker Registry with GitLab. +Learn how to administer your GitLab instance. Regular users don't +have access to GitLab administration tools and settings. + +### Install, update, upgrade, migrate + +- [Install](install/README.md): Requirements, directory structures and installation from source. +- [Mattermost](https://docs.gitlab.com/omnibus/gitlab-mattermost/): Integrate [Mattermost](https://about.mattermost.com/) with your GitLab installation. +- [Migrate GitLab CI to CE/EE](migrate_ci_to_ce/README.md): If you have an old GitLab installation (older than 8.0), follow this guide to migrate your existing GitLab CI data to GitLab CE/EE. +- [Restart GitLab](administration/restart_gitlab.md): Learn how to restart GitLab and its components. +- [Update](update/README.md): Update guides to upgrade your installation. + +### User permissions + +- [Access restrictions](user/admin_area/settings/visibility_and_access_controls.md#enabled-git-access-protocols): Define which Git access protocols can be used to talk to GitLab +- [Authentication/Authorization](topics/authentication/index.md#gitlab-administrators): Enforce 2FA, configure external authentication with LDAP, SAML, CAS and additional Omniauth providers. + +### GitLab admins' superpowers + +- [Container Registry](administration/container_registry.md): Configure Docker Registry with GitLab. +- [Custom Git hooks](administration/custom_hooks.md): Custom Git hooks (on the filesystem) for when webhooks aren't enough. +- [Git LFS configuration](workflow/lfs/lfs_administration.md): Learn how to use LFS under GitLab. +- [GitLab Pages configuration](administration/pages/index.md): Configure GitLab Pages. +- [High Availability](administration/high_availability/README.md): Configure multiple servers for scaling or high availability. +- [User cohorts](user/admin_area/user_cohorts.md) View user activity over time. +- [Web terminals](administration/integration/terminal.md): Provide terminal access to environments from within GitLab. +- GitLab CI + - [CI admin settings](user/admin_area/settings/continuous_integration.md): Define max artifacts size and expiration time. + +### Integrations + +- [Integrations](integration/README.md): How to integrate with systems such as JIRA, Redmine, Twitter. +- [Koding](administration/integration/koding.md): Set up Koding to use with GitLab. +- [Mattermost](user/project/integrations/mattermost.md): Set up GitLab with Mattermost. + +### Monitoring + +- [GitLab performance monitoring with InfluxDB](administration/monitoring/performance/introduction.md): Configure GitLab and InfluxDB for measuring performance metrics. +- [GitLab performance monitoring with Prometheus](administration/monitoring/prometheus/index.md): Configure GitLab and Prometheus for measuring performance metrics. +- [Monitoring uptime](user/admin_area/monitoring/health_check.md): Check the server status using the health check endpoint. + +### Performance + +- [Housekeeping](administration/housekeeping.md): Keep your Git repository tidy and fast. +- [Operations](administration/operations.md): Keeping GitLab up and running. +- [Polling](administration/polling.md): Configure how often the GitLab UI polls for updates. +- [Request Profiling](administration/monitoring/performance/request_profiling.md): Get a detailed profile on slow requests. + +### Customization + +- [Adjust your instance's timezone](workflow/timezone.md): Customize the default time zone of GitLab. +- [Environment variables](administration/environment_variables.md): Supported environment variables that can be used to override their defaults values in order to configure GitLab. +- [Header logo](customization/branded_page_and_email_header.md): Change the logo on the overall page and email header. +- [Issue closing pattern](administration/issue_closing_pattern.md): Customize how to close an issue from commit messages. +- [Libravatar](customization/libravatar.md): Use Libravatar instead of Gravatar for user avatars. +- [Welcome message](customization/welcome_message.md): Add a custom welcome message to the sign-in page. + +### Admin tools + +- [Raketasks](raketasks/README.md): Backups, maintenance, automatic webhook setup and the importing of projects. + - [Backup and restore](raketasks/backup_restore.md): Backup and restore your GitLab instance. +- [Reply by email](administration/reply_by_email.md): Allow users to comment on issues and merge requests by replying to notification emails. +- [Repository checks](administration/repository_checks.md): Periodic Git repository checks. +- [Repository storage paths](administration/repository_storage_paths.md): Manage the paths used to store repositories. +- [Security](security/README.md): Learn what you can do to further secure your GitLab instance. +- [System hooks](system_hooks/system_hooks.md): Notifications when users, projects and keys are changed. + +### Troubleshooting + +- [Debugging tips](administration/troubleshooting/debug.md): Tips to debug problems when things go wrong +- [Log system](administration/logs.md): Where to look for logs. +- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md): Debug when Sidekiq appears hung and is not processing jobs. ## Contributor documentation -- [Development](development/README.md) All styleguides and explanations how to contribute. -- [Legal](legal/README.md) Contributor license agreements. +- [Development](development/README.md): All styleguides and explanations how to contribute. +- [Legal](legal/README.md): Contributor license agreements. +- [Writing documentation](development/writing_documentation.md): Contributing to GitLab Docs. diff --git a/doc/administration/auth/ldap.md b/doc/administration/auth/ldap.md index f6027b2f99e..725fc1f6076 100644 --- a/doc/administration/auth/ldap.md +++ b/doc/administration/auth/ldap.md @@ -65,14 +65,14 @@ main: # 'main' is the GitLab 'provider ID' of this LDAP server # # Example: 'Paris' or 'Acme, Ltd.' label: 'LDAP' - + # Example: 'ldap.mydomain.com' host: '_your_ldap_server' # This port is an example, it is sometimes different but it is always an integer and not a string port: 389 - uid: 'sAMAccountName' + uid: 'sAMAccountName' # This should be the attribute, not the value that maps to uid. method: 'plain' # "tls" or "ssl" or "plain" - + # Examples: 'america\\momo' or 'CN=Gitlab Git,CN=Users,DC=mydomain,DC=com' bind_dn: '_the_full_dn_of_the_user_you_will_bind_with' password: '_the_password_of_the_bind_user' diff --git a/doc/administration/environment_variables.md b/doc/administration/environment_variables.md index 76029b30dd8..b6676026d06 100644 --- a/doc/administration/environment_variables.md +++ b/doc/administration/environment_variables.md @@ -20,7 +20,6 @@ Variable | Type | Description `GITLAB_EMAIL_FROM` | string | The e-mail address used in the "From" field in e-mails sent by GitLab `GITLAB_EMAIL_DISPLAY_NAME` | string | The name used in the "From" field in e-mails sent by GitLab `GITLAB_EMAIL_REPLY_TO` | string | The e-mail address used in the "Reply-To" field in e-mails sent by GitLab -`GITLAB_EMAIL_REPLY_TO` | string | The e-mail address used in the "Reply-To" field in e-mails sent by GitLab `GITLAB_EMAIL_SUBJECT_SUFFIX` | string | The e-mail subject suffix used in e-mails sent by GitLab `GITLAB_UNICORN_MEMORY_MIN` | integer | The minimum memory threshold (in bytes) for the Unicorn worker killer `GITLAB_UNICORN_MEMORY_MAX` | integer | The maximum memory threshold (in bytes) for the Unicorn worker killer diff --git a/doc/administration/gitaly/index.md b/doc/administration/gitaly/index.md index 30a4c08508d..6c6942a7bfe 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -1,8 +1,8 @@ # Gitaly -[Gitaly](https://gitlab.com/gitlab-org/gitlay) (introduced in GitLab +[Gitaly](https://gitlab.com/gitlab-org/gitaly) (introduced in GitLab 9.0) is a service that provides high-level RPC access to Git -repositories. As of GitLab 9.0 it is still an optional component with +repositories. As of GitLab 9.1 it is still an optional component with limited scope. GitLab components that access Git repositories (gitlab-rails, @@ -11,28 +11,26 @@ not have direct access to Gitaly. ## Configuring Gitaly -The Gitaly service itself is configured via environment variables. -These variables are documented [in the gitaly +The Gitaly service itself is configured via a TOML configuration file. +This file is documented [in the gitaly repository](https://gitlab.com/gitlab-org/gitaly/blob/master/doc/configuration/README.md). -To change a Gitaly environment variable in Omnibus you can use -`gitaly['env']` in `/etc/gitlab/gitlab.rb`. Changes will be applied +To change a Gitaly setting in Omnibus you can use +`gitaly['my_setting']` in `/etc/gitlab/gitlab.rb`. Changes will be applied when you run `gitlab-ctl reconfigure`. ```ruby -gitaly['env'] = { - 'GITALY_MY_VARIABLE' => 'value' -} +gitaly['prometheus_listen_addr'] = 'localhost:9236' ``` -To change a Gitaly environment variable in installations from source -you can edit `/home/git/gitaly/env`. +To change a Gitaly setting in installations from source you can edit +`/home/git/gitaly/config.toml`. -```shell -GITALY_MY_VARIABLE='value' +```toml +prometheus_listen_addr = "localhost:9236" ``` -Changes to `/home/git/gitaly/env` are applied when you run `service +Changes to `/home/git/gitaly/config.toml` are applied when you run `service gitlab restart`. ## Configuring GitLab to not use Gitaly @@ -49,15 +47,15 @@ gitaly['enable'] = false ``` In source installations, edit `/home/git/gitlab/config/gitlab.yml` and -make sure `socket_path` in the `gitaly` section is commented out. This -does not disable the Gitaly service; it only prevents it from being -used. +make sure `enabled` in the `gitaly` section is set to 'false'. This +does not disable the Gitaly service in your init script; it only +prevents it from being used. Apply the change with `service gitlab restart`. ```yaml gitaly: - # socket_path: tmp/sockets/private/gitlay.socket + enabled: false ``` ## Disabling or enabling the Gitaly service diff --git a/doc/administration/high_availability/README.md b/doc/administration/high_availability/README.md index d5a5aef7ec0..4d3be0ab8f6 100644 --- a/doc/administration/high_availability/README.md +++ b/doc/administration/high_availability/README.md @@ -5,6 +5,20 @@ The solution you choose will be based on the level of scalability and availability you require. The easiest solutions are scalable, but not necessarily highly available. +GitLab provides a service that is usually essential to most organizations: it +enables people to collaborate on code in a timely fashion. Any downtime should +therefore be short and planned. Luckily, GitLab provides a solid setup even on +a single server without special measures. Due to the distributed nature +of Git, developers can still commit code locally even when GitLab is not +available. However, some GitLab features such as the issue tracker and +Continuous Integration are not available when GitLab is down. + +**Keep in mind that all Highly Available solutions come with a trade-off between +cost/complexity and uptime**. The more uptime you want, the more complex the +solution. And the more complex the solution, the more work is involved in +setting up and maintaining it. High availability is not free and every HA +solution should balance the costs against the benefits. + ## Architecture There are two kinds of setups: @@ -37,6 +51,10 @@ Block Device) to keep all data in sync. DRBD requires a low latency link to remain in sync. It is not advisable to attempt to run DRBD between data centers or in different cloud availability zones. +> **Note:** GitLab recommends against choosing this HA method because of the + complexity of managing DRBD and crafting automatic failover. This is + *compatible* with GitLab, but not officially *supported*. + Components/Servers Required: 2 servers/virtual machines (one active/one passive)  diff --git a/doc/administration/high_availability/database.md b/doc/administration/high_availability/database.md index c22b1af8bfb..da9687aa849 100644 --- a/doc/administration/high_availability/database.md +++ b/doc/administration/high_availability/database.md @@ -27,7 +27,7 @@ If you use a cloud-managed service, or provide your own PostgreSQL: steps on the download page. 1. Create/edit `/etc/gitlab/gitlab.rb` and use the following configuration. Be sure to change the `external_url` to match your eventual GitLab front-end - URL. + URL. If there is a directive listed below that you do not see in the configuration, be sure to add it. ```ruby external_url 'https://gitlab.example.com' @@ -39,6 +39,8 @@ If you use a cloud-managed service, or provide your own PostgreSQL: unicorn['enable'] = false sidekiq['enable'] = false redis['enable'] = false + prometheus['enable'] = false + gitaly['enable'] = false gitlab_workhorse['enable'] = false mailroom['enable'] = false diff --git a/doc/administration/high_availability/load_balancer.md b/doc/administration/high_availability/load_balancer.md index 3245988fc14..359de0efadb 100644 --- a/doc/administration/high_availability/load_balancer.md +++ b/doc/administration/high_availability/load_balancer.md @@ -13,12 +13,13 @@ you need to use with GitLab. | LB Port | Backend Port | Protocol | | ------- | ------------ | --------------- | | 80 | 80 | HTTP [^1] | -| 443 | 443 | HTTPS [^1] [^2] | +| 443 | 443 | TCP or HTTPS [^1] [^2] | | 22 | 22 | TCP | ## GitLab Pages Ports -If you're using GitLab Pages you will need some additional port configurations. +If you're using GitLab Pages with custom domain support you will need some +additional port configurations. GitLab Pages requires a separate virtual IP address. Configure DNS to point the `pages_external_url` from `/etc/gitlab/gitlab.rb` at the new virtual IP address. See the [GitLab Pages documentation][gitlab-pages] for more information. diff --git a/doc/administration/high_availability/nfs.md b/doc/administration/high_availability/nfs.md index bf1aa6b9ac5..d8e76d6ab94 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -7,21 +7,39 @@ supported natively in NFS version 4. NFSv3 also supports locking as long as Linux Kernel 2.6.5+ is used. We recommend using version 4 and do not specifically test NFSv3. -**no_root_squash**: NFS normally changes the `root` user to `nobody`. This is -a good security measure when NFS shares will be accessed by many different -users. However, in this case only GitLab will use the NFS share so it -is safe. GitLab requires the `no_root_squash` setting because we need to -manage file permissions automatically. Without the setting you will receive -errors when the Omnibus package tries to alter permissions. Note that GitLab -and other bundled components do **not** run as `root` but as non-privileged -users. The requirement for `no_root_squash` is to allow the Omnibus package to -set ownership and permissions on files, as needed. +## AWS Elastic File System + +GitLab does not recommend using AWS Elastic File System (EFS). + +Customers and users have reported that AWS EFS does not perform well for GitLab's +use-case. There are several issues that can cause problems. For these reasons +GitLab does not recommend using EFS with GitLab. + +- EFS bases allowed IOPS on volume size. The larger the volume, the more IOPS + are allocated. For smaller volumes, users may experience decent performance + for a period of time due to 'Burst Credits'. Over a period of weeks to months + credits may run out and performance will bottom out. +- For larger volumes, allocated IOPS may not be the problem. Workloads where + many small files are written in a serialized manner are not well-suited for EFS. + EBS with an NFS server on top will perform much better. + +For more details on another person's experience with EFS, see +[Amazon's Elastic File System: Burst Credits](https://www.rawkode.io/2017/04/amazons-elastic-file-system-burst-credits/) ### Recommended options When you define your NFS exports, we recommend you also add the following options: +- `no_root_squash` - NFS normally changes the `root` user to `nobody`. This is + a good security measure when NFS shares will be accessed by many different + users. However, in this case only GitLab will use the NFS share so it + is safe. GitLab recommends the `no_root_squash` setting because we need to + manage file permissions automatically. Without the setting you may receive + errors when the Omnibus package tries to alter permissions. Note that GitLab + and other bundled components do **not** run as `root` but as non-privileged + users. The recommendation for `no_root_squash` is to allow the Omnibus package + to set ownership and permissions on files, as needed. - `sync` - Force synchronous behavior. Default is asynchronous and under certain circumstances it could lead to data loss if a failure occurs before data has synced. diff --git a/doc/administration/high_availability/redis.md b/doc/administration/high_availability/redis.md index b4e7bf21e35..0e92f7c5a34 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -42,10 +42,10 @@ instances run in different machines. If you fail to provision the machines in that specific way, any issue with the shared environment can bring your entire setup down. -It is OK to run a Sentinel along with a master or slave Redis instance. -No more than one Sentinel in the same machine though. +It is OK to run a Sentinel alongside of a master or slave Redis instance. +There should be no more than one Sentinel on the same machine though. -You also need to take in consideration the underlying network topology, +You also need to take into consideration the underlying network topology, making sure you have redundant connectivity between Redis / Sentinel and GitLab instances, otherwise the networks will become a single point of failure. @@ -113,7 +113,7 @@ the Omnibus GitLab package in `5` **independent** machines, both with ### Redis setup overview You must have at least `3` Redis servers: `1` Master, `2` Slaves, and they -need to be each in a independent machine (see explanation above). +need to each be on independent machines (see explanation above). You can have additional Redis nodes, that will help survive a situation where more nodes goes down. Whenever there is only `2` nodes online, a failover @@ -232,7 +232,7 @@ Pick the one that suits your needs. This is the section where we install and setup the new Redis instances. >**Notes:** -- We assume that you install GitLab and all HA components from scratch. If you +- We assume that you have installed GitLab and all HA components from scratch. If you already have it installed and running, read how to [switch from a single-machine installation to Redis HA](#switching-from-an-existing-single-machine-installation-to-redis-ha). - Redis nodes (both master and slaves) will need the same password defined in @@ -245,10 +245,9 @@ The prerequisites for a HA Redis setup are the following: 1. Provision the minimum required number of instances as specified in the [recommended setup](#recommended-setup) section. -1. **Do NOT** install Redis or Redis Sentinel in the same machines your - GitLab application is running on. You can however opt in to install Redis - and Sentinel in the same machine (each in independent ones is recommended - though). +1. We **Do not** recommend installing Redis or Redis Sentinel in the same machines your + GitLab application is running on as this weakens your HA configuration. You can however opt in to install Redis + and Sentinel in the same machine. 1. All Redis nodes must be able to talk to each other and accept incoming connections over Redis (`6379`) and Sentinel (`26379`) ports (unless you change the default ones). @@ -492,7 +491,7 @@ which ideally should not have Redis or Sentinels on it for a HA setup. redis['master_name'] = 'gitlab-redis' ## The same password for Redis authentication you set up for the master node. - redis['password'] = 'redis-password-goes-here' + redis['master_password'] = 'redis-password-goes-here' ## A list of sentinels with `host` and `port` gitlab_rails['redis_sentinels'] = [ diff --git a/doc/administration/integration/plantuml.md b/doc/administration/integration/plantuml.md index 6515b1a264a..b21817c1fd3 100644 --- a/doc/administration/integration/plantuml.md +++ b/doc/administration/integration/plantuml.md @@ -1,6 +1,6 @@ # PlantUML & GitLab -> [Introduced][ce-7810] in GitLab 8.16. +> [Introduced][ce-8537] in GitLab 8.16. When [PlantUML](http://plantuml.com) integration is enabled and configured in GitLab we are able to create simple diagrams in AsciiDoc and Markdown documents @@ -28,7 +28,7 @@ using Tomcat: sudo apt-get install tomcat7 sudo cp target/plantuml.war /var/lib/tomcat7/webapps/plantuml.war sudo chown tomcat7:tomcat7 /var/lib/tomcat7/webapps/plantuml.war -sudo service restart tomcat7 +sudo service tomcat7 restart ``` Once the Tomcat service restarts the PlantUML service will be ready and @@ -93,3 +93,5 @@ Some parameters can be added to the AsciiDoc block definition: - *height*: Height attribute added to the img tag. Markdown does not support any parameters and will always use PNG format. + +[ce-8537]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8537
\ No newline at end of file diff --git a/doc/administration/integration/terminal.md b/doc/administration/integration/terminal.md index 3b5ee86b68b..91e844c7b42 100644 --- a/doc/administration/integration/terminal.md +++ b/doc/administration/integration/terminal.md @@ -32,7 +32,7 @@ In brief: As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of Workhorse needs to be configured to pass the `Connection` and `Upgrade` headers -through to the next one in the chain. If you installed Gitlab using Omnibus, or +through to the next one in the chain. If you installed GitLab using Omnibus, or from source, starting with GitLab 8.15, this should be done by the default configuration, so there's no need for you to do anything. @@ -58,7 +58,7 @@ document for more details. If you'd like to disable web terminal support in GitLab, just stop passing the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse proxy in the chain. For most users, this will be the NGINX server bundled with -Omnibus Gitlab, in which case, you need to: +Omnibus GitLab, in which case, you need to: * Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file * Ensure the whole block is uncommented, and then comment out or remove the diff --git a/doc/administration/polling.md b/doc/administration/polling.md new file mode 100644 index 00000000000..35aaa20df2c --- /dev/null +++ b/doc/administration/polling.md @@ -0,0 +1,24 @@ +# Polling configuration + +The GitLab UI polls for updates for different resources (issue notes, issue +titles, pipeline statuses, etc.) on a schedule appropriate to the resource. + +In "Application settings -> Real-time features" you can configure "Polling +interval multiplier". This multiplier is applied to all resources at once, +and decimal values are supported. For the sake of the examples below, we will +say that issue notes poll every 2 seconds, and issue titles poll every 5 +seconds; these are _not_ the actual values. + +- 1 is the default, and recommended for most installations. (Issue notes poll +every 2 seconds, and issue titles poll every 5 seconds.) +- 0 will disable UI polling completely. (On the next poll, clients will stop +polling for updates.) +- A value greater than 1 will slow polling down. If you see issues with +database load from lots of clients polling for updates, increasing the +multiplier from 1 can be a good compromise, rather than disabling polling +completely. (For example: If this is set to 2, then issue notes poll every 4 +seconds, and issue titles poll every 10 seconds.) +- A value between 0 and 1 will make the UI poll more frequently (so updates +will show in other sessions faster), but is **not recommended**. 1 should be +fast enough. (For example, if this is set to 0.5, then issue notes poll every +1 second, and issue titles poll every 2.5 seconds.) diff --git a/doc/administration/raketasks/github_import.md b/doc/administration/raketasks/github_import.md new file mode 100644 index 00000000000..affb4d17861 --- /dev/null +++ b/doc/administration/raketasks/github_import.md @@ -0,0 +1,36 @@ +# GitHub import + +>**Note:** +> +> - [Introduced][ce-10308] in GitLab 9.1. +> - You need a personal access token in order to retrieve and import GitHub +> projects. You can get it from: https://github.com/settings/tokens +> - You also need to pass an username as the second argument to the rake task +> which will become the owner of the project. + +To import a project from the list of your GitHub projects available: + +```bash +# Omnibus installations +sudo gitlab-rake import:github[access_token,root,foo/bar] + +# Installations from source +bundle exec rake import:github[access_token,root,foo/bar] RAILS_ENV=production +``` + +In this case, `access_token` is your GitHub personal access token, `root` +is your GitLab username, and `foo/bar` is the new GitLab namespace/project that +will get created from your GitHub project. Subgroups are also possible: `foo/foo/bar`. + + +To import a specific GitHub project (named `foo/github_repo` here): + +```bash +# Omnibus installations +sudo gitlab-rake import:github[access_token,root,foo/bar,foo/github_repo] + +# Installations from source +bundle exec rake import:github[access_token,root,foo/bar,foo/github_repo] RAILS_ENV=production +``` + +[ce-10308]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10308 diff --git a/doc/api/README.md b/doc/api/README.md index e627b6f2ee8..1b0f6470b13 100644 --- a/doc/api/README.md +++ b/doc/api/README.md @@ -61,8 +61,9 @@ The following documentation is for the [internal CI API](ci/README.md): ## Authentication -All API requests require authentication via a session cookie or token. There are -three types of tokens available: private tokens, OAuth 2 tokens, and personal +Most API requests require authentication via a session cookie or token. For those cases where it is not required, this will be mentioned in the documentation +for each individual endpoint. For example, the [`/projects/:id` endpoint](projects.md). +There are three types of tokens available: private tokens, OAuth 2 tokens, and personal access tokens. If authentication information is invalid or omitted, an error message will be @@ -303,6 +304,17 @@ Additional pagination headers are also sent back. | `X-Next-Page` | The index of the next page | | `X-Prev-Page` | The index of the previous page | +## Namespaced path encoding + +If using namespaced API calls, make sure that the `NAMESPACE/PROJECT_NAME` is +URL-encoded. + +For example, `/` is represented by `%2F`: + +``` +/api/v4/projects/diaspora%2Fdiaspora +``` + ## `id` vs `iid` When you work with the API, you may notice two similar fields in API entities: @@ -398,7 +410,6 @@ Content-Type: application/json } ``` - ## Clients There are many unofficial GitLab API Clients for most of the popular diff --git a/doc/api/access_requests.md b/doc/api/access_requests.md index 96b8d654c58..603fa4a8194 100644 --- a/doc/api/access_requests.md +++ b/doc/api/access_requests.md @@ -1,4 +1,4 @@ -# Group and project access requests +# Group and project access requests API >**Note:** This feature was introduced in GitLab 8.11 @@ -25,7 +25,7 @@ GET /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/access_requests @@ -66,7 +66,7 @@ POST /projects/:id/access_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/:id/access_requests @@ -97,7 +97,7 @@ PUT /projects/:id/access_requests/:user_id/approve | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | | `access_level` | integer | no | A valid access level (defaults: `30`, developer access level) | @@ -130,7 +130,7 @@ DELETE /projects/:id/access_requests/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the access requester | ```bash diff --git a/doc/api/award_emoji.md b/doc/api/award_emoji.md index f57928d3c93..d6924741ee4 100644 --- a/doc/api/award_emoji.md +++ b/doc/api/award_emoji.md @@ -1,4 +1,4 @@ -# Award Emoji +# Award Emoji API > [Introduced][ce-4575] in GitLab 8.9, Snippet support in 8.12 @@ -23,7 +23,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | ```bash @@ -83,7 +83,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | | `award_id` | integer | yes | The ID of the award emoji | @@ -126,7 +126,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `awardable_id` | integer | yes | The ID (`iid` for merge requests/issues, `id` for snippets) of an awardable | | `name` | string | yes | The name of the emoji, without colons | @@ -152,7 +152,7 @@ Example Response: "updated_at": "2016-06-17T17:47:29.266Z", "awardable_id": 80, "awardable_type": "Issue" -} +} ``` ### Delete an award emoji @@ -170,7 +170,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 an issue | | `award_id` | integer | yes | The ID of a award_emoji | @@ -195,7 +195,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 an issue | | `note_id` | integer | yes | The ID of an note | @@ -237,7 +237,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 an issue | | `note_id` | integer | yes | The ID of a note | | `award_id` | integer | yes | The ID of the award emoji | @@ -277,7 +277,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 an issue | | `note_id` | integer | yes | The ID of a note | | `name` | string | yes | The name of the emoji, without colons | @@ -320,7 +320,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 an issue | | `note_id` | integer | yes | The ID of a note | | `award_id` | integer | yes | The ID of a award_emoji | diff --git a/doc/api/boards.md b/doc/api/boards.md index b2106463639..69c47abc806 100644 --- a/doc/api/boards.md +++ b/doc/api/boards.md @@ -1,4 +1,4 @@ -# Boards +# Issue Boards API Every API call to boards must be authenticated. @@ -15,7 +15,7 @@ GET /projects/:id/boards | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/:id/boards @@ -71,7 +71,7 @@ GET /projects/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | ```bash @@ -122,7 +122,7 @@ GET /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id`| integer | yes | The ID of a board's list | @@ -154,7 +154,7 @@ POST /projects/:id/boards/:board_id/lists | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `label_id` | integer | yes | The ID of a label | @@ -186,7 +186,7 @@ PUT /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | | `position` | integer | yes | The position of the list | @@ -219,7 +219,7 @@ DELETE /projects/:id/boards/:board_id/lists/:list_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `board_id` | integer | yes | The ID of a board | | `list_id` | integer | yes | The ID of a board's list | diff --git a/doc/api/branches.md b/doc/api/branches.md index 815aabda8e3..325d0ea4ce3 100644 --- a/doc/api/branches.md +++ b/doc/api/branches.md @@ -1,4 +1,4 @@ -# Branches +# Branches API ## List repository branches @@ -12,7 +12,7 @@ GET /projects/:id/repository/branches | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/5/repository/branches @@ -59,7 +59,7 @@ GET /projects/:id/repository/branches/:branch | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `branch` | string | yes | The name of the branch | ```bash @@ -109,7 +109,7 @@ curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `branch` | string | yes | The name of the branch | | `developers_can_push` | boolean | no | Flag if developers can push to the branch | | `developers_can_merge` | boolean | no | Flag if developers can merge to the branch | @@ -157,7 +157,7 @@ curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `branch` | string | yes | The name of the branch | Example response: @@ -195,7 +195,7 @@ POST /projects/:id/repository/branches | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `branch` | string | yes | The name of the branch | | `ref` | string | yes | The branch name or commit SHA to create branch from | @@ -238,7 +238,7 @@ DELETE /projects/:id/repository/branches/:branch | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `branch` | string | yes | The name of the branch | In case of an error, an explaining message is provided. @@ -257,7 +257,7 @@ DELETE /projects/:id/repository/merged_branches | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash diff --git a/doc/api/broadcast_messages.md b/doc/api/broadcast_messages.md index ad254e3515e..a8a248a17f4 100644 --- a/doc/api/broadcast_messages.md +++ b/doc/api/broadcast_messages.md @@ -1,4 +1,4 @@ -# Broadcast Messages +# Broadcast Messages API > **Note:** This feature was introduced in GitLab 8.12. diff --git a/doc/api/build_variables.md b/doc/api/build_variables.md index 1c26e9b33ab..2aaf1c93705 100644 --- a/doc/api/build_variables.md +++ b/doc/api/build_variables.md @@ -1,4 +1,4 @@ -# Build Variables +# Build Variables API ## List project variables @@ -10,7 +10,7 @@ GET /projects/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/variables" @@ -39,7 +39,7 @@ GET /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ``` @@ -63,7 +63,7 @@ POST /projects/:id/variables | Attribute | Type | required | Description | |-----------|---------|----------|-----------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable; must have no more than 255 characters; only `A-Z`, `a-z`, `0-9`, and `_` are allowed | | `value` | string | yes | The `value` of a variable | @@ -88,7 +88,7 @@ PUT /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | | `value` | string | yes | The `value` of a variable | @@ -113,7 +113,7 @@ DELETE /projects/:id/variables/:key | Attribute | Type | required | Description | |-----------|---------|----------|-------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID of a project or [urlencoded NAMESPACE/PROJECT_NAME of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key` | string | yes | The `key` of a variable | ``` diff --git a/doc/api/ci/lint.md b/doc/api/ci/lint.md index 74def207816..6a4dca92cfe 100644 --- a/doc/api/ci/lint.md +++ b/doc/api/ci/lint.md @@ -1,4 +1,4 @@ -# Validate the .gitlab-ci.yml +# Validate the .gitlab-ci.yml (API) > [Introduced][ce-5953] in GitLab 8.12. diff --git a/doc/api/ci/runners.md b/doc/api/ci/runners.md index 16028d1f124..342c039dad8 100644 --- a/doc/api/ci/runners.md +++ b/doc/api/ci/runners.md @@ -1,4 +1,4 @@ -# Runners API +# Register and Delete Runners API API used by Runners to register and delete themselves. diff --git a/doc/api/commits.md b/doc/api/commits.md index 24c402346b1..9cb58dd3ae9 100644 --- a/doc/api/commits.md +++ b/doc/api/commits.md @@ -10,7 +10,7 @@ GET /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `ref_name` | string | no | The name of a repository branch or tag or if not given the default branch | | `since` | string | no | Only commits after or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | | `until` | string | no | Only commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ | @@ -68,7 +68,7 @@ POST /projects/:id/repository/commits | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `branch` | string | yes | The name of a branch | | `commit_message` | string | yes | Commit message | | `actions[]` | array | yes | An array of action hashes to commit as a batch. See the next table for what attributes it can take. | @@ -155,7 +155,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -203,7 +203,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash | | `branch` | string | yes | The name of the branch | @@ -245,7 +245,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -281,7 +281,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit hash or name of a repository branch or tag | ```bash @@ -330,7 +330,7 @@ POST /projects/:id/repository/commits/:sha/comments | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA or name of a repository branch or tag | | `note` | string | yes | The text of the comment | | `path` | string | no | The file path relative to the repository | @@ -375,7 +375,7 @@ GET /projects/:id/repository/commits/:sha/statuses | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `ref` | string | no | The name of a repository branch or tag or, if not given, the default branch | `stage` | string | no | Filter by [build stage](../ci/yaml/README.md#stages), e.g., `test` @@ -449,7 +449,7 @@ POST /projects/:id/statuses/:sha | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of a project or NAMESPACE/PROJECT_NAME owned by the authenticated user +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | `sha` | string | yes | The commit SHA | `state` | string | yes | The state of the status. Can be one of the following: `pending`, `running`, `success`, `failed`, `canceled` | `ref` | string | no | The `ref` (branch or tag) to which the status refers diff --git a/doc/api/deploy_key_multiple_projects.md b/doc/api/deploy_key_multiple_projects.md index f94dbfa4059..127f9a196de 100644 --- a/doc/api/deploy_key_multiple_projects.md +++ b/doc/api/deploy_key_multiple_projects.md @@ -1,4 +1,4 @@ -# Adding deploy keys to multiple projects +# Adding deploy keys to multiple projects via API If you want to easily add the same deploy key to multiple projects in the same group, this can be achieved quite easily with the API. diff --git a/doc/api/deploy_keys.md b/doc/api/deploy_keys.md index f051f55ac3e..4fa800ecb9c 100644 --- a/doc/api/deploy_keys.md +++ b/doc/api/deploy_keys.md @@ -1,4 +1,4 @@ -# Deploy Keys +# Deploy Keys API ## List all deploy keys @@ -43,7 +43,7 @@ GET /projects/:id/deploy_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/deploy_keys" @@ -82,7 +82,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```bash @@ -114,7 +114,7 @@ POST /projects/:id/deploy_keys | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `title` | string | yes | New deploy key's title | | `key` | string | yes | New deploy key | | `can_push` | boolean | no | Can deploy key push to the project's repository | @@ -145,7 +145,7 @@ DELETE /projects/:id/deploy_keys/:key_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | ```bash @@ -162,7 +162,7 @@ curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitla | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `key_id` | integer | yes | The ID of the deploy key | Example response: diff --git a/doc/api/deployments.md b/doc/api/deployments.md index 76e18c8a9bd..ab9e63e01d3 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -10,7 +10,7 @@ GET /projects/:id/deployments | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/deployments" @@ -48,7 +48,6 @@ Example of response "bio": null, "created_at": "2016-08-11T07:09:20.351Z", "id": 1, - "is_admin": true, "linkedin": "", "location": null, "name": "Administrator", @@ -106,7 +105,6 @@ Example of response "bio": null, "created_at": "2016-08-11T07:09:20.351Z", "id": 1, - "is_admin": true, "linkedin": "", "location": null, "name": "Administrator", @@ -147,7 +145,7 @@ GET /projects/:id/deployments/:deployment_id | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `deployment_id` | integer | yes | The ID of the deployment | ```bash @@ -195,7 +193,6 @@ Example of response "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", "web_url": "http://localhost:3000/root", "created_at": "2016-08-11T07:09:20.351Z", - "is_admin": true, "bio": null, "location": null, "skype": "", diff --git a/doc/api/enviroments.md b/doc/api/enviroments.md index 3f0a8d989f9..5ca766bf87d 100644 --- a/doc/api/enviroments.md +++ b/doc/api/enviroments.md @@ -1,4 +1,4 @@ -# Environments +# Environments API ## List environments @@ -10,7 +10,7 @@ GET /projects/:id/environments | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/environments @@ -41,7 +41,7 @@ POST /projects/:id/environment | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the environment | | `external_url` | string | no | Place to link to for this environment | @@ -72,7 +72,7 @@ PUT /projects/:id/environments/:environments_id | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | The ID of the environment | | `name` | string | no | The new name of the environment | | `external_url` | string | no | The new external_url | @@ -102,7 +102,7 @@ DELETE /projects/:id/environments/:environment_id | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | ```bash @@ -119,7 +119,7 @@ POST /projects/:id/environments/:environment_id/stop | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `environment_id` | integer | yes | The ID of the environment | ```bash diff --git a/doc/api/groups.md b/doc/api/groups.md index dfc6b80bfd9..2b3d8e125c8 100644 --- a/doc/api/groups.md +++ b/doc/api/groups.md @@ -1,4 +1,4 @@ -# Groups +# Groups API ## List groups @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or path of a group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | | `archived` | boolean | no | Limit by archived status | | `visibility` | string | no | Limit by visibility `public`, `internal`, or `private` | | `order_by` | string | no | Return projects ordered by `id`, `name`, `path`, `created_at`, `updated_at`, or `last_activity_at` fields. Default is `created_at` | @@ -119,7 +119,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or path of a group | +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/groups/4 @@ -299,7 +299,7 @@ POST /groups/:id/projects/:project_id Parameters: -- `id` (required) - The ID or path of a group +- `id` (required) - The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user - `project_id` (required) - The ID or path of a project ## Update group diff --git a/doc/api/issues.md b/doc/api/issues.md index a19c965a8c3..3f949ca5667 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -1,4 +1,4 @@ -# Issues +# Issues API Every API call to issues must be authenticated. @@ -26,16 +26,18 @@ GET /issues?labels=foo,bar&state=opened GET /issues?milestone=1.0.0 GET /issues?milestone=1.0.0&state=opened GET /issues?iids[]=42&iids[]=43 +GET /issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `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. `No+Label` lists all issues with no labels | -| `milestone` | string| no | The milestone title | -| `iids` | Array[integer] | no | Return only the issues having the given `iid` | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| `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. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `iids` | Array[integer] | no | Return only the issues having the given `iid` | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search issues against their `title` and `description` | ```bash curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/issues @@ -68,6 +70,14 @@ Example response: "updated_at" : "2016-01-04T15:31:39.996Z" }, "project_id" : 1, + "assignees" : [{ + "state" : "active", + "id" : 1, + "name" : "Administrator", + "web_url" : "https://gitlab.example.com/root", + "avatar_url" : null, + "username" : "root" + }], "assignee" : { "state" : "active", "id" : 1, @@ -90,6 +100,8 @@ Example response: ] ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## List group issues Get a list of a group's issues. @@ -104,17 +116,19 @@ GET /groups/:id/issues?labels=foo,bar&state=opened GET /groups/:id/issues?milestone=1.0.0 GET /groups/:id/issues?milestone=1.0.0&state=opened GET /groups/:id/issues?iids[]=42&iids[]=43 +GET /groups/:id/issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a group | -| `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. `No+Label` lists all issues with no labels | -| `iids` | Array[integer] | no | Return only the issues having the given `iid` | -| `milestone` | string| no | The milestone title | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the group](README.md#namespaced-path-encoding) owned by the authenticated user | +| `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. `No+Label` lists all issues with no labels | +| `iids` | Array[integer] | no | Return only the issues having the given `iid` | +| `milestone` | string | no | The milestone title | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search group issues against their `title` and `description` | ```bash @@ -149,6 +163,14 @@ Example response: "description" : "Omnis vero earum sunt corporis dolor et placeat.", "state" : "closed", "iid" : 1, + "assignees" : [{ + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }], "assignee" : { "avatar_url" : null, "web_url" : "https://gitlab.example.com/lennie", @@ -170,6 +192,8 @@ Example response: ] ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## List project issues Get a list of a project's issues. @@ -184,17 +208,19 @@ GET /projects/:id/issues?labels=foo,bar&state=opened GET /projects/:id/issues?milestone=1.0.0 GET /projects/:id/issues?milestone=1.0.0&state=opened GET /projects/:id/issues?iids[]=42&iids[]=43 +GET /projects/:id/issues?search=issue+title+or+description ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `iids` | Array[integer] | no | Return only the milestone having the given `iid` | -| `state` | string | no | Return all issues or just those that are `opened` or `closed`| -| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | -| `milestone` | string| no | The milestone title | -| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | -| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| Attribute | Type | Required | Description | +|-------------|----------------|----------|-----------------------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `iids` | Array[integer] | no | Return only the milestone having the given `iid` | +| `state` | string | no | Return all issues or just those that are `opened` or `closed` | +| `labels` | string | no | Comma-separated list of label names, issues must have all labels to be returned. `No+Label` lists all issues with no labels | +| `milestone` | string | no | The milestone title | +| `order_by` | string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `search` | string | no | Search project issues against their `title` and `description` | ```bash @@ -229,6 +255,14 @@ Example response: "description" : "Omnis vero earum sunt corporis dolor et placeat.", "state" : "closed", "iid" : 1, + "assignees" : [{ + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }], "assignee" : { "avatar_url" : null, "web_url" : "https://gitlab.example.com/lennie", @@ -250,6 +284,8 @@ Example response: ] ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Single issue Get a single project issue. @@ -259,8 +295,8 @@ GET /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -294,6 +330,14 @@ Example response: "description" : "Omnis vero earum sunt corporis dolor et placeat.", "state" : "closed", "iid" : 1, + "assignees" : [{ + "avatar_url" : null, + "web_url" : "https://gitlab.example.com/lennie", + "state" : "active", + "username" : "lennie", + "id" : 9, + "name" : "Dr. Luella Kovacek" + }], "assignee" : { "avatar_url" : null, "web_url" : "https://gitlab.example.com/lennie", @@ -315,6 +359,8 @@ Example response: } ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## New issue Creates a new project issue. @@ -323,19 +369,19 @@ Creates a new project issue. POST /projects/:id/issues ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | -| `title` | string | yes | The title of an issue | -| `description` | string | no | The description of an issue | -| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | -| `assignee_id` | integer | no | The ID of a user to assign issue | -| `milestone_id` | integer | no | The ID of a milestone to assign issue | -| `labels` | string | no | Comma-separated label names for an issue | -| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | -| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | -| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values. | -| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | +| Attribute | Type | Required | Description | +|-------------------------------------------|----------------|----------|--------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `title` | string | yes | The title of an issue | +| `description` | string | no | The description of an issue | +| `confidential` | boolean | no | Set an issue to be confidential. Default is `false`. | +| `assignee_ids` | Array[integer] | no | The ID of the users to assign issue | +| `milestone_id` | integer | no | The ID of a milestone to assign issue | +| `labels` | string | no | Comma-separated label names for an issue | +| `created_at` | string | no | Date time string, ISO 8601 formatted, e.g. `2016-03-11T03:45:40Z` (requires admin or project owner rights) | +| `due_date` | string | no | Date time string in the format YEAR-MONTH-DAY, e.g. `2016-03-11` | +| `merge_request_to_resolve_discussions_of` | integer | no | The IID of a merge request in which to resolve all issues. This will fill the issue with a default description and mark all discussions as resolved. When passing a description or title, these values will take precedence over the default values.| +| `discussion_to_resolve` | string | no | The ID of a discussion to resolve. This will fill in the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`. | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/4/issues?title=Issues%20with%20auth&labels=bug @@ -351,6 +397,7 @@ Example response: "iid" : 14, "title" : "Issues with auth", "state" : "opened", + "assignees" : [], "assignee" : null, "labels" : [ "bug" @@ -374,6 +421,8 @@ Example response: } ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Edit issue Updates an existing project issue. This call is also used to mark an issue as @@ -384,13 +433,13 @@ PUT /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|----------------|---------|----------|------------------------------------------------------------------------------------------------------------| +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `issue_iid` | integer | yes | The internal ID of a project's issue | | `title` | string | no | The title of an issue | | `description` | string | no | The description of an issue | | `confidential` | boolean | no | Updates an issue to be confidential | -| `assignee_id` | integer | no | The ID of a user to assign the issue to | +| `assignee_ids` | Array[integer] | no | The ID of the users to assign the issue to | | `milestone_id` | integer | no | The ID of a milestone to assign the issue to | | `labels` | string | no | Comma-separated label names for an issue | | `state_event` | string | no | The state event of an issue. Set `close` to close the issue and `reopen` to reopen it | @@ -424,6 +473,7 @@ Example response: "bug" ], "id" : 85, + "assignees" : [], "assignee" : null, "milestone" : null, "subscribed" : true, @@ -434,6 +484,8 @@ Example response: } ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Delete an issue Only for admins and project owners. Soft deletes the issue in question. @@ -443,8 +495,8 @@ DELETE /projects/:id/issues/:issue_iid ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -465,8 +517,8 @@ POST /projects/:id/issues/:issue_iid/move ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-----------------|---------|----------|--------------------------------------| +| `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 | | `to_project_id` | integer | yes | The ID of the new project | @@ -488,6 +540,14 @@ Example response: "updated_at": "2016-04-07T12:20:17.596Z", "labels": [], "milestone": null, + "assignees": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "assignee": { "name": "Miss Monserrate Beier", "username": "axel.block", @@ -510,6 +570,8 @@ Example response: } ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Subscribe to an issue Subscribes the authenticated user to an issue to receive notifications. @@ -521,8 +583,8 @@ POST /projects/:id/issues/:issue_iid/subscribe ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -543,6 +605,14 @@ Example response: "updated_at": "2016-04-07T12:20:17.596Z", "labels": [], "milestone": null, + "assignees": [{ + "name": "Miss Monserrate Beier", + "username": "axel.block", + "id": 12, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/46f6f7dc858ada7be1853f7fb96e81da?s=80&d=identicon", + "web_url": "https://gitlab.example.com/axel.block" + }], "assignee": { "name": "Miss Monserrate Beier", "username": "axel.block", @@ -565,6 +635,8 @@ Example response: } ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Unsubscribe from an issue Unsubscribes the authenticated user from the issue to not receive notifications @@ -576,8 +648,8 @@ POST /projects/:id/issues/:issue_iid/unsubscribe ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -595,8 +667,8 @@ POST /projects/:id/issues/:issue_iid/todo ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -646,6 +718,14 @@ Example response: "updated_at": "2016-06-17T07:47:33.832Z", "due_date": null }, + "assignees": [{ + "name": "Jarret O'Keefe", + "username": "francisca", + "id": 14, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/a7fa515d53450023c83d62986d0658a8?s=80&d=identicon", + "web_url": "https://gitlab.example.com/francisca" + }], "assignee": { "name": "Jarret O'Keefe", "username": "francisca", @@ -677,6 +757,8 @@ Example response: } ``` +**Note**: `assignee` column is deprecated, now we show it as a single-sized array `assignees` to conform to the GitLab EE API. + ## Set a time estimate for an issue Sets an estimated time of work for this issue. @@ -686,8 +768,8 @@ POST /projects/:id/issues/:issue_iid/time_estimate ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|------------------------------------------| +| `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 | | `duration` | string | yes | The duration in human format. e.g: 3h30m | @@ -715,8 +797,8 @@ POST /projects/:id/issues/:issue_iid/reset_time_estimate ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -743,8 +825,8 @@ POST /projects/:id/issues/:issue_iid/add_spent_time ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|------------------------------------------| +| `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 | | `duration` | string | yes | The duration in human format. e.g: 3h30m | @@ -772,8 +854,8 @@ POST /projects/:id/issues/:issue_iid/reset_spent_time ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -798,8 +880,8 @@ GET /projects/:id/issues/:issue_iid/time_stats ``` | Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +|-------------|---------|----------|--------------------------------------| +| `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 | ```bash @@ -817,6 +899,67 @@ Example response: } ``` +## List merge requests that will close issue on merge + +Get all the merge requests that will close issue when merged. + +``` +GET /projects/:id/issues/:issue_iid/closed_by +``` + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `issue_iid` | integer | yes | The internal ID of a project issue | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/issues/11/closed_by +``` + +Example response: + +```json +[ + { + "id": 6471, + "iid": 6432, + "project_id": 1, + "title": "add a test for cgi lexer options", + "description": "closes #11", + "state": "opened", + "created_at": "2017-04-06T18:33:34.168Z", + "updated_at": "2017-04-09T20:10:24.983Z", + "target_branch": "master", + "source_branch": "feature.custom-highlighting", + "upvotes": 0, + "downvotes": 0, + "author": { + "name": "Administrator", + "username": "root", + "id": 1, + "state": "active", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon", + "web_url": "https://gitlab.example.com/root" + }, + "assignee": null, + "source_project_id": 1, + "target_project_id": 1, + "labels": [], + "work_in_progress": false, + "milestone": null, + "merge_when_pipeline_succeeds": false, + "merge_status": "unchecked", + "sha": "5a62481d563af92b8e32d735f2fa63b94e806835", + "merge_commit_sha": null, + "user_notes_count": 1, + "should_remove_source_branch": null, + "force_remove_source_branch": false, + "web_url": "https://gitlab.example.com/gitlab-org/gitlab-test/merge_requests/6432" + } +] +``` + + ## Comments on issues Comments are done via the [notes](notes.md) resource. diff --git a/doc/api/jobs.md b/doc/api/jobs.md index 7340123e09d..297115e94ac 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -10,8 +10,8 @@ GET /projects/:id/jobs | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | -| `scope` | string **or** array of strings | no | The scope of jobs to show, one or array of: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`; showing all jobs if none provided | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string **or** array of strings | no | The scope of jobs to show, one or array of: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `manual`; showing all jobs if none provided | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/1/jobs?scope[]=pending&scope[]=running' @@ -57,7 +57,6 @@ Example of response "bio": null, "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "is_admin": true, "linkedin": "", "name": "Administrator", "skype": "", @@ -101,7 +100,6 @@ Example of response "bio": null, "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "is_admin": true, "linkedin": "", "name": "Administrator", "skype": "", @@ -120,14 +118,14 @@ Example of response Get a list of jobs for a pipeline. ``` -GET /projects/:id/pipeline/:pipeline_id/jobs +GET /projects/:id/pipelines/:pipeline_id/jobs ``` | Attribute | Type | Required | Description | |---------------|--------------------------------|----------|----------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | -| `scope` | string **or** array of strings | no | The scope of jobs to show, one or array of: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`; showing all jobs if none provided | +| `scope` | string **or** array of strings | no | The scope of jobs to show, one or array of: `created`, `pending`, `running`, `failed`, `success`, `canceled`, `skipped`, `manual`; showing all jobs if none provided | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" 'https://gitlab.example.com/api/v4/projects/1/pipelines/6/jobs?scope[]=pending&scope[]=running' @@ -173,7 +171,6 @@ Example of response "bio": null, "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "is_admin": true, "linkedin": "", "name": "Administrator", "skype": "", @@ -217,7 +214,6 @@ Example of response "bio": null, "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "is_admin": true, "linkedin": "", "name": "Administrator", "skype": "", @@ -241,7 +237,7 @@ GET /projects/:id/jobs/:job_id | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | ``` @@ -284,7 +280,6 @@ Example of response "bio": null, "created_at": "2015-12-21T13:14:24.077Z", "id": 1, - "is_admin": true, "linkedin": "", "name": "Administrator", "skype": "", @@ -309,7 +304,7 @@ GET /projects/:id/jobs/:job_id/artifacts | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | ``` @@ -340,7 +335,7 @@ Parameters | Attribute | Type | Required | Description | |-------------|---------|----------|-------------------------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `ref_name` | string | yes | The ref from a repository | | `job` | string | yes | The name of the job | @@ -369,7 +364,7 @@ GET /projects/:id/jobs/:job_id/trace | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| id | integer | yes | The ID of a project | +| id | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | job_id | integer | yes | The ID of a job | ``` @@ -393,7 +388,7 @@ POST /projects/:id/jobs/:job_id/cancel | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | ``` @@ -439,7 +434,7 @@ POST /projects/:id/jobs/:job_id/retry | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | ``` @@ -487,7 +482,7 @@ Parameters | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | Example of request @@ -537,7 +532,7 @@ Parameters | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | Example request: @@ -585,7 +580,7 @@ POST /projects/:id/jobs/:job_id/play | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `job_id` | integer | yes | The ID of a job | ``` diff --git a/doc/api/keys.md b/doc/api/keys.md index 3b55c2baf56..376ac27df3a 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -1,4 +1,4 @@ -# Keys +# Keys API ## Get SSH key with user by ID of an SSH key @@ -26,7 +26,6 @@ Parameters: "avatar_url": "http://www.gravatar.com/avatar/cfa35b8cd2ec278026357769582fa563?s=40\u0026d=identicon", "web_url": "http://localhost:3000/john_smith", "created_at": "2015-09-03T07:24:01.670Z", - "is_admin": false, "bio": null, "skype": "", "linkedin": "", diff --git a/doc/api/labels.md b/doc/api/labels.md index 839000a4f48..ec93cf50e7a 100644 --- a/doc/api/labels.md +++ b/doc/api/labels.md @@ -1,4 +1,4 @@ -# Labels +# Labels API ## List labels @@ -10,7 +10,7 @@ GET /projects/:id/labels | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | 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: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/projects/1/labels @@ -88,7 +88,7 @@ POST /projects/:id/labels | Attribute | Type | Required | Description | | ------------- | ------- | -------- | ---------------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | | `color` | string | yes | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | | `description` | string | no | The description of the label | @@ -124,7 +124,7 @@ DELETE /projects/:id/labels | Attribute | Type | Required | Description | | --------- | ------- | -------- | --------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the label | ```bash @@ -142,7 +142,7 @@ PUT /projects/:id/labels | Attribute | Type | Required | Description | | --------------- | ------- | --------------------------------- | ------------------------------- | -| `id` | integer | yes | The ID of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `name` | string | yes | The name of the existing label | | `new_name` | string | yes if `color` is not provided | The new name of the label | | `color` | string | yes if `new_name` is not provided | The color of the label given in 6-digit hex notation with leading '#' sign (e.g. #FFAABB) or one of the [CSS color names](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value#Color_keywords) | @@ -182,7 +182,7 @@ POST /projects/:id/labels/:label_id/subscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```bash @@ -217,7 +217,7 @@ POST /projects/:id/labels/:label_id/unsubscribe | Attribute | Type | Required | Description | | ---------- | ----------------- | -------- | ------------------------------------ | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `label_id` | integer or string | yes | The ID or title of a project's label | ```bash diff --git a/doc/api/members.md b/doc/api/members.md index fe46f8f84bc..3234f833eae 100644 --- a/doc/api/members.md +++ b/doc/api/members.md @@ -1,4 +1,4 @@ -# Group and project members +# Group and project members API **Valid access levels** @@ -23,7 +23,7 @@ GET /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `query` | string | no | A query string to search for members | ```bash @@ -65,7 +65,7 @@ GET /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```bash @@ -98,7 +98,7 @@ POST /projects/:id/members | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the new member | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | @@ -132,7 +132,7 @@ PUT /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | | `access_level` | integer | yes | A valid access level | | `expires_at` | string | no | A date string in the format YEAR-MONTH-DAY | @@ -166,7 +166,7 @@ DELETE /projects/:id/members/:user_id | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The group/project ID or path | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project or group](README.md#namespaced-path-encoding) owned by the authenticated user | | `user_id` | integer | yes | The user ID of the member | ```bash diff --git a/doc/api/merge_requests.md b/doc/api/merge_requests.md index 2e0545da1c4..cb22b67f556 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -1,4 +1,4 @@ -# Merge requests +# Merge requests API ## List merge requests @@ -11,15 +11,21 @@ GET /projects/:id/merge_requests GET /projects/:id/merge_requests?state=opened GET /projects/:id/merge_requests?state=all GET /projects/:id/merge_requests?iids[]=42&iids[]=43 +GET /projects/:id/merge_requests?milestone=release +GET /projects/:id/merge_requests?labels=bug,reproduced ``` Parameters: -- `id` (required) - The ID of a project -- `iid` (optional) - Return the request having the given `iid` -- `state` (optional) - Return `all` requests or just those that are `merged`, `opened` or `closed` -- `order_by` (optional) - Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` -- `sort` (optional) - Return requests sorted in `asc` or `desc` order. Default is `desc` +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer | yes | The ID of a project | +| `iids` | Array[integer] | no | Return the request having the given `iid` | +| `state` | string | no | Return all merge requests or just those that are `opened`, `closed`, or `merged`| +| `order_by`| string | no | Return requests ordered by `created_at` or `updated_at` fields. Default is `created_at` | +| `sort` | string | no | Return requests sorted in `asc` or `desc` order. Default is `desc` | +| `milestone` | string | no | Return merge requests for a specific milestone | +| `labels` | string | no | Return merge requests matching a comma separated list of labels | ```json [ @@ -87,7 +93,7 @@ GET /projects/:id/merge_requests/:merge_request_iid Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request ```json @@ -155,7 +161,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/commits Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request @@ -192,7 +198,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/changes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The internal ID of the merge request ```json @@ -271,7 +277,7 @@ POST /projects/:id/merge_requests | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | string | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `source_branch` | string | yes | The source branch | | `target_branch` | string | yes | The target branch | | `title` | string | yes | Title of MR | @@ -347,7 +353,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | string | yes | The ID of a project | +| `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 ID of a merge request | | `target_branch` | string | no | The target branch | | `title` | string | no | Title of MR | @@ -422,9 +428,9 @@ Only for admins and project owners. Soft deletes the merge request in question. DELETE /projects/:id/merge_requests/:merge_request_iid ``` -| Attribute | Type | Required | Description | -| --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `merge_request_iid` | integer | yes | The internal ID of the merge request | ```bash @@ -450,7 +456,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/merge Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - Internal ID of MR - `merge_commit_message` (optional) - Custom merge commit message - `should_remove_source_branch` (optional) - if `true` removes the source branch @@ -524,7 +530,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/cancel_merge_when_pipeline_s ``` Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - Internal ID of MR ```json @@ -596,7 +602,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/closes_issues | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | ```bash @@ -671,7 +677,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/subscribe | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | ```bash @@ -745,7 +751,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/unsubscribe | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | ```bash @@ -819,7 +825,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/todo | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | ```bash @@ -1027,7 +1033,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/time_estimate | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | | `duration` | string | yes | The duration in human format. e.g: 3h30m | @@ -1056,7 +1062,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_time_estimate | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 a project's merge_request | ```bash @@ -1084,7 +1090,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/add_spent_time | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | | `duration` | string | yes | The duration in human format. e.g: 3h30m | @@ -1113,7 +1119,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/reset_spent_time | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 a project's merge_request | ```bash @@ -1139,7 +1145,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/time_stats | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 | ```bash diff --git a/doc/api/milestones.md b/doc/api/milestones.md index 3c86357a6c3..a082d548499 100644 --- a/doc/api/milestones.md +++ b/doc/api/milestones.md @@ -1,4 +1,4 @@ -# Milestones +# Milestones API ## List project milestones @@ -17,7 +17,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `iids` | Array[integer] | optional | Return only the milestones having the given `iids` | | `state` | string | optional | Return only `active` or `closed` milestones` | | `search` | string | optional | Return only milestones with a title or description matching the provided string | @@ -56,8 +56,8 @@ GET /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID of a project -- `milestone_id` (required) - The ID of a project milestone +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user +- `milestone_id` (required) - The ID of the project's milestone ## Create new milestone @@ -69,7 +69,7 @@ POST /projects/:id/milestones Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `title` (required) - The title of an milestone - `description` (optional) - The description of the milestone - `due_date` (optional) - The due date of the milestone @@ -85,7 +85,7 @@ PUT /projects/:id/milestones/:milestone_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone - `title` (optional) - The title of a milestone - `description` (optional) - The description of a milestone @@ -103,7 +103,7 @@ GET /projects/:id/milestones/:milestone_id/issues Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone ## Get all merge requests assigned to a single milestone @@ -116,5 +116,5 @@ GET /projects/:id/milestones/:milestone_id/merge_requests Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `milestone_id` (required) - The ID of a project milestone diff --git a/doc/api/namespaces.md b/doc/api/namespaces.md index eef06d5f324..4ad6071a0ed 100644 --- a/doc/api/namespaces.md +++ b/doc/api/namespaces.md @@ -1,4 +1,4 @@ -# Namespaces +# Namespaces API Usernames and groupnames fall under a special category called namespaces. diff --git a/doc/api/notes.md b/doc/api/notes.md index 5e927143714..388e6989df2 100644 --- a/doc/api/notes.md +++ b/doc/api/notes.md @@ -1,4 +1,4 @@ -# Notes +# Notes API Notes are comments on snippets, issues or merge requests. @@ -14,7 +14,7 @@ GET /projects/:id/issues/:issue_iid/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `issue_iid` (required) - The IID of an issue ```json @@ -68,7 +68,7 @@ GET /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `issue_iid` (required) - The IID of a project issue - `note_id` (required) - The ID of an issue note @@ -83,7 +83,7 @@ POST /projects/:id/issues/:issue_iid/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `issue_id` (required) - The IID of an issue - `body` (required) - The content of a note - `created_at` (optional) - Date time string, ISO 8601 formatted, e.g. 2016-03-11T03:45:40Z @@ -98,7 +98,7 @@ PUT /projects/:id/issues/:issue_iid/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `issue_iid` (required) - The IID of an issue - `note_id` (required) - The ID of a note - `body` (required) - The content of a note @@ -115,7 +115,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 IID of an issue | | `note_id` | integer | yes | The ID of a note | @@ -135,7 +135,7 @@ GET /projects/:id/snippets/:snippet_id/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project snippet ### Get single snippet note @@ -148,7 +148,7 @@ GET /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project snippet - `note_id` (required) - The ID of an snippet note @@ -182,7 +182,7 @@ POST /projects/:id/snippets/:snippet_id/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a snippet - `body` (required) - The content of a note @@ -196,7 +196,7 @@ PUT /projects/:id/snippets/:snippet_id/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a snippet - `note_id` (required) - The ID of a note - `body` (required) - The content of a note @@ -213,7 +213,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `snippet_id` | integer | yes | The ID of a snippet | | `note_id` | integer | yes | The ID of a note | @@ -233,7 +233,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The IID of a project merge request ### Get single merge request note @@ -246,7 +246,7 @@ GET /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The IID of a project merge request - `note_id` (required) - The ID of a merge request note @@ -283,7 +283,7 @@ POST /projects/:id/merge_requests/:merge_request_iid/notes Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The IID of a merge request - `body` (required) - The content of a note @@ -297,7 +297,7 @@ PUT /projects/:id/merge_requests/:merge_request_iid/notes/:note_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `merge_request_iid` (required) - The IID of a merge request - `note_id` (required) - The ID of a note - `body` (required) - The content of a note @@ -314,7 +314,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `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 IID of a merge request | | `note_id` | integer | yes | The ID of a note | diff --git a/doc/api/notification_settings.md b/doc/api/notification_settings.md index 43047917f77..3a2c398e355 100644 --- a/doc/api/notification_settings.md +++ b/doc/api/notification_settings.md @@ -1,4 +1,4 @@ -# Notification settings +# Notification settings API >**Note:** This feature was [introduced][ce-5632] in GitLab 8.12. diff --git a/doc/api/pipeline_triggers.md b/doc/api/pipeline_triggers.md index 50fc19f0e08..9030ae32d17 100644 --- a/doc/api/pipeline_triggers.md +++ b/doc/api/pipeline_triggers.md @@ -1,4 +1,4 @@ -# Pipeline triggers +# Pipeline triggers API You can read more about [triggering pipelines through the API](../ci/triggers/README.md). @@ -12,7 +12,7 @@ GET /projects/:id/triggers | Attribute | Type | required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/triggers" @@ -43,7 +43,7 @@ GET /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |--------------|---------|----------|--------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger id | ``` @@ -73,7 +73,7 @@ POST /projects/:id/triggers | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `description` | string | yes | The trigger name | ``` @@ -103,7 +103,7 @@ PUT /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger id | | `description` | string | no | The trigger name | @@ -134,7 +134,7 @@ POST /projects/:id/triggers/:trigger_id/take_ownership | Attribute | Type | required | Description | |---------------|---------|----------|--------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger id | ``` @@ -164,7 +164,7 @@ DELETE /projects/:id/triggers/:trigger_id | Attribute | Type | required | Description | |----------------|---------|----------|--------------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `trigger_id` | integer | yes | The trigger id | ``` diff --git a/doc/api/pipelines.md b/doc/api/pipelines.md index 574a8bacb25..890945cfc7e 100644 --- a/doc/api/pipelines.md +++ b/doc/api/pipelines.md @@ -10,7 +10,15 @@ GET /projects/:id/pipelines | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | +| `scope` | string | 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 | +| `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 | +| `order_by`| string | no | Order pipelines by `id`, `status`, `ref`, or `user_id` (default: `id`) | +| `sort` | string | no | Sort pipelines in `asc` or `desc` order (default: `desc`) | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/1/pipelines" @@ -45,7 +53,7 @@ GET /projects/:id/pipelines/:pipeline_id | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ``` @@ -91,7 +99,7 @@ POST /projects/:id/pipeline | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `ref` | string | yes | Reference to commit | ``` @@ -137,7 +145,7 @@ POST /projects/:id/pipelines/:pipeline_id/retry | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ``` @@ -173,7 +181,7 @@ Response: } ``` -## Cancel a pipelines jobs +## Cancel a pipelines jobs > [Introduced][ce-5837] in GitLab 8.11 @@ -183,7 +191,7 @@ POST /projects/:id/pipelines/:pipeline_id/cancel | Attribute | Type | Required | Description | |------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `pipeline_id` | integer | yes | The ID of a pipeline | ``` diff --git a/doc/api/project_snippets.md b/doc/api/project_snippets.md index 4f6f561b83e..ff379473961 100644 --- a/doc/api/project_snippets.md +++ b/doc/api/project_snippets.md @@ -23,7 +23,7 @@ GET /projects/:id/snippets Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user ## Single snippet @@ -35,7 +35,7 @@ GET /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet ```json @@ -67,7 +67,7 @@ POST /projects/:id/snippets Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `title` (required) - The title of a snippet - `file_name` (required) - The name of a snippet file - `code` (required) - The content of a snippet @@ -83,7 +83,7 @@ PUT /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet - `title` (optional) - The title of a snippet - `file_name` (optional) - The name of a snippet file @@ -101,7 +101,7 @@ DELETE /projects/:id/snippets/:snippet_id Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet ## Snippet content @@ -114,5 +114,5 @@ GET /projects/:id/snippets/:snippet_id/raw Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `snippet_id` (required) - The ID of a project's snippet diff --git a/doc/api/projects.md b/doc/api/projects.md index 686f3dba35d..6b919f71792 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -1,5 +1,4 @@ -# Projects - +# Projects API ### Project visibility level @@ -17,7 +16,6 @@ Constants for project visibility levels are next: * `public`: The project can be cloned without any authentication. - ## List projects Get a list of visible projects for authenticated user. When being accessed without authentication, all public projects are returned. @@ -39,6 +37,7 @@ Parameters: | `owned` | boolean | no | Limit by projects owned by the current user | | `membership` | boolean | no | Limit by projects that the current user is a member of | | `starred` | boolean | no | Limit by projects starred by the current user | +| `statistics` | boolean | no | Include project statistics | ```json [ @@ -90,7 +89,14 @@ Parameters: "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, - "request_access_enabled": false + "request_access_enabled": false, + "statistics": { + "commit_count": 37, + "storage_size": 1038090, + "repository_size": 1038090, + "lfs_objects_size": 0, + "job_artifacts_size": 0 + } }, { "id": 6, @@ -150,15 +156,21 @@ Parameters: "shared_with_groups": [], "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, - "request_access_enabled": false + "request_access_enabled": false, + "statistics": { + "commit_count": 12, + "storage_size": 2066080, + "repository_size": 2066080, + "lfs_objects_size": 0, + "job_artifacts_size": 0 + } } ] ``` ### Get single project -Get a specific project, identified by project ID or NAMESPACE/PROJECT_NAME, which is owned by the authenticated user. -If using namespaced projects call make sure that the NAMESPACE/PROJECT_NAME is URL-encoded, eg. `/api/v3/projects/diaspora%2Fdiaspora` (where `/` is represented by `%2F`). This endpoint can be accessed without authentication if +Get a specific project. This endpoint can be accessed without authentication if the project is publicly accessible. ``` @@ -169,7 +181,8 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | +| `statistics` | boolean | no | Include project statistics | ```json { @@ -241,7 +254,14 @@ Parameters: ], "only_allow_merge_if_pipeline_succeeds": false, "only_allow_merge_if_all_discussions_are_resolved": false, - "request_access_enabled": false + "request_access_enabled": false, + "statistics": { + "commit_count": 37, + "storage_size": 1038090, + "repository_size": 1038090, + "lfs_objects_size": 0, + "job_artifacts_size": 0 + } } ``` @@ -295,7 +315,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```json [ @@ -497,7 +517,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `name` | string | yes | The name of the project | | `path` | string | no | Custom repository name for the project. By default generated based on name | | `default_branch` | string | no | `master` by default | @@ -529,7 +549,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `namespace` | integer/string | yes | The ID or path of the namespace that the project will be forked to | ### Star a project @@ -544,7 +564,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID or NAMESPACE/PROJECT_NAME of the project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/star" @@ -609,7 +629,7 @@ POST /projects/:id/unstar | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/unstar" @@ -675,7 +695,7 @@ POST /projects/:id/archive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/archive" @@ -757,7 +777,7 @@ POST /projects/:id/unarchive | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```bash curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/5/unarchive" @@ -840,7 +860,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ## Uploads @@ -856,9 +876,20 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `file` | string | yes | The file to be uploaded | +To upload a file from your filesystem, use the `--form` argument. This causes +cURL to post data using the header `Content-Type: multipart/form-data`. +The `file=` parameter must point to a file on your filesystem and be preceded +by `@`. For example: + +```bash +curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --form "file=@dk.png" https://gitlab.example.com/api/v3/projects/5/uploads +``` + +Returned object: + ```json { "alt": "dk", @@ -868,8 +899,8 @@ Parameters: ``` **Note**: The returned `url` is relative to the project path. -In Markdown contexts, the link is automatically expanded when the format in `markdown` is used. - +In Markdown contexts, the link is automatically expanded when the format in +`markdown` is used. ## Project members @@ -887,7 +918,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group to share with | | `group_access` | integer | yes | The permissions level to grant the group | | `expires_at` | string | no | Share expiration date in ISO 8601 format: 2016-09-26 | @@ -904,7 +935,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `group_id` | integer | yes | The ID of the group | ```bash @@ -928,7 +959,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ### Get project hook @@ -942,7 +973,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of a project hook | ```json @@ -975,7 +1006,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | | `issues_events` | boolean | no | Trigger hook on issues events | @@ -1000,7 +1031,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the project hook | | `url` | string | yes | The hook URL | | `push_events` | boolean | no | Trigger hook on push events | @@ -1027,7 +1058,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `hook_id` | integer | yes | The ID of the project hook | Note the JSON response differs if the hook is available or not. If the project hook @@ -1049,7 +1080,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ```json [ @@ -1106,7 +1137,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `branch` | string | yes | The name of the branch | | `developers_can_push` | boolean | no | Flag if developers can push to the branch | | `developers_can_merge` | boolean | no | Flag if developers can merge to the branch | @@ -1123,7 +1154,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `branch` | string | yes | The name of the branch | ### Unprotect single branch @@ -1138,7 +1169,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `branch` | string | yes | The name of the branch | ## Admin fork relation @@ -1155,7 +1186,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | | `forked_from_id` | ID | yes | The ID of the project that was forked from | ### Delete an existing forked from relationship @@ -1168,7 +1199,7 @@ Parameter: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer/string | yes | The ID of the project or NAMESPACE/PROJECT_NAME | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) | ## Search for projects by name diff --git a/doc/api/repositories.md b/doc/api/repositories.md index b1bf9ca07cc..bccef924375 100644 --- a/doc/api/repositories.md +++ b/doc/api/repositories.md @@ -1,4 +1,4 @@ -# Repositories +# Repositories API ## List repository tree @@ -13,7 +13,7 @@ GET /projects/:id/repository/tree Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `path` (optional) - The path inside repository. Used to get contend of subdirectories - `ref` (optional) - The name of a repository branch or tag or if not given the default branch - `recursive` (optional) - Boolean value used to get a recursive tree (false by default) @@ -84,7 +84,7 @@ GET /projects/:id/repository/blobs/:sha Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `sha` (required) - The commit or branch name ## Raw blob content @@ -98,7 +98,7 @@ GET /projects/:id/repository/blobs/:sha/raw Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `sha` (required) - The blob SHA ## Get file archive @@ -112,7 +112,7 @@ GET /projects/:id/repository/archive Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `sha` (optional) - The commit SHA to download defaults to the tip of the default branch ## Compare branches, tags or commits @@ -126,7 +126,7 @@ GET /projects/:id/repository/compare Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `from` (required) - the commit SHA or branch name - `to` (required) - the commit SHA or branch name @@ -181,7 +181,7 @@ GET /projects/:id/repository/contributors Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user Response: diff --git a/doc/api/repository_files.md b/doc/api/repository_files.md index aec91abd390..0b5782a8cc4 100644 --- a/doc/api/repository_files.md +++ b/doc/api/repository_files.md @@ -1,4 +1,4 @@ -# Repository files +# Repository files API **CRUD for repository files** diff --git a/doc/api/runners.md b/doc/api/runners.md index 46f882ce937..16d362a3530 100644 --- a/doc/api/runners.md +++ b/doc/api/runners.md @@ -222,7 +222,7 @@ GET /projects/:id/runners | Attribute | Type | Required | Description | |-----------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | ``` curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v4/projects/9/runners" @@ -259,7 +259,7 @@ POST /projects/:id/runners | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ``` @@ -290,7 +290,7 @@ DELETE /projects/:id/runners/:runner_id | Attribute | Type | Required | Description | |-------------|---------|----------|---------------------| -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `runner_id` | integer | yes | The ID of a runner | ``` diff --git a/doc/api/services.md b/doc/api/services.md index 7d4779f1137..49b87a4228c 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -1,4 +1,4 @@ -# Services +# Services API ## Asana @@ -490,41 +490,98 @@ Remove all previously JIRA settings from a project. DELETE /projects/:id/services/jira ``` -## Mattermost Slash Commands +## Slack slash commands -Ability to receive slash commands from a Mattermost chat instance. +Ability to receive slash commands from a Slack chat instance. -### Create/Edit Mattermost Slash Command service +### Get Slack slash command service settings -Set Mattermost Slash Command for a project. +Get Slack slash command service settings for a project. ``` -PUT /projects/:id/services/mattermost-slash-commands +GET /projects/:id/services/slack-slash-commands +``` + +Example response: + +```json +{ + "id": 4, + "title": "Slack slash commands", + "created_at": "2017-06-27T05:51:39-07:00", + "updated_at": "2017-06-27T05:51:39-07:00", + "active": true, + "push_events": true, + "issues_events": true, + "merge_requests_events": true, + "tag_push_events": true, + "note_events": true, + "job_events": true, + "pipeline_events": true, + "properties": { + "token": "9koXpg98eAheJpvBs5tK" + } +} +``` + +### Create/Edit Slack slash command service + +Set Slack slash command for a project. + +``` +PUT /projects/:id/services/slack-slash-commands ``` Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `token` | string | yes | The Mattermost token | +| `token` | string | yes | The Slack token | -### Delete Mattermost Slash Command service +### Delete Slack slash command service -Delete Mattermost Slash Command service for a project. +Delete Slack slash command service for a project. ``` -DELETE /projects/:id/services/mattermost-slash-commands +DELETE /projects/:id/services/slack-slash-commands ``` -### Get Mattermost Slash Command service settings +## Mattermost slash commands + +Ability to receive slash commands from a Mattermost chat instance. + +### Get Mattermost slash command service settings -Get Mattermost Slash Command service settings for a project. +Get Mattermost slash command service settings for a project. ``` GET /projects/:id/services/mattermost-slash-commands ``` +### Create/Edit Mattermost slash command service + +Set Mattermost slash command for a project. + +``` +PUT /projects/:id/services/mattermost-slash-commands +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `token` | string | yes | The Mattermost token | + + +### Delete Mattermost slash command service + +Delete Mattermost slash command service for a project. + +``` +DELETE /projects/:id/services/mattermost-slash-commands +``` + ## Pipeline-Emails Get emails for GitLab CI pipelines. diff --git a/doc/api/session.md b/doc/api/session.md index 056cc32597c..7dd504b67c5 100644 --- a/doc/api/session.md +++ b/doc/api/session.md @@ -1,4 +1,4 @@ -# Session +# Session API ## Deprecation Notice diff --git a/doc/api/settings.md b/doc/api/settings.md index ad975e2e325..eefbdda42ce 100644 --- a/doc/api/settings.md +++ b/doc/api/settings.md @@ -1,4 +1,4 @@ -# Application settings +# Application settings API These API calls allow you to read and modify GitLab instance application settings as appear in `/admin/application_settings`. You have to be an @@ -48,7 +48,8 @@ Example response: "koding_url": null, "plantuml_enabled": false, "plantuml_url": null, - "terminal_max_session_time": 0 + "terminal_max_session_time": 0, + "polling_interval_multiplier": 1.0 } ``` @@ -88,6 +89,7 @@ PUT /application/settings | `plantuml_enabled` | boolean | no | Enable PlantUML integration. Default is `false`. | | `plantuml_url` | string | yes (if `plantuml_enabled` is `true`) | The PlantUML instance URL for integration. | | `terminal_max_session_time` | integer | no | Maximum time for web terminal websocket connection (in seconds). Set to 0 for unlimited time. | +| `polling_interval_multiplier` | decimal | no | Interval multiplier used by endpoints that perform polling. Set to 0 to disable polling. | ```bash curl --request PUT --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/application/settings?signup_enabled=false&default_project_visibility=internal @@ -124,6 +126,7 @@ Example response: "koding_url": null, "plantuml_enabled": false, "plantuml_url": null, - "terminal_max_session_time": 0 + "terminal_max_session_time": 0, + "polling_interval_multiplier": 1.0 } ``` diff --git a/doc/api/sidekiq_metrics.md b/doc/api/sidekiq_metrics.md index ea10a26bcd0..b9500916cf2 100644 --- a/doc/api/sidekiq_metrics.md +++ b/doc/api/sidekiq_metrics.md @@ -1,4 +1,4 @@ -# Sidekiq Metrics +# Sidekiq Metrics API >**Note:** This endpoint is only available on GitLab 8.9 and above. diff --git a/doc/api/snippets.md b/doc/api/snippets.md index e09d930698e..fb8cf97896c 100644 --- a/doc/api/snippets.md +++ b/doc/api/snippets.md @@ -1,4 +1,4 @@ -# Snippets +# Snippets API > [Introduced][ce-6373] in GitLab 8.15. diff --git a/doc/api/system_hooks.md b/doc/api/system_hooks.md index bad380794c1..9750475f0a6 100644 --- a/doc/api/system_hooks.md +++ b/doc/api/system_hooks.md @@ -1,4 +1,4 @@ -# System hooks +# System hooks API All methods require administrator authorization. diff --git a/doc/api/tags.md b/doc/api/tags.md index bf350f024f5..54f092d1d30 100644 --- a/doc/api/tags.md +++ b/doc/api/tags.md @@ -1,4 +1,4 @@ -# Tags +# Tags API ## List project repository tags @@ -12,7 +12,7 @@ GET /projects/:id/repository/tags Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user ```json [ @@ -53,7 +53,7 @@ Parameters: | Attribute | Type | Required | Description | | --------- | ---- | -------- | ----------- | -| `id` | integer | yes | The ID of a project | +| `id` | integer/string | yes | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user | | `tag_name` | string | yes | The name of the tag | ```bash @@ -93,7 +93,7 @@ POST /projects/:id/repository/tags Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag - `ref` (required) - Create tag using commit SHA, another tag name, or branch name. - `message` (optional) - Creates annotated tag. @@ -138,7 +138,7 @@ DELETE /projects/:id/repository/tags/:tag_name Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag @@ -153,7 +153,7 @@ POST /projects/:id/repository/tags/:tag_name/release Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag - `description` (required) - Release notes with markdown support @@ -174,7 +174,7 @@ PUT /projects/:id/repository/tags/:tag_name/release Parameters: -- `id` (required) - The ID of a project +- `id` (required) - The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user - `tag_name` (required) - The name of a tag - `description` (required) - Release notes with markdown support diff --git a/doc/api/templates/gitignores.md b/doc/api/templates/gitignores.md index 3f2f4ed54e0..d3f5c88ca90 100644 --- a/doc/api/templates/gitignores.md +++ b/doc/api/templates/gitignores.md @@ -1,4 +1,4 @@ -# Gitignores +# Gitignores API ## List gitignore templates diff --git a/doc/api/templates/gitlab_ci_ymls.md b/doc/api/templates/gitlab_ci_ymls.md index 27e8973da58..bdb128fc336 100644 --- a/doc/api/templates/gitlab_ci_ymls.md +++ b/doc/api/templates/gitlab_ci_ymls.md @@ -1,4 +1,4 @@ -# GitLab CI YMLs +# GitLab CI YMLs API ## List GitLab CI YML templates diff --git a/doc/api/templates/licenses.md b/doc/api/templates/licenses.md index 33018f0c53f..8d1006e08c5 100644 --- a/doc/api/templates/licenses.md +++ b/doc/api/templates/licenses.md @@ -1,4 +1,4 @@ -# Licenses +# Licenses API ## List license templates diff --git a/doc/api/todos.md b/doc/api/todos.md index 77667a57195..dd4c737b729 100644 --- a/doc/api/todos.md +++ b/doc/api/todos.md @@ -1,4 +1,4 @@ -# Todos +# Todos API > [Introduced][ce-3188] in GitLab 8.10. diff --git a/doc/api/users.md b/doc/api/users.md index 2ada4d09c84..331f9a9b80b 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -1,4 +1,4 @@ -# Users +# Users API ## List users @@ -62,7 +62,6 @@ GET /users "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg", "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", - "is_admin": false, "bio": null, "location": null, "skype": "", @@ -72,6 +71,7 @@ GET /users "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, "current_sign_in_at": "2012-06-02T06:36:55Z", @@ -94,7 +94,6 @@ GET /users "avatar_url": "http://localhost:3000/uploads/user/avatar/2/index.jpg", "web_url": "http://localhost:3000/jack_smith", "created_at": "2012-05-23T08:01:01Z", - "is_admin": false, "bio": null, "location": null, "skype": "", @@ -104,6 +103,7 @@ GET /users "organization": "", "last_sign_in_at": null, "confirmed_at": "2012-05-30T16:53:06.148Z", + "last_activity_on": "2012-05-23", "color_scheme_id": 3, "projects_limit": 100, "current_sign_in_at": "2014-03-19T17:54:13Z", @@ -130,6 +130,18 @@ For example: GET /users?username=jack_smith ``` +You can also lookup users by external UID and provider: + +``` +GET /users?extern_uid=:extern_uid&provider=:provider +``` + +For example: + +``` +GET /users?extern_uid=1234567&provider=github +``` + You can search for users who are external with: `/users?external=true` ## Single user @@ -155,7 +167,6 @@ Parameters: "avatar_url": "http://localhost:3000/uploads/user/avatar/1/cd8.jpeg", "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", - "is_admin": false, "bio": null, "location": null, "skype": "", @@ -186,7 +197,6 @@ Parameters: "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg", "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", - "is_admin": false, "bio": null, "location": null, "skype": "", @@ -196,6 +206,7 @@ Parameters: "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, "current_sign_in_at": "2012-06-02T06:36:55Z", @@ -310,7 +321,6 @@ GET /user "avatar_url": "http://localhost:3000/uploads/user/avatar/1/index.jpg", "web_url": "http://localhost:3000/john_smith", "created_at": "2012-05-23T08:00:58Z", - "is_admin": false, "bio": null, "location": null, "skype": "", @@ -320,6 +330,7 @@ GET /user "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, "current_sign_in_at": "2012-06-02T06:36:55Z", @@ -365,6 +376,7 @@ GET /user "organization": "", "last_sign_in_at": "2012-06-01T11:41:01Z", "confirmed_at": "2012-05-23T09:05:22Z", + "last_activity_on": "2012-05-23", "color_scheme_id": 2, "projects_limit": 100, "current_sign_in_at": "2012-06-02T06:36:55Z", @@ -986,3 +998,55 @@ Parameters: | --------- | ---- | -------- | ----------- | | `user_id` | integer | yes | The ID of the user | | `impersonation_token_id` | integer | yes | The ID of the impersonation token | + +### Get user activities (admin only) + +>**Note:** This API endpoint is only available on 8.15 (EE) and 9.1 (CE) and above. + +Get the last activity date for all users, sorted from oldest to newest. + +The activities that update the timestamp are: + + - Git HTTP/SSH activities (such as clone, push) + - User logging in into GitLab + +By default, it shows the activity for all users in the last 6 months, but this can be +amended by using the `from` parameter. + +``` +GET /user/activities +``` + +Parameters: + +| Attribute | Type | Required | Description | +| --------- | ---- | -------- | ----------- | +| `from` | string | no | Date string in the format YEAR-MONTH-DAY, e.g. `2016-03-11`. Defaults to 6 months ago. | + +```bash +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/activities +``` + +Example response: + +```json +[ + { + "username": "user1", + "last_activity_on": "2015-12-14", + "last_activity_at": "2015-12-14" + }, + { + "username": "user2", + "last_activity_on": "2015-12-15", + "last_activity_at": "2015-12-15" + }, + { + "username": "user3", + "last_activity_on": "2015-12-16", + "last_activity_at": "2015-12-16" + } +] +``` + +Please note that `last_activity_at` is deprecated, please use `last_activity_on`. diff --git a/doc/api/v3_to_v4.md b/doc/api/v3_to_v4.md index 8e002fe0022..9db8e0351cf 100644 --- a/doc/api/v3_to_v4.md +++ b/doc/api/v3_to_v4.md @@ -1,8 +1,10 @@ -# V3 to V4 version +# API V3 to API V4 Since GitLab 9.0, API V4 is the preferred version to be used. -V3 will remain working until at least GitLab 9.3. The V3 API documentation is still [available](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable/doc/api/README.md). +API V3 will be removed in GitLab 9.5, to be released on August 22, 2017. In the +meantime, we advise you to make any necessary changes to applications that use +V3. The V3 API documentation is still [available](https://gitlab.com/gitlab-org/gitlab-ce/blob/8-16-stable/doc/api/README.md). Below are the changes made between V3 and V4. diff --git a/doc/articles/how_to_configure_ldap_gitlab_ce/img/gitlab_ou.png b/doc/articles/how_to_configure_ldap_gitlab_ce/img/gitlab_ou.png Binary files differnew file mode 100644 index 00000000000..11ce324f938 --- /dev/null +++ b/doc/articles/how_to_configure_ldap_gitlab_ce/img/gitlab_ou.png diff --git a/doc/articles/how_to_configure_ldap_gitlab_ce/img/ldap_ou.gif b/doc/articles/how_to_configure_ldap_gitlab_ce/img/ldap_ou.gif Binary files differnew file mode 100644 index 00000000000..a6727a3d85f --- /dev/null +++ b/doc/articles/how_to_configure_ldap_gitlab_ce/img/ldap_ou.gif diff --git a/doc/articles/how_to_configure_ldap_gitlab_ce/img/user_auth.gif b/doc/articles/how_to_configure_ldap_gitlab_ce/img/user_auth.gif Binary files differnew file mode 100644 index 00000000000..36e6085259f --- /dev/null +++ b/doc/articles/how_to_configure_ldap_gitlab_ce/img/user_auth.gif diff --git a/doc/articles/how_to_configure_ldap_gitlab_ce/index.md b/doc/articles/how_to_configure_ldap_gitlab_ce/index.md new file mode 100644 index 00000000000..6892905dd94 --- /dev/null +++ b/doc/articles/how_to_configure_ldap_gitlab_ce/index.md @@ -0,0 +1,266 @@ +# How to configure LDAP with GitLab CE + +> **Article [Type](../../development/writing_documentation.html#types-of-technical-articles):** admin guide || +> **Level:** intermediary || +> **Author:** [Chris Wilson](https://gitlab.com/MrChrisW) || +> **Publication date:** 2017/05/03 + +## Introduction + +Managing a large number of users in GitLab can become a burden for system administrators. As an organization grows so do user accounts. Keeping these user accounts in sync across multiple enterprise applications often becomes a time consuming task. + +In this guide we will focus on configuring GitLab with Active Directory. [Active Directory](https://en.wikipedia.org/wiki/Active_Directory) is a popular LDAP compatible directory service provided by Microsoft, included in all modern Windows Server operating systems. + +GitLab has supported LDAP integration since [version 2.2](https://about.gitlab.com/2012/02/22/gitlab-version-2-2/). With GitLab LDAP [group syncing](#group-syncing-ee) being added to GitLab Enterprise Edition in [version 6.0](https://about.gitlab.com/2013/08/20/gitlab-6-dot-0-released/). LDAP integration has become one of the most popular features in GitLab. + +## Getting started + +### Choosing an LDAP Server + +The main reason organizations choose to utilize a LDAP server is to keep the entire organization's user base consolidated into a central repository. Users can access multiple applications and systems across the IT environment using a single login. Because LDAP is an open, vendor-neutral, industry standard application protocol, the number of applications using LDAP authentication continues to increase. + +There are many commercial and open source [directory servers](https://en.wikipedia.org/wiki/Directory_service#LDAP_implementations) that support the LDAP protocol. Deciding on the right directory server highly depends on the existing IT environment in which the server will be integrated with. + +For example, [Active Directory](https://technet.microsoft.com/en-us/library/hh831484(v=ws.11).aspx) is generally favored in a primarily Windows environment, as this allows quick integration with existing services. Other popular directory services include: + +- [Oracle Internet Directory](http://www.oracle.com/technetwork/middleware/id-mgmt/overview/index-082035.html) +- [OpenLDAP](http://www.openldap.org/) +- [389 Directory](http://directory.fedoraproject.org/) +- [OpenDJ](https://forgerock.org/opendj/) +- [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. + +### Active Directory (AD) + +We won't cover the installation and configuration of Windows Server or Active Directory Domain Services in this tutorial. There are a number of resources online to guide you through this process: + +- Install Windows Server 2012 - (_technet.microsoft.com_) - [Installing Windows Server 2012 ](https://technet.microsoft.com/en-us/library/jj134246(v=ws.11).aspx) + +- Install Active Directory Domain Services (AD DS) (_technet.microsoft.com_)- [Install Active Directory Domain Services](https://technet.microsoft.com/windows-server-docs/identity/ad-ds/deploy/install-active-directory-domain-services--level-100-#BKMK_PS) + +> **Shortcut:** You can quickly install AD DS via PowerShell using +`Install-WindowsFeature AD-Domain-Services -IncludeManagementTools` + +### Creating an AD **OU** structure + +Configuring organizational units (**OU**s) is an important part of setting up Active Directory. **OU**s form the base for an entire organizational structure. Using GitLab as an example we have designed the **OU** structure below using the geographic **OU** model. In the Geographic Model we separate **OU**s for different geographic regions. + +| GitLab **OU** Design | GitLab AD Structure | +| :----------------------------: | :------------------------------: | +| ![GitLab OU Design][gitlab_ou] | ![GitLab AD Structure][ldap_ou] | + +[gitlab_ou]: img/gitlab_ou.png +[ldap_ou]: img/ldap_ou.gif + +Using PowerShell you can output the **OU** structure as a table (_all names are examples only_): + +```ps +Get-ADObject -LDAPFilter "(objectClass=*)" -SearchBase 'OU=GitLab INT,DC=GitLab,DC=org' -Properties CanonicalName | Format-Table Name,CanonicalName -A +``` + +``` +OU CanonicalName +---- ------------- +GitLab INT GitLab.org/GitLab INT +United States GitLab.org/GitLab INT/United States +Developers GitLab.org/GitLab INT/United States/Developers +Gary Johnson GitLab.org/GitLab INT/United States/Developers/Gary Johnson +Ellis Matthews GitLab.org/GitLab INT/United States/Developers/Ellis Matthews +William Collins GitLab.org/GitLab INT/United States/Developers/William Collins +People Ops GitLab.org/GitLab INT/United States/People Ops +Margaret Baker GitLab.org/GitLab INT/United States/People Ops/Margaret Baker +Libby Hartzler GitLab.org/GitLab INT/United States/People Ops/Libby Hartzler +Victoria Ryles GitLab.org/GitLab INT/United States/People Ops/Victoria Ryles +The Netherlands GitLab.org/GitLab INT/The Netherlands +Developers GitLab.org/GitLab INT/The Netherlands/Developers +John Doe GitLab.org/GitLab INT/The Netherlands/Developers/John Doe +Jon Mealy GitLab.org/GitLab INT/The Netherlands/Developers/Jon Mealy +Jane Weingarten GitLab.org/GitLab INT/The Netherlands/Developers/Jane Weingarten +Production GitLab.org/GitLab INT/The Netherlands/Production +Sarah Konopka GitLab.org/GitLab INT/The Netherlands/Production/Sarah Konopka +Cynthia Bruno GitLab.org/GitLab INT/The Netherlands/Production/Cynthia Bruno +David George GitLab.org/GitLab INT/The Netherlands/Production/David George +United Kingdom GitLab.org/GitLab INT/United Kingdom +Developers GitLab.org/GitLab INT/United Kingdom/Developers +Leroy Fox GitLab.org/GitLab INT/United Kingdom/Developers/Leroy Fox +Christopher Alley GitLab.org/GitLab INT/United Kingdom/Developers/Christopher Alley +Norris Morita GitLab.org/GitLab INT/United Kingdom/Developers/Norris Morita +Support GitLab.org/GitLab INT/United Kingdom/Support +Laura Stanley GitLab.org/GitLab INT/United Kingdom/Support/Laura Stanley +Nikki Schuman GitLab.org/GitLab INT/United Kingdom/Support/Nikki Schuman +Harriet Butcher GitLab.org/GitLab INT/United Kingdom/Support/Harriet Butcher +Global Groups GitLab.org/GitLab INT/Global Groups +DevelopersNL GitLab.org/GitLab INT/Global Groups/DevelopersNL +DevelopersUK GitLab.org/GitLab INT/Global Groups/DevelopersUK +DevelopersUS GitLab.org/GitLab INT/Global Groups/DevelopersUS +ProductionNL GitLab.org/GitLab INT/Global Groups/ProductionNL +SupportUK GitLab.org/GitLab INT/Global Groups/SupportUK +People Ops US GitLab.org/GitLab INT/Global Groups/People Ops US +Global Admins GitLab.org/GitLab INT/Global Groups/Global Admins +``` + +> See [more information](https://technet.microsoft.com/en-us/library/ff730967.aspx) on searching Active Directory with Windows PowerShell from [The Scripting Guys](https://technet.microsoft.com/en-us/scriptcenter/dd901334.aspx) + +## GitLab LDAP configuration + +The initial configuration of LDAP in GitLab requires changes to the `gitlab.rb` configuration file. Below is an example of a complete configuration using an Active Directory. + +The two Active Directory specific values are `active_directory: true` and `uid: 'sAMAccountName'`. `sAMAccountName` is an attribute returned by Active Directory used for GitLab usernames. See the example output from `ldapsearch` for a full list of attributes a "person" object (user) has in **AD** - [`ldapsearch` example](#using-ldapsearch-unix) + +> Both group_base and admin_group configuration options are only available in GitLab Enterprise Edition. See [GitLab EE - LDAP Features](#gitlab-enterprise-edition---ldap-features) + +### Example `gitlab.rb` LDAP + +``` +gitlab_rails['ldap_enabled'] = true +gitlab_rails['ldap_servers'] = { +'main' => { + 'label' => 'GitLab AD', + 'host' => 'ad.example.org', + 'port' => 636, + 'uid' => 'sAMAccountName', + 'method' => 'ssl', + 'bind_dn' => 'CN=GitLabSRV,CN=Users,DC=GitLab,DC=org', + 'password' => 'Password1', + 'active_directory' => true, + 'base' => 'OU=GitLab INT,DC=GitLab,DC=org', + 'group_base' => 'OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org', + 'admin_group' => 'Global Admins' + } +} +``` + +> **Note:** Remember to run `gitlab-ctl reconfigure` after modifying `gitlab.rb` + +## Security improvements (LDAPS) + +Security is an important aspect when deploying an LDAP server. By default, LDAP traffic is transmitted unsecured. LDAP can be secured using SSL/TLS called LDAPS, or commonly "LDAP over SSL". + +Securing LDAP (enabling LDAPS) on Windows Server 2012 involves installing a valid SSL certificate. For full details see Microsoft's guide [How to enable LDAP over SSL with a third-party certification authority](https://support.microsoft.com/en-us/help/321051/how-to-enable-ldap-over-ssl-with-a-third-party-certification-authority) + +> By default a LDAP service listens for connections on TCP and UDP port 389. LDAPS (LDAP over SSL) listens on port 636 + +### Testing you AD server + +#### Using **AdFind** (Windows) + +You can use the [`AdFind`](https://social.technet.microsoft.com/wiki/contents/articles/7535.adfind-command-examples.aspx) utility (on Windows based systems) to test that your LDAP server is accessible and authentication is working correctly. This is a freeware utility built by [Joe Richards](http://www.joeware.net/freetools/tools/adfind/index.htm). + +**Return all objects** + +You can use the filter `objectclass=*` to return all directory objects. + +```sh +adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -up Password1 -b "OU=GitLab INT,DC=GitLab,DC=org" -f (objectClass=*) +``` + +**Return single object using filter** + +You can also retrieve a single object by **specifying** the object name or full **DN**. In this example we specify the object name only `CN=Leroy Fox`. + +```sh +adfind -h ad.example.org:636 -ssl -u "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -up Password1 -b "OU=GitLab INT,DC=GitLab,DC=org" -f (&(objectcategory=person)(CN=Leroy Fox))” +``` + +#### Using **ldapsearch** (Unix) + +You can use the `ldapsearch` utility (on Unix based systems) to test that your LDAP server is accessible and authentication is working correctly. This utility is included in the [`ldap-utils`](https://wiki.debian.org/LDAP/LDAPUtils) package. + +**Return all objects** + +You can use the filter `objectclass=*` to return all directory objects. + +```sh +ldapsearch -D "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" \ +-w Password1 -p 636 -h ad.example.org \ +-b "OU=GitLab INT,DC=GitLab,DC=org" -Z \ +-s sub "(objectclass=*)" +``` + +**Return single object using filter** + +You can also retrieve a single object by **specifying** the object name or full **DN**. In this example we specify the object name only `CN=Leroy Fox`. + +```sh +ldapsearch -D "CN=GitLabSRV,CN=Users,DC=GitLab,DC=org" -w Password1 -p 389 -h ad.example.org -b "OU=GitLab INT,DC=GitLab,DC=org" -Z -s sub "CN=Leroy Fox" +``` + +**Full output of `ldapsearch` command:** - Filtering for _CN=Leroy Fox_ + +``` +# LDAPv3 +# base <OU=GitLab INT,DC=GitLab,DC=org> with scope subtree +# filter: CN=Leroy Fox +# requesting: ALL +# + +# Leroy Fox, Developers, United Kingdom, GitLab INT, GitLab.org +dn: CN=Leroy Fox,OU=Developers,OU=United Kingdom,OU=GitLab INT,DC=GitLab,DC=or + g +objectClass: top +objectClass: person +objectClass: organizationalPerson +objectClass: user +cn: Leroy Fox +sn: Fox +givenName: Leroy +distinguishedName: CN=Leroy Fox,OU=Developers,OU=United Kingdom,OU=GitLab INT, + DC=GitLab,DC=org +instanceType: 4 +whenCreated: 20170210030500.0Z +whenChanged: 20170213050128.0Z +displayName: Leroy Fox +uSNCreated: 16790 +memberOf: CN=DevelopersUK,OU=Global Groups,OU=GitLab INT,DC=GitLab,DC=org +uSNChanged: 20812 +name: Leroy Fox +objectGUID:: rBCAo6NR6E6vfSKgzcUILg== +userAccountControl: 512 +badPwdCount: 0 +codePage: 0 +countryCode: 0 +badPasswordTime: 0 +lastLogoff: 0 +lastLogon: 0 +pwdLastSet: 131311695009850084 +primaryGroupID: 513 +objectSid:: AQUAAAAAAAUVAAAA9GMAb7tdJZvsATf7ZwQAAA== +accountExpires: 9223372036854775807 +logonCount: 0 +sAMAccountName: Leroyf +sAMAccountType: 805306368 +userPrincipalName: Leroyf@GitLab.org +objectCategory: CN=Person,CN=Schema,CN=Configuration,DC=GitLab,DC=org +dSCorePropagationData: 16010101000000.0Z +lastLogonTimestamp: 131314356887754250 + +# search result +search: 2 +result: 0 Success + +# numResponses: 2 +# numEntries: 1 +``` + +## Basic user authentication + +After configuring LDAP, basic authentication will be available. Users can then login using their directory credentials. An extra tab is added to the GitLab login screen for the configured LDAP server (e.g "**GitLab AD**"). + + + +Users that are removed from the LDAP base group (e.g `OU=GitLab INT,DC=GitLab,DC=org`) will be **blocked** in GitLab. [More information](../../administration/auth/ldap.md#security) on LDAP security. + +If `allow_username_or_email_login` is enabled in the LDAP configuration, GitLab will ignore everything after the first '@' in the LDAP username used on login. Example: The username `jon.doe@example.com` is converted to `jon.doe` when authenticating with the LDAP server. Disable this setting if you use `userPrincipalName` as the `uid`. + +## LDAP extended features on GitLab EE + +With [GitLab Enterprise Edition (EE)](https://about.gitlab.com/giltab-ee/), besides everything we just described, you'll +have extended functionalities with LDAP, such as: + +- Group sync +- Group permissions +- Updating user permissions +- Multiple LDAP servers + +Read through the article on [LDAP for GitLab EE](https://docs.gitlab.com/ee/articles/how_to_configure_ldap_gitlab_ee/) for an overview. diff --git a/doc/articles/how_to_install_git/index.md b/doc/articles/how_to_install_git/index.md new file mode 100644 index 00000000000..66d866b2d09 --- /dev/null +++ b/doc/articles/how_to_install_git/index.md @@ -0,0 +1,66 @@ +# Installing Git + +> **Article [Type](../../development/writing_documentation.html#types-of-technical-articles):** user guide || +> **Level:** beginner || +> **Author:** [Sean Packham](https://gitlab.com/SeanPackham) || +> **Publication date:** 2017/05/15 + +To begin contributing to GitLab projects +you will need to install the Git client on your computer. +This article will show you how to install Git on macOS, Ubuntu Linux and Windows. + +## Install Git on macOS using the Homebrew package manager + +Although it is easy to use the version of Git shipped with macOS +or install the latest version of Git on macOS by downloading it from the project website, +we recommend installing it via Homebrew to get access to +an extensive selection of dependancy managed libraries and applications. + +If you are sure you don't need access to any additional development libraries +or don't have approximately 15gb of available disk space for Xcode and Homebrew +use one of the the aforementioned methods. + +### Installing Xcode + +Xcode is needed by Homebrew to build dependencies. +You can install [XCode](https://developer.apple.com/xcode/) +through the macOS App Store. + +### Installing Homebrew + +Once Xcode is installed browse to the [Homebrew website](http://brew.sh/index.html) +for the official Homebrew installation instructions. + +### Installing Git via Homebrew + +With Homebrew installed you are now ready to install Git. +Open a Terminal and enter in the following command: + +```bash +brew install git +``` + +Congratulations you should now have Git installed via Homebrew. +Next read our article on [adding an SSH key to GitLab](../../ssh/README.md). + +## Install Git on Ubuntu Linux + +On Ubuntu and other Linux operating systems +it is recommended to use the built in package manager to install Git. + +Open a Terminal and enter in the following commands +to install the latest Git from the official Git maintained package archives: + +```bash +sudo apt-add-repository ppa:git-core/ppa +sudo apt-get update +sudo apt-get install git +``` + +Congratulations you should now have Git installed via the Ubuntu package manager. +Next read our article on [adding an SSH key to GitLab](../../ssh/README.md). + +## Installing Git on Windows from the Git website + +Browse to the [Git website](https://git-scm.com/) and download and install Git for Windows. +Next read our article on [adding an SSH key to GitLab](../../ssh/README.md). diff --git a/doc/articles/index.md b/doc/articles/index.md new file mode 100644 index 00000000000..342fa88e80f --- /dev/null +++ b/doc/articles/index.md @@ -0,0 +1,25 @@ +# Technical Articles + +[Technical Articles](../development/writing_documentation.md#technical-articles) are +topic-related documentation, written with an user-friendly approach and language, aiming +to provide the community with guidance on specific processes to achieve certain objectives. + +They are written by members of the GitLab Team and by +[Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/). + +## Authentication + +- **LDAP** + - [How to configure LDAP with GitLab CE](how_to_configure_ldap_gitlab_ce/index.md) + +## Git + +- [How to install Git](how_to_install_git/index.md) + +## GitLab Pages + +- **GitLab Pages from A to Z** + - [Part 1: Static sites and GitLab Pages domains](../user/project/pages/getting_started_part_one.md) + - [Part 2: Quick start guide - Setting up GitLab Pages](../user/project/pages/getting_started_part_two.md) + - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](../user/project/pages/getting_started_part_three.md) + - [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](../user/project/pages/getting_started_part_four.md) diff --git a/doc/ci/README.md b/doc/ci/README.md index d8fba5d7a77..ca7266ac68f 100644 --- a/doc/ci/README.md +++ b/doc/ci/README.md @@ -1,34 +1,148 @@ -# GitLab CI Documentation +# GitLab Continuous Integration (GitLab CI) -## CI User documentation + + +The benefits of Continuous Integration are huge when automation plays an +integral part of your workflow. GitLab comes with built-in Continuous +Integration, Continuous Deployment, and Continuous Delivery support to build, +test, and deploy your application. + +Here's some info we've gathered to get you started. + +## Getting started + +The first steps towards your GitLab CI journey. - [Getting started with GitLab CI](quick_start/README.md) -- [CI examples for various languages](examples/README.md) -- [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) - [Pipelines and jobs](pipelines.md) -- [Environments and deployments](environments.md) -- [Learn how `.gitlab-ci.yml` works](yaml/README.md) - [Configure a Runner, the application that runs your jobs](runners/README.md) -- [Use Docker images with GitLab Runner](docker/using_docker_images.md) -- [Use CI to build Docker images](docker/using_docker_build.md) +- **Articles:** + - [Getting started with GitLab and GitLab CI - Intro to CI](https://about.gitlab.com/2015/12/14/getting-started-with-gitlab-and-gitlab-ci/) + - [Continuous Integration, Delivery, and Deployment with GitLab - Intro to CI/CD](https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/) + - [GitLab CI: Run jobs sequentially, in parallel, or build a custom pipeline](https://about.gitlab.com/2016/07/29/the-basics-of-gitlab-ci/) + - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) + - [GitLab CI: Deployment & environments](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) +- **Videos:** + - [Demo (March, 2017): how to get started using CI/CD with GitLab](https://about.gitlab.com/2017/03/13/ci-cd-demo/) + - [Webcast (April, 2016): getting started with CI in GitLab](https://about.gitlab.com/2016/04/20/webcast-recording-and-slides-introduction-to-ci-in-gitlab/) +- **Third-party videos:** + - [Intégration continue avec GitLab (September, 2016)](https://www.youtube.com/watch?v=URcMBXjIr24&t=13s) + - [GitLab CI for Minecraft Plugins (July, 2016)](https://www.youtube.com/watch?v=Z4pcI9F8yf8) + +## Reference guides + +Once you get familiar with the getting started guides, you'll find yourself +digging into specific reference guides. + +- [`.gitlab-ci.yml` reference](yaml/README.md) - Learn all about the ins and + outs of `.gitlab-ci.yml` definitions - [CI Variables](variables/README.md) - Learn how to use variables defined in your `.gitlab-ci.yml` or secured ones defined in your project's settings -- [Use SSH keys in your build environment](ssh_keys/README.md) -- [Trigger jobs through the API](triggers/README.md) +- **The permissions model** - Learn about the access levels a user can have for + performing certain CI actions + - [User permissions](../user/permissions.md#gitlab-ci) + - [Jobs permissions](../user/permissions.md#jobs-permissions) + +## GitLab CI + Docker + +Leverage the power of Docker to run your CI pipelines. + +- [Use Docker images with GitLab Runner](docker/using_docker_images.md) +- [Use CI to build Docker images](docker/using_docker_build.md) +- [CI services (linked Docker containers)](services/README.md) +- **Articles:** + - [Setting up GitLab Runner For Continuous Integration](https://about.gitlab.com/2016/03/01/gitlab-runner-with-docker/) + +## Advanced use + +Once you get familiar with the basics of GitLab CI, it's time to dive in and +learn how to leverage its potential even more. + +- [Environments and deployments](environments.md) - Separate your jobs into + environments and use them for different purposes like testing, building and + deploying - [Job artifacts](../user/project/pipelines/job_artifacts.md) -- [User permissions](../user/permissions.md#gitlab-ci) -- [Jobs permissions](../user/permissions.md#jobs-permissions) -- [API](../api/ci/README.md) -- [CI services (linked docker containers)](services/README.md) -- [CI/CD pipelines settings](../user/project/pipelines/settings.md) -- [Review Apps](review_apps/index.md) -- [Git submodules](git_submodules.md) Using Git submodules in your CI jobs +- [Git submodules](git_submodules.md) - How to run your CI jobs when Git + submodules are involved - [Auto deploy](autodeploy/index.md) +- [Use SSH keys in your build environment](ssh_keys/README.md) +- [Trigger pipelines through the GitLab API](triggers/README.md) +- [Trigger pipelines on a schedule](../user/project/pipelines/schedules.md) + +## Review Apps + +- [Review Apps](review_apps/index.md) +- **Articles:** + - [Introducing Review Apps](https://about.gitlab.com/2016/11/22/introducing-review-apps/) + - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) + +## GitLab CI for GitLab Pages + +See the topic on [GitLab Pages](../user/project/pages/index.md). + +## Special configuration + +You can change the default behavior of GitLab CI in your whole GitLab instance +as well as in each project. + +- **Project specific** + - [Pipelines settings](../user/project/pipelines/settings.md) + - [Learn how to enable or disable GitLab CI](enable_or_disable_ci.md) +- **Affecting the whole GitLab instance** + - [Continuous Integration admin settings](../user/admin_area/settings/continuous_integration.md) + +## Examples + +>**Note:** +A collection of `.gitlab-ci.yml` files is maintained at the +[GitLab CI Yml project][gitlab-ci-templates]. +If your favorite programming language or framework is missing we would love +your help by sending a merge request with a `.gitlab-ci.yml`. + +Here is an collection of tutorials and guides on setting up your CI pipeline. + +- [GitLab CI examples](examples/README.md) for the following languages and frameworks: + - [PHP](examples/php.md) + - [Ruby](examples/test-and-deploy-ruby-application-to-heroku.md) + - [Python](examples/test-and-deploy-python-application-to-heroku.md) + - [Clojure](examples/test-clojure-application.md) + - [Scala](examples/test-scala-application.md) + - [Phoenix](examples/test-phoenix-application.md) + - [Run PHP Composer & NPM scripts then deploy them to a staging server](examples/deployment/composer-npm-deploy.md) + - [Analyze code quality with the Code Climate CLI](examples/code_climate.md) +- **Blog posts** + - [Automated Debian packaging](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/) + - [Spring boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/) + - [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) + - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/) + - [Building a new GitLab Docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + - [CI/CD with GitLab in action](https://about.gitlab.com/2017/03/13/ci-cd-demo/) + - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/) +- **Miscellaneous** + - [Using `dpl` as deployment tool](examples/deployment/README.md) + - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples) + - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) + - [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) + +## Integrations + +- **Articles:** + - [Continuous Delivery with GitLab and Convox](https://about.gitlab.com/2016/06/09/continuous-delivery-with-gitlab-and-convox/) + - [Getting Started with GitLab and Shippable Continuous Integration](https://about.gitlab.com/2016/05/05/getting-started-gitlab-and-shippable/) + - [GitLab Partners with DigitalOcean to make Continuous Integration faster, safer, and more affordable](https://about.gitlab.com/2016/04/19/gitlab-partners-with-digitalocean-to-make-continuous-integration-faster-safer-and-more-affordable/) + +## Why GitLab CI? + +- **Articles:** + - [Why We Chose GitLab CI for our CI/CD Solution](https://about.gitlab.com/2016/10/17/gitlab-ci-oohlala/) + - [Building our web-app on GitLab CI: 5 reasons why Captain Train migrated from Jenkins to GitLab CI](https://about.gitlab.com/2016/07/22/building-our-web-app-on-gitlab-ci/) ## Breaking changes -- [CI variables renaming](variables/README.md#9-0-renaming) Read about the +- [CI variables renaming for GitLab 9.0](variables/README.md#9-0-renaming) Read about the deprecated CI variables and what you should use for GitLab 9.0+. - [New CI job permissions model](../user/project/new_ci_build_permissions_model.md) Read about what changed in GitLab 8.12 and how that affects your jobs. There's a new way to access your Git submodules and LFS objects in jobs. + +[gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml diff --git a/doc/ci/api/README.md b/doc/ci/api/README.md index 4ca8d92d7cc..98f37935427 100644 --- a/doc/ci/api/README.md +++ b/doc/ci/api/README.md @@ -1,3 +1 @@ -# GitLab CI API - This document was moved to a [new location](../../api/ci/README.md). diff --git a/doc/ci/api/builds.md b/doc/ci/api/builds.md index f5bd3181c02..0563a367609 100644 --- a/doc/ci/api/builds.md +++ b/doc/ci/api/builds.md @@ -1,3 +1 @@ -# Builds API - This document was moved to a [new location](../../api/ci/builds.md). diff --git a/doc/ci/api/runners.md b/doc/ci/api/runners.md index b14ea99db76..1027363851c 100644 --- a/doc/ci/api/runners.md +++ b/doc/ci/api/runners.md @@ -1,3 +1 @@ -# Runners API - This document was moved to a [new location](../../api/ci/runners.md). diff --git a/doc/ci/autodeploy/img/auto_deploy_dropdown.png b/doc/ci/autodeploy/img/auto_deploy_dropdown.png Binary files differindex 957870ec8c7..b93b0a08fea 100644 --- a/doc/ci/autodeploy/img/auto_deploy_dropdown.png +++ b/doc/ci/autodeploy/img/auto_deploy_dropdown.png diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md index 4028a5efa9e..9fa2b2c4969 100644 --- a/doc/ci/autodeploy/index.md +++ b/doc/ci/autodeploy/index.md @@ -1,6 +1,8 @@ # Auto deploy -> [Introduced][mr-8135] in GitLab 8.15. Currently requires a [Public project][project-settings]. +> [Introduced][mr-8135] in GitLab 8.15. +> Auto deploy is an experimental feature and is not recommended for Production use at this time. +> As of GitLab 9.1, access to the container registry is only available while the Pipeline is running. Restarting a pod, scaling a service, or other actions which require on-going access will fail. On-going secure access is planned for a subsequent release. Auto deploy is an easy way to configure GitLab CI for the deployment of your application. GitLab Community maintains a list of `.gitlab-ci.yml` @@ -15,7 +17,8 @@ deployment. ## Supported templates -The list of supported auto deploy templates is available [here][auto-deploy-templates]. +The list of supported auto deploy templates is available in the +[gitlab-ci-yml project][auto-deploy-templates]. ## Configuration @@ -32,10 +35,37 @@ enable [Kubernetes service][kubernetes-service]. 1. Test your deployment configuration using a [Review App][review-app] that was created automatically for you. +## Private Project Support + +> Experimental support [introduced][mr-2] in GitLab 9.1. + +When a project has been marked as private, GitLab's [Container Registry][container-registry] requires authentication when downloading containers. Auto deploy will automatically provide the required authentication information to Kubernetes, allowing temporary access to the registry. Authentication credentials will be valid while the pipeline is running, allowing for a successful initial deployment. + +After the pipeline completes, Kubernetes will no longer be able to access the container registry. Restarting a pod, scaling a service, or other actions which require on-going access to the registry will fail. On-going secure access is planned for a subsequent release. + +## PostgreSQL Database Support + +> Experimental support [introduced][mr-8] in GitLab 9.1. + +In order to support applications that require a database, [PostgreSQL][postgresql] is provisioned by default. Credentials to access the database are preconfigured, but can be customized by setting the associated [variables](#postgresql-variables). These credentials can be used for defining a `DATABASE_URL` of the format: `postgres://user:password@postgres-host:postgres-port/postgres-database`. It is important to note that the database itself is temporary, and contents will be not be saved. + +PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`. + +### PostgreSQL Variables + +1. `DISABLE_POSTGRES: "yes"`: disable automatic deployment of PostgreSQL +1. `POSTGRES_USER: "my-user"`: use custom username for PostgreSQL +1. `POSTGRES_PASSWORD: "password"`: use custom password for PostgreSQL +1. `POSTGRES_DB: "my database"`: use custom database name for PostgreSQL + [mr-8135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8135 +[mr-2]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/2 +[mr-8]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/8 [project-settings]: https://docs.gitlab.com/ce/public_access/public_access.html [project-services]: ../../user/project/integrations/project_services.md [auto-deploy-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml/tree/master/autodeploy [kubernetes-service]: ../../user/project/integrations/kubernetes.md [docker-in-docker]: ../docker/using_docker_build.md#use-docker-in-docker-executor [review-app]: ../review_apps/index.md +[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html +[postgresql]: https://www.postgresql.org/ diff --git a/doc/ci/docker/using_docker_build.md b/doc/ci/docker/using_docker_build.md index edb315d5b84..408d46a756c 100644 --- a/doc/ci/docker/using_docker_build.md +++ b/doc/ci/docker/using_docker_build.md @@ -37,7 +37,7 @@ GitLab Runner then executes job scripts as the `gitlab-runner` user. ```bash sudo gitlab-ci-multi-runner register -n \ - --url https://gitlab.com/ci \ + --url https://gitlab.com/ \ --registration-token REGISTRATION_TOKEN \ --executor shell \ --description "My Runner" @@ -94,7 +94,7 @@ In order to do that, follow the steps: ```bash sudo gitlab-ci-multi-runner register -n \ - --url https://gitlab.com/ci \ + --url https://gitlab.com/ \ --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ @@ -112,7 +112,7 @@ In order to do that, follow the steps: ``` [[runners]] - url = "https://gitlab.com/ci" + url = "https://gitlab.com/" token = TOKEN executor = "docker" [runners.docker] @@ -179,7 +179,7 @@ In order to do that, follow the steps: ```bash sudo gitlab-ci-multi-runner register -n \ - --url https://gitlab.com/ci \ + --url https://gitlab.com/ \ --registration-token REGISTRATION_TOKEN \ --executor docker \ --description "My Docker Runner" \ @@ -197,7 +197,7 @@ In order to do that, follow the steps: ``` [[runners]] - url = "https://gitlab.com/ci" + url = "https://gitlab.com/" token = REGISTRATION_TOKEN executor = "docker" [runners.docker] @@ -299,8 +299,8 @@ could look like: stage: build script: - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com - - docker build -t registry.example.com/group/project:latest . - - docker push registry.example.com/group/project:latest + - docker build -t registry.example.com/group/project/image:latest . + - docker push registry.example.com/group/project/image:latest ``` You have to use the special `gitlab-ci-token` user created for you in order to @@ -350,8 +350,8 @@ stages: - deploy variables: - CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project:$CI_COMMIT_REF_NAME - CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project:latest + CONTAINER_TEST_IMAGE: registry.example.com/my-group/my-project/my-image:$CI_COMMIT_REF_NAME + CONTAINER_RELEASE_IMAGE: registry.example.com/my-group/my-project/my-image:latest before_script: - docker login -u gitlab-ci-token -p $CI_JOB_TOKEN registry.example.com diff --git a/doc/ci/docker/using_docker_images.md b/doc/ci/docker/using_docker_images.md index f025a7e3496..96834e15bb9 100644 --- a/doc/ci/docker/using_docker_images.md +++ b/doc/ci/docker/using_docker_images.md @@ -146,7 +146,7 @@ private registries that could also require authentication. All you have to do is be explicit on the image definition in `.gitlab-ci.yml`. ```yaml -image: my.registry.tld:5000/namepace/image:tag +image: my.registry.tld:5000/namespace/image:tag ``` In the example above, GitLab Runner will look at `my.registry.tld:5000` for the diff --git a/doc/ci/environments.md b/doc/ci/environments.md index b28f3e13eae..169e0fbae3d 100644 --- a/doc/ci/environments.md +++ b/doc/ci/environments.md @@ -442,7 +442,8 @@ and/or `production`) you can see this information in the merge request itself.  -### Go directly from source files to public pages on the environment +### <a name="route-map"></a>Go directly from source files to public pages on the environment + > Introduced in GitLab 8.17. @@ -590,6 +591,38 @@ exist, you should see something like:  +## Monitoring environments + +>**Notes:** +> +- For the monitor dashboard to appear, you need to: + - Have enabled the [Kubernetes integration][kube] + - Have your app deployed on Kubernetes + - Have enabled the [Prometheus integration][prom] +- With GitLab 9.2, all deployments to an environment are shown directly on the + monitoring dashboard + +If your application is deployed on Kubernetes and you have enabled Prometheus +collecting metrics, you can monitor the performance behavior of your app +through the environments. + +Once configured, GitLab will attempt to retrieve performance metrics for any +environment which has had a successful deployment. If monitoring data was +successfully retrieved, a Monitoring button will appear on the environment's +detail page. + + + +Clicking on the Monitoring button will display a new page, showing up to the last +8 hours of performance data. It may take a minute or two for data to appear +after initial deployment. + +All deployments to an environment are shown directly on the monitoring dashboard +which allows easy correlation between any changes in performance and a new +version of the app, all without leaving GitLab. + + + ## Checkout deployments locally Since 8.13, a reference in the git repository is saved for each deployment, so @@ -631,3 +664,5 @@ Below are some links you may find interesting: [gitlab-flow]: ../workflow/gitlab_flow.md [gitlab runner]: https://docs.gitlab.com/runner/ [git-strategy]: yaml/README.md#git-strategy +[kube]: ../user/project/integrations/kubernetes.md +[prom]: ../user/project/integrations/prometheus.md diff --git a/doc/ci/examples/README.md b/doc/ci/examples/README.md index 5377bf9ee80..2458cb959ab 100644 --- a/doc/ci/examples/README.md +++ b/doc/ci/examples/README.md @@ -1,4 +1,4 @@ -# CI Examples +# GitLab CI Examples A collection of `.gitlab-ci.yml` files is maintained at the [GitLab CI Yml project][gitlab-ci-templates]. If your favorite programming language or framework are missing we would love your help by sending a merge request @@ -6,22 +6,74 @@ with a `.gitlab-ci.yml`. Apart from those, here is an collection of tutorials and guides on setting up your CI pipeline: +## Languages, frameworks, OSs + +### PHP + - [Testing a PHP application](php.md) +- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md) + +### Ruby + - [Test and deploy a Ruby application to Heroku](test-and-deploy-ruby-application-to-heroku.md) + +### Python + - [Test and deploy a Python application to Heroku](test-and-deploy-python-application-to-heroku.md) -- [Test a Clojure application](test-clojure-application.md) + +### Java + +- **Articles:** + - [Continuous Delivery of a Spring Boot application with GitLab CI and Kubernetes](https://about.gitlab.com/2016/12/14/continuous-delivery-of-a-spring-boot-application-with-gitlab-ci-and-kubernetes/) + +### Scala + - [Test a Scala application](test-scala-application.md) + +### Clojure + +- [Test a Clojure application](test-clojure-application.md) + +### Elixir + - [Test a Phoenix application](test-phoenix-application.md) -- [Using `dpl` as deployment tool](deployment/README.md) -- [Example project that shows how to use Review Apps](https://gitlab.com/gitlab-examples/review-apps-nginx/) -- [Run PHP Composer & NPM scripts then deploy them to a staging server](deployment/composer-npm-deploy.md) -- Help your favorite programming language and GitLab by sending a merge request - with a guide for that language. +- **Articles:** + - [Building an Elixir Release into a Docker image using GitLab CI](https://about.gitlab.com/2016/08/11/building-an-elixir-release-into-docker-image-using-gitlab-ci-part-1/) + +### iOS + +- **Articles:** + - [Setting up GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) + +### Android -## Outside the documentation +- **Articles:** + - [Setting up GitLab CI for Android projects](https://about.gitlab.com/2016/11/30/setting-up-gitlab-ci-for-android-projects/) -- [Blog post about using GitLab CI for iOS projects](https://about.gitlab.com/2016/03/10/setting-up-gitlab-ci-for-ios-projects/) +### Other + +- [Using `dpl` as deployment tool](deployment/README.md) - [Repositories with examples for various languages](https://gitlab.com/groups/gitlab-examples) - [The .gitlab-ci.yml file for GitLab itself](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) +- [Analyze code quality with the Code Climate CLI](code_climate.md) +- **Articles:** + - [Continuous Deployment with GitLab: how to build and deploy a Debian Package with GitLab CI](https://about.gitlab.com/2016/10/12/automated-debian-package-build-with-gitlab-ci/) + +## GitLab CI for GitLab Pages + +- [Example projects](https://gitlab.com/pages) +- **Articles:** + - [Creating and Tweaking `.gitlab-ci.yml` for GitLab Pages](../../user/project/pages/getting_started_part_four.md) + - [SSGs Part 3: Build any SSG site with GitLab Pages](https://about.gitlab.com/2016/06/17/ssg-overview-gitlab-pages-part-3-examples-ci/): + examples for Ruby-, NodeJS-, Python-, and GoLang-based SSGs + - [Building a new GitLab docs site with Nanoc, GitLab CI, and GitLab Pages](https://about.gitlab.com/2016/12/07/building-a-new-gitlab-docs-site-with-nanoc-gitlab-ci-and-gitlab-pages/) + - [Publish code coverage reports with GitLab Pages](https://about.gitlab.com/2016/11/03/publish-code-coverage-report-with-gitlab-pages/) + +See the topic [GitLab Pages](../../user/project/pages/index.md) for a complete overview. + +## More + +Contributions are very much welcomed! You can help your favorite programming +language and GitLab by sending a merge request with a guide for that language. [gitlab-ci-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml diff --git a/doc/ci/examples/code_climate.md b/doc/ci/examples/code_climate.md new file mode 100644 index 00000000000..bd53f80ce14 --- /dev/null +++ b/doc/ci/examples/code_climate.md @@ -0,0 +1,28 @@ +# Analyze project code quality with Code Climate CLI + +This example shows how to run [Code Climate CLI][cli] on your code by using\ +GitLab CI and Docker. + +First, you need GitLab Runner with [docker-in-docker executor](../docker/using_docker_build.md#use-docker-in-docker-executor). + +Once you setup the Runner add new job to `.gitlab-ci.yml`: + +```yaml +codeclimate: + image: docker:latest + variables: + DOCKER_DRIVER: overlay + services: + - docker:dind + script: + - docker pull codeclimate/codeclimate + - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate init + - docker run --env CODECLIMATE_CODE="$PWD" --volume "$PWD":/code --volume /var/run/docker.sock:/var/run/docker.sock --volume /tmp/cc:/tmp/cc codeclimate/codeclimate analyze -f json > codeclimate.json + artifacts: + paths: [codeclimate.json] +``` + +This will create a `codeclimate` job in your CI pipeline and will allow you to +download and analyze the report artifact in JSON format. + +[cli]: https://github.com/codeclimate/codeclimate diff --git a/doc/ci/examples/deployment/README.md b/doc/ci/examples/deployment/README.md index 7b0995597c4..e80e246c5dd 100644 --- a/doc/ci/examples/deployment/README.md +++ b/doc/ci/examples/deployment/README.md @@ -111,7 +111,7 @@ We also use two secure variables: ## Storing API keys Secure Variables can added by going to your project's -**Settings ➔ CI/CD Pipelines ➔ Secret variables**. The variables that are defined +**Settings ➔ Pipelines ➔ Secret variables**. The variables that are defined in the project settings are sent along with the build script to the Runner. The secure variables are stored out of the repository. Never store secrets in your project's `.gitlab-ci.yml`. It is also important that the secret's value diff --git a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md index e4d3970deac..73aebaf6d7f 100644 --- a/doc/ci/examples/test-and-deploy-python-application-to-heroku.md +++ b/doc/ci/examples/test-and-deploy-python-application-to-heroku.md @@ -55,11 +55,11 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/). ### Create runner First install [Docker Engine](https://docs.docker.com/installation/). To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). -You can use public runners available on `gitlab.com/ci`, but you can register your own: +You can use public runners available on `gitlab.com`, but you can register your own: ``` gitlab-ci-multi-runner register \ --non-interactive \ - --url "https://gitlab.com/ci/" \ + --url "https://gitlab.com/" \ --registration-token "PROJECT_REGISTRATION_TOKEN" \ --description "python-3.5" \ --executor "docker" \ 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 42f15a27f12..6fa64a67e82 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 @@ -50,11 +50,11 @@ You can do this through the [Dashboard](https://dashboard.heroku.com/). ### Create runner First install [Docker Engine](https://docs.docker.com/installation/). To build this project you also need to have [GitLab Runner](https://about.gitlab.com/gitlab-ci/#gitlab-runner). -You can use public runners available on `gitlab.com/ci`, but you can register your own: +You can use public runners available on `gitlab.com`, but you can register your own: ``` gitlab-ci-multi-runner register \ --non-interactive \ - --url "https://gitlab.com/ci/" \ + --url "https://gitlab.com/" \ --registration-token "PROJECT_REGISTRATION_TOKEN" \ --description "ruby-2.2" \ --executor "docker" \ diff --git a/doc/ci/examples/test-scala-application.md b/doc/ci/examples/test-scala-application.md index 01c13941c21..09d83c33f95 100644 --- a/doc/ci/examples/test-scala-application.md +++ b/doc/ci/examples/test-scala-application.md @@ -54,7 +54,7 @@ You can use other versions of Scala and SBT by defining them in ## Display test coverage in job Add the `Coverage was \[\d+.\d+\%\]` regular expression in the -**Settings ➔ CI/CD Pipelines ➔ Coverage report** project setting to +**Settings ➔ Pipelines ➔ Coverage report** project setting to retrieve the [test coverage] rate from the build trace and have it displayed with your jobs. diff --git a/doc/ci/img/cicd_pipeline_infograph.png b/doc/ci/img/cicd_pipeline_infograph.png Binary files differnew file mode 100644 index 00000000000..9ddd4aa828b --- /dev/null +++ b/doc/ci/img/cicd_pipeline_infograph.png diff --git a/doc/ci/img/environments_monitoring.png b/doc/ci/img/environments_monitoring.png Binary files differnew file mode 100644 index 00000000000..387b6c54b61 --- /dev/null +++ b/doc/ci/img/environments_monitoring.png diff --git a/doc/ci/img/pipelines.png b/doc/ci/img/pipelines.png Binary files differindex 5937e9d99c8..a604fcb2587 100644 --- a/doc/ci/img/pipelines.png +++ b/doc/ci/img/pipelines.png diff --git a/doc/ci/img/pipelines_grouped.png b/doc/ci/img/pipelines_grouped.png Binary files differnew file mode 100644 index 00000000000..06f52e03320 --- /dev/null +++ b/doc/ci/img/pipelines_grouped.png diff --git a/doc/ci/img/pipelines_index.png b/doc/ci/img/pipelines_index.png Binary files differnew file mode 100644 index 00000000000..3b522a9c5e4 --- /dev/null +++ b/doc/ci/img/pipelines_index.png diff --git a/doc/ci/img/pipelines_mini_graph.png b/doc/ci/img/pipelines_mini_graph.png Binary files differnew file mode 100644 index 00000000000..042c8ffeef5 --- /dev/null +++ b/doc/ci/img/pipelines_mini_graph.png diff --git a/doc/ci/img/pipelines_mini_graph_simple.png b/doc/ci/img/pipelines_mini_graph_simple.png Binary files differnew file mode 100644 index 00000000000..eb36c09b2d4 --- /dev/null +++ b/doc/ci/img/pipelines_mini_graph_simple.png diff --git a/doc/ci/img/pipelines_mini_graph_sorting.png b/doc/ci/img/pipelines_mini_graph_sorting.png Binary files differnew file mode 100644 index 00000000000..3a4e5453360 --- /dev/null +++ b/doc/ci/img/pipelines_mini_graph_sorting.png diff --git a/doc/ci/img/prometheus_environment_detail_with_metrics.png b/doc/ci/img/prometheus_environment_detail_with_metrics.png Binary files differnew file mode 100644 index 00000000000..214b10624a9 --- /dev/null +++ b/doc/ci/img/prometheus_environment_detail_with_metrics.png diff --git a/doc/ci/pipelines.md b/doc/ci/pipelines.md index db92a4b0d80..5a2b61fb0cb 100644 --- a/doc/ci/pipelines.md +++ b/doc/ci/pipelines.md @@ -1,7 +1,6 @@ # Introduction to pipelines and jobs ->**Note:** -Introduced in GitLab 8.8. +> Introduced in GitLab 8.8. ## Pipelines @@ -9,11 +8,17 @@ A pipeline is a group of [jobs][] that get executed in [stages][](batches). All of the jobs in a stage are executed in parallel (if there are enough concurrent [Runners]), and if they all succeed, the pipeline moves on to the next stage. If one of the jobs fails, the next stage is not (usually) -executed. +executed. You can access the pipelines page in your project's **Pipelines** tab. + +In the following image you can see that the pipeline consists of four stages +(`build`, `test`, `staging`, `production`) each one having one or more jobs. + +>**Note:** +GitLab capitalizes the stages' names when shown in the [pipeline graphs](#pipeline-graphs).  -## Types of Pipelines +## Types of pipelines There are three types of pipelines that often use the single shorthand of "pipeline". People often talk about them as if each one is "the" pipeline, but really, they're just pieces of a single, comprehensive pipeline. @@ -23,7 +28,7 @@ There are three types of pipelines that often use the single shorthand of "pipel 2. **Deploy Pipeline**: Deploy stage(s) defined in `.gitlab-ci.yml` The flow of deploying code to servers through various stages: e.g. development to staging to production 3. **Project Pipeline**: Cross-project CI dependencies [triggered via API][triggers], particularly for micro-services, but also for complicated build dependencies: e.g. api -> front-end, ce/ee -> omnibus. -## Development Workflows +## Development workflows Pipelines accommodate several development workflows: @@ -45,18 +50,141 @@ confused with a `build` job or `build` stage. Pipelines are defined in `.gitlab-ci.yml` by specifying [jobs] that run in [stages]. -See full [documentation](yaml/README.md#jobs). +See the reference [documentation for jobs](yaml/README.md#jobs). ## Seeing pipeline status -You can find the current and historical pipeline runs under **Pipelines** for -your project. +You can find the current and historical pipeline runs under your project's +**Pipelines** tab. Clicking on a pipeline will show the jobs that were run for +that pipeline. + + ## Seeing job status -Clicking on a pipeline will show the jobs that were run for that pipeline. +When you visit a single pipeline you can see the related jobs for that pipeline. Clicking on an individual job will show you its job trace, and allow you to -cancel the job, retry it, or erase the job trace. +cancel the job, retry it, or erase the job trace. + + + +## Pipeline graphs + +> [Introduced][ce-5742] in GitLab 8.11. + +Pipelines can be complex structures with many sequential and parallel jobs. +To make it a little easier to see what is going on, you can view a graph +of a single pipeline and its status. + +A pipeline graph can be shown in two different ways depending on what page you +are on. + +--- + +The regular pipeline graph that shows the names of the jobs of each stage can +be found when you are on a [single pipeline page](#seeing-pipeline-status). + + + +Then, there is the pipeline mini graph which takes less space and can give you a +quick glance if all jobs pass or something failed. The pipeline mini graph can +be found when you visit: + +- the pipelines index page +- a single commit page +- a merge request page + +That way, you can see all related jobs for a single commit and the net result +of each stage of your pipeline. This allows you to quickly see what failed and +fix it. Stages in pipeline mini graphs are collapsible. Hover your mouse over +them and click to expand their jobs. + +| **Mini graph** | **Mini graph expanded** | +| :------------: | :---------------------: | +|  |  | + +### Grouping similar jobs in the pipeline graph + +> [Introduced][ce-6242] in GitLab 8.12. + +If you have many similar jobs, your pipeline graph becomes very long and hard +to read. For that reason, similar jobs can automatically be grouped together. +If the job names are formatted in certain ways, they will be collapsed into +a single group in regular pipeline graphs (not the mini graphs). +You'll know when a pipeline has grouped jobs if you don't see the retry or +cancel button inside them. Hovering over them will show the number of grouped +jobs. Click to expand them. + + + +The basic requirements is that there are two numbers separated with one of +the following (you can even use them interchangeably): + +- a space +- a backslash (`/`) +- a colon (`:`) + +>**Note:** +More specifically, [it uses][regexp] this regular expression: `\d+[\s:\/\\]+\d+\s*`. + +The jobs will be ordered by comparing those two numbers from left to right. You +usually want the first to be the index and the second the total. + +For example, the following jobs will be grouped under a job named `test`: + +- `test 0 3` => `test` +- `test 1 3` => `test` +- `test 2 3` => `test` + +The following jobs will be grouped under a job named `test ruby`: + +- `test 1:2 ruby` => `test ruby` +- `test 2:2 ruby` => `test ruby` + +The following jobs will be grouped under a job named `test ruby` as well: + +- `1/3 test ruby` => `test ruby` +- `2/3 test ruby` => `test ruby` +- `3/3 test ruby` => `test ruby` + +### Manual actions from the pipeline graph + +> [Introduced][ce-7931] in GitLab 8.15. + +[Manual actions][manual] allow you to require manual interaction before moving +forward with a particular job in CI. Your entire pipeline can run automatically, +but the actual [deploy to production][env-manual] will require a click. + +You can do this straight from the pipeline graph. Just click on the play button +to execute that particular job. For example, in the image below, the `production` +stage has a job with a manual action. + + + +### Ordering of jobs in pipeline graphs + +**Regular pipeline graph** + +In the single pipeline page, jobs are sorted by name. + +**Mini pipeline graph** + +> [Introduced][ce-9760] in GitLab 9.0. + +In the pipeline mini graphs, the jobs are sorted first by severity and then +by name. The order of severity is: + +- failed +- warning +- pending +- running +- manual +- canceled +- success +- skipped +- created + + ## How the pipeline duration is calculated @@ -96,7 +224,14 @@ respective link in the [Pipelines settings] page. [jobs]: #jobs [jobs-yaml]: yaml/README.md#jobs +[manual]: yaml/README.md#manual +[env-manual]: environments.md#manually-deploying-to-environments [stages]: yaml/README.md#stages [runners]: runners/README.html [pipelines settings]: ../user/project/pipelines/settings.md [triggers]: triggers/README.md +[ce-5742]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5742 +[ce-6242]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/6242 +[ce-7931]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7931 +[ce-9760]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9760 +[regexp]: https://gitlab.com/gitlab-org/gitlab-ce/blob/2f3dc314f42dbd79813e6251792853bc231e69dd/app/models/commit_status.rb#L99 diff --git a/doc/ci/quick_start/README.md b/doc/ci/quick_start/README.md index 30f209f80eb..41cae58782d 100644 --- a/doc/ci/quick_start/README.md +++ b/doc/ci/quick_start/README.md @@ -155,7 +155,7 @@ Find more information about different Runners in the [Runners](../runners/README.md) documentation. You can find whether any Runners are assigned to your project by going to -**Settings ➔ Runners**. Setting up a Runner is easy and straightforward. The +**Settings ➔ CI/CD Pipelines**. Setting up a Runner is easy and straightforward. The official Runner supported by GitLab is written in Go and its documentation can be found at <https://docs.gitlab.com/runner/>. @@ -168,7 +168,7 @@ Follow the links above to set up your own Runner or use a Shared Runner as described in the next section. Once the Runner has been set up, you should see it on the Runners page of your -project, following **Settings ➔ Runners**. +project, following **Settings ➔ CI/CD Pipelines**.  @@ -181,7 +181,7 @@ These are special virtual machines that run on GitLab's infrastructure and can build any project. To enable the **Shared Runners** you have to go to your project's -**Settings ➔ Runners** and click **Enable shared runners**. +**Settings ➔ CI/CD Pipelines** and click **Enable shared runners**. [Read more on Shared Runners](../runners/README.md). diff --git a/doc/ci/triggers/README.md b/doc/ci/triggers/README.md index e380282f910..cb646827fb4 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -1,6 +1,6 @@ -# Triggering jobs through the API +# Triggering pipelines through the API -> **Note**: +> **Notes**: - [Introduced][ci-229] in GitLab CE 7.14. - GitLab 8.12 has a completely redesigned job permissions system. Read all about the [new model and its implications](../../user/project/new_ci_build_permissions_model.md#job-triggers). @@ -12,7 +12,7 @@ with an API call. ## Add a trigger You can add a new trigger by going to your project's -**Settings ➔ CI/CD Pipelines ➔ Triggers**. The **Add trigger** button will +**Settings ➔ Pipelines ➔ Triggers**. The **Add trigger** button will create a new token which you can then use to trigger a rerun of this particular project's pipeline. @@ -60,7 +60,7 @@ POST /projects/:id/trigger/pipeline The required parameters are the trigger's `token` and the Git `ref` on which the trigger will be performed. Valid refs are the branch and the tag. The `:id` of a project can be found by [querying the API](../../api/projects.md) -or by visiting the **CI/CD Pipelines** settings page which provides +or by visiting the **Pipelines** settings page which provides self-explanatory examples. When a rerun of a pipeline is triggered, the information is exposed in GitLab's @@ -208,7 +208,7 @@ curl --request POST \ https://gitlab.example.com/api/v4/projects/9/trigger/pipeline ``` -### Using webhook to trigger job +### Using a webhook to trigger a pipeline You can add the following webhook to another project in order to trigger a job: @@ -216,7 +216,11 @@ You can add the following webhook to another project in order to trigger a job: https://gitlab.example.com/api/v4/projects/9/ref/master/trigger/pipeline?token=TOKEN&variables[UPLOAD_TO_S3]=true ``` -### Using cron to trigger nightly jobs +### Using cron to trigger nightly pipelines + +>**Note:** +The following behavior can also be achieved through GitLab's UI with +[pipeline schedules](../../user/project/pipelines/schedules.md). Whether you craft a script or just run cURL directly, you can trigger jobs in conjunction with cron. The example below triggers a job on the `master` diff --git a/doc/ci/variables/README.md b/doc/ci/variables/README.md index b35caf672a8..0d4d08106f8 100644 --- a/doc/ci/variables/README.md +++ b/doc/ci/variables/README.md @@ -152,7 +152,7 @@ available in the build environment. It's the recommended method to use for storing things like passwords, secret keys and credentials. Secret variables can be added by going to your project's -**Settings ➔ CI/CD Pipelines**, then finding the section called +**Settings ➔ Pipelines**, then finding the section called **Secret Variables**. Once you set them, they will be available for all subsequent jobs. @@ -311,7 +311,7 @@ Running on runner-8a2f473d-project-1796893-concurrent-0 via runner-8a2f473d-mach ++ export GITLAB_USER_ID=42 ++ GITLAB_USER_ID=42 ++ export GITLAB_USER_EMAIL=user@example.com -++ GITLAB_USER_EMAIL=axilleas@axilleas.me +++ GITLAB_USER_EMAIL=user@example.com ++ export VERY_SECURE_VARIABLE=imaverysecurevariable ++ VERY_SECURE_VARIABLE=imaverysecurevariable ++ mkdir -p /builds/gitlab-examples/ci-debug-trace.tmp @@ -333,7 +333,7 @@ prefix the variable name with the dollar sign (`$`): ``` job_name: script: - - echo $CI_job_ID + - echo $CI_JOB_ID ``` You can also list all environment variables with the `export` command, @@ -352,7 +352,7 @@ Example values: export CI_JOB_ID="50" export CI_COMMIT_SHA="1ecfd275763eff1d6b4844ea3168962458c9f27a" export CI_COMMIT_REF_NAME="master" -export CI_REPOSITORY_URL="https://gitab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git" +export CI_REPOSITORY_URL="https://gitlab-ci-token:abcde-1234ABCD5678ef@example.com/gitlab-org/gitlab-ce.git" export CI_COMMIT_TAG="1.0.0" export CI_JOB_NAME="spec:other" export CI_JOB_STAGE="test" diff --git a/doc/ci/yaml/README.md b/doc/ci/yaml/README.md index ad3ebd144df..da20076da52 100644 --- a/doc/ci/yaml/README.md +++ b/doc/ci/yaml/README.md @@ -147,6 +147,10 @@ variables: DATABASE_URL: "postgres://postgres@postgres/my_database" ``` +>**Note:** +Integers (as well as strings) are legal both for variable's name and value. +Floats are not legal and cannot be used. + These variables can be later used in all executed commands and scripts. The YAML-defined variables are also set to all created service containers, thus allowing to fine tune them. Variables can be also defined on a @@ -162,7 +166,11 @@ which can be set in GitLab's UI. ### cache -> Introduced in GitLab Runner v0.7.0. +> +**Notes:** +- Introduced in GitLab Runner v0.7.0. +- Prior to GitLab 9.2, caches were restored after artifacts. +- From GitLab 9.2, caches are restored before artifacts. `cache` is used to specify a list of files and directories which should be cached between jobs. You can only use paths that are within the project @@ -553,6 +561,8 @@ The above script will: #### Manual actions > Introduced in GitLab 8.10. +> Blocking manual actions were introduced in GitLab 9.0 +> Protected actions were introduced in GitLab 9.2 Manual actions are a special type of job that are not executed automatically; they need to be explicitly started by a user. Manual actions can be started @@ -578,7 +588,10 @@ Optional manual actions have `allow_failure: true` set by default. **Statuses of optional actions do not contribute to overall pipeline status.** -> Blocking manual actions were introduced in GitLab 9.0 +**Manual actions are considered to be write actions, so permissions for +protected branches are used when user wants to trigger an action. In other +words, in order to trigger a manual action assigned to a branch that the +pipeline is running for, user needs to have ability to push to this branch.** ### environment @@ -764,6 +777,8 @@ as Review Apps. You can see a simple example using Review Apps at **Notes:** - Introduced in GitLab Runner v0.7.0 for non-Windows platforms. - Windows support was added in GitLab Runner v.1.0.0. +- Prior to GitLab 9.2, caches were restored after artifacts. +- From GitLab 9.2, caches are restored before artifacts. - Currently not all executors are supported. - Job artifacts are only collected for successful jobs by default. @@ -1147,7 +1162,7 @@ Example: ```yaml variables: - GET_SOURCES_ATTEMPTS: "3" + GET_SOURCES_ATTEMPTS: 3 ``` You can set them in the global [`variables`](#variables) section or the diff --git a/doc/development/README.md b/doc/development/README.md index 3c797505aa9..934c6849ff9 100644 --- a/doc/development/README.md +++ b/doc/development/README.md @@ -33,7 +33,6 @@ ## Backend howtos - [Architecture](architecture.md) of GitLab -- [CI setup](ci_setup.md) for testing GitLab - [Gotchas](gotchas.md) to avoid - [How to dump production data to staging](db_dump.md) - [Instrumentation](instrumentation.md) @@ -42,12 +41,18 @@ - [Shell commands](shell_commands.md) in the GitLab codebase - [Sidekiq debugging](sidekiq_debugging.md) - [Object state models](object_state_models.md) +- [Building a package for testing purposes](build_test_package.md) ## Databases - [What requires downtime?](what_requires_downtime.md) - [Adding database indexes](adding_database_indexes.md) - [Post Deployment Migrations](post_deployment_migrations.md) +- [Foreign Keys & Associations](foreign_keys.md) + +## i18n + +- [Internationalization for GitLab](i18n_guide.md) ## Compliance diff --git a/doc/development/architecture.md b/doc/development/architecture.md index 4eb7a8eee48..b36fd52603b 100644 --- a/doc/development/architecture.md +++ b/doc/development/architecture.md @@ -4,7 +4,7 @@ There are two editions of GitLab: [Enterprise Edition](https://about.gitlab.com/gitlab-ee/) (EE) and [Community Edition](https://about.gitlab.com/gitlab-ce/) (CE). GitLab CE is delivered via git from the [gitlabhq repository](https://gitlab.com/gitlab-org/gitlab-ce/tree/master). New versions of GitLab are released in stable branches and the master branch is for bleeding edge development. -EE releases are available not long after CE releases. To obtain the GitLab EE there is a [repository at gitlab.com](https://gitlab.com/subscribers/gitlab-ee). For more information about the release process see the section 'New versions and upgrading' in the readme. +EE releases are available not long after CE releases. To obtain the GitLab EE there is a [repository at gitlab.com](https://gitlab.com/gitlab-org/gitlab-ee). For more information about the release process see the section 'New versions and upgrading' in the readme. Both EE and CE require some add-on components called gitlab-shell and Gitaly. These components are available from the [gitlab-shell](https://gitlab.com/gitlab-org/gitlab-shell/tree/master) and [gitaly](https://gitlab.com/gitlab-org/gitaly/tree/master) repositories respectively. New versions are usually tags but staying on the master branch will give you the latest stable version. New releases are generally around the same time as GitLab CE releases with exception for informal security updates deemed critical. diff --git a/doc/development/build_test_package.md b/doc/development/build_test_package.md new file mode 100644 index 00000000000..439d228baef --- /dev/null +++ b/doc/development/build_test_package.md @@ -0,0 +1,39 @@ +# Building a package for testing + +While developing a new feature or modifying an existing one, it is helpful if an +installable package (or a docker image) containing those changes is available +for testing. For this very purpose, a manual job is provided in the GitLab CI/CD +pipeline that can be used to trigger a pipeline in the omnibus-gitlab repository +that will create +1. A deb package for Ubuntu 16.04, available as a build artifact, and +2. A docker image, which is pushed to [Omnibus GitLab's container +registry](https://gitlab.com/gitlab-org/omnibus-gitlab/container_registry) +(images titled `gitlab-ce` and `gitlab-ee` respectively and image tag is the +commit which triggered the pipeline). + +When you push a commit to either the gitlab-ce or gitlab-ee project, the +pipeline for that commit will have a `build-package` manual action you can +trigger. + + + + + +## Specifying versions of components + +If you want to create a package from a specific branch, commit or tag of any of +the GitLab components (like GitLab Workhorse, Gitaly, GitLab Pages, etc.), you +can specify the branch name, commit sha or tag in the component's respective +`*_VERSION` file. For example, if you want to build a package that uses the +branch `0-1-stable`, modify the content of `GITALY_SERVER_VERSION` to +`0-1-stable` and push the commit. This will create a manual job that can be +used to trigger the build. + +## Specifying the branch in omnibus-gitlab repository + +In scenarios where a configuration change is to be introduced and omnibus-gitlab +repository already has the necessary changes in a specific branch, you can build +a package against that branch through an environment variable named +`OMNIBUS_BRANCH`. To do this, specify that environment variable with the name of +the branch as value in `.gitlab-ci.yml` and push a commit. This will create a +manual job that can be used to trigger the build. diff --git a/doc/development/ci_setup.md b/doc/development/ci_setup.md deleted file mode 100644 index 0810b32efd7..00000000000 --- a/doc/development/ci_setup.md +++ /dev/null @@ -1,47 +0,0 @@ -# CI setup - -This document describes what services we use for testing GitLab and GitLab CI. - -We currently use four CI services to test GitLab: - -1. GitLab CI on [GitHost.io](https://gitlab-ce.githost.io/projects/4/) for the [GitLab.com repo](https://gitlab.com/gitlab-org/gitlab-ce) -2. GitLab CI at ci.gitlab.org to test the private GitLab B.V. repo at dev.gitlab.org -3. [Semephore](https://semaphoreapp.com/gitlabhq/gitlabhq/) for [GitHub.com repo](https://github.com/gitlabhq/gitlabhq) -4. [Mock CI Service](../user/project/integrations/mock_ci.md) for local development - -| Software @ configuration being tested | GitLab CI (ci.gitlab.org) | GitLab CI (GitHost.io) | Semaphore | -|---------------------------------------|---------------------------|---------------------------------------------------------------------------|-----------| -| GitLab CE @ MySQL | ✓ | ✓ [Core team can trigger builds](https://gitlab-ce.githost.io/projects/4) | | -| GitLab CE @ PostgreSQL | | | ✓ [Core team can trigger builds](https://semaphoreapp.com/gitlabhq/gitlabhq/branches/master) | -| GitLab EE @ MySQL | ✓ | | | -| GitLab CI @ MySQL | ✓ | | | -| GitLab CI @ PostgreSQL | | | ✓ | -| GitLab CI Runner | ✓ | | ✓ | -| GitLab Shell | ✓ | | ✓ | -| GitLab Shell | ✓ | | ✓ | - -Core team has access to trigger builds if needed for GitLab CE. - -We use [these build scripts](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.gitlab-ci.yml) for testing with GitLab CI. - -# Build configuration on [Semaphore](https://semaphoreapp.com/gitlabhq/gitlabhq/) for testing the [GitHub.com repo](https://github.com/gitlabhq/gitlabhq) - -- Language: Ruby -- Ruby version: 2.1.8 -- database.yml: pg - -Build commands - -```bash -sudo apt-get install cmake libicu-dev -y (Setup) -bundle install --deployment --path vendor/bundle (Setup) -cp config/gitlab.yml.example config/gitlab.yml (Setup) -bundle exec rake db:create (Setup) -bundle exec rake spinach (Thread #1) -bundle exec rake spec (thread #2) -bundle exec rake rubocop (thread #3) -bundle exec rake brakeman (thread #4) -bundle exec rake jasmine:ci (thread #5) -``` - -Use rubygems mirror. diff --git a/doc/development/code_review.md b/doc/development/code_review.md index 819578404b6..4ed89146072 100644 --- a/doc/development/code_review.md +++ b/doc/development/code_review.md @@ -1,5 +1,27 @@ # Code Review Guidelines +## Getting your merge request reviewed, approved, and merged + +There are a few rules to get your merge request accepted: + +1. Your merge request should only be **merged by a [maintainer][team]**. + 1. If your merge request includes only backend changes [^1], it must be + **approved by a [backend maintainer][projects]**. + 1. If your merge request includes only frontend changes [^1], it must be + **approved by a [frontend maintainer][projects]**. + 1. If your merge request includes frontend and backend changes [^1], it must + be **approved by a [frontend and a backend maintainer][projects]**. +1. To lower the amount of merge requests maintainers need to review, you can + ask or assign any [reviewers][projects] for a first review. + 1. If you need some guidance (e.g. it's your first merge request), feel free + to ask one of the [Merge request coaches][team]. + 1. The reviewer will assign the merge request to a maintainer once the + reviewer is satisfied with the state of the merge request. + +For more guidance, see [CONTRIBUTING.md](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/CONTRIBUTING.md). + +## Best practices + This guide contains advice and best practices for performing code review, and having your code reviewed. @@ -10,9 +32,9 @@ code is effective, understandable, and maintainable. Any developer can, and is encouraged to, perform code review on merge requests of colleagues and contributors. However, the final decision to accept a merge request is up to one the project's maintainers, denoted on the -[team page](https://about.gitlab.com/team). +[engineering projects][projects]. -## Everyone +### Everyone - Accept that many programming decisions are opinions. Discuss tradeoffs, which you prefer, and reach a resolution quickly. @@ -31,8 +53,11 @@ request is up to one the project's maintainers, denoted on the - Consider one-on-one chats or video calls if there are too many "I didn't understand" or "Alternative solution:" comments. Post a follow-up comment summarizing one-on-one discussion. +- If you ask a question to a specific person, always start the comment by + mentioning them; this will ensure they see it if their notification level is + set to "mentioned" and other people will understand they don't have to respond. -## Having your code reviewed +### Having your code reviewed Please keep in mind that code review is a process that can take multiple iterations, and reviewers may spot things later that they may not have seen the @@ -50,11 +75,12 @@ first time. - Extract unrelated changes and refactorings into future merge requests/issues. - Seek to understand the reviewer's perspective. - Try to respond to every comment. +- Let the reviewer select the "Resolve discussion" buttons. - Push commits based on earlier rounds of feedback as isolated commits to the branch. Do not squash until the branch is ready to merge. Reviewers should be able to read individual updates based on their earlier feedback. -## Reviewing code +### Reviewing code Understand why the change is necessary (fixes a bug, improves the user experience, refactors the existing code). Then: @@ -69,12 +95,19 @@ experience, refactors the existing code). Then: someone else would be confused by it as well. - After a round of line notes, it can be helpful to post a summary note such as "LGTM :thumbsup:", or "Just a couple things to address." +- Assign the merge request to the author if changes are required following your + review. +- Set the milestone before merging a merge request. - Avoid accepting a merge request before the job succeeds. Of course, "Merge When Pipeline Succeeds" (MWPS) is fine. - If you set the MR to "Merge When Pipeline Succeeds", you should take over subsequent revisions for anything that would be spotted after that. +- Consider using the [Squash and + merge][squash-and-merge] feature when the merge request has a lot of commits. + +[squash-and-merge]: https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html#squash-and-merge -## The right balance +### The right balance One of the most difficult things during code review is finding the right balance in how deep the reviewer can interfere with the code created by a @@ -100,7 +133,7 @@ reviewee. tomorrow. When you are not able to find the right balance, ask other people about their opinion. -## Credits +### Credits Largely based on the [thoughtbot code review guide]. @@ -109,3 +142,6 @@ Largely based on the [thoughtbot code review guide]. --- [Return to Development documentation](README.md) + +[projects]: https://about.gitlab.com/handbook/engineering/projects/ +[team]: https://about.gitlab.com/team/ diff --git a/doc/development/doc_styleguide.md b/doc/development/doc_styleguide.md index bb78a0de0c5..5b09f79f143 100644 --- a/doc/development/doc_styleguide.md +++ b/doc/development/doc_styleguide.md @@ -29,7 +29,8 @@ The table below shows what kind of documentation goes where. | `doc/legal/` | Legal documents about contributing to GitLab. | | `doc/install/`| Probably the most visited directory, since `installation.md` is there. Ideally this should go under `doc/administration/`, but it's best to leave it as-is in order to avoid confusion (still debated though). | | `doc/update/` | Same with `doc/install/`. Should be under `administration/`, but this is a well known location, better leave as-is, at least for now. | -| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`); Technical Articles: user guides, admin guides, technical overviews, tutorials (`doc/topics/topic-name/`). | +| `doc/topics/` | Indexes per Topic (`doc/topics/topic-name/index.md`): all resources for that topic (user and admin documentation, articles, and third-party docs) | +| `doc/articles/` | [Technical Articles](writing_documentation.md#technical-articles): user guides, admin guides, technical overviews, tutorials (`doc/articles/article-title/index.md`). | --- @@ -61,8 +62,8 @@ The table below shows what kind of documentation goes where. located at `doc/user/admin_area/settings/visibility_and_access_controls.md`. 1. The `doc/topics/` directory holds topic-related technical content. Create `doc/topics/topic-name/subtopic-name/index.md` when subtopics become necessary. - Note that `topics` holds the index page per topic, and technical articles. General - user- and admin- related documentation, should be placed accordingly. + General user- and admin- related documentation, should be placed accordingly. +1. For technical articles, place their images under `doc/articles/article-title/img/`. --- @@ -197,10 +198,17 @@ You can combine one or more of the following: the `.md` document that you're working on is located. Always prepend their names with the name of the document that they will be included in. For example, if there is a document called `twitter.md`, then a valid image name - could be `twitter_login_screen.png`. + could be `twitter_login_screen.png`. [**Exception**: images for + [articles](writing_documentation.md#technical-articles) should be + put in a directory called `img` underneath `/articles/article_title/img/`, therefore, + there's no need to prepend the document name to their filenames.] - Images should have a specific, non-generic name that will differentiate them. - Keep all file names in lower case. - Consider using PNG images instead of JPEG. +- Compress all images with <https://tinypng.com/> or similar tool. +- Compress gifs with <https://ezgif.com/optimize> or similar toll. +- Images should be used (only when necessary) to _illustrate_ the description +of a process, not to _replace_ it. Inside the document: diff --git a/doc/development/fe_guide/droplab/droplab.md b/doc/development/fe_guide/droplab/droplab.md new file mode 100644 index 00000000000..112ff3419d9 --- /dev/null +++ b/doc/development/fe_guide/droplab/droplab.md @@ -0,0 +1,258 @@ +# DropLab + +A generic dropdown for all of your custom dropdown needs. + +## Usage + +DropLab can be used by simply adding a `data-dropdown-trigger` HTML attribute. +This attribute allows us to find the "trigger" _(toggle)_ for the dropdown, +whether that is a button, link or input. + +The value of the `data-dropdown-trigger` should be a CSS selector that +DropLab can use to find the trigger's dropdown list. + +You should also add the `data-dropdown` attribute to declare the dropdown list. +The value is irrelevant. + +The DropLab class has no side effects, so you must always call `.init` when +the DOM is ready. `DropLab.prototype.init` takes the same arguments as `DropLab.prototype.addHook`. +If you do not provide any arguments, it will globally query and instantiate all droplab compatible dropdowns. + +```html +<a href="#" data-dropdown-trigger="#list">Toggle</a> + +<ul id="list" data-dropdown> + <!-- ... --> +<ul> +``` +```js +const droplab = new DropLab(); +droplab.init(); +``` + +As you can see, we have a "Toggle" link, that is declared as a trigger. +It provides a selector to find the dropdown list it should control. + +### Static data + +You can add static list items. + +```html +<a href="#" data-dropdown-trigger="#list">Toggle</a> + +<ul id="list" data-dropdown> + <li>Static value 1</li> + <li>Static value 2</li> +<ul> +``` +```js +const droplab = new DropLab(); +droplab.init(); +``` + +### Explicit instantiation + +You can pass the trigger and list elements as constructor arguments to return +a non-global instance of DropLab using the `DropLab.prototype.init` method. + +```html +<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> + +<ul id="list" data-dropdown> + <!-- ... --> +<ul> +``` +```js +const trigger = document.getElementById('trigger'); +const list = document.getElementById('list'); + +const droplab = new DropLab(); +droplab.init(trigger, list); +``` + +You can also add hooks to an existing DropLab instance using `DropLab.prototype.addHook`. + +```html +<a href="#" data-dropdown-trigger="#auto-dropdown">Toggle</a> +<ul id="auto-dropdown" data-dropdown><!-- ... --><ul> + +<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> +<ul id="list" data-dropdown><!-- ... --><ul> +``` +```js +const droplab = new DropLab(); + +droplab.init(); + +const trigger = document.getElementById('trigger'); +const list = document.getElementById('list'); + +droplab.addHook(trigger, list); +``` + + +### Dynamic data + +Adding `data-dynamic` to your dropdown element will enable dynamic list rendering. + +You can template a list item using the keys of the data object provided. +Use the handlebars syntax `{{ value }}` to HTML escape the value. +Use the `<%= value %>` syntax to simply interpolate the value. +Use the `<%= value %>` syntax to evaluate the value. + +Passing an array of objects to `DropLab.prototype.addData` will render that data +for all `data-dynamic` dropdown lists tracked by that DropLab instance. + +```html +<a href="#" data-dropdown-trigger="#list">Toggle</a> + +<ul id="list" data-dropdown data-dynamic> + <li><a href="#" data-id="{{id}}">{{text}}</a></li> +</ul> +``` +```js +const droplab = new DropLab(); + +droplab.init().addData([{ + id: 0, + text: 'Jacob', +}, { + id: 1, + text: 'Jeff', +}]); +``` + +Alternatively, you can specify a specific dropdown to add this data to but passing +the data as the second argument and and the `id` of the trigger element as the first argument. + +```html +<a href="#" data-dropdown-trigger="#list" id="trigger">Toggle</a> + +<ul id="list" data-dropdown data-dynamic> + <li><a href="#" data-id="{{id}}">{{text}}</a></li> +</ul> +``` +```js +const droplab = new DropLab(); + +droplab.init().addData('trigger', [{ + id: 0, + text: 'Jacob', +}, { + id: 1, + text: 'Jeff', +}]); +``` + +This allows you to mix static and dynamic content with ease, even with one trigger. + +Note the use of scoping regarding the `data-dropdown` attribute to capture both +dropdown lists, one of which is dynamic. + +```html +<input id="trigger" data-dropdown-trigger="#list"> +<div id="list" data-dropdown> + <ul> + <li><a href="#">Static item 1</a></li> + <li><a href="#">Static item 2</a></li> + </ul> + <ul data-dynamic> + <li><a href="#" data-id="{{id}}">{{text}}</a></li> + </ul> +</div> +``` +```js +const droplab = new DropLab(); + +droplab.init().addData('trigger', [{ + id: 0, + text: 'Jacob', +}, { + id: 1, + text: 'Jeff', +}]); +``` + +## Internal selectors + +DropLab adds some CSS classes to help lower the barrier to integration. + +For example, + +* The `droplab-item-selected` css class is added to items that have been selected +either by a mouse click or by enter key selection. +* The `droplab-item-active` css class is added to items that have been selected +using arrow key navigation. +* You can add the `droplab-item-ignore` css class to any item that you do not want to be selectable. For example, +an `<li class="divider"></li>` list divider element that should not be interactive. + +## Internal events + +DropLab uses some custom events to help lower the barrier to integration. + +For example, + +* The `click.dl` event is fired when an `li` list item has been clicked. It is also +fired when a list item has been selected with the keyboard. It is also fired when a +`HookButton` button is clicked (a registered `button` tag or `a` tag trigger). +* The `input.dl` event is fired when a `HookInput` (a registered `input` tag trigger) triggers an `input` event. +* The `mousedown.dl` event is fired when a `HookInput` triggers a `mousedown` event. +* The `keyup.dl` event is fired when a `HookInput` triggers a `keyup` event. +* The `keydown.dl` event is fired when a `HookInput` triggers a `keydown` event. + +These custom events add a `detail` object to the vanilla `Event` object that provides some potentially useful data. + +## Plugins + +Plugins are objects that are registered to be executed when a hook is added (when a droplab trigger and dropdown are instantiated). + +If no modules API is detected, the library will fall back as it does with `window.DropLab` and will add `window.DropLab.plugins.PluginName`. + +### Usage + +To use plugins, you can pass them in an array as the third argument of `DropLab.prototype.init` or `DropLab.prototype.addHook`. +Some plugins require configuration values, the config object can be passed as the fourth argument. + +```html +<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> +<ul id="list" data-dropdown><!-- ... --><ul> +``` +```js +const droplab = new DropLab(); + +const trigger = document.getElementById('trigger'); +const list = document.getElementById('list'); + +droplab.init(trigger, list, [droplabAjax], { + droplabAjax: { + endpoint: '/some-endpoint', + method: 'setData', + }, +}); +``` + +### Documentation + +* [Ajax plugin](plugins/ajax.md) +* [Filter plugin](plugins/filter.md) +* [InputSetter plugin](plugins/input_setter.md) + +### Development + +When plugins are initialised for a droplab trigger+dropdown, DropLab will +call the plugins `init` function, so this must be implemented in the plugin. + +```js +class MyPlugin { + static init() { + this.someProp = 'someProp'; + this.someMethod(); + } + + static someMethod() { + this.otherProp = 'otherProp'; + } +} + +export default MyPlugin; +``` diff --git a/doc/development/fe_guide/droplab/plugins/ajax.md b/doc/development/fe_guide/droplab/plugins/ajax.md new file mode 100644 index 00000000000..9c7e56fa448 --- /dev/null +++ b/doc/development/fe_guide/droplab/plugins/ajax.md @@ -0,0 +1,37 @@ +# Ajax + +`Ajax` is a droplab plugin that allows for retrieving and rendering list data from a server. + +## Usage + +Add the `Ajax` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. + +`Ajax` requires 2 config values, the `endpoint` and `method`. + +* `endpoint` should be a URL to the request endpoint. +* `method` should be `setData` or `addData`. +* `setData` completely replaces the dropdown with the response data. +* `addData` appends the response data to the current dropdown list. + +```html +<a href="#" id="trigger" data-dropdown-trigger="#list">Toggle</a> +<ul id="list" data-dropdown><!-- ... --><ul> +``` +```js + const droplab = new DropLab(); + + const trigger = document.getElementById('trigger'); + const list = document.getElementById('list'); + + droplab.addHook(trigger, list, [Ajax], { + Ajax: { + endpoint: '/some-endpoint', + method: 'setData', + }, + }); +``` + +Optionally you can set `loadingTemplate` to a HTML string. This HTML string will +replace the dropdown list whilst the request is pending. + +Additionally, you can set `onError` to a function to catch any XHR errors. diff --git a/doc/development/fe_guide/droplab/plugins/filter.md b/doc/development/fe_guide/droplab/plugins/filter.md new file mode 100644 index 00000000000..0853ea4d320 --- /dev/null +++ b/doc/development/fe_guide/droplab/plugins/filter.md @@ -0,0 +1,45 @@ +# Filter + +`Filter` is a plugin that allows for filtering data that has been added +to the dropdown using a simple fuzzy string search of an input value. + +## Usage + +Add the `Filter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. + +* `Filter` requires a config value for `template`. +* `template` should be the key of the objects within your data array that you want to compare +to the user input string, for filtering. + +```html +<input href="#" id="trigger" data-dropdown-trigger="#list"> +<ul id="list" data-dropdown data-dynamic> + <li><a href="#" data-id="{{id}}">{{text}}</a></li> +<ul> +``` +```js + const droplab = new DropLab(); + + const trigger = document.getElementById('trigger'); + const list = document.getElementById('list'); + + droplab.init(trigger, list, [Filter], { + Filter: { + template: 'text', + }, + }); + + droplab.addData('trigger', [{ + id: 0, + text: 'Jacob', + }, { + id: 1, + text: 'Jeff', + }]); +``` + +Above, the input string will be compared against the `test` key of the passed data objects. + +Optionally you can set `filterFunction` to a function. This function will be used instead +of `Filter`'s built in string search. `filterFunction` is passed 2 arguments, the first +is one of the data objects, the second is the current input value. diff --git a/doc/development/fe_guide/droplab/plugins/input_setter.md b/doc/development/fe_guide/droplab/plugins/input_setter.md new file mode 100644 index 00000000000..a549603c20d --- /dev/null +++ b/doc/development/fe_guide/droplab/plugins/input_setter.md @@ -0,0 +1,60 @@ +# InputSetter + +`InputSetter` is a plugin that allows for udating DOM out of the scope of droplab when a list item is clicked. + +## Usage + +Add the `InputSetter` object to the plugins array of a `DropLab.prototype.init` or `DropLab.prototype.addHook` call. + +* `InputSetter` requires a config value for `input` and `valueAttribute`. +* `input` should be the DOM element that you want to manipulate. +* `valueAttribute` should be a string that is the name of an attribute on your list items that is used to get the value +to update the `input` element with. + +You can also set the `InputSetter` config to an array of objects, which will allow you to update multiple elements. + + +```html +<input id="input" value=""> +<div id="div" data-selected-id=""></div> + +<input href="#" id="trigger" data-dropdown-trigger="#list"> +<ul id="list" data-dropdown data-dynamic> + <li><a href="#" data-id="{{id}}">{{text}}</a></li> +<ul> +``` +```js + const droplab = new DropLab(); + + const trigger = document.getElementById('trigger'); + const list = document.getElementById('list'); + + const input = document.getElementById('input'); + const div = document.getElementById('div'); + + droplab.init(trigger, list, [InputSetter], { + InputSetter: [{ + input: input, + valueAttribute: 'data-id', + } { + input: div, + valueAttribute: 'data-id', + inputAttribute: 'data-selected-id', + }], + }); + + droplab.addData('trigger', [{ + id: 0, + text: 'Jacob', + }, { + id: 1, + text: 'Jeff', + }]); +``` + +Above, if the second list item was clicked, it would update the `#input` element +to have a `value` of `1`, it would also update the `#div` element's `data-selected-id` to `1`. + +Optionally you can set `inputAttribute` to a string that is the name of an attribute on your `input` element that you want to update. +If you do not provide an `inputAttribute`, `InputSetter` will update the `value` of the `input` element if it is an `INPUT` element, +or the `textContent` of the `input` element if it is not an `INPUT` element. diff --git a/doc/development/fe_guide/img/boards_diagram.png b/doc/development/fe_guide/img/boards_diagram.png Binary files differnew file mode 100644 index 00000000000..7a2cf972fd0 --- /dev/null +++ b/doc/development/fe_guide/img/boards_diagram.png diff --git a/doc/development/fe_guide/img/testing_triangle.png b/doc/development/fe_guide/img/testing_triangle.png Binary files differnew file mode 100644 index 00000000000..7a9a848c2ee --- /dev/null +++ b/doc/development/fe_guide/img/testing_triangle.png diff --git a/doc/development/fe_guide/img/vue_arch.png b/doc/development/fe_guide/img/vue_arch.png Binary files differnew file mode 100644 index 00000000000..a67706c7c1e --- /dev/null +++ b/doc/development/fe_guide/img/vue_arch.png diff --git a/doc/development/fe_guide/index.md b/doc/development/fe_guide/index.md index f963bffde37..64bcb4a0257 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -27,6 +27,55 @@ For our currently-supported browsers, see our [requirements][requirements]. --- +## Development Process + +When you are assigned an issue please follow the next steps: + +### Divide a big feature into small Merge Requests +1. Big Merge Request are painful to review. In order to make this process easier we +must break a big feature into smaller ones and create a Merge Request for each step. +1. First step is to create a branch from `master`, let's call it `new-feature`. This branch +will be the recipient of all the smaller Merge Requests. Only this one will be merged to master. +1. Don't do any work on this one, let's keep it synced with master. +1. Create a new branch from `new-feature`, let's call it `new-feature-step-1`. We advise you +to clearly identify which step the branch represents. +1. Do the first part of the modifications in this branch. The target branch of this Merge Request +should be `new-feature`. +1. Once `new-feature-step-1` gets merged into `new-feature` we can continue our work. Create a new +branch from `new-feature`, let's call it `new-feature-step-2` and repeat the process done before. + +```shell +master +└─ new-feature + ├─ new-feature-step-1 + ├─ new-feature-step-2 + └─ new-feature-step-3 +``` + +**Tips** +- Make sure `new-feature` branch is always synced with `master`: merge master frequently. +- Do the same for the feature branch you have opened. This can be accomplished by merging `master` into `new-feature` and `new-feature` into `new-feature-step-*` +- Avoid rewriting history. + +### Share your work early +1. Before writing code guarantee your vision of the architecture is aligned with +GitLab's architecture. +1. Add a diagram to the issue and ask a Frontend Architecture about it. + +  + +1. Don't take more than one week between starting work on a feature and +sharing a Merge Request with a reviewer or a maintainer. + +### Vue features +1. Follow the steps in [Vue.js Best Practices](vue.md) +1. Follow the style guide. +1. Only a handful of people are allowed to merge Vue related features. +Reach out to one of Vue experts early in this process. + + +--- + ## [Architecture](architecture.md) How we go about making fundamental design decisions in GitLab's frontend team or make changes to our frontend development guidelines. @@ -90,3 +139,13 @@ Our accessibility standards and resources. [scss-lint]: https://github.com/brigade/scss-lint [install]: ../../install/installation.md#4-node [requirements]: ../../install/requirements.md#supported-web-browsers + +--- + +## [DropLab](droplab/droplab.md) +Our internal `DropLab` dropdown library. + +* [DropLab](droplab/droplab.md) +* [Ajax plugin](droplab/plugins/ajax.md) +* [Filter plugin](droplab/plugins/filter.md) +* [InputSetter plugin](droplab/plugins/input_setter.md) diff --git a/doc/development/fe_guide/performance.md b/doc/development/fe_guide/performance.md index 9437a5f7a6e..2ddcbe13afa 100644 --- a/doc/development/fe_guide/performance.md +++ b/doc/development/fe_guide/performance.md @@ -12,8 +12,8 @@ Thus, we must strike a balance between sending requests and the feeling of realt Use the following rules when creating realtime solutions. 1. The server will tell you how much to poll by sending `Poll-Interval` in the header. -Use that as your polling interval. This way it is easy for system administrators to change the -polling rate. +Use that as your polling interval. This way it is [easy for system administrators to change the +polling rate](../../administration/polling.md). A `Poll-Interval: -1` means you should disable polling, and this must be implemented. 1. A response with HTTP status `4XX` or `5XX` should disable polling as well. 1. Use a common library for polling. @@ -48,8 +48,8 @@ Steps to split page-specific JavaScript from the main `main.js`: ```haml - content_for :page_specific_javascripts do - = page_specific_javascript_bundle_tag('lib_chart') - = page_specific_javascript_bundle_tag('graphs') + = webpack_bundle_tag 'lib_chart' + = webpack_bundle_tag 'graphs' ``` The above loads `chart.js` and `graphs_bundle.js` for this page only. `chart.js` diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index abd241c0bc8..d2d89517241 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -11,401 +11,483 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. #### ESlint -- **Never** disable eslint rules unless you have a good reason. You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` at the top, but legacy files are a special case. Any time you develop a new feature or refactor an existing one, you should abide by the eslint rules. - -- **Never Ever EVER** disable eslint globally for a file +1. **Never** disable eslint rules unless you have a good reason. +You may see a lot of legacy files with `/* eslint-disable some-rule, some-other-rule */` +at the top, but legacy files are a special case. Any time you develop a new feature or +refactor an existing one, you should abide by the eslint rules. +1. **Never Ever EVER** disable eslint globally for a file ```javascript - // bad - /* eslint-disable */ + // bad + /* eslint-disable */ - // better - /* eslint-disable some-rule, some-other-rule */ + // better + /* eslint-disable some-rule, some-other-rule */ - // best - // nothing :) + // best + // nothing :) ``` -- If you do need to disable a rule for a single violation, try to do it as locally as possible - +1. If you do need to disable a rule for a single violation, try to do it as locally as possible ```javascript - // bad - /* eslint-disable no-new */ + // bad + /* eslint-disable no-new */ - import Foo from 'foo'; + import Foo from 'foo'; - new Foo(); + new Foo(); - // better - import Foo from 'foo'; + // better + import Foo from 'foo'; - // eslint-disable-next-line no-new - new Foo(); + // eslint-disable-next-line no-new + new Foo(); ``` +1. There are few rules that we need to disable due to technical debt. Which are: + 1. [no-new][eslint-new] + 1. [class-methods-use-this][eslint-this] -- When they are needed _always_ place ESlint directive comment blocks on the first line of a script, followed by any global declarations, then a blank newline prior to any imports or code. - +1. When they are needed _always_ place ESlint directive comment blocks on the first line of a script, +followed by any global declarations, then a blank newline prior to any imports or code. ```javascript - // bad - /* global Foo */ - /* eslint-disable no-new */ - import Bar from './bar'; + // bad + /* global Foo */ + /* eslint-disable no-new */ + import Bar from './bar'; - // good - /* eslint-disable no-new */ - /* global Foo */ + // good + /* eslint-disable no-new */ + /* global Foo */ - import Bar from './bar'; + import Bar from './bar'; ``` -- **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. +1. **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. + +1. When declaring multiple globals, always use one `/* global [name] */` line per variable. + ```javascript + // bad + /* globals Flash, Cookies, jQuery */ -- When declaring multiple globals, always use one `/* global [name] */` line per variable. + // good + /* global Flash */ + /* global Cookies */ + /* global jQuery */ + ``` +1. Use up to 3 parameters for a function or class. If you need more accept an Object instead. ```javascript - // bad - /* globals Flash, Cookies, jQuery */ + // bad + fn(p1, p2, p3, p4) {} - // good - /* global Flash */ - /* global Cookies */ - /* global jQuery */ + // good + fn(options) {} ``` #### Modules, Imports, and Exports -- Use ES module syntax to import modules - +1. Use ES module syntax to import modules ```javascript - // bad - require('foo'); + // bad + require('foo'); - // good - import Foo from 'foo'; + // good + import Foo from 'foo'; - // bad - module.exports = Foo; + // bad + module.exports = Foo; - // good - export default Foo; + // good + export default Foo; ``` -- Relative paths - - Unless you are writing a test, always reference other scripts using relative paths instead of `~` +1. Relative paths: Unless you are writing a test, always reference other scripts using +relative paths instead of `~` + * In **app/assets/javascripts**: - In **app/assets/javascripts**: - ```javascript - // bad - import Foo from '~/foo' - - // good - import Foo from '../foo'; - ``` + ```javascript + // bad + import Foo from '~/foo' - In **spec/javascripts**: - ```javascript - // bad - import Foo from '../../app/assets/javascripts/foo' + // good + import Foo from '../foo'; + ``` + * In **spec/javascripts**: - // good - import Foo from '~/foo'; - ``` + ```javascript + // bad + import Foo from '../../app/assets/javascripts/foo' -- Avoid using IIFE. Although we have a lot of examples of files which wrap their contents in IIFEs (immediately-invoked function expressions), this is no longer necessary after the transition from Sprockets to webpack. Do not use them anymore and feel free to remove them when refactoring legacy code. + // good + import Foo from '~/foo'; + ``` -- Avoid adding to the global namespace. +1. Avoid using IIFE. Although we have a lot of examples of files which wrap their +contents in IIFEs (immediately-invoked function expressions), +this is no longer necessary after the transition from Sprockets to webpack. +Do not use them anymore and feel free to remove them when refactoring legacy code. +1. Avoid adding to the global namespace. ```javascript - // bad - window.MyClass = class { /* ... */ }; + // bad + window.MyClass = class { /* ... */ }; - // good - export default class MyClass { /* ... */ } + // good + export default class MyClass { /* ... */ } ``` -- Side effects are forbidden in any script which contains exports - +1. Side effects are forbidden in any script which contains exports ```javascript - // bad - export default class MyClass { /* ... */ } + // bad + export default class MyClass { /* ... */ } - document.addEventListener("DOMContentLoaded", function(event) { - new MyClass(); - } + document.addEventListener("DOMContentLoaded", function(event) { + new MyClass(); + } ``` #### Data Mutation and Pure functions -- Strive to write many small pure functions, and minimize where mutations occur. - +1. Strive to write many small pure functions, and minimize where mutations occur. ```javascript - // bad - const values = {foo: 1}; + // bad + const values = {foo: 1}; - function impureFunction(items) { - const bar = 1; + function impureFunction(items) { + const bar = 1; - items.foo = items.a * bar + 2; + items.foo = items.a * bar + 2; - return items.a; - } + return items.a; + } - const c = impureFunction(values); + const c = impureFunction(values); - // good - var values = {foo: 1}; + // good + var values = {foo: 1}; - function pureFunction (foo) { - var bar = 1; + function pureFunction (foo) { + var bar = 1; - foo = foo * bar + 2; + foo = foo * bar + 2; - return foo; - } + return foo; + } - var c = pureFunction(values.foo); + var c = pureFunction(values.foo); ``` -- Avoid constructors with side-effects +1. Avoid constructors with side-effects +1. Prefer `.map`, `.reduce` or `.filter` over `.forEach` +A forEach will cause side effects, it will be mutating the array being iterated. Prefer using `.map`, +`.reduce` or `.filter` + ```javascript + const users = [ { name: 'Foo' }, { name: 'Bar' } ]; -#### Parse Strings into Numbers -- `parseInt()` is preferable over `Number()` or `+` + // bad + users.forEach((user, index) => { + user.id = index; + }); + // good + const usersWithId = users.map((user, index) => { + return Object.assign({}, user, { id: index }); + }); + ``` + +#### Parse Strings into Numbers +1. `parseInt()` is preferable over `Number()` or `+` ```javascript - // bad - +'10' // 10 + // bad + +'10' // 10 - // good - Number('10') // 10 + // good + Number('10') // 10 - // better - parseInt('10', 10); + // better + parseInt('10', 10); ``` +#### CSS classes used for JavaScript +1. If the class is being used in Javascript it needs to be prepend with `js-` + ```html + // bad + <button class="add-user"> + Add User + </button> + + // good + <button class="js-add-user"> + Add User + </button> + ``` ### Vue.js - #### Basic Rules -- Only include one Vue.js component per file. -- Export components as plain objects: - +1. The service has it's own file +1. The store has it's own file +1. Use a function in the bundle file to instantiate the Vue component: ```javascript - export default { - template: `<h1>I'm a component</h1> - } + // bad + class { + init() { + new Component({}) + } + } + + // good + document.addEventListener('DOMContentLoaded', () => new Vue({ + el: '#element', + components: { + componentName + }, + render: createElement => createElement('component-name'), + })); ``` -#### Naming -- **Extensions**: Use `.vue` extension for Vue components. -- **Reference Naming**: Use PascalCase for Vue components and camelCase for their instances: +1. Don not use a singleton for the service or the store ```javascript - // bad - import cardBoard from 'cardBoard'; + // bad + class Store { + constructor() { + if (!this.prototype.singleton) { + // do something + } + } + } - // good - import CardBoard from 'cardBoard' + // good + class Store { + constructor() { + // do something + } + } + ``` - // bad - components: { - CardBoard: CardBoard - }; +#### Naming +1. **Extensions**: Use `.vue` extension for Vue components. +1. **Reference Naming**: Use camelCase for their instances: + ```javascript + // good + import cardBoard from 'cardBoard' - // good - components: { - cardBoard: CardBoard - }; + components: { + cardBoard: + }; ``` -- **Props Naming:** -- Avoid using DOM component prop names. -- Use kebab-case instead of camelCase to provide props in templates. +1. **Props Naming:** Avoid using DOM component prop names. +1. **Props Naming:** Use kebab-case instead of camelCase to provide props in templates. ```javascript - // bad - <component class="btn"> + // bad + <component class="btn"> - // good - <component css-class="btn"> + // good + <component css-class="btn"> - // bad - <component myProp="prop" /> + // bad + <component myProp="prop" /> - // good - <component my-prop="prop" /> -``` + // good + <component my-prop="prop" /> + ``` #### Alignment -- Follow these alignment styles for the template method: - +1. Follow these alignment styles for the template method: ```javascript - // bad - <component v-if="bar" - param="baz" /> - - // good - <component - v-if="bar" - param="baz" - /> - - // if props fit in one line then keep it on the same line - <component bar="bar" /> + // bad + <component v-if="bar" + param="baz" /> + + <button class="btn">Click me</button> + + // good + <component + v-if="bar" + param="baz" + /> + + <button class="btn"> + Click me + </button> + + // if props fit in one line then keep it on the same line + <component bar="bar" /> ``` #### Quotes -- Always use double quotes `"` inside templates and single quotes `'` for all other JS. - +1. Always use double quotes `"` inside templates and single quotes `'` for all other JS. ```javascript - // bad - template: ` - <button :class='style'>Button</button> - ` - - // good - template: ` - <button :class="style">Button</button> - ` + // bad + template: ` + <button :class='style'>Button</button> + ` + + // good + template: ` + <button :class="style">Button</button> + ` ``` #### Props -- Props should be declared as an object - +1. Props should be declared as an object ```javascript - // bad - props: ['foo'] - - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + // bad + props: ['foo'] + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } } - } ``` -- Required key should always be provided when declaring a prop - +1. Required key should always be provided when declaring a prop ```javascript - // bad - props: { - foo: { - type: String, + // bad + props: { + foo: { + type: String, + } } - } - - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } } - } ``` -- Default key should always be provided if the prop is not required: - +1. Default key should always be provided if the prop is not required: ```javascript - // bad - props: { - foo: { - type: String, - required: false, + // bad + props: { + foo: { + type: String, + required: false, + } } - } - - // good - props: { - foo: { - type: String, - required: false, - default: 'bar' + + // good + props: { + foo: { + type: String, + required: false, + default: 'bar' + } } - } - // good - props: { - foo: { - type: String, - required: true + // good + props: { + foo: { + type: String, + required: true + } } - } ``` #### Data -- `data` method should always be a function +1. `data` method should always be a function ```javascript - // bad - data: { - foo: 'foo' - } - - // good - data() { - return { + // bad + data: { foo: 'foo' - }; - } + } + + // good + data() { + return { + foo: 'foo' + }; + } ``` #### Directives -- Shorthand `@` is preferable over `v-on` - +1. Shorthand `@` is preferable over `v-on` ```javascript - // bad - <component v-on:click="eventHandler"/> + // bad + <component v-on:click="eventHandler"/> - // good - <component @click="eventHandler"/> + // good + <component @click="eventHandler"/> ``` -- Shorthand `:` is preferable over `v-bind` - +1. Shorthand `:` is preferable over `v-bind` ```javascript - // bad - <component v-bind:class="btn"/> + // bad + <component v-bind:class="btn"/> - // good - <component :class="btn"/> + // good + <component :class="btn"/> ``` #### Closing tags -- Prefer self closing component tags - +1. Prefer self closing component tags ```javascript - // bad - <component></component> + // bad + <component></component> - // good - <component /> + // good + <component /> ``` #### Ordering -- Order for a Vue Component: +1. Order for a Vue Component: 1. `name` - 2. `props` - 3. `data` - 4. `components` - 5. `computedProps` - 6. `methods` - 7. lifecycle methods - 1. `beforeCreate` - 2. `created` - 3. `beforeMount` - 4. `mounted` - 5. `beforeUpdate` - 6. `updated` - 7. `activated` - 8. `deactivated` - 9. `beforeDestroy` - 10. `destroyed` - 8. `template` + 1. `props` + 1. `mixins` + 1. `data` + 1. `components` + 1. `computedProps` + 1. `methods` + 1. `beforeCreate` + 1. `created` + 1. `beforeMount` + 1. `mounted` + 1. `beforeUpdate` + 1. `updated` + 1. `activated` + 1. `deactivated` + 1. `beforeDestroy` + 1. `destroyed` + +#### Vue and Boostrap +1. Tooltips: Do not rely on `has-tooltip` class name for vue components + ``` javascript + // bad + <span class="has-tooltip"> + Text + </span> + + // good + <span data-toggle="tooltip"> + Text + </span> + ``` + +1. Tooltips: When using a tooltip, include the tooltip mixin + +1. Don't change `data-original-title`. + ```javascript + // bad + <span data-original-title="tooltip text">Foo</span> + + // good + <span title="tooltip text">Foo</span> + + $('span').tooltip('fixTitle'); + ``` ## SCSS @@ -413,3 +495,5 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. [airbnb-js-style-guide]: https://github.com/airbnb/javascript [eslintrc]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/.eslintrc +[eslint-this]: http://eslint.org/docs/rules/class-methods-use-this +[eslint-new]: http://eslint.org/docs/rules/no-new diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md index 8d3513d3566..0ef9fc61a61 100644 --- a/doc/development/fe_guide/testing.md +++ b/doc/development/fe_guide/testing.md @@ -1,11 +1,20 @@ # Frontend Testing -There are two types of tests you'll encounter while developing frontend code -at GitLab. We use Karma and Jasmine for JavaScript unit testing, and RSpec -feature tests with Capybara for integration testing. +There are two types of test suites you'll encounter while developing frontend code +at GitLab. We use Karma and Jasmine for JavaScript unit and integration testing, and RSpec +feature tests with Capybara for e2e (end-to-end) integration testing. -Feature tests need to be written for all new features. Regression tests ought -to be written for all bug fixes to prevent them from recurring in the future. +Unit and feature tests need to be written for all new features. +Most of the time, you should use rspec for your feature tests. +There are cases where the behaviour you are testing is not worth the time spent running the full application, +for example, if you are testing styling, animation or small actions that don't involve the backend, +you should write an integration test using Jasmine. + + + +_This diagram demonstrates the relative priority of each test type we use_ + +Regression tests should be written for bug fixes to prevent them from recurring in the future. See [the Testing Standards and Style Guidelines](../testing.md) for more information on general testing practices at GitLab. @@ -13,9 +22,126 @@ for more information on general testing practices at GitLab. ## Karma test suite GitLab uses the [Karma][karma] test runner with [Jasmine][jasmine] as its test -framework for our JavaScript unit tests. For tests that rely on DOM -manipulation we use fixtures which are pre-compiled from HAML source files and -served during testing by the [jasmine-jquery][jasmine-jquery] plugin. +framework for our JavaScript unit and integration tests. For integration tests, +we generate HTML files using RSpec (see `spec/javascripts/fixtures/*.rb` for examples). +Some fixtures are still HAML templates that are translated to HTML files using the same mechanism (see `static_fixtures.rb`). +Adding these static fixtures should be avoided as they are harder to keep up to date with real views. +The existing static fixtures will be migrated over time. +Please see [gitlab-org/gitlab-ce#24753](https://gitlab.com/gitlab-org/gitlab-ce/issues/24753) to track our progress. +Fixtures are served during testing by the [jasmine-jquery][jasmine-jquery] plugin. + +JavaScript tests live in `spec/javascripts/`, matching the folder structure +of `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js` +has a corresponding `spec/javascripts/behaviors/autosize_spec.js` file. + +Keep in mind that in a CI environment, these tests are run in a headless +browser and you will not have access to certain APIs, such as +[`Notification`](https://developer.mozilla.org/en-US/docs/Web/API/notification), +which will have to be stubbed. + +### Best practice + +#### Naming unit tests + +When writing describe test blocks to test specific functions/methods, +please use the method name as the describe block name. + +```javascript +// Good +describe('methodName', () => { + it('passes', () => { + expect(true).toEqual(true); + }); +}); + +// Bad +describe('#methodName', () => { + it('passes', () => { + expect(true).toEqual(true); + }); +}); + +// Bad +describe('.methodName', () => { + it('passes', () => { + expect(true).toEqual(true); + }); +}); +``` +#### Testing Promises + +When testing Promises you should always make sure that the test is asynchronous and rejections are handled. +Your Promise chain should therefore end with a call of the `done` callback and `done.fail` in case an error occurred. + +```javascript +// Good +it('tests a promise', (done) => { + promise + .then((data) => { + expect(data).toBe(asExpected); + }) + .then(done) + .catch(done.fail); +}); + +// Good +it('tests a promise rejection', (done) => { + promise + .then(done.fail) + .catch((error) => { + expect(error).toBe(expectedError); + }) + .then(done) + .catch(done.fail); +}); + +// Bad (missing done callback) +it('tests a promise', () => { + promise + .then((data) => { + expect(data).toBe(asExpected); + }) +}); + +// Bad (missing catch) +it('tests a promise', (done) => { + promise + .then((data) => { + expect(data).toBe(asExpected); + }) + .then(done) +}); + +// Bad (use done.fail in asynchronous tests) +it('tests a promise', (done) => { + promise + .then((data) => { + expect(data).toBe(asExpected); + }) + .then(done) + .catch(fail) +}); + +// Bad (missing catch) +it('tests a promise rejection', (done) => { + promise + .catch((error) => { + expect(error).toBe(expectedError); + }) + .then(done) +}); +``` + +#### Stubbing + +For unit tests, you should stub methods that are unrelated to the current unit you are testing. +If you need to use a prototype method, instantiate an instance of the class and call it there instead of mocking the instance completely. + +For integration tests, you should stub methods that will effect the stability of the test if they +execute their original behaviour. i.e. Network requests. + +### Vue.js unit tests +See this [section][vue-test]. ### Running frontend tests @@ -80,24 +206,23 @@ If an integration test depends on JavaScript to run correctly, you need to make sure the spec is configured to enable JavaScript when the tests are run. If you don't do this you'll see vague error messages from the spec runner. -To enable a JavaScript driver in an `rspec` test, add `js: true` to the +To enable a JavaScript driver in an `rspec` test, add `:js` to the individual spec or the context block containing multiple specs that need JavaScript enabled: ```ruby - # For one spec -it 'presents information about abuse report', js: true do - # assertions... +it 'presents information about abuse report', :js do + # assertions... end -describe "Admin::AbuseReports", js: true do - it 'presents information about abuse report' do - # assertions... - end - it 'shows buttons for adding to abuse report' do - # assertions... - end +describe "Admin::AbuseReports", :js do + it 'presents information about abuse report' do + # assertions... + end + it 'shows buttons for adding to abuse report' do + # assertions... + end end ``` @@ -113,13 +238,12 @@ file for the failing spec, add the `@javascript` flag above the Scenario: ``` @javascript Scenario: Developer can approve merge request - Given I am a "Shop" developer - And I visit project "Shop" merge requests page - And merge request 'Bug NS-04' must be approved - And I click link "Bug NS-04" - When I click link "Approve" - Then I should see approved merge request "Bug NS-04" - + Given I am a "Shop" developer + And I visit project "Shop" merge requests page + And merge request 'Bug NS-04' must be approved + And I click link "Bug NS-04" + When I click link "Approve" + Then I should see approved merge request "Bug NS-04" ``` [capybara]: http://teamcapybara.github.io/capybara/ @@ -127,3 +251,4 @@ Scenario: Developer can approve merge request [jasmine-focus]: https://jasmine.github.io/2.5/focused_specs.html [jasmine-jquery]: https://github.com/velesin/jasmine-jquery [karma]: http://karma-runner.github.io/ +[vue-test]:https://docs.gitlab.com/ce/development/fe_guide/vue.html#testing-vue-components diff --git a/doc/development/fe_guide/vue.md b/doc/development/fe_guide/vue.md index 3e3406e7d6a..a984bb6c94c 100644 --- a/doc/development/fe_guide/vue.md +++ b/doc/development/fe_guide/vue.md @@ -19,13 +19,31 @@ We don't want to refactor all GitLab frontend code into Vue.js, here are some gu when not to use Vue.js: - Adding or changing static information; -- Features that highly depend on jQuery will be hard to work with Vue.js +- Features that highly depend on jQuery will be hard to work with Vue.js; +- Features without reactive data; As always, the Frontend Architectural Experts are available to help with any Vue or JavaScript questions. -## How to build a new feature with Vue.js +## Vue architecture -**Components, Stores and Services** +All new features built with Vue.js must follow a [Flux architecture][flux]. +The main goal we are trying to achieve is to have only one data flow and only one data entry. +In order to achieve this goal, each Vue bundle needs a Store - where we keep all the data -, +a Service - that we use to communicate with the server - and a main Vue component. + +Think of the Main Vue Component as the entry point of your application. This is the only smart +component that should exist in each Vue feature. +This component is responsible for: +1. Calling the Service to get data from the server +1. Calling the Store to store the data received +1. Mounting all the other components + +  + +You can also read about this architecture in vue docs about [state management][state-management] +and about [one way data flow][one-way-data-flow]. + +### Components, Stores and Services In some features implemented with Vue.js, like the [issue board][issue-boards] or [environments table][environments-table] @@ -46,16 +64,17 @@ _For consistency purposes, we recommend you to follow the same structure._ Let's look into each of them: -**A `*_bundle.js` file** +### A `*_bundle.js` file This is the index file of your new feature. This is where the root Vue instance of the new feature should be. -The Store and the Service should be imported and initialized in this file and provided as a prop to the main component. +The Store and the Service should be imported and initialized in this file and +provided as a prop to the main component. Don't forget to follow [these steps.][page_specific_javascript] -**A folder for Components** +### A folder for Components This folder holds all components that are specific of this new feature. If you need to use or create a component that will probably be used somewhere @@ -70,20 +89,219 @@ in one table would not be a good use of this pattern. You can read more about components in Vue.js site, [Component System][component-system] -**A folder for the Store** +### A folder for the Store The Store is a class that allows us to manage the state in a single -source of truth. +source of truth. It is not aware of the service or the components. The concept we are trying to follow is better explained by Vue documentation itself, please read this guide: [State Management][state-management] -**A folder for the Service** +### A folder for the Service + +The Service is a class used only to communicate with the server. +It does not store or manipulate any data. It is not aware of the store or the components. +We use [vue-resource][vue-resource-repo] to communicate with the server. + +Vue Resource should only be imported in the service file. + + ```javascript + import Vue from 'vue'; + import VueResource from 'vue-resource'; + + Vue.use(VueResource); + ``` + +### CSRF token +We use a Vue Resource interceptor to manage the CSRF token. +`app/assets/javascripts/vue_shared/vue_resource_interceptor.js` holds all our common interceptors. +Note: You don't need to load `app/assets/javascripts/vue_shared/vue_resource_interceptor.js` +since it's already being loaded by `common_vue.js`. + +### End Result + +The following example shows an application: + +```javascript +// store.js +export default class Store { + + /** + * This is where we will iniatialize the state of our data. + * Usually in a small SPA you don't need any options when starting the store. In the case you do + * need guarantee it's an Object and it's documented. + * + * @param {Object} options + */ + constructor(options) { + this.options = options; + + // Create a state object to handle all our data in the same place + this.todos = []: + } + + setTodos(todos = []) { + this.todos = todos; + } + + addTodo(todo) { + this.todos.push(todo); + } + + removeTodo(todoID) { + const state = this.todos; + + const newState = state.filter((element) => {element.id !== todoID}); + + this.todos = newState; + } +} + +// service.js +import Vue from 'vue'; +import VueResource from 'vue-resource'; +import 'vue_shared/vue_resource_interceptor'; + +Vue.use(VueResource); + +export default class Service { + constructor(options) { + this.todos = Vue.resource(endpoint.todosEndpoint); + } + + getTodos() { + return this.todos.get(); + } + + addTodo(todo) { + return this.todos.put(todo); + } +} +// todo_component.vue +<script> +export default { + props: { + data: { + type: Object, + required: true, + }, + } +} +</script> +<template> + <div> + <h1> + Title: {{data.title}} + </h1> + <p> + {{data.text}} + </p> + </div> +</template> + +// todos_main_component.vue +<script> +import Store from 'store'; +import Service from 'service'; +import TodoComponent from 'todoComponent'; +export default { + /** + * Although most data belongs in the store, each component it's own state. + * We want to show a loading spinner while we are fetching the todos, this state belong + * in the component. + * + * We need to access the store methods through all methods of our component. + * We need to access the state of our store. + */ + data() { + const store = new Store(); + + return { + isLoading: false, + store: store, + todos: store.todos, + }; + }, + + components: { + todo: TodoComponent, + }, + + created() { + this.service = new Service('todos'); + + this.getTodos(); + }, + + methods: { + getTodos() { + this.isLoading = true; + + this.service.getTodos() + .then(response => response.json()) + .then((response) => { + this.store.setTodos(response); + this.isLoading = false; + }) + .catch(() => { + this.isLoading = false; + // Show an error + }); + }, + + addTodo(todo) { + this.service.addTodo(todo) + then(response => response.json()) + .then((response) => { + this.store.addTodo(response); + }) + .catch(() => { + // Show an error + }); + } + } +} +</script> +<template> + <div class="container"> + <div v-if="isLoading"> + <i + class="fa fa-spin fa-spinner" + aria-hidden="true" /> + </div> + + <div + v-if="!isLoading" + class="js-todo-list"> + <template v-for='todo in todos'> + <todo :data="todo" /> + </template> + + <button + @click="addTodo" + class="js-add-todo"> + Add Todo + </button> + </div> + <div> +</template> + +// bundle.js +import todoComponent from 'todos_main_component.vue'; + +new Vue({ + el: '.js-todo-app', + components: { + todoComponent, + }, + render: createElement => createElement('todo-component' { + props: { + someProp: [], + } + }), +}); -The Service is used only to communicate with the server. -It does not store or manipulate any data. -We use [vue-resource][vue-resource-repo] to -communicate with the server. +``` The [issue boards service][issue-boards-service] is a good example of this pattern. @@ -93,6 +311,128 @@ is a good example of this pattern. Please refer to the Vue section of our [style guide](style_guide_js.md#vuejs) for best practices while writing your Vue components and templates. +## Testing Vue Components + +Each Vue component has a unique output. This output is always present in the render function. + +Although we can test each method of a Vue component individually, our goal must be to test the output +of the render/template function, which represents the state at all times. + +Make use of Vue Resource Interceptors to mock data returned by the service. + +Here's how we would test the Todo App above: + +```javascript +import component from 'todos_main_component'; + +describe('Todos App', () => { + it('should render the loading state while the request is being made', () => { + const Component = Vue.extend(component); + + const vm = new Component().$mount(); + + expect(vm.$el.querySelector('i.fa-spin')).toBeDefined(); + }); + + describe('with data', () => { + // Mock the service to return data + const interceptor = (request, next) => { + next(request.respondWith(JSON.stringify([{ + title: 'This is a todo', + body: 'This is the text' + }]), { + status: 200, + })); + }; + + let vm; + + beforeEach(() => { + Vue.http.interceptors.push(interceptor); + + const Component = Vue.extend(component); + + vm = new Component().$mount(); + }); + + afterEach(() => { + Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor); + }); + + + it('should render todos', (done) => { + setTimeout(() => { + expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(1); + done(); + }, 0); + }); + }); + + describe('add todo', () => { + let vm; + beforeEach(() => { + const Component = Vue.extend(component); + vm = new Component().$mount(); + }); + it('should add a todos', (done) => { + setTimeout(() => { + vm.$el.querySelector('.js-add-todo').click(); + + // Add a new interceptor to mock the add Todo request + Vue.nextTick(() => { + expect(vm.$el.querySelectorAll('.js-todo-list div').length).toBe(2); + }); + }, 0); + }); + }); +}); +``` +#### Test the component's output +The main return value of a Vue component is the rendered output. In order to test the component we +need to test the rendered output. [Vue][vue-test] guide's to unit test show us exactly that: + + +### Stubbing API responses +[Vue Resource Interceptors][vue-resource-interceptor] allow us to add a interceptor with +the response we need: + +```javascript + // Mock the service to return data + const interceptor = (request, next) => { + next(request.respondWith(JSON.stringify([{ + title: 'This is a todo', + body: 'This is the text' + }]), { + status: 200, + })); + }; + + beforeEach(() => { + Vue.http.interceptors.push(interceptor); + }); + + afterEach(() => { + Vue.http.interceptors = _.without(Vue.http.interceptors, interceptor); + }); + + it('should do something', (done) => { + setTimeout(() => { + // Test received data + done(); + }, 0); + }); +``` + +1. Use `$.mount()` to mount the component +```javascript + // bad + new Component({ + el: document.createElement('div') + }); + + // good + new Component().$mount(); +``` [vue-docs]: http://vuejs.org/guide/index.html [issue-boards]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/app/assets/javascripts/boards @@ -100,5 +440,9 @@ for best practices while writing your Vue components and templates. [page_specific_javascript]: https://docs.gitlab.com/ce/development/frontend.html#page-specific-javascript [component-system]: https://vuejs.org/v2/guide/#Composing-with-Components [state-management]: https://vuejs.org/v2/guide/state-management.html#Simple-State-Management-from-Scratch +[one-way-data-flow]: https://vuejs.org/v2/guide/components.html#One-Way-Data-Flow [vue-resource-repo]: https://github.com/pagekit/vue-resource +[vue-resource-interceptor]: https://github.com/pagekit/vue-resource/blob/develop/docs/http.md#interceptors +[vue-test]: https://vuejs.org/v2/guide/unit-testing.html [issue-boards-service]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/assets/javascripts/boards/services/board_service.js.es6 +[flux]: https://facebook.github.io/flux diff --git a/doc/development/foreign_keys.md b/doc/development/foreign_keys.md new file mode 100644 index 00000000000..0ab0deb156f --- /dev/null +++ b/doc/development/foreign_keys.md @@ -0,0 +1,63 @@ +# Foreign Keys & Associations + +When adding an association to a model you must also add a foreign key. For +example, say you have the following model: + +```ruby +class User < ActiveRecord::Base + has_many :posts +end +``` + +Here you will need to add a foreign key on column `posts.user_id`. This ensures +that data consistency is enforced on database level. Foreign keys also mean that +the database can very quickly remove associated data (e.g. when removing a +user), instead of Rails having to do this. + +## Adding Foreign Keys In Migrations + +Foreign keys can be added concurrently using `add_concurrent_foreign_key` as +defined in `Gitlab::Database::MigrationHelpers`. See the [Migration Style +Guide](migration_style_guide.md) for more information. + +Keep in mind that you can only safely add foreign keys to existing tables after +you have removed any orphaned rows. The method `add_concurrent_foreign_key` +does not take care of this so you'll need to do so manually. + +## Cascading Deletes + +Every foreign key must define an `ON DELETE` clause, and in 99% of the cases +this should be set to `CASCADE`. + +## Indexes + +When adding a foreign key in PostgreSQL the column is not indexed automatically, +thus you must also add a concurrent index. Not doing so will result in cascading +deletes being very slow. + +## Dependent Removals + +Don't define options such as `dependent: :destroy` or `dependent: :delete` when +defining an association. Defining these options means Rails will handle the +removal of data, instead of letting the database handle this in the most +efficient way possible. + +In other words, this is bad and should be avoided at all costs: + +```ruby +class User < ActiveRecord::Base + has_many :posts, dependent: :destroy +end +``` + +Should you truly have a need for this it should be approved by a database +specialist first. + +You should also not define any `before_destroy` or `after_destroy` callbacks on +your models _unless_ absolutely required and only when approved by database +specialists. For example, if each row in a table has a corresponding file on a +file system it may be tempting to add a `after_destroy` hook. This however +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. diff --git a/doc/development/i18n_guide.md b/doc/development/i18n_guide.md new file mode 100644 index 00000000000..44eca68aaca --- /dev/null +++ b/doc/development/i18n_guide.md @@ -0,0 +1,239 @@ +# Internationalization for GitLab + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10669) in GitLab 9.2. + +For working with internationalization (i18n) we use +[GNU gettext](https://www.gnu.org/software/gettext/) given it's the most used +tool for this task and we have a lot of applications that will help us to work +with it. + +## Tools + +We use a couple of gems: + +1. [`gettext_i18n_rails`](https://github.com/grosser/gettext_i18n_rails): this + gem allow us to translate content from models, views and controllers. Also + it gives us access to the following raketasks: + - `rake gettext:find`: Parses almost all the files from the + Rails application looking for content that has been marked for + translation. Finally, it updates the PO files with the new content that + it has found. + - `rake gettext:pack`: Processes the PO files and generates the + MO files that are binary and are finally used by the application. + +1. [`gettext_i18n_rails_js`](https://github.com/webhippie/gettext_i18n_rails_js): + this gem is useful to make the translations available in JavaScript. It + provides the following raketask: + - `rake gettext:po_to_json`: Reads the contents from the PO files and + generates JSON files containing all the available translations. + +1. PO editor: there are multiple applications that can help us to work with PO + files, a good option is [Poedit](https://poedit.net/download) which is + available for macOS, GNU/Linux and Windows. + +## Preparing a page for translation + +We basically have 4 types of files: + +1. Ruby files: basically Models and Controllers. +1. HAML files: these are the view files. +1. ERB files: used for email templates. +1. JavaScript files: we mostly need to work with VUE JS templates. + +### Ruby files + +If there is a method or variable that works with a raw string, for instance: + +```ruby +def hello + "Hello world!" +end +``` + +Or: + +```ruby +hello = "Hello world!" +``` + +You can easily mark that content for translation with: + +```ruby +def hello + _("Hello world!") +end +``` + +Or: + +```ruby +hello = _("Hello world!") +``` + +### HAML files + +Given the following content in HAML: + +```haml +%h1 Hello world! +``` + +You can mark that content for translation with: + +```haml +%h1= _("Hello world!") +``` + +### ERB files + +Given the following content in ERB: + +```erb +<h1>Hello world!</h1> +``` + +You can mark that content for translation with: + +```erb +<h1><%= _("Hello world!") %></h1> +``` + +### JavaScript files + +In JavaScript we added the `__()` (double underscore parenthesis) function +for translations. + +### Updating the PO files with the new content + +Now that the new content is marked for translation, we need to update the PO +files with the following command: + +```sh +bundle exec rake gettext:find +``` + +This command will update the `locale/**/gitlab.edit.po` file with the +new content that the parser has found. + +New translations will be added with their default content and will be marked +fuzzy. To use the translation, look for the `#, fuzzy` mention in `gitlab.edit.po` +and remove it. + +Translations that aren't used in the source code anymore will be marked with +`~#`; these can be removed to keep our translation files clutter-free. + +## Working with special content + +### Interpolation + +- In Ruby/HAML: + + ```ruby + _("Hello %{name}") % { name: 'Joe' } + ``` + +- In JavaScript: Not supported at this moment. + +### Plurals + +- In Ruby/HAML: + + ```ruby + n_('Apple', 'Apples', 3) => 'Apples' + ``` + + Using interpolation: + ```ruby + n_("There is a mouse.", "There are %d mice.", size) % size + ``` + +- In JavaScript: + + ```js + n__('Apple', 'Apples', 3) => 'Apples' + ``` + + Using interpolation: + + ```js + n__('Last day', 'Last %d days', 30) => 'Last 30 days' + ``` + +### Namespaces + +Sometimes you need to add some context to the text that you want to translate +(if the word occurs in a sentence and/or the word is ambiguous). + +- In Ruby/HAML: + + ```ruby + s_('OpenedNDaysAgo|Opened') + ``` + + In case the translation is not found it will return `Opened`. + +- In JavaScript: + + ```js + s__('OpenedNDaysAgo|Opened') + ``` + +### Just marking content for parsing + +Sometimes there are some dynamic translations that can't be found by the +parser when running `bundle exec rake gettext:find`. For these scenarios you can +use the [`_N` method](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#unfound-translations-with-rake-gettextfind). + +There is also and alternative method to [translate messages from validation errors](https://github.com/grosser/gettext_i18n_rails/blob/c09e38d481e0899ca7d3fc01786834fa8e7aab97/Readme.md#option-a). + +## Adding a new language + +Let's suppose you want to add translations for a new language, let's say French. + +1. The first step is to register the new language in `lib/gitlab/i18n.rb`: + + ```ruby + ... + AVAILABLE_LANGUAGES = { + ..., + 'fr' => 'Français' + }.freeze + ... + ``` + +1. Next, you need to add the language: + + ```sh + bundle exec rake gettext:add_language[fr] + ``` + + If you want to add a new language for a specific region, the command is similar, + you just need to separate the region with an underscore (`_`). For example: + + ```sh + bundle exec rake gettext:add_language[en_gb] + ``` + +1. Now that the language is added, a new directory has been created under the + path: `locale/fr/`. You can now start using your PO editor to edit the PO file + located in: `locale/fr/gitlab.edit.po`. + +1. After you're done updating the translations, you need to process the PO files + in order to generate the binary MO files and finally update the JSON files + containing the translations: + + ```sh + bundle exec rake gettext:pack + bundle exec rake gettext:po_to_json + ``` + +1. In order to see the translated content we need to change our preferred language + which can be found under the user's **Settings** (`/profile`). + +1. After checking that the changes are ok, you can proceed to commit the new files. + For example: + + ```sh + git add locale/fr/ app/assets/javascripts/locale/fr/ + git commit -m "Add French translations for Cycle Analytics page" + ``` diff --git a/doc/development/img/cache-hit.svg b/doc/development/img/cache-hit.svg new file mode 100644 index 00000000000..1c37693df2d --- /dev/null +++ b/doc/development/img/cache-hit.svg @@ -0,0 +1,21 @@ +<svg version="1.1" id="mscgen_js-svg-__svg" class="mscgen_js-svg-__svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="976" height="310" viewBox="0 0 976 310"><desc> + +# Generated by mscgen_js - https://sverweij.github.io/mscgen_js +msc { + # options + hscale="1.5"; + + # entities + c [label="Client", textbgcolor="lime"], + rails [label="Rails", textbgcolor="cyan"], + etag [label="EtagCaching", textbgcolor="orange"], + redis [label="Redis", textbgcolor="white"]; + + # arcs + c => rails [label="GET /projects/5/pipelines"]; + rails => etag [label="GET /projects/5/pipelines"]; + etag => redis [label="read(key = 'GET <Etag>')"]; + redis => etag [label="cache hit", linecolor="green", textcolor="green"]; + |||; + etag => c [label="304 Not Modified", linecolor="blue", textcolor="blue"]; +}</desc><defs><style type="text/css">svg.mscgen_js-svg-__svg{font-family:Helvetica,sans-serif;font-size:12px;font-weight:normal;font-style:normal;text-decoration:none;background-color:white;stroke:black;stroke-width:2;color:black}.mscgen_js-svg-__svg path, .mscgen_js-svg-__svg rect{fill:none;color:black;stroke:black}.mscgen_js-svg-__svg .label-text-background{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg .bglayer{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg line{stroke:black}.mscgen_js-svg-__svg .return, .mscgen_js-svg-__svg .comment{stroke-dasharray:5,3}.mscgen_js-svg-__svg .inline_expression_divider{stroke-dasharray:10,5}.mscgen_js-svg-__svg text{color:inherit;stroke:none;text-anchor:middle}.mscgen_js-svg-__svg text.entity-text{text-decoration:underline}.mscgen_js-svg-__svg text.anchor-start{text-anchor:start}.mscgen_js-svg-__svg .arrow-marker{overflow:visible}.mscgen_js-svg-__svg .arrow-style{stroke-width:1}.mscgen_js-svg-__svg .arcrow, .mscgen_js-svg-__svg .arcrowomit, .mscgen_js-svg-__svg .emphasised{stroke-linecap:butt}.mscgen_js-svg-__svg .arcrowomit{stroke-dasharray:2,2;}.mscgen_js-svg-__svg .box, .mscgen_js-svg-__svg .entity{fill:white;stroke-linejoin:round}.mscgen_js-svg-__svg .inherit{stroke:inherit;color:inherit}.mscgen_js-svg-__svg .inherit-fill{fill:inherit}.mscgen_js-svg-__svg .watermark{stroke:black;color:black;fill:black;font-size:48pt;font-weight:bold;opacity:0.14}</style><marker orient="auto" id="mscgen_js-svg-__svgmethod-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-green" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="green" fill="green"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-green" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="green" fill="green"></polygon></marker></defs><g id="mscgen_js-svg-__svg__body" transform="translate(53,3) scale(1,1)"><g id="mscgen_js-svg-__svg__background"><rect width="976" height="310" x="-53" y="-3" class="bglayer"></rect></g><g id="mscgen_js-svg-__svg__arcspanlayer"></g><g id="mscgen_js-svg-__svg__lifelinelayer"><line x1="75" y1="38" x2="75" y2="76" class="arcrow"></line><line x1="315" y1="38" x2="315" y2="76" class="arcrow"></line><line x1="555" y1="38" x2="555" y2="76" class="arcrow"></line><line x1="795" y1="38" x2="795" y2="76" class="arcrow"></line><line x1="75" y1="76" x2="75" y2="114" class="arcrow"></line><line x1="315" y1="76" x2="315" y2="114" class="arcrow"></line><line x1="555" y1="76" x2="555" y2="114" class="arcrow"></line><line x1="795" y1="76" x2="795" y2="114" class="arcrow"></line><line x1="75" y1="114" x2="75" y2="152" class="arcrow"></line><line x1="315" y1="114" x2="315" y2="152" class="arcrow"></line><line x1="555" y1="114" x2="555" y2="152" class="arcrow"></line><line x1="795" y1="114" x2="795" y2="152" class="arcrow"></line><line x1="75" y1="152" x2="75" y2="190" class="arcrow"></line><line x1="315" y1="152" x2="315" y2="190" class="arcrow"></line><line x1="555" y1="152" x2="555" y2="190" class="arcrow"></line><line x1="795" y1="152" x2="795" y2="190" class="arcrow"></line><line x1="75" y1="190" x2="75" y2="228" class="arcrow"></line><line x1="315" y1="190" x2="315" y2="228" class="arcrow"></line><line x1="555" y1="190" x2="555" y2="228" class="arcrow"></line><line x1="795" y1="190" x2="795" y2="228" class="arcrow"></line><line x1="75" y1="228" x2="75" y2="266" class="arcrow"></line><line x1="315" y1="228" x2="315" y2="266" class="arcrow"></line><line x1="555" y1="228" x2="555" y2="266" class="arcrow"></line><line x1="795" y1="228" x2="795" y2="266" class="arcrow"></line><line x1="75" y1="266" x2="75" y2="304" class="arcrow"></line><line x1="315" y1="266" x2="315" y2="304" class="arcrow"></line><line x1="555" y1="266" x2="555" y2="304" class="arcrow"></line><line x1="795" y1="266" x2="795" y2="304" class="arcrow"></line></g><g id="mscgen_js-svg-__svg__sequencelayer"><g id="mscgen_js-svg-__svgentities"><g><rect width="150" height="38" class="entity" style="fill:lime;"></rect><g><text x="75" y="22.5" class="entity-text "><tspan>Client</tspan></text></g></g><g><rect width="150" height="38" x="240" class="entity" style="fill:cyan;"></rect><g><text x="315" y="22.5" class="entity-text "><tspan>Rails</tspan></text></g></g><g><rect width="150" height="38" x="480" class="entity" style="fill:orange;"></rect><g><text x="555" y="22.5" class="entity-text "><tspan>EtagCaching</tspan></text></g></g><g><rect width="150" height="38" x="720" class="entity" style="fill:white;"></rect><g><text x="795" y="22.5" class="entity-text "><tspan>Redis</tspan></text></g></g></g><g><line x1="75" y1="95" x2="315" y2="95" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="127.97" y="79.5" class="label-text-background"></rect><text x="195" y="90.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="133" x2="555" y2="133" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="117.5" class="label-text-background"></rect><text x="435" y="128.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="555" y1="171" x2="795" y2="171" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="135.64" height="14" x="607.17" y="155.5" class="label-text-background"></rect><text x="675" y="166.5" class="directional-text method-text "><tspan>read(key = 'GET <Etag>')</tspan></text></g></g><g><line x1="795" y1="209" x2="555" y2="209" class="arc directional method" style="stroke:green" marker-end="url(#mscgen_js-svg-__svgmethod-green)"></line><g><rect width="48.02" height="14" x="650.98" y="193.5" class="label-text-background"></rect><text x="675" y="204.5" class="directional-text method-text " style="fill:green;"><tspan>cache hit</tspan></text></g></g><g></g><g><line x1="555" y1="285" x2="75" y2="285" class="arc directional method" style="stroke:blue" marker-end="url(#mscgen_js-svg-__svgmethod-blue)"></line><g><rect width="90.72" height="14" x="269.63" y="269.5" class="label-text-background"></rect><text x="315" y="280.5" class="directional-text method-text " style="fill:blue;"><tspan>304 Not Modified</tspan></text></g></g></g><g id="mscgen_js-svg-__svg__notelayer"></g><g id="mscgen_js-svg-__svg__watermark"></g></g></svg>
\ No newline at end of file diff --git a/doc/development/img/cache-miss.svg b/doc/development/img/cache-miss.svg new file mode 100644 index 00000000000..8429e6a1918 --- /dev/null +++ b/doc/development/img/cache-miss.svg @@ -0,0 +1,24 @@ +<svg version="1.1" id="mscgen_js-svg-__svg" class="mscgen_js-svg-__svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="976" height="386" viewBox="0 0 976 386"><desc> + +# Generated by mscgen_js - https://sverweij.github.io/mscgen_js +msc { + # options + hscale="1.5"; + + # entities + c [label="Client", textbgcolor="lime"], + rails [label="Rails", textbgcolor="cyan"], + etag [label="EtagCaching", textbgcolor="orange"], + redis [label="Redis", textbgcolor="white"]; + + # arcs + c => rails [label="GET /projects/5/pipelines"]; + rails => etag [label="GET /projects/5/pipelines"]; + etag => redis [label="read(key = 'GET <Etag>')"]; + redis => etag [label="cache miss", linecolor="red", textcolor="red"]; + |||; + etag => redis [label="write('<New Etag>')"]; + etag => rails [label="GET /projects/5/pipelines"]; + rails => c [label="JSON response w/ ETag", linecolor="blue", textcolor="blue"]; +} +</desc><defs><style type="text/css">svg.mscgen_js-svg-__svg{font-family:Helvetica,sans-serif;font-size:12px;font-weight:normal;font-style:normal;text-decoration:none;background-color:white;stroke:black;stroke-width:2}.mscgen_js-svg-__svg path, .mscgen_js-svg-__svg rect{fill:none}.mscgen_js-svg-__svg .label-text-background{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg .bglayer{fill:white;stroke:white;stroke-width:0}.mscgen_js-svg-__svg line{}.mscgen_js-svg-__svg .return, .mscgen_js-svg-__svg .comment{stroke-dasharray:5,3}.mscgen_js-svg-__svg .inline_expression_divider{stroke-dasharray:10,5}.mscgen_js-svg-__svg text{color:inherit;stroke:none;text-anchor:middle}.mscgen_js-svg-__svg text.entity-text{text-decoration:underline}.mscgen_js-svg-__svg text.anchor-start{text-anchor:start}.mscgen_js-svg-__svg .arrow-marker{overflow:visible}.mscgen_js-svg-__svg .arrow-style{stroke-width:1}.mscgen_js-svg-__svg .arcrow, .mscgen_js-svg-__svg .arcrowomit, .mscgen_js-svg-__svg .emphasised{stroke-linecap:butt}.mscgen_js-svg-__svg .arcrowomit{stroke-dasharray:2,2}.mscgen_js-svg-__svg .box, .mscgen_js-svg-__svg .entity{fill:white;stroke-linejoin:round}.mscgen_js-svg-__svg .inherit{stroke:inherit;color:inherit}.mscgen_js-svg-__svg .inherit-fill{fill:inherit}.mscgen_js-svg-__svg .watermark{font-size:48pt;font-weight:bold;opacity:0.14}</style><marker orient="auto" id="mscgen_js-svg-__svgmethod-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-black" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="black" fill="black"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-blue" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="blue" fill="blue"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-red" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="1,1 9,3 1,5" class="arrow-style" stroke="red" fill="red"></polygon></marker><marker orient="auto" id="mscgen_js-svg-__svgmethod-l-red" class="arrow-marker" viewBox="0 0 10 10" refX="9" refY="3" markerUnits="strokeWidth" markerWidth="10" markerHeight="10"><polygon points="17,1 9,3 17,5" class="arrow-style" stroke="red" fill="red"></polygon></marker></defs><g id="mscgen_js-svg-__svg__body" transform="translate(53,3) scale(1,1)"><g id="mscgen_js-svg-__svg__background"><rect width="976" height="386" x="-53" y="-3" class="bglayer"></rect></g><g id="mscgen_js-svg-__svg__arcspanlayer"></g><g id="mscgen_js-svg-__svg__lifelinelayer"><line x1="75" y1="38" x2="75" y2="76" class="arcrow"></line><line x1="315" y1="38" x2="315" y2="76" class="arcrow"></line><line x1="555" y1="38" x2="555" y2="76" class="arcrow"></line><line x1="795" y1="38" x2="795" y2="76" class="arcrow"></line><line x1="75" y1="76" x2="75" y2="114" class="arcrow"></line><line x1="315" y1="76" x2="315" y2="114" class="arcrow"></line><line x1="555" y1="76" x2="555" y2="114" class="arcrow"></line><line x1="795" y1="76" x2="795" y2="114" class="arcrow"></line><line x1="75" y1="114" x2="75" y2="152" class="arcrow"></line><line x1="315" y1="114" x2="315" y2="152" class="arcrow"></line><line x1="555" y1="114" x2="555" y2="152" class="arcrow"></line><line x1="795" y1="114" x2="795" y2="152" class="arcrow"></line><line x1="75" y1="152" x2="75" y2="190" class="arcrow"></line><line x1="315" y1="152" x2="315" y2="190" class="arcrow"></line><line x1="555" y1="152" x2="555" y2="190" class="arcrow"></line><line x1="795" y1="152" x2="795" y2="190" class="arcrow"></line><line x1="75" y1="190" x2="75" y2="228" class="arcrow"></line><line x1="315" y1="190" x2="315" y2="228" class="arcrow"></line><line x1="555" y1="190" x2="555" y2="228" class="arcrow"></line><line x1="795" y1="190" x2="795" y2="228" class="arcrow"></line><line x1="75" y1="228" x2="75" y2="266" class="arcrow"></line><line x1="315" y1="228" x2="315" y2="266" class="arcrow"></line><line x1="555" y1="228" x2="555" y2="266" class="arcrow"></line><line x1="795" y1="228" x2="795" y2="266" class="arcrow"></line><line x1="75" y1="266" x2="75" y2="304" class="arcrow"></line><line x1="315" y1="266" x2="315" y2="304" class="arcrow"></line><line x1="555" y1="266" x2="555" y2="304" class="arcrow"></line><line x1="795" y1="266" x2="795" y2="304" class="arcrow"></line><line x1="75" y1="304" x2="75" y2="342" class="arcrow"></line><line x1="315" y1="304" x2="315" y2="342" class="arcrow"></line><line x1="555" y1="304" x2="555" y2="342" class="arcrow"></line><line x1="795" y1="304" x2="795" y2="342" class="arcrow"></line><line x1="75" y1="342" x2="75" y2="380" class="arcrow"></line><line x1="315" y1="342" x2="315" y2="380" class="arcrow"></line><line x1="555" y1="342" x2="555" y2="380" class="arcrow"></line><line x1="795" y1="342" x2="795" y2="380" class="arcrow"></line></g><g id="mscgen_js-svg-__svg__sequencelayer"><g id="mscgen_js-svg-__svgentities"><g><rect width="150" height="38" class="entity" style="fill:lime;"></rect><g><text x="75" y="22.5" class="entity-text "><tspan>Client</tspan></text></g></g><g><rect width="150" height="38" x="240" class="entity" style="fill:cyan;"></rect><g><text x="315" y="22.5" class="entity-text "><tspan>Rails</tspan></text></g></g><g><rect width="150" height="38" x="480" class="entity" style="fill:orange;"></rect><g><text x="555" y="22.5" class="entity-text "><tspan>EtagCaching</tspan></text></g></g><g><rect width="150" height="38" x="720" class="entity" style="fill:white;"></rect><g><text x="795" y="22.5" class="entity-text "><tspan>Redis</tspan></text></g></g></g><g><line x1="75" y1="95" x2="315" y2="95" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="127.97" y="79.5" class="label-text-background"></rect><text x="195" y="90.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="133" x2="555" y2="133" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="117.5" class="label-text-background"></rect><text x="435" y="128.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="555" y1="171" x2="795" y2="171" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="135.64" height="14" x="607.17" y="155.5" class="label-text-background"></rect><text x="675" y="166.5" class="directional-text method-text "><tspan>read(key = 'GET <Etag>')</tspan></text></g></g><g><line x1="795" y1="209" x2="555" y2="209" class="arc directional method" style="stroke:red" marker-end="url(#mscgen_js-svg-__svgmethod-red)"></line><g><rect width="60.02" height="14" x="644.98" y="193.5" class="label-text-background"></rect><text x="675" y="204.5" class="directional-text method-text " style="fill:red;"><tspan>cache miss</tspan></text></g></g><g></g><g><line x1="555" y1="285" x2="795" y2="285" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="103.94" height="14" x="623.02" y="269.5" class="label-text-background"></rect><text x="675" y="280.5" class="directional-text method-text "><tspan>write('<New Etag>')</tspan></text></g></g><g><line x1="555" y1="323" x2="315" y2="323" class="arc directional method" style="stroke:black" marker-end="url(#mscgen_js-svg-__svgmethod-black)"></line><g><rect width="134.06" height="14" x="367.97" y="307.5" class="label-text-background"></rect><text x="435" y="318.5" class="directional-text method-text "><tspan>GET /projects/5/pipelines</tspan></text></g></g><g><line x1="315" y1="361" x2="75" y2="361" class="arc directional method" style="stroke:blue" marker-end="url(#mscgen_js-svg-__svgmethod-blue)"></line><g><rect width="130.72" height="14" x="129.63" y="345.5" class="label-text-background"></rect><text x="195" y="356.5" class="directional-text method-text " style="fill:blue;"><tspan>JSON response w/ ETag</tspan></text></g></g></g><g id="mscgen_js-svg-__svg__notelayer"></g><g id="mscgen_js-svg-__svg__watermark"></g></g></svg>
\ No newline at end of file diff --git a/doc/development/img/trigger_ss1.png b/doc/development/img/trigger_ss1.png Binary files differnew file mode 100644 index 00000000000..ccff1009a25 --- /dev/null +++ b/doc/development/img/trigger_ss1.png diff --git a/doc/development/img/trigger_ss2.png b/doc/development/img/trigger_ss2.png Binary files differnew file mode 100644 index 00000000000..94dfd048793 --- /dev/null +++ b/doc/development/img/trigger_ss2.png diff --git a/doc/development/migration_style_guide.md b/doc/development/migration_style_guide.md index fd8335d251e..77ba2a5fd87 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -4,28 +4,53 @@ When writing migrations for GitLab, you have to take into account that these will be ran by hundreds of thousands of organizations of all sizes, some with many years of data in their database. -In addition, having to take a server offline for a an upgrade small or big is -a big burden for most organizations. For this reason it is important that your -migrations are written carefully, can be applied online and adhere to the style guide below. +In addition, having to take a server offline for a a upgrade small or big is a +big burden for most organizations. For this reason it is important that your +migrations are written carefully, can be applied online and adhere to the style +guide below. -Migrations should not require GitLab installations to be taken offline unless -_absolutely_ necessary - see the ["What Requires Downtime?"](what_requires_downtime.md) -page. If a migration requires downtime, this should be clearly mentioned during -the review process, as well as being documented in the monthly release post. For -more information, see the "Downtime Tagging" section below. +Migrations are **not** allowed to require GitLab installations to be taken +offline unless _absolutely necessary_. Downtime assumptions should be based on +the behaviour of a migration when performed using PostgreSQL, as various +operations in MySQL may require downtime without there being alternatives. + +When downtime is necessary the migration has to be approved by: + +1. The VP of Engineering +1. A Backend Lead +1. A Database Specialist + +An up-to-date list of people holding these titles can be found at +<https://about.gitlab.com/team/>. + +The document ["What Requires Downtime?"](what_requires_downtime.md) specifies +various database operations, whether they require downtime and how to +work around that whenever possible. When writing your migrations, also consider that databases might have stale data -or inconsistencies and guard for that. Try to make as little assumptions as possible -about the state of the database. +or inconsistencies and guard for that. Try to make as few assumptions as +possible about the state of the database. -Please don't depend on GitLab specific code since it can change in future versions. -If needed copy-paste GitLab code into the migration to make it forward compatible. +Please don't depend on GitLab-specific code since it can change in future +versions. If needed copy-paste GitLab code into the migration to make it forward +compatible. + +## Commit Guidelines + +Each migration **must** be added in its own commit with a descriptive commit +message. If a commit adds a migration it _should only_ include the migration and +any corresponding changes to `db/schema.rb`. This makes it easy to revert a +database migration without accidentally reverting other changes. ## Downtime Tagging Every migration must specify if it requires downtime or not, and if it should -require downtime it must also specify a reason for this. To do so, add the -following two constants to the migration class' body: +require downtime it must also specify a reason for this. This is required even +if 99% of the migrations won't require downtime as this makes it easier to find +the migrations that _do_ require downtime. + +To tag a migration, add the following two constants to the migration class' +body: * `DOWNTIME`: a boolean that when set to `true` indicates the migration requires downtime. @@ -50,23 +75,79 @@ from a migration class. ## Reversibility -Your migration should be reversible. This is very important, as it should +Your migration **must be** reversible. This is very important, as it should be possible to downgrade in case of a vulnerability or bugs. In your migration, add a comment describing how the reversibility of the migration was tested. +## Multi Threading + +Sometimes a migration might need to use multiple Ruby threads to speed up a +migration. For this to work your migration needs to include the module +`Gitlab::Database::MultiThreadedMigration`: + +```ruby +class MyMigration < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + include Gitlab::Database::MultiThreadedMigration +end +``` + +You can then use the method `with_multiple_threads` to perform work in separate +threads. For example: + +```ruby +class MyMigration < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + include Gitlab::Database::MultiThreadedMigration + + def up + with_multiple_threads(4) do + disable_statement_timeout + + # ... + end + end +end +``` + +Here the call to `disable_statement_timeout` will use the connection local to +the `with_multiple_threads` block, instead of re-using the global connection +pool. This ensures each thread has its own connection object, and won't time +out when trying to obtain one. + +**NOTE:** PostgreSQL has a maximum amount of connections that it allows. This +limit can vary from installation to installation. As a result it's recommended +you do not use more than 32 threads in a single migration. Usually 4-8 threads +should be more than enough. + ## Removing indices -If you need to remove index, please add a condition like in following example: +When removing an index make sure to use the method `remove_concurrent_index` instead +of the regular `remove_index` method. The `remove_concurrent_index` method +automatically drops concurrent indexes when using PostgreSQL, removing the +need for downtime. To use this method you must disable transactions by calling +the method `disable_ddl_transaction!` in the body of your migration class like +so: ```ruby -remove_index :namespaces, column: :name if index_exists?(:namespaces, :name) +class MyMigration < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + disable_ddl_transaction! + + def up + remove_concurrent_index :table_name, :column_name if index_exists?(:table_name, :column_name) + end +end ``` ## Adding indices -If you need to add an unique index please keep in mind there is possibility of existing duplicates. If it is possible write a separate migration for handling this situation. It can be just removing or removing with overwriting all references to these duplicates depend on situation. +If you need to add a unique index please keep in mind there is the possibility +of existing duplicates being present in the database. This means that should +always _first_ add a migration that removes any duplicates, before adding the +unique index. When adding an index make sure to use the method `add_concurrent_index` instead of the regular `add_index` method. The `add_concurrent_index` method @@ -78,17 +159,22 @@ so: ```ruby class MyMigration < ActiveRecord::Migration include Gitlab::Database::MigrationHelpers + disable_ddl_transaction! - def change + def up + add_concurrent_index :table, :column + end + def down + remove_index :table, :column if index_exists?(:table, :column) end end ``` ## Adding Columns With Default Values -When adding columns with default values you should use the method +When adding columns with default values you must use the method `add_column_with_default`. This method ensures the table is updated without requiring downtime. This method is not reversible so you must manually define the `up` and `down` methods in your migration class. @@ -111,6 +197,9 @@ class MyMigration < ActiveRecord::Migration end ``` +Keep in mind that this operation can easily take 10-15 minutes to complete on +larger installations (e.g. GitLab.com). As a result you should only add default +values if absolutely necessary. ## Integer column type @@ -135,13 +224,15 @@ add_column(:projects, :foo, :integer, default: 10, limit: 8) ## Testing -Make sure that your migration works with MySQL and PostgreSQL with data. An empty database does not guarantee that your migration is correct. +Make sure that your migration works with MySQL and PostgreSQL with data. An +empty database does not guarantee that your migration is correct. Make sure your migration can be reversed. ## Data migration -Please prefer Arel and plain SQL over usual ActiveRecord syntax. In case of using plain SQL you need to quote all input manually with `quote_string` helper. +Please prefer Arel and plain SQL over usual ActiveRecord syntax. In case of +using plain SQL you need to quote all input manually with `quote_string` helper. Example with Arel: @@ -165,3 +256,42 @@ select_all("SELECT name, COUNT(id) as cnt FROM tags GROUP BY name HAVING COUNT(i execute("DELETE FROM tags WHERE id IN(#{duplicate_ids.join(",")})") end ``` + +If you need more complex logic you can define and use models local to a +migration. For example: + +```ruby +class MyMigration < ActiveRecord::Migration + class Project < ActiveRecord::Base + self.table_name = 'projects' + end +end +``` + +When doing so be sure to explicitly set the model's table name so it's not +derived from the class name or namespace. + +### Renaming reserved paths + +When a new route for projects is introduced that could conflict with any +existing records. The path for this records should be renamed, and the +related data should be moved on disk. + +Since we had to do this a few times already, there are now some helpers to help +with this. + +To use this you can include `Gitlab::Database::RenameReservedPathsMigration::V1` +in your migration. This will provide 3 methods which you can pass one or more +paths that need to be rejected. + +**`rename_root_paths`**: This will rename the path of all _namespaces_ with the +given name that don't have a `parent_id`. + +**`rename_child_paths`**: This will rename the path of all _namespaces_ with the +given name that have a `parent_id`. + +**`rename_wildcard_paths`**: This will rename the path of all _projects_, and all +_namespaces_ that have a `project_id`. + +The `path` column for these rows will be renamed to their previous value followed +by an integer. For example: `users` would turn into `users0` diff --git a/doc/development/polling.md b/doc/development/polling.md index a7f2962acf0..3b34f985cd4 100644 --- a/doc/development/polling.md +++ b/doc/development/polling.md @@ -22,6 +22,14 @@ Instead you should use polling mechanism with ETag caching in Redis. ## How it works +Cache Miss: + + + +Cache Hit: + + + 1. Whenever a resource changes we generate a random value and store it in Redis. 1. When a client makes a request we set the `ETag` response header to the value @@ -36,6 +44,13 @@ Instead you should use polling mechanism with ETag caching in Redis. 1. If the `If-None-Match` header does not match the current value in Redis we have to generate a new response, because the resource changed. +Do not use query parameters (for example `?scope=all`) for endpoints where you +want to enable ETag caching. The middleware takes into account only the request +path and ignores query parameters. All parameters should be included in the +request path. By doing this we avoid query parameter ordering problems and make +route matching easier. + For more information see: +- [`Poll-Interval` header](fe_guide/performance.md#realtime-components) - [RFC 7232](https://tools.ietf.org/html/rfc7232) - [ETag proposal](https://gitlab.com/gitlab-org/gitlab-ce/issues/26926) diff --git a/doc/development/rake_tasks.md b/doc/development/rake_tasks.md index ec9e4dcc59d..fdaaa65fa28 100644 --- a/doc/development/rake_tasks.md +++ b/doc/development/rake_tasks.md @@ -31,16 +31,26 @@ files it can find, also the ones in `/tmp` To run a single test file you can use: -- `bundle exec rspec spec/controllers/commit_controller_spec.rb` for a rspec test -- `bundle exec spinach features/project/issues/milestones.feature` for a spinach test +- `bin/rspec spec/controllers/commit_controller_spec.rb` for a rspec test +- `bin/spinach features/project/issues/milestones.feature` for a spinach test To run several tests inside one directory: -- `bundle exec rspec spec/requests/api/` for the rspec tests if you want to test API only -- `bundle exec spinach features/profile/` for the spinach tests if you want to test only profile pages +- `bin/rspec spec/requests/api/` for the rspec tests if you want to test API only +- `bin/spinach features/profile/` for the spinach tests if you want to test only profile pages -If you want to use [Spring](https://github.com/rails/spring) set -`ENABLE_SPRING=1` in your environment. +### Speed-up tests, rake tasks, and migrations + +[Spring](https://github.com/rails/spring) is a Rails application preloader. It +speeds up development by keeping your application running in the background so +you don't need to boot it every time you run a test, rake task or migration. + +If you want to use it, you'll need to export the `ENABLE_SPRING` environment +variable to `1`: + +``` +export ENABLE_SPRING=1 +``` ## Compile Frontend Assets diff --git a/doc/development/testing.md b/doc/development/testing.md index 5bc958f5a96..6d8b846d27f 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -9,59 +9,187 @@ this guide defines a rule that contradicts the thoughtbot guide, this guide takes precedence. Some guidelines may be repeated verbatim to stress their importance. -## Factories +## Definitions + +### Unit tests + +Formal definition: https://en.wikipedia.org/wiki/Unit_testing + +These kind of tests ensure that a single unit of code (a method) works as +expected (given an input, it has a predictable output). These tests should be +isolated as much as possible. For example, model methods that don't do anything +with the database shouldn't need a DB record. Classes that don't need database +records should use stubs/doubles as much as possible. + +| Code path | Tests path | Testing engine | Notes | +| --------- | ---------- | -------------- | ----- | +| `app/finders/` | `spec/finders/` | RSpec | | +| `app/helpers/` | `spec/helpers/` | RSpec | | +| `app/db/{post_,}migrate/` | `spec/migrations/` | RSpec | | +| `app/policies/` | `spec/policies/` | RSpec | | +| `app/presenters/` | `spec/presenters/` | RSpec | | +| `app/routing/` | `spec/routing/` | RSpec | | +| `app/serializers/` | `spec/serializers/` | RSpec | | +| `app/services/` | `spec/services/` | RSpec | | +| `app/tasks/` | `spec/tasks/` | RSpec | | +| `app/uploaders/` | `spec/uploaders/` | RSpec | | +| `app/views/` | `spec/views/` | RSpec | | +| `app/workers/` | `spec/workers/` | RSpec | | +| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [JavaScript](#javascript) section. | + +### Integration tests + +Formal definition: https://en.wikipedia.org/wiki/Integration_testing + +These kind of tests ensure that individual parts of the application work well together, without the overhead of the actual app environment (i.e. the browser). These tests should assert at the request/response level: status code, headers, body. They're useful to test permissions, redirections, what view is rendered etc. + +| Code path | Tests path | Testing engine | Notes | +| --------- | ---------- | -------------- | ----- | +| `app/controllers/` | `spec/controllers/` | RSpec | | +| `app/mailers/` | `spec/mailers/` | RSpec | | +| `lib/api/` | `spec/requests/api/` | RSpec | | +| `lib/ci/api/` | `spec/requests/ci/api/` | RSpec | | +| `app/assets/javascripts/` | `spec/javascripts/` | Karma | More details in the [JavaScript](#javascript) section. | + +#### About controller tests + +In an ideal world, controllers should be thin. However, when this is not the +case, it's acceptable to write a system/feature test without JavaScript instead +of a controller test. The reason is that testing a fat controller usually +involves a lot of stubbing, things like: -GitLab uses [factory_girl] as a test fixture replacement. - -- Factory definitions live in `spec/factories/`, named using the pluralization - of their corresponding model (`User` factories are defined in `users.rb`). -- There should be only one top-level factory definition per file. -- FactoryGirl methods are mixed in to all RSpec groups. This means you can (and - should) call `create(...)` instead of `FactoryGirl.create(...)`. -- Make use of [traits] to clean up definitions and usages. -- When defining a factory, don't define attributes that are not required for the - resulting record to pass validation. -- When instantiating from a factory, don't supply attributes that aren't - required by the test. -- Factories don't have to be limited to `ActiveRecord` objects. - [See example](https://gitlab.com/gitlab-org/gitlab-ce/commit/0b8cefd3b2385a21cfed779bd659978c0402766d). - -[factory_girl]: https://github.com/thoughtbot/factory_girl -[traits]: http://www.rubydoc.info/gems/factory_girl/file/GETTING_STARTED.md#Traits - -## JavaScript - -GitLab uses [Karma] to run its [Jasmine] JavaScript specs. They can be run on -the command line via `bundle exec karma`. - -- JavaScript tests live in `spec/javascripts/`, matching the folder structure - of `app/assets/javascripts/`: `app/assets/javascripts/behaviors/autosize.js` - has a corresponding `spec/javascripts/behaviors/autosize_spec.js` file. -- Haml fixtures required for JavaScript tests live in - `spec/javascripts/fixtures`. They should contain the bare minimum amount of - markup necessary for the test. - - > **Warning:** Keep in mind that a Rails view may change and - invalidate your test, but everything will still pass because your fixture - doesn't reflect the latest view. Because of this we encourage you to - generate fixtures from actual rails views whenever possible. - -- Keep in mind that in a CI environment, these tests are run in a headless - browser and you will not have access to certain APIs, such as - [`Notification`](https://developer.mozilla.org/en-US/docs/Web/API/notification), - which will have to be stubbed. - -[Karma]: https://github.com/karma-runner/karma -[Jasmine]: https://github.com/jasmine/jasmine +```ruby +controller.instance_variable_set(:@user, user) +``` -For more information, see the [frontend testing guide](fe_guide/testing.md). +and use methods which are deprecated in Rails 5 ([#23768]). + +[#23768]: https://gitlab.com/gitlab-org/gitlab-ce/issues/23768 + +#### About Karma + +As you may have noticed, Karma is both in the Unit tests and the Integration +tests category. That's because Karma is a tool that provides an environment to +run JavaScript tests, so you can either run unit tests (e.g. test a single +JavaScript method), or integration tests (e.g. test a component that is composed +of multiple components). + +### System tests or Feature tests + +Formal definition: https://en.wikipedia.org/wiki/System_testing. + +These kind of tests ensure the application works as expected from a user point +of view (aka black-box testing). These tests should test a happy path for a +given page or set of pages, and a test case should be added for any regression +that couldn't have been caught at lower levels with better tests (i.e. if a +regression is found, regression tests should be added at the lowest-level +possible). + +| Tests path | Testing engine | Notes | +| ---------- | -------------- | ----- | +| `spec/features/` | [Capybara] + [RSpec] | If your spec has the `:js` metadata, the browser driver will be [Poltergeist], otherwise it's using [RackTest]. | +| `features/` | Spinach | Spinach tests are deprecated, [you shouldn't add new Spinach tests](#spinach-feature-tests). | + +[Capybara]: https://github.com/teamcapybara/capybara +[RSpec]: https://github.com/rspec/rspec-rails#feature-specs +[Poltergeist]: https://github.com/teamcapybara/capybara#poltergeist +[RackTest]: https://github.com/teamcapybara/capybara#racktest + +#### Best practices + +- Create only the necessary records in the database +- Test a happy path and a less happy path but that's it +- Every other possible path should be tested with Unit or Integration tests +- Test what's displayed on the page, not the internals of ActiveRecord models. + For instance, if you want to verify that a record was created, add + expectations that its attributes are displayed on the page, not that + `Model.count` increased by one. +- It's ok to look for DOM elements but don't abuse it since it makes the tests + more brittle + +If we're confident that the low-level components work well (and we should be if +we have enough Unit & Integration tests), we shouldn't need to duplicate their +thorough testing at the System test level. + +It's very easy to add tests, but a lot harder to remove or improve tests, so one +should take care of not introducing too many (slow and duplicated) specs. + +The reasons why we should follow these best practices are as follows: + +- System tests are slow to run since they spin up the entire application stack + in a headless browser, and even slower when they integrate a JS driver +- When system tests run with a JavaScript driver, the tests are run in a + different thread than the application. This means it does not share a + database connection and your test will have to commit the transactions in + order for the running application to see the data (and vice-versa). In that + case we need to truncate the database after each spec instead of simply + rolling back a transaction (the faster strategy that's in use for other kind + of tests). This is slower than transactions, however, so we want to use + truncation only when necessary. + +### Black-box tests or End-to-end tests + +GitLab consists of [multiple pieces] such as [GitLab Shell], [GitLab Workhorse], +[Gitaly], [GitLab Pages], [GitLab Runner], and GitLab Rails. All theses pieces +are configured and packaged by [GitLab Omnibus]. + +[GitLab QA] is a tool that allows to test that all these pieces integrate well +together by building a Docker image for a given version of GitLab Rails and +running feature tests (i.e. using Capybara) against it. + +The actual test scenarios and steps are [part of GitLab Rails] so that they're +always in-sync with the codebase. + +[multiple pieces]: ./architecture.md#components +[GitLab Shell]: https://gitlab.com/gitlab-org/gitlab-shell +[GitLab Workhorse]: https://gitlab.com/gitlab-org/gitlab-workhorse +[Gitaly]: https://gitlab.com/gitlab-org/gitaly +[GitLab Pages]: https://gitlab.com/gitlab-org/gitlab-pages +[GitLab Runner]: https://gitlab.com/gitlab-org/gitlab-ci-multi-runner +[GitLab Omnibus]: https://gitlab.com/gitlab-org/omnibus-gitlab +[GitLab QA]: https://gitlab.com/gitlab-org/gitlab-qa +[part of GitLab Rails]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/qa + +## How to test at the correct level? + +As many things in life, deciding what to test at each level of testing is a +trade-off: + +- Unit tests are usually cheap, and you should consider them like the basement + of your house: you need them to be confident that your code is behaving + correctly. However if you run only unit tests without integration / system tests, you might [miss] the [big] [picture]! +- Integration tests are a bit more expensive, but don't abuse them. A feature test + is often better than an integration test that is stubbing a lot of internals. +- System tests are expensive (compared to unit tests), even more if they require + a JavaScript driver. Make sure to follow the guidelines in the [Speed](#test-speed) + section. + +Another way to see it is to think about the "cost of tests", this is well +explained [in this article][tests-cost] and the basic idea is that the cost of a +test includes: + +- The time it takes to write the test +- The time it takes to run the test every time the suite runs +- The time it takes to understand the test +- The time it takes to fix the test if it breaks and the underlying code is OK +- Maybe, the time it takes to change the code to make the code testable. + +[miss]: https://twitter.com/ThePracticalDev/status/850748070698651649 +[big]: https://twitter.com/timbray/status/822470746773409794 +[picture]: https://twitter.com/withzombies/status/829716565834752000 +[tests-cost]: https://medium.com/table-xi/high-cost-tests-and-high-value-tests-a86e27a54df#.2ulyh3a4e + +## Frontend testing + +Please consult the [dedicated "Frontend testing" guide](./fe_guide/testing.md). ## RSpec ### General Guidelines - Use a single, top-level `describe ClassName` block. -- Use `described_class` instead of repeating the class name being described. +- Use `described_class` instead of repeating the class name being described + (_this is enforced by RuboCop_). - Use `.method` to describe class methods and `#method` to describe instance methods. - Use `context` to test branching logic. @@ -70,11 +198,12 @@ For more information, see the [frontend testing guide](fe_guide/testing.md). - Don't `describe` symbols (see [Gotchas](gotchas.md#dont-describe-symbols)). - Don't assert against the absolute value of a sequence-generated attribute (see [Gotchas](gotchas.md#dont-assert-against-the-absolute-value-of-a-sequence-generated-attribute)). - Don't supply the `:each` argument to hooks since it's the default. -- Prefer `not_to` to `to_not` (_this is enforced by Rubocop_). +- Prefer `not_to` to `to_not` (_this is enforced by RuboCop_). - Try to match the ordering of tests to the ordering within the class. - Try to follow the [Four-Phase Test][four-phase-test] pattern, using newlines to separate phases. - Try to use `Gitlab.config.gitlab.host` rather than hard coding `'localhost'` +- On `before` and `after` hooks, prefer it scoped to `:context` over `:all` [four-phase-test]: https://robots.thoughtbot.com/four-phase-test @@ -98,6 +227,20 @@ so we need to set some guidelines for their use going forward: [lets-not]: https://robots.thoughtbot.com/lets-not +#### `set` variables + +In some cases there is no need to recreate the same object for tests again for +each example. For example, a project is needed to test issues on the same +project, one project will do for the entire file. This can be achieved by using +`set` in the same way you would use `let`. + +`rspec-set` only works on ActiveRecord objects, and before new examples it +reloads or recreates the model, _only_ if needed. That is, when you changed +properties or destroyed the object. + +There is one gotcha; you can't reference a model defined in a `let` block in a +`set` block. + ### Time-sensitive tests [Timecop](https://github.com/travisjeffery/timecop) is available in our @@ -117,53 +260,124 @@ it 'is overdue' do end ``` -### Test speed +### System / Feature tests -GitLab has a massive test suite that, without parallelization, can take more -than an hour to run. It's important that we make an effort to write tests that -are accurate and effective _as well as_ fast. +- Feature specs should be named `ROLE_ACTION_spec.rb`, such as + `user_changes_password_spec.rb`. +- Use only one `feature` block per feature spec file. +- Use scenario titles that describe the success and failure paths. +- Avoid scenario titles that add no information, such as "successfully". +- Avoid scenario titles that repeat the feature title. -Here are some things to keep in mind regarding test performance: +### Matchers -- `double` and `spy` are faster than `FactoryGirl.build(...)` -- `FactoryGirl.build(...)` and `.build_stubbed` are faster than `.create`. -- Don't `create` an object when `build`, `build_stubbed`, `attributes_for`, - `spy`, or `double` will do. Database persistence is slow! -- Use `create(:empty_project)` instead of `create(:project)` when you don't need - the underlying Git repository. Filesystem operations are slow! -- Don't mark a feature as requiring JavaScript (through `@javascript` in - Spinach or `js: true` in RSpec) unless it's _actually_ required for the test - to be valid. Headless browser testing is slow! +Custom matchers should be created to clarify the intent and/or hide the +complexity of RSpec expectations.They should be placed under +`spec/support/matchers/`. Matchers can be placed in subfolder if they apply to +a certain type of specs only (e.g. features, requests etc.) but shouldn't be if +they apply to multiple type of specs. -### Features / Integration +### Shared contexts -GitLab uses [rspec-rails feature specs] to test features in a browser -environment. These are [capybara] specs running on the headless [poltergeist] -driver. +All shared contexts should be be placed under `spec/support/shared_contexts/`. +Shared contexts can be placed in subfolder if they apply to a certain type of +specs only (e.g. features, requests etc.) but shouldn't be if they apply to +multiple type of specs. -- Feature specs live in `spec/features/` and should be named - `ROLE_ACTION_spec.rb`, such as `user_changes_password_spec.rb`. -- Use only one `feature` block per feature spec file. -- Use scenario titles that describe the success and failure paths. -- Avoid scenario titles that add no information, such as "successfully." -- Avoid scenario titles that repeat the feature title. +Each file should include only one context and have a descriptive name, e.g. +`spec/support/shared_contexts/controllers/githubish_import_controller_shared_context.rb`. -[rspec-rails feature specs]: https://github.com/rspec/rspec-rails#feature-specs -[capybara]: https://github.com/teamcapybara/capybara -[poltergeist]: https://github.com/teampoltergeist/poltergeist +### Shared examples -## Spinach (feature) tests +All shared examples should be be placed under `spec/support/shared_examples/`. +Shared examples can be placed in subfolder if they apply to a certain type of +specs only (e.g. features, requests etc.) but shouldn't be if they apply to +multiple type of specs. -GitLab [moved from Cucumber to Spinach](https://github.com/gitlabhq/gitlabhq/pull/1426) -for its feature/integration tests in September 2012. +Each file should include only one context and have a descriptive name, e.g. +`spec/support/shared_examples/controllers/githubish_import_controller_shared_example.rb`. -As of March 2016, we are [trying to avoid adding new Spinach -tests](https://gitlab.com/gitlab-org/gitlab-ce/issues/14121) going forward, -opting for [RSpec feature](#features-integration) specs. +### Helpers -Adding new Spinach scenarios is acceptable _only if_ the new scenario requires -no more than one new `step` definition. If more than that is required, the -test should be re-implemented using RSpec instead. +Helpers are usually modules that provide some methods to hide the complexity of +specific RSpec examples. You can define helpers in RSpec files if they're not +intended to be shared with other specs. Otherwise, they should be be placed +under `spec/support/helpers/`. Helpers can be placed in subfolder if they apply +to a certain type of specs only (e.g. features, requests etc.) but shouldn't be +if they apply to multiple type of specs. + +Helpers should follow the Rails naming / namespacing convention. For instance +`spec/support/helpers/cycle_analytics_helpers.rb` should define: + +```ruby +module Spec + module Support + module Helpers + module CycleAnalyticsHelpers + def create_commit_referencing_issue(issue, branch_name: random_git_name) + project.repository.add_branch(user, branch_name, 'master') + create_commit("Commit for ##{issue.iid}", issue.project, user, branch_name) + end + end + end + end +end +``` + +Helpers should not change the RSpec config. For instance, the helpers module +described above should not include: + +```ruby +RSpec.configure do |config| + config.include Spec::Support::Helpers::CycleAnalyticsHelpers +end +``` + +### Factories + +GitLab uses [factory_girl] as a test fixture replacement. + +- Factory definitions live in `spec/factories/`, named using the pluralization + of their corresponding model (`User` factories are defined in `users.rb`). +- There should be only one top-level factory definition per file. +- FactoryGirl methods are mixed in to all RSpec groups. This means you can (and + should) call `create(...)` instead of `FactoryGirl.create(...)`. +- Make use of [traits] to clean up definitions and usages. +- When defining a factory, don't define attributes that are not required for the + resulting record to pass validation. +- When instantiating from a factory, don't supply attributes that aren't + required by the test. +- Factories don't have to be limited to `ActiveRecord` objects. + [See example](https://gitlab.com/gitlab-org/gitlab-ce/commit/0b8cefd3b2385a21cfed779bd659978c0402766d). + +[factory_girl]: https://github.com/thoughtbot/factory_girl +[traits]: http://www.rubydoc.info/gems/factory_girl/file/GETTING_STARTED.md#Traits + +### Fixtures + +All fixtures should be be placed under `spec/fixtures/`. + +### Config + +RSpec config files are files that change the RSpec config (i.e. +`RSpec.configure do |config|` blocks). They should be placed under +`spec/support/config/`. + +Each file should be related to a specific domain, e.g. +`spec/support/config/capybara.rb`, `spec/support/config/carrierwave.rb`, etc. + +Helpers can be included in the `spec/support/config/rspec.rb` file. If a +helpers module applies only to a certain kind of specs, it should add modifiers +to the `config.include` call. For instance if +`spec/support/helpers/cycle_analytics_helpers.rb` applies to `:lib` and +`type: :model` specs only, you would write the following: + +```ruby +RSpec.configure do |config| + config.include Spec::Support::Helpers::CycleAnalyticsHelpers, :lib + config.include Spec::Support::Helpers::CycleAnalyticsHelpers, type: :model +end +``` ## Testing Rake Tasks @@ -201,6 +415,86 @@ describe 'gitlab:shell rake tasks' do end ``` +## Test speed + +GitLab has a massive test suite that, without [parallelization], can take hours +to run. It's important that we make an effort to write tests that are accurate +and effective _as well as_ fast. + +Here are some things to keep in mind regarding test performance: + +- `double` and `spy` are faster than `FactoryGirl.build(...)` +- `FactoryGirl.build(...)` and `.build_stubbed` are faster than `.create`. +- Don't `create` an object when `build`, `build_stubbed`, `attributes_for`, + `spy`, or `double` will do. Database persistence is slow! +- Use `create(:empty_project)` instead of `create(:project)` when you don't need + the underlying Git repository. Filesystem operations are slow! +- Don't mark a feature as requiring JavaScript (through `@javascript` in + Spinach or `:js` in RSpec) unless it's _actually_ required for the test + to be valid. Headless browser testing is slow! + +[parallelization]: #test-suite-parallelization-on-the-ci + +### Test suite parallelization on the CI + +Our current CI parallelization setup is as follows: + +1. The `knapsack` job in the prepare stage that is supposed to ensure we have a + `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file: + - The `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file is fetched + from S3, if it's not here we initialize the file with `{}`. +1. Each `rspec x y` job are run with `knapsack rspec` and should have an evenly + distributed share of tests: + - It works because the jobs have access to the + `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` since the "artifacts + from all previous stages are passed by default". [^1] + - the jobs set their own report path to + `KNAPSACK_REPORT_PATH=knapsack/${CI_PROJECT_NAME}/${JOB_NAME[0]}_node_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json`. + - if knapsack is doing its job, test files that are run should be listed under + `Report specs`, not under `Leftover specs`. +1. The `update-knapsack` job takes all the + `knapsack/${CI_PROJECT_NAME}/${JOB_NAME[0]}_node_${CI_NODE_INDEX}_${CI_NODE_TOTAL}_report.json` + files from the `rspec x y` jobs and merge them all together into a single + `knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file that is then + uploaded to S3. + +After that, the next pipeline will use the up-to-date +`knapsack/${CI_PROJECT_NAME}/rspec_report-master.json` file. The same strategy +is used for Spinach tests as well. + +### Monitoring + +The GitLab test suite is [monitored] for the `master` branch, and any branch +that includes `rspec-profile` in their name. + +A [public dashboard] is available for everyone to see. Feel free to look at the +slowest test files and try to improve them. + +[monitored]: ./performance.md#rspec-profiling +[public dashboard]: https://redash.gitlab.com/public/dashboards/l1WhHXaxrCWM5Ai9D7YDqHKehq6OU3bx5gssaiWe?org_slug=default + +## CI setup + +- On CE, the test suite only runs against PostgreSQL by default. We additionally + run the suite against MySQL for tags, `master`, and any branch that includes + `mysql` in the name. +- On EE, the test suite always runs both PostgreSQL and MySQL. + +## Spinach (feature) tests + +GitLab [moved from Cucumber to Spinach](https://github.com/gitlabhq/gitlabhq/pull/1426) +for its feature/integration tests in September 2012. + +As of March 2016, we are [trying to avoid adding new Spinach +tests](https://gitlab.com/gitlab-org/gitlab-ce/issues/14121) going forward, +opting for [RSpec feature](#features-integration) specs. + +Adding new Spinach scenarios is acceptable _only if_ the new scenario requires +no more than one new `step` definition. If more than that is required, the +test should be re-implemented using RSpec instead. + --- [Return to Development documentation](README.md) + +[^1]: /ci/yaml/README.html#dependencies diff --git a/doc/development/ux_guide/basics.md b/doc/development/ux_guide/basics.md index 259b214bd59..a436e9b1948 100644 --- a/doc/development/ux_guide/basics.md +++ b/doc/development/ux_guide/basics.md @@ -22,7 +22,7 @@ GitLab's main typeface used throughout the UI is **Source Sans Pro**. We support ### Monospace typeface -This is the typeface used for code blocks. GitLab uses the OS default font. +This is the typeface used for code blocks and references to commits, branches, and tags (`.commit-sha` or `.ref-name`). GitLab uses the OS default font. - **Menlo** (Mac) - **Consolas** (Windows) - **Liberation Mono** (Linux) diff --git a/doc/development/what_requires_downtime.md b/doc/development/what_requires_downtime.md index bbcd26477f3..c4830322fa8 100644 --- a/doc/development/what_requires_downtime.md +++ b/doc/development/what_requires_downtime.md @@ -2,7 +2,8 @@ When working with a database certain operations can be performed without taking GitLab offline, others do require a downtime period. This guide describes -various operations and their impact. +various operations, their impact, and how to perform them without requiring +downtime. ## Adding Columns @@ -41,50 +42,158 @@ information on how to use this method. ## Dropping Columns -On PostgreSQL you can safely remove an existing column without the need for -downtime. When you drop a column in PostgreSQL it's not immediately removed, -instead it is simply disabled. The data is removed on the next vacuum run. +Removing columns is tricky because running GitLab processes may still be using +the columns. To work around this you will need two separate merge requests and +releases: one to ignore and then remove the column, and one to remove the ignore +rule. -On MySQL this operation requires downtime. +### Step 1: Ignoring The Column -While database wise dropping a column may be fine on PostgreSQL this operation -still requires downtime because the application code may still be using the -column that was removed. For example, consider the following migration: +The first step is to ignore the column in the application code. This is +necessary because Rails caches the columns and re-uses this cache in various +places. This can be done by including the `IgnorableColumn` module into the +model, followed by defining the columns to ignore. For example, to ignore +`updated_at` in the User model you'd use the following: ```ruby -class MyMigration < ActiveRecord::Migration - def change - remove_column :projects, :dummy - end +class User < ActiveRecord::Base + include IgnorableColumn + + ignore_column :updated_at end ``` -Now imagine that the GitLab instance is running and actively uses the `dummy` -column. If we were to run the migration this would result in the GitLab instance -producing errors whenever it tries to use the `dummy` column. +Once added you should create a _post-deployment_ migration that removes the +column. Both these changes should be submitted in the same merge request. -As a result of the above downtime _is_ required when removing a column, even -when using PostgreSQL. +### Step 2: Removing The Ignore Rule + +Once the changes from step 1 have been released & deployed you can set up a +separate merge request that removes the ignore rule. This merge request can +simply remove the `ignore_column` line, and the `include IgnorableColumn` line +if no other `ignore_column` calls remain. ## Renaming Columns -Renaming columns requires downtime as running GitLab instances will continue -using the old column name until a new version is deployed. This can result -in the instance producing errors, which in turn can impact the user experience. +Renaming columns the normal way requires downtime as an application may continue +using the old column name during/after a database migration. To rename a column +without requiring downtime we need two migrations: a regular migration, and a +post-deployment migration. Both these migration can go in the same release. -## Changing Column Constraints +### Step 1: Add The Regular Migration + +First we need to create the regular migration. This migration should use +`Gitlab::Database::MigrationHelpers#rename_column_concurrently` to perform the +renaming. For example + +```ruby +# A regular migration in db/migrate +class RenameUsersUpdatedAtToUpdatedAtTimestamp < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + + disable_ddl_transaction! + + def up + rename_column_concurrently :users, :updated_at, :updated_at_timestamp + end + + def down + cleanup_concurrent_column_rename :users, :updated_at_timestamp, :updated_at + end +end +``` + +This will take care of renaming the column, ensuring data stays in sync, copying +over indexes and foreign keys, etc. + +**NOTE:** if a column contains 1 or more indexes that do not contain the name of +the original column, the above procedure will fail. In this case you will first +need to rename these indexes. -Generally changing column constraints requires checking all rows in the table to -see if they meet the new constraint, unless a constraint is _removed_. For -example, changing a column that previously allowed NULL values to not allow NULL -values requires the database to verify all existing rows. +### Step 2: Add A Post-Deployment Migration -The specific behaviour varies a bit between databases but in general the safest -approach is to assume changing constraints requires downtime. +The renaming procedure requires some cleaning up in a post-deployment migration. +We can perform this cleanup using +`Gitlab::Database::MigrationHelpers#cleanup_concurrent_column_rename`: + +```ruby +# A post-deployment migration in db/post_migrate +class CleanupUsersUpdatedAtRename < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + + disable_ddl_transaction! + + def up + cleanup_concurrent_column_rename :users, :updated_at, :updated_at_timestamp + end + + def down + rename_column_concurrently :users, :updated_at_timestamp, :updated_at + end +end +``` + +## Changing Column Constraints + +Adding or removing a NOT NULL clause (or another constraint) can typically be +done without requiring downtime. However, this does require that any application +changes are deployed _first_. Thus, changing the constraints of a column should +happen in a post-deployment migration. +NOTE: Avoid using `change_column` as it produces inefficient query because it re-defines +the whole column type. For example, to add a NOT NULL constraint, prefer `change_column_null ` ## Changing Column Types -This operation requires downtime. +Changing the type of a column can be done using +`Gitlab::Database::MigrationHelpers#change_column_type_concurrently`. This +method works similarly to `rename_column_concurrently`. For example, let's say +we want to change the type of `users.username` from `string` to `text`. + +### Step 1: Create A Regular Migration + +A regular migration is used to create a new column with a temporary name along +with setting up some triggers to keep data in sync. Such a migration would look +as follows: + +```ruby +# A regular migration in db/migrate +class ChangeUsersUsernameStringToText < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + + disable_ddl_transaction! + + def up + change_column_type_concurrently :users, :username, :text + end + + def down + cleanup_concurrent_column_type_change :users, :username + end +end +``` + +### Step 2: Create A Post Deployment Migration + +Next we need to clean up our changes using a post-deployment migration: + +```ruby +# A post-deployment migration in db/post_migrate +class ChangeUsersUsernameStringToTextCleanup < ActiveRecord::Migration + include Gitlab::Database::MigrationHelpers + + disable_ddl_transaction! + + def up + cleanup_concurrent_column_type_change :users + end + + def down + change_column_type_concurrently :users, :username, :string + end +end +``` + +And that's it, we're done! ## Adding Indexes @@ -101,12 +210,19 @@ Migrations can take advantage of this by using the method ```ruby class MyMigration < ActiveRecord::Migration - def change + def up add_concurrent_index :projects, :column_name end + + def down + remove_index(:projects, :column_name) if index_exists?(:projects, :column_name) + end end ``` +Note that `add_concurrent_index` can not be reversed automatically, thus you +need to manually define `up` and `down`. + When running this on PostgreSQL the `CONCURRENTLY` option mentioned above is used. On MySQL this method produces a regular `CREATE INDEX` query. @@ -125,43 +241,54 @@ This operation is safe as there's no code using the table just yet. ## Dropping Tables -This operation requires downtime as application code may still be using the -table. +Dropping tables can be done safely using a post-deployment migration, but only +if the application no longer uses the table. ## Adding Foreign Keys -Adding foreign keys acquires an exclusive lock on both the source and target -tables in PostgreSQL. This requires downtime as otherwise the entire application -grinds to a halt for the duration of the operation. +Adding foreign keys usually works in 3 steps: + +1. Start a transaction +1. Run `ALTER TABLE` to add the constraint(s) +1. Check all existing data -On MySQL this operation also requires downtime _unless_ foreign key checks are -disabled. Because this means checks aren't enforced this is not ideal, as such -one should assume MySQL also requires downtime. +Because `ALTER TABLE` typically acquires an exclusive lock until the end of a +transaction this means this approach would require downtime. + +GitLab allows you to work around this by using +`Gitlab::Database::MigrationHelpers#add_concurrent_foreign_key`. This method +ensures that when PostgreSQL is used no downtime is needed. ## Removing Foreign Keys -This operation should not require downtime on both PostgreSQL and MySQL. +This operation does not require downtime. -## Updating Data +## Data Migrations -Updating data should generally be safe. The exception to this is data that's -being migrated from one version to another while the application still produces -data in the old version. +Data migrations can be tricky. The usual approach to migrate data is to take a 3 +step approach: -For example, imagine the application writes the string `'dog'` to a column but -it really is meant to write `'cat'` instead. One might think that the following -migration is all that is needed to solve this problem: +1. Migrate the initial batch of data +1. Deploy the application code +1. Migrate any remaining data -```ruby -class MyMigration < ActiveRecord::Migration - def up - execute("UPDATE some_table SET column = 'cat' WHERE column = 'dog';") - end -end -``` +Usually this works, but not always. For example, if a field's format is to be +changed from JSON to something else we have a bit of a problem. If we were to +change existing data before deploying application code we'll most likely run +into errors. On the other hand, if we were to migrate after deploying the +application code we could run into the same problems. + +If you merely need to correct some invalid data, then a post-deployment +migration is usually enough. If you need to change the format of data (e.g. from +JSON to something else) it's typically best to add a new column for the new data +format, and have the application use that. In such a case the procedure would +be: -Unfortunately this is not enough. Because the application is still running and -using the old value this may result in the table still containing rows where -`column` is set to `dog`, even after the migration finished. +1. Add a new column in the new format +1. Copy over existing data to this new column +1. Deploy the application code +1. In a post-deployment migration, copy over any remaining data -In these cases downtime _is_ required, even for rarely updated tables. +In general there is no one-size-fits-all solution, therefore it's best to +discuss these kind of migrations in a merge request to make sure they are +implemented in the best way possible. diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md index 482ec54207b..eac9ec2a470 100644 --- a/doc/development/writing_documentation.md +++ b/doc/development/writing_documentation.md @@ -2,7 +2,7 @@ - **General Documentation**: written by the developers responsible by creating features. Should be submitted in the same merge request containing code. Feature proposals (by GitLab contributors) should also be accompanied by its respective documentation. They can be later improved by PMs and Technical Writers. - **Technical Articles**: written by any [GitLab Team](https://about.gitlab.com/team/) member, GitLab contributors, or [Community Writers](https://about.gitlab.com/handbook/product/technical-writing/community-writers/). - - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs, in the same merge request containing code. + - **Indexes per topic**: initially prepared by the Technical Writing Team, and kept up-to-date by developers and PMs in the same merge request containing code. They gather all resources for that topic in a single page (user and admin documentation, articles, and third-party docs). ## Distinction between General Documentation and Technical Articles @@ -18,7 +18,7 @@ They are topic-related documentation, written with an user-friendly approach and A technical article guides users and/or admins to achieve certain objectives (within guides and tutorials), or provide an overview of that particular topic or feature (within technical overviews). It can also describe the use, implementation, or integration of third-party tools with GitLab. -They live under `doc/topics/topic-name/`, and can be searched per topic, within "Indexes per Topic" pages. The topics are listed on the main [Indexes per Topic](../topics/index.md) page. +They live under `doc/articles/article-title/index.md`, and their images should be placed under `doc/articles/article-title/img/`. Find a list of existing [technical articles](../articles/index.md) here. #### Types of Technical Articles @@ -52,11 +52,13 @@ Every **Technical Article** contains, in the very beginning, a blockquote with t - A reference to the **type of article** (user guide, admin guide, tech overview, tutorial) - A reference to the **knowledge level** expected from the reader to be able to follow through (beginner, intermediate, advanced) - A reference to the **author's name** and **GitLab.com handle** +- A reference of the **publication date** ```md -> **Type:** tutorial || +> **Article [Type](../../development/writing_documentation.html#types-of-technical-articles):** tutorial || > **Level:** intermediary || -> **Author:** [Name Surname](https://gitlab.com/username) +> **Author:** [Name Surname](https://gitlab.com/username) || +> **Publication date:** AAAA/MM/DD ``` #### Technical Articles - Writing Method @@ -70,3 +72,34 @@ All the docs follow the same [styleguide](doc_styleguide.md). ### Markdown Currently GitLab docs use Redcarpet as [markdown](../user/markdown.md) engine, but there's an [open discussion](https://gitlab.com/gitlab-com/gitlab-docs/issues/50) for implementing Kramdown in the near future. + +## Testing + +We try to treat documentation as code, thus have implemented some testing. +Currently, the following tests are in place: + +1. `docs lint`: Check that all internal (relative) links work correctly and + that all cURL examples in API docs use the full switches. + +If your contribution contains **only** documentation changes, you can speed up +the CI process by following some branch naming conventions. You have three +choices: + +| Branch name | Valid example | +| ----------- | ------------- | +| Starting with `docs/` | `docs/update-api-issues` | +| Starting with `docs-` | `docs-update-api-issues` | +| Ending in `-docs` | `123-update-api-issues-docs` | + +If your branch name matches any of the above, it will run only the docs +tests. If it doesn't, the whole test suite will run (including docs). + +--- + +When you submit a merge request to GitLab Community Edition (CE), there is an +additional job called `rake ee_compat_check` that runs against Enterprise +Edition (EE) and checks if your changes can apply cleanly to the EE codebase. +If that job fails, read the instructions in the job log for what to do next. +Contributors do not need to submit their changes to EE, GitLab Inc. employees +on the other hand need to make sure that their changes apply cleanly to both +CE and EE. diff --git a/doc/gitlab-basics/README.md b/doc/gitlab-basics/README.md index d7e3aa35bdd..12466437edc 100644 --- a/doc/gitlab-basics/README.md +++ b/doc/gitlab-basics/README.md @@ -11,5 +11,5 @@ Step-by-step guides on the basics of working with Git and GitLab. - [Fork a project](fork-project.md) - [Add a file](add-file.md) - [Add an image](add-image.md) -- [Create an issue](create-issue.md) +- [Create an issue](../user/project/issues/create_new_issue.md) - [Create a merge request](add-merge-request.md) diff --git a/doc/gitlab-basics/create-group.md b/doc/gitlab-basics/create-group.md index 64274ccd5eb..b4889bb8818 100644 --- a/doc/gitlab-basics/create-group.md +++ b/doc/gitlab-basics/create-group.md @@ -25,6 +25,8 @@ To create a group: 1. Set the "Group path" which will be the namespace under which your projects will be hosted (path can contain only letters, digits, underscores, dashes and dots; it cannot start with dashes or end in dot). + 1. The "Group name" will populate with the path. Optionally, you can change + it. This is the name that will display in the group views. 1. Optionally, you can add a description so that others can briefly understand what this group is about. 1. Optionally, choose and avatar for your project. diff --git a/doc/gitlab-basics/create-issue.md b/doc/gitlab-basics/create-issue.md index 13e5a738c89..abb163dbf18 100644 --- a/doc/gitlab-basics/create-issue.md +++ b/doc/gitlab-basics/create-issue.md @@ -1,30 +1,2 @@ -# How to create an Issue in GitLab -The issue tracker is a good place to add things that need to be improved or -solved in a project. - ---- - -1. Go to the project where you'd like to create the issue and navigate to the - **Issues** tab on top. - -  - -1. Click on the **New issue** button on the right side of your screen. - -  - -1. At the very minimum, add a title and a description to your issue. - You may assign it to a user, add a milestone or add labels (all optional). - -  - -1. When ready, click on **Submit issue**. - ---- - -Your Issue will now be added to the issue tracker of the project you opened it -at and will be ready to be reviewed. You can comment on it and mention the -people involved. You can also link issues to the merge requests where the issues -are solved. To do this, you can use an -[issue closing pattern](../user/project/issues/automatic_issue_closing.md). +This document was moved to [another location](../user/project/issues/index.md#new-issue). diff --git a/doc/gitlab-basics/create-project.md b/doc/gitlab-basics/create-project.md index 1c549844ee1..2513f4b420a 100644 --- a/doc/gitlab-basics/create-project.md +++ b/doc/gitlab-basics/create-project.md @@ -1,24 +1,28 @@ # How to create a project in GitLab -There are two ways to create a new project in GitLab. - -1. While in your dashboard, you can create a new project using the **New project** - green button or you can use the cross icon in the upper right corner next to - your avatar which is always visible. +1. In your dashboard, click the green **New project** button or use the plus + icon in the upper right corner of the navigation bar.  -1. From there you can see several options. +1. This opens the **New project** page.  -1. Fill out the information: - - 1. "Project name" is the name of your project (you can't use special characters, - but you can use spaces, hyphens, underscores or even emojis). - 1. The "Project description" is optional and will be shown in your project's - dashboard so others can briefly understand what your project is about. - 1. Select a [visibility level](../public_access/public_access.md). - 1. You can also [import your existing projects](../workflow/importing/README.md). - -1. Finally, click **Create project**. +1. Provide the following information: + - Enter 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. + - If you have a project in a different repository, you can [import it] by + clicking an **Import project from** button provided this is enabled in + your GitLab instance. Ask your administrator if not. + - 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 + idea to fill this in. + - Changing the **Visibility Level** modifies the project's + [viewing and access rights](../public_access/public_access.md) for users. + +1. Click **Create project**. + +[import it]: ../workflow/importing/README.md diff --git a/doc/gitlab-basics/img/create_new_group_info.png b/doc/gitlab-basics/img/create_new_group_info.png Binary files differindex 020b4ac00d6..8d2501d9f7a 100644 --- a/doc/gitlab-basics/img/create_new_group_info.png +++ b/doc/gitlab-basics/img/create_new_group_info.png diff --git a/doc/gitlab-basics/img/create_new_project_button.png b/doc/gitlab-basics/img/create_new_project_button.png Binary files differindex 8d7a69e55ed..567f104880f 100644 --- a/doc/gitlab-basics/img/create_new_project_button.png +++ b/doc/gitlab-basics/img/create_new_project_button.png diff --git a/doc/install/README.md b/doc/install/README.md index d35709266e4..bc831a37735 100644 --- a/doc/install/README.md +++ b/doc/install/README.md @@ -18,10 +18,10 @@ the hardware requirements. Useful for unsupported systems like *BSD. For an overview of the directory structure, read the [structure documentation](structure.md). - [Docker](https://docs.gitlab.com/omnibus/docker/) - Install GitLab using Docker. -- [Installation on Google Cloud Platform](google_cloud_platform/index.md) - Install - GitLab on Google Cloud Platform using our official image. -- [Digital Ocean and Docker](digitaloceandocker.md) - Install GitLab quickly - on DigitalOcean using Docker. +- [Installing in Kubernetes](kubernetes/index.md) - Install GitLab into a Kubernetes + Cluster using our official Helm Chart Repository. +- Testing only! [DigitalOcean and Docker Machine](digitaloceandocker.md) - + Quickly test any version of GitLab on DigitalOcean using Docker Machine. ## Database diff --git a/doc/install/digitaloceandocker.md b/doc/install/digitaloceandocker.md index 820060a489b..8efc0530b8a 100644 --- a/doc/install/digitaloceandocker.md +++ b/doc/install/digitaloceandocker.md @@ -1,4 +1,7 @@ -# Digital Ocean and Docker +# Digital Ocean and Docker Machine test environment + +## Warning. This guide is for quickly testing different versions of GitLab and +## not recommended for ease of future upgrades or keeping the data you create. ## Initial setup diff --git a/doc/install/google_cloud_platform/index.md b/doc/install/google_cloud_platform/index.md index 26506111548..35220119e9b 100644 --- a/doc/install/google_cloud_platform/index.md +++ b/doc/install/google_cloud_platform/index.md @@ -2,6 +2,10 @@  +>**Important note:** +GitLab has no official images in Google Cloud Platform yet. This guide serves +as a template for when the GitLab VM will be available. + The fastest way to get started on [Google Cloud Platform (GCP)][gcp] is through the [Google Cloud Launcher][launcher] program. diff --git a/doc/install/installation.md b/doc/install/installation.md index a2248a38435..5bba405f159 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -109,14 +109,19 @@ Then select 'Internet Site' and press enter to confirm the hostname. ## 2. Ruby -**Note:** The current supported Ruby version is 2.3.x. GitLab 9.0 dropped support -for Ruby 2.1.x. +The Ruby interpreter is required to run GitLab. + +**Note:** The current supported Ruby (MRI) version is 2.3.x. GitLab 9.0 dropped +support for Ruby 2.1.x. The use of Ruby version managers such as [RVM], [rbenv] or [chruby] with GitLab in production, frequently leads to hard to diagnose problems. For example, GitLab Shell is called from OpenSSH, and having a version manager can prevent pushing and pulling over SSH. Version managers are not supported and we strongly -advise everyone to follow the instructions below to use a system Ruby. +advise everyone to follow the instructions below to use a system Ruby. + +Linux distributions generally have older versions of Ruby available, so these +instructions are designed to install Ruby from the official source code. Remove the old Ruby 1.8 if present: @@ -132,7 +137,7 @@ Download Ruby and compile it: make sudo make install -Install the Bundler Gem: +Then install the Bundler Gem: sudo gem install bundler --no-ri --no-rdoc @@ -289,9 +294,9 @@ sudo usermod -aG redis git ### Clone the Source # Clone GitLab repository - sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 9-0-stable gitlab + sudo -u git -H git clone https://gitlab.com/gitlab-org/gitlab-ce.git -b 9-2-stable gitlab -**Note:** You can change `9-0-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! +**Note:** You can change `9-2-stable` to `master` if you want the *bleeding edge* version, but never install master on a production server! ### Configure It @@ -423,6 +428,11 @@ which is the recommended location. sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse]" RAILS_ENV=production +You can specify a different Git repository by providing it as an extra paramter: + + sudo -u git -H bundle exec rake "gitlab:workhorse:install[/home/git/gitlab-workhorse,https://example.com/gitlab-workhorse.git]" RAILS_ENV=production + + ### Initialize Database and Activate Advanced Features sudo -u git -H bundle exec rake gitlab:setup RAILS_ENV=production @@ -459,20 +469,26 @@ Make GitLab start on boot: ### Install Gitaly -As of GitLab 9.0 Gitaly is an **optional** component. Its -configuration is expected to change in GitLab 9.1. It is OK to wait -with setting up Gitaly until you upgrade to GitLab 9.1 or later. +As of GitLab 9.1 Gitaly is an **optional** component. Its +configuration is still changing regularly. It is OK to wait +with setting up Gitaly until you upgrade to GitLab 9.2 or later. # Fetch Gitaly source with Git and compile with Go sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly]" RAILS_ENV=production +You can specify a different Git repository by providing it as an extra paramter: + + sudo -u git -H bundle exec rake "gitlab:gitaly:install[/home/git/gitaly,https://example.com/gitaly.git]" RAILS_ENV=production + +Next, make sure gitaly configured: + # Restrict Gitaly socket access sudo chmod 0700 /home/git/gitlab/tmp/sockets/private sudo chown git /home/git/gitlab/tmp/sockets/private - # Configure Gitaly - echo 'GITALY_SOCKET_PATH=/home/git/gitlab/tmp/sockets/private/gitaly.socket' | \ - sudo -u git tee -a /home/git/gitaly/env + # If you are using non-default settings you need to update config.toml + cd /home/git/gitaly + sudo -u git -H editor config.toml # Enable Gitaly in the init script echo 'gitaly_enabled=true' | sudo tee -a /etc/default/gitlab diff --git a/doc/install/kubernetes/gitlab_chart.md b/doc/install/kubernetes/gitlab_chart.md new file mode 100644 index 00000000000..2d7edbe16e4 --- /dev/null +++ b/doc/install/kubernetes/gitlab_chart.md @@ -0,0 +1,436 @@ +# GitLab Helm Chart + +The `gitlab` Helm chart deploys GitLab into your Kubernetes cluster. + +This chart includes the following: + +- Deployment using the [gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce) or [gitlab-ee](https://hub.docker.com/r/gitlab/gitlab-ee) container image +- ConfigMap containing the `gitlab.rb` contents that configure [Omnibus GitLab](https://docs.gitlab.com/omnibus/settings/configuration.html#configuration-options) +- Persistent Volume Claims for Data, Config, Logs, and Registry Storage +- A Kubernetes service +- Optional Redis deployment using the [Redis Chart](https://github.com/kubernetes/charts/tree/master/stable/redis) (defaults to enabled) +- Optional PostgreSQL deployment using the [PostgreSQL Chart](https://github.com/kubernetes/charts/tree/master/stable/postgresql) (defaults to enabled) +- Optional Ingress (defaults to disabled) + +## Prerequisites + +- _At least_ 3 GB of RAM available on your cluster, in chunks of 1 GB +- Kubernetes 1.4+ with Beta APIs enabled +- [Persistent Volume](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) provisioner support in the underlying infrastructure +- The ability to point a DNS entry or URL at your GitLab install +- The `kubectl` CLI installed locally and authenticated for the cluster +- The Helm Client installed locally +- The Helm Server (Tiller) already installed and running in the cluster, by running `helm init` +- The GitLab Helm Repo [added to your Helm Client](index.md#add-the-gitlab-helm-repository) + +## Configuring GitLab + +Create a `values.yaml` file for your GitLab configuration. See the +[Helm docs](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/values_files.md) +for information on how your values file will override the defaults. + +The default configuration can always be [found in the `values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab/values.yaml), in the chart repository. + +### Required configuration + +In order for GitLab to function, your config file **must** specify the following: + +- An `externalUrl` that GitLab will be reachable at. + +### Choosing GitLab Edition + +The Helm chart defaults to installing GitLab CE. This can be controlled by setting the `edition` variable in your values. + +Setting `edition` to GitLab Enterprise Edition (EE) in your `values.yaml` + +```yaml +edition: EE + +externalUrl: 'http://gitlab.example.com' +``` + +### Choosing a different GitLab release version + +The version of GitLab installed is based on the `edition` setting (see [section](#choosing-gitlab-edition) above), and +the value of the corresponding helm setting: `ceImage` or `eeImage`. + +```yaml +## GitLab Edition +## ref: https://about.gitlab.com/products/ +## - CE - Community Edition +## - EE - Enterprise Edition - (requires license issued by GitLab Inc) +## +edition: CE + +## GitLab CE image +## ref: https://hub.docker.com/r/gitlab/gitlab-ce/tags/ +## +ceImage: gitlab/gitlab-ce:9.1.2-ce.0 + +## GitLab EE image +## ref: https://hub.docker.com/r/gitlab/gitlab-ee/tags/ +## +eeImage: gitlab/gitlab-ee:9.1.2-ee.0 +``` + +The different images can be found in the [gitlab-ce](https://hub.docker.com/r/gitlab/gitlab-ce/tags/) and [gitlab-ee](https://hub.docker.com/r/gitlab/gitlab-ee/tags/) +repositories on Docker Hub + +> **Note:** +There is no guarantee that other release versions of GitLab, other than what are +used by default in the chart, will be supported by a chart install. + + +### Custom Omnibus GitLab configuration + +In addition to the configuration options provided for GitLab in the Helm Chart, you can also pass any custom configuration +that is valid for the [Omnibus GitLab Configuration](https://docs.gitlab.com/omnibus/settings/configuration.html). + +The setting to pass these values in is `omnibusConfigRuby`. It accepts any valid +Ruby code that could used in the Omnibus `/etc/gitlab/gitlab.rb` file. In +Kubernetes, the contents will be stored in a ConfigMap. + +Example setting: + +```yaml +omnibusConfigRuby: | + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; +``` + +### Persistent storage + +By default, persistent storage is enabled for GitLab and the charts it depends +on (Redis and PostgreSQL). + +Components can have their claim size set from your `values.yaml`, and each +component allows you to optionally configure the `storageClass` variable so you +can take advantage of faster drives on your cloud provider. + +Basic configuration: + +```yaml +## Enable persistence using Persistent Volume Claims +## ref: http://kubernetes.io/docs/user-guide/persistent-volumes/ +## ref: https://docs.gitlab.com/ce/install/requirements.html#storage +## +persistence: + ## This volume persists generated configuration files, keys, and certs. + ## + gitlabEtc: + enabled: true + size: 1Gi + ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass> + ## Default: volume.alpha.kubernetes.io/storage-class: default + ## + # storageClass: + accessMode: ReadWriteOnce + ## This volume is used to store git data and other project files. + ## ref: https://docs.gitlab.com/omnibus/settings/configuration.html#storing-git-data-in-an-alternative-directory + ## + gitlabData: + enabled: true + size: 10Gi + ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass> + ## Default: volume.alpha.kubernetes.io/storage-class: default + ## + # storageClass: + accessMode: ReadWriteOnce + gitlabRegistry: + enabled: true + size: 10Gi + ## If defined, volume.beta.kubernetes.io/storage-class: <storageClass> + ## Default: volume.alpha.kubernetes.io/storage-class: default + ## + # storageClass: + + postgresql: + persistence: + # storageClass: + size: 10Gi + ## Configuration values for the Redis dependency. + ## ref: https://github.com/kubernetes/charts/blob/master/stable/redis/README.md + ## + redis: + persistence: + # storageClass: + size: 10Gi +``` + +>**Note:** +You can make use of faster SSD drives by adding a [StorageClass] to your cluster +and using the `storageClass` setting in the above config to the name of +your new storage class. + +### Routing + +By default, the GitLab chart uses a service type of `LoadBalancer` which will +result in the GitLab service being exposed externally using your cloud provider's +load balancer. + +This field is configurable in your `values.yml` by setting the top-level +`serviceType` field. See the [Service documentation][kube-srv] for more +information on the possible values. + +#### Ingress routing + +Optionally, you can enable the Chart's ingress for use by an ingress controller +deployed in your cluster. + +To enable the ingress, edit its section in your `values.yaml`: + +```yaml +ingress: + ## If true, gitlab Ingress will be created + ## + enabled: true + + ## gitlab Ingress hostnames + ## Must be provided if Ingress is enabled + ## + hosts: + - gitlab.example.com + + ## gitlab Ingress annotations + ## + annotations: + kubernetes.io/ingress.class: nginx +``` + +You must also provide the list of hosts that the ingress will use. In order for +you ingress controller to work with the GitLab Ingress, you will need to specify +its class in an annotation. + +>**Note:** +The Ingress alone doesn't expose GitLab externally. You need to have a Ingress controller setup to do that. +Setting up an Ingress controller can be as simple as installing the `nginx-ingress` helm chart. But be sure +to read the [documentation](https://github.com/kubernetes/charts/blob/master/stable/nginx-ingress/README.md) + +### External database + +You can configure the GitLab Helm chart to connect to an external PostgreSQL +database. + +>**Note:** +This is currently our recommended approach for a Production setup. + +To use an external database, in your `values.yaml`, disable the included +PostgreSQL dependency, then configure access to your database: + +```yaml +dbHost: "<reachable postgres hostname>" +dbPassword: "<password for the user with access to the db>" +dbUsername: "<user with read/write access to the database>" +dbDatabase: "<database name on postgres to connect to for GitLab>" + +postgresql: + # Sets whether the PostgreSQL helm chart is used as a dependency + enabled: false +``` + +Be sure to check the GitLab documentation on how to +[configure the external database](../requirements.md#postgresql-requirements) + +You can also configure the chart to use an external Redis server, but this is +not required for basic production use: + +```yaml +dbHost: "<reachable redis hostname>" +dbPassword: "<password>" + +redis: + # Sets whether the Redis helm chart is used as a dependency + enabled: false +``` + +### Sending email + +By default, the GitLab container will not be able to send email from your cluster. +In order to send email, you should configure SMTP settings in the +`omnibusConfigRuby` section, as per the [GitLab Omnibus documentation](https://docs.gitlab.com/omnibus/settings/smtp.html). + +>**Note:** +Some cloud providers restrict emails being sent out on SMTP, so you will have +to use a SMTP service that is supported by your provider. See this +[Google Cloud Platform page](https://cloud.google.com/compute/docs/tutorials/sending-mail/) +as and example. + +Here is an example configuration for Mailgun SMTP support: + +```yaml +omnibusConfigRuby: | + # This is example config of what you may already have in your omnibusConfigRuby object + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; + + # SMTP settings + gitlab_rails['smtp_enable'] = true + gitlab_rails['smtp_address'] = "smtp.mailgun.org" + gitlab_rails['smtp_port'] = 2525 # High port needed for Google Cloud + gitlab_rails['smtp_authentication'] = "plain" + gitlab_rails['smtp_enable_starttls_auto'] = false + gitlab_rails['smtp_user_name'] = "postmaster@mg.your-mail-domain" + gitlab_rails['smtp_password'] = "you-password" + gitlab_rails['smtp_domain'] = "mg.your-mail-domain" +``` + +### HTTPS configuration + +To setup HTTPS access to your GitLab server, first you need to configure the +chart to use the [ingress](#ingress-routing). + +GitLab's config should be updated to support [proxied SSL](https://docs.gitlab.com/omnibus/settings/nginx.html#supporting-proxied-ssl). + +In addition to having a Ingress Controller deployed and the basic ingress +settings configured, you will also need to specify in the ingress settings +which hosts to use HTTPS for. + +Make sure `externalUrl` now includes `https://` instead of `http://` in its +value, and update the `omnibusConfigRuby` section: + +```yaml +externalUrl: 'https://gitlab.example.com' + +omnibusConfigRuby: | + # This is example config of what you may already have in your omnibusConfigRuby object + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; + + # These are the settings needed to support proxied SSL + nginx['listen_port'] = 80 + nginx['listen_https'] = false + nginx['proxy_set_headers'] = { + "X-Forwarded-Proto" => "https", + "X-Forwarded-Ssl" => "on" + } + +ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + # kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt support + + hosts: + - gitlab.example.com + + ## gitlab Ingress TLS configuration + ## Secrets must be created in the namespace, and is not done for you in this chart + ## + tls: + - secretName: gitlab-tls + hosts: + - gitlab.example.com +``` + +You will need to create the named secret in your cluster, specifying the private +and public certificate pair using the format outlined in the +[ingress documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/#tls). + +Alternatively, you can use the `kubernetes.io/tls-acme` annotation, and install +the `kube-lego` chart to your cluster to have Let's Encrypt issue your +certificate. See the [kube-lego documentation](https://github.com/kubernetes/charts/blob/master/stable/kube-lego/README.md) +for more information. + +### Enabling the GitLab Container Registry + +The GitLab Registry is disabled by default but can be enabled by providing an +external URL for it in the configuration. In order for the Registry to be easily +used by GitLab CI and your Kubernetes cluster, you will need to set it up with +a TLS certificate, so these examples will include the ingress settings for that +as well. See the [HTTPS Configuration section](#https-configuration) +for more explanation on some of these settings. + +Example config: + +```yaml +externalUrl: 'https://gitlab.example.com' + +omnibusConfigRuby: | + # This is example config of what you may already have in your omnibusConfigRuby object + unicorn['worker_processes'] = 2; + gitlab_rails['trusted_proxies'] = ["10.0.0.0/8","172.16.0.0/12","192.168.0.0/16"]; + + registry_external_url 'https://registry.example.com'; + + # These are the settings needed to support proxied SSL + nginx['listen_port'] = 80 + nginx['listen_https'] = false + nginx['proxy_set_headers'] = { + "X-Forwarded-Proto" => "https", + "X-Forwarded-Ssl" => "on" + } + registry_nginx['listen_port'] = 80 + registry_nginx['listen_https'] = false + registry_nginx['proxy_set_headers'] = { + "X-Forwarded-Proto" => "https", + "X-Forwarded-Ssl" => "on" + } + +ingress: + enabled: true + annotations: + kubernetes.io/ingress.class: nginx + # kubernetes.io/tls-acme: 'true' Annotation used for letsencrypt support + + hosts: + - gitlab.example.com + - registry.example.com + + ## gitlab Ingress TLS configuration + ## Secrets must be created in the namespace, and is not done for you in this chart + ## + tls: + - secretName: gitlab-tls + hosts: + - gitlab.example.com + - registry.example.com +``` + +## Installing GitLab using the Helm Chart + +Once you [have configured](#configuration) GitLab in your `values.yml` file, +run the following: + +```bash +helm install --namespace <NAMESPACE> --name gitlab -f <CONFIG_VALUES_FILE> gitlab/gitlab +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where you want to install GitLab. +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom + configuration. See the [Configuration](#configuration) section to create it. + +## Updating GitLab using the Helm Chart + +Once your GitLab Chart is installed, configuration changes and chart updates +should we done using `helm upgrade` + +```bash +helm upgrade --namespace <NAMESPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where GitLab is installed. +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom + [configuration] (#configuration). +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab`. + +## Uninstalling GitLab using the Helm Chart + +To uninstall the GitLab Chart, run the following: + +```bash +helm delete --namespace <NAMESPACE> <RELEASE-NAME> +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where GitLab is installed. +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab`. + +[kube-srv]: https://kubernetes.io/docs/concepts/services-networking/service/#publishing-services---service-types +[storageclass]: https://kubernetes.io/docs/concepts/storage/persistent-volumes/#storageclasses diff --git a/doc/install/kubernetes/gitlab_runner_chart.md b/doc/install/kubernetes/gitlab_runner_chart.md new file mode 100644 index 00000000000..dbd9ae3f70c --- /dev/null +++ b/doc/install/kubernetes/gitlab_runner_chart.md @@ -0,0 +1,175 @@ +# GitLab Runner Helm Chart + +The `gitlab-runner` Helm chart deploys a GitLab Runner instance into your +Kubernetes cluster. + +This chart configures the Runner to: + +- Run using the GitLab Runner [Kubernetes executor](https://docs.gitlab.com/runner/install/kubernetes.html) +- For each new job it receives from [GitLab CI](https://about.gitlab.com/features/gitlab-ci-cd/), it will provision a + new pod within the specified namespace to run it. + +## Prerequisites + +- Your GitLab Server's API is reachable from the cluster +- Kubernetes 1.4+ with Beta APIs enabled +- The `kubectl` CLI installed locally and authenticated for the cluster +- The Helm Client installed locally +- The Helm Server (Tiller) already installed and running in the cluster, by running `helm init` +- The GitLab Helm Repo added to your Helm Client. See [Adding GitLab Helm Repo](index.md#add-the-gitlab-helm-repository) + +## Configuring GitLab Runner using the Helm Chart + +Create a `values.yaml` file for your GitLab Runner configuration. See [Helm docs](https://github.com/kubernetes/helm/blob/master/docs/chart_template_guide/values_files.md) +for information on how your values file will override the defaults. + +The default configuration can always be found in the [values.yaml](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-runner/values.yaml) in the chart repository. + +### Required configuration + +In order for GitLab Runner to function, your config file **must** specify the following: + + - `gitlabURL` - the GitLab Server URL (with protocol) to register the runner against + - `runnerRegistrationToken` - The Registration Token for adding new Runners to the GitLab Server. This must be + retrieved from your GitLab Instance. See the [GitLab Runner Documentation](../../ci/runners/README.md#creating-and-registering-a-runner) for more information. + +### Other configuration + +The rest of the configuration is [documented in the `values.yaml`](https://gitlab.com/charts/charts.gitlab.io/blob/master/charts/gitlab-runner/values.yaml) in the chart repository. + +Here is a snippet of the important settings: + +```yaml +## The GitLab Server URL (with protocol) that want to register the runner against +## ref: https://docs.gitlab.com/runner/commands/README.html#gitlab-runner-register +## +gitlabURL: http://gitlab.your-domain.com/ + +## The Registration Token for adding new Runners to the GitLab Server. This must +## be retreived from your GitLab Instance. +## ref: https://docs.gitlab.com/ce/ci/runners/README.html#creating-and-registering-a-runner +## +runnerRegistrationToken: "" + +## Configure the maximum number of concurrent jobs +## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section +## +concurrent: 10 + +## Defines in seconds how often to check GitLab for a new builds +## ref: https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-global-section +## +checkInterval: 30 + +## Configuration for the Pods that that the runner launches for each new job +## +runners: + ## Default container image to use for builds when none is specified + ## + image: ubuntu:16.04 + + ## Run all containers with the privileged flag enabled + ## This will allow the docker:dind image to run if you need to run Docker + ## commands. Please read the docs before turning this on: + ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind + ## + privileged: false + + ## Namespace to run Kubernetes jobs in (defaults to 'default') + ## + # namespace: + + ## Build Container specific configuration + ## + builds: + # cpuLimit: 200m + # memoryLimit: 256Mi + cpuRequests: 100m + memoryRequests: 128Mi + + ## Service Container specific configuration + ## + services: + # cpuLimit: 200m + # memoryLimit: 256Mi + cpuRequests: 100m + memoryRequests: 128Mi + + ## Helper Container specific configuration + ## + helpers: + # cpuLimit: 200m + # memoryLimit: 256Mi + cpuRequests: 100m + memoryRequests: 128Mi + +``` + +### Running Docker-in-Docker containers with GitLab Runners + +See [Running Privileged Containers for the Runners](#running-privileged-containers-for-the-runners) for how to enable it, +and the [GitLab CI Runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds) on running dind. + +### Running privileged containers for the Runners + +You can tell the GitLab Runner to run using privileged containers. You may need +this enabled if you need to use the Docker executable within your GitLab CI jobs. + +This comes with several risks that you can read about in the +[GitLab CI Runner documentation](https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-in-your-builds). + +If you are okay with the risks, and your GitLab CI Runner instance is registered +against a specific project in GitLab that you trust the CI jobs of, you can +enable privileged mode in `values.yaml`: + +```yaml +runners: + ## Run all containers with the privileged flag enabled + ## This will allow the docker:dind image to run if you need to run Docker + ## commands. Please read the docs before turning this on: + ## ref: https://docs.gitlab.com/runner/executors/kubernetes.html#using-docker-dind + ## + privileged: true +``` + +## Installing GitLab Runner using the Helm Chart + +Once you [have configured](#configuration) GitLab Runner in your `values.yml` file, +run the following: + +```bash +helm install --namepace <NAMEPACE> --name gitlab-runner -f <CONFIG_VALUES_FILE> gitlab/gitlab-runner +``` + +- `<NAMESPACE>` is the Kubernetes namespace where you want to install the GitLab Runner. +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the + [Configuration](#configuration) section to create it. + +## Updating GitLab Runner using the Helm Chart + +Once your GitLab Runner Chart is installed, configuration changes and chart updates should we done using `helm upgrade` + +```bash +helm upgrade --namepace <NAMEPACE> -f <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner +``` + +Where: +- `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed +- `<CONFIG_VALUES_FILE>` is the path to values file containing your custom configuration. See the + [Configuration](#configuration) section to create it. +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab-runner`. + +## Uninstalling GitLab Runner using the Helm Chart + +To uninstall the GitLab Runner Chart, run the following: + +```bash +helm delete --namespace <NAMESPACE> <RELEASE-NAME> +``` + +where: + +- `<NAMESPACE>` is the Kubernetes namespace where GitLab Runner is installed +- `<RELEASE-NAME>` is the name you gave the chart when installing it. + In the [Install section](#installing) we called it `gitlab-runner`. diff --git a/doc/install/kubernetes/index.md b/doc/install/kubernetes/index.md new file mode 100644 index 00000000000..cae5837a12b --- /dev/null +++ b/doc/install/kubernetes/index.md @@ -0,0 +1,46 @@ +# Installing GitLab in Kubernetes +> Officially supported cloud providers are Google Container Service and Azure Container Service. +> Officially supported schedulers are Kubernetes and Terraform. + +The easiest method to deploy GitLab in [Kubernetes](https://kubernetes.io/) is +to take advantage of the official GitLab Helm charts. [Helm] is a package +management tool for Kubernetes, allowing apps to be easily managed via their +Charts. A [Chart] is a detailed description of the application including how it +should be deployed, upgraded, and configured. + +The GitLab Helm repository is located at https://charts.gitlab.io. +You can report any issues related to GitLab's Helm Charts at +https://gitlab.com/charts/charts.gitlab.io/issues. +Contributions and improvements are also very welcome. + +## Prerequisites + +To use the charts, the Helm tool must be installed and initialized. The best +place to start is by reviewing the [Helm Quick Start Guide][helm-quick]. + +## Add the GitLab Helm repository + +Once Helm has been installed, the GitLab chart repository must be added: + +```bash +helm repo add gitlab https://charts.gitlab.io +``` + +After adding the repository, Helm must be re-initialized: + +```bash +helm init +``` + +## Using the GitLab Helm Charts + +GitLab makes available two Helm Charts, one for the GitLab server and another +for the Runner. More detailed information on installing and configuring each +Chart can be found below: + +- [Install GitLab](gitlab_chart.md) +- [Install GitLab Runner](gitlab_runner_chart.md) + +[chart]: https://github.com/kubernetes/charts +[helm-quick]: https://github.com/kubernetes/helm/blob/master/docs/quickstart.md +[helm]: https://github.com/kubernetes/helm/blob/master/README.md diff --git a/doc/install/requirements.md b/doc/install/requirements.md index 7b586138f42..2e456557d77 100644 --- a/doc/install/requirements.md +++ b/doc/install/requirements.md @@ -122,13 +122,26 @@ To change the Unicorn workers when you have the Omnibus package please see [the We currently support the following databases: -- PostgreSQL (recommended) +- PostgreSQL - MySQL/MariaDB -If you want to run the database separately, expect a size of about 1 MB per user. +We _highly_ recommend the use of PostgreSQL instead of MySQL/MariaDB as not all +features of GitLab may work with MySQL/MariaDB. For example, MySQL does not have +the right features to support nested groups in an efficient manner; see +<https://gitlab.com/gitlab-org/gitlab-ce/issues/30472> for more information +about this. Existing users using GitLab with MySQL/MariaDB are advised to +migrate to PostgreSQL instead. + +The server running the database should have _at least_ 5-10 GB of storage +available, though the exact requirements depend on the size of the GitLab +installation (e.g. the number of users, projects, etc). ### PostgreSQL Requirements +As of GitLab 9.0, PostgreSQL 9.2 or newer is required, and earlier versions are +not supported. We highly recommend users to use at least PostgreSQL 9.6 as this +is the PostgreSQL version used for development and testing. + Users using PostgreSQL must ensure the `pg_trgm` extension is loaded into every GitLab database. This extension can be enabled (using a PostgreSQL super user) by running the following query for every database: @@ -162,4 +175,4 @@ about it, check the [Prometheus documentation](../administration/monitoring/prom We support the current and the previous major release of Firefox, Chrome/Chromium, Safari and Microsoft browsers (Microsoft Edge and Internet Explorer 11). -Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version.
\ No newline at end of file +Each time a new browser version is released, we begin supporting that version and stop supporting the third most recent version. diff --git a/doc/integration/chat_commands.md b/doc/integration/chat_commands.md index 4b0084678d9..c878dc7e650 100644 --- a/doc/integration/chat_commands.md +++ b/doc/integration/chat_commands.md @@ -1,14 +1,14 @@ # Chat Commands -Chat commands allow user to perform common operations on GitLab right from there chat client. -Right now both Mattermost and Slack are supported. +Chat commands in Mattermost and Slack (also called Slack slash commands) allow you to control GitLab and view GitLab content right inside your chat client, without having to leave it. For Slack, this requires a [project service configuration](../user/project/integrations/slack_slash_commands.md). Simply type the command as a message in your chat client to activate it. -## Available commands +Commands are scoped to a project, with a trigger term that is specified during configuration. (We suggest you use the project name as the trigger term for simplicty and clarity.) Taking the trigger term as `project-name`, the commands are: -The trigger is configurable, but for the sake of this example, we'll use `/trigger` -* `/trigger help` - Displays all available commands for this user -* `/trigger issue new <title> <shift+return> <description>` - creates a new issue on the project -* `/trigger issue show <id>` - Shows the issue with the given ID, if you've got access -* `/trigger issue search <query>` - Shows a maximum of 5 items matching the query -* `/trigger deploy <from> to <to>` - Deploy from an environment to another +| Command | Effect | +| ------- | ------ | +| `/project-name help` | Shows all available chat commands | +| `/project-name issue new <title> <shift+return> <description>` | Creates a new issue with title `<title>` and description `<description>` | +| `/project-name issue show <id>` | Shows the issue with id `<id>` | +| `/project-name issue search <query>` | Shows up to 5 issues matching `<query>` | +| `/project-name deploy <from> to <to>` | Deploy from the `<from>` environment to the `<to>` environment |
\ No newline at end of file diff --git a/doc/integration/github.md b/doc/integration/github.md index 4b0d33334bd..de9aedbc596 100644 --- a/doc/integration/github.md +++ b/doc/integration/github.md @@ -103,12 +103,54 @@ GitHub will generate an application ID and secret key for you to use. 1. Save the configuration file. -1. [Reconfigure][] or [restart GitLab][] for the changes to take effect if you +1. [Reconfigure GitLab][] or [restart GitLab][] for the changes to take effect if you installed GitLab via Omnibus or from source respectively. On the sign in page there should now be a GitHub icon below the regular sign in form. Click the icon to begin the authentication process. GitHub will ask the user to sign in and authorize the GitLab application. If everything goes well the user will be returned to GitLab and will be signed in. -[reconfigure]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure +### GitHub Enterprise with Self-Signed Certificate + +If you are attempting to import projects from GitHub Enterprise with a self-signed +certificate and the imports are failing, you will need to disable SSL verification. +It should be disabled by adding `verify_ssl` to `false` to the provider configuration. + +For omnibus package: + +```ruby + gitlab_rails['omniauth_providers'] = [ + { + "name" => "github", + "app_id" => "YOUR_APP_ID", + "app_secret" => "YOUR_APP_SECRET", + "url" => "https://github.com/", + "verify_ssl" => false, + "args" => { "scope" => "user:email" } + } + ] +``` + +For installation from source: + +``` + - { name: 'github', app_id: 'YOUR_APP_ID', + app_secret: 'YOUR_APP_SECRET', + url: "https://github.example.com/", + verify_ssl: false, + args: { scope: 'user:email' } } +``` + + +For the changes to take effect, [reconfigure Gitlab] if you installed +via Omnibus, or [restart GitLab] if you installed from source. + +You will also need to disable Git SSL verification on the server hosting GitLab with the following command: + +``` +$ git config --global http.sslVerify false +``` +[reconfigure GitLab]: ../administration/restart_gitlab.md#omnibus-gitlab-reconfigure [restart GitLab]: ../administration/restart_gitlab.md#installations-from-source + + diff --git a/doc/intro/README.md b/doc/intro/README.md index 1df6a52ce8a..7485912d1a2 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -11,9 +11,9 @@ Create projects and groups. Create issues, labels, milestones, cast your vote, and review issues. -- [Create a new issue](../gitlab-basics/create-issue.md) +- [Create a new issue](../user/project/issues/index.md#new-issue) - [Assign labels to issues](../user/project/labels.md) -- [Use milestones as an overview of your project's tracker](../workflow/milestones.md) +- [Use milestones as an overview of your project's tracker](../user/project/milestones/index.md) - [Use voting to express your like/dislike to issues and merge requests](../workflow/award_emoji.md) ## Collaborate diff --git a/doc/migrate_ci_to_ce/README.md b/doc/migrate_ci_to_ce/README.md index 8f9ef054949..2e7782736ff 100644 --- a/doc/migrate_ci_to_ce/README.md +++ b/doc/migrate_ci_to_ce/README.md @@ -1,4 +1,4 @@ -## Migrate GitLab CI to GitLab CE or EE +# Migrate GitLab CI to GitLab CE or EE Beginning with version 8.0 of GitLab Community Edition (CE) and Enterprise Edition (EE), GitLab CI is no longer its own application, but is instead built @@ -12,7 +12,7 @@ is not possible.** We recommend that you read through the entire migration process in this document before beginning. -### Overview +## Overview In this document we assume you have a GitLab server and a GitLab CI server. It does not matter if these are the same machine. @@ -26,7 +26,7 @@ can be online for most of the procedure; the only GitLab downtime (if any) is during the upgrade to 8.0. Your CI service will be offline from the moment you upgrade to 8.0 until you finish the migration procedure. -### Before upgrading +## Before upgrading If you have GitLab CI installed using omnibus-gitlab packages but **you don't want to migrate your existing data**: @@ -38,12 +38,12 @@ run `sudo gitlab-ctl reconfigure` and you can reach CI at `gitlab.example.com/ci If you want to migrate your existing data, continue reading. -#### 0. Updating Omnibus from versions prior to 7.13 +### 0. Updating Omnibus from versions prior to 7.13 If you are updating from older versions you should first update to 7.14 and then to 8.0. Otherwise it's pretty likely that you will encounter problems described in the [Troubleshooting](#troubleshooting). -#### 1. Verify that backups work +### 1. Verify that backups work Make sure that the backup script on both servers can connect to the database. @@ -73,7 +73,7 @@ sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production SKIP=r If this fails you need to fix it before upgrading to 8.0. Also see https://about.gitlab.com/getting-help/ -#### 2. Check source and target database types +### 2. Check source and target database types Check what databases you use on your GitLab server and your CI server. Look for the 'adapter:' line. If your CI server and your GitLab server use @@ -102,7 +102,7 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production ``` -#### 3. Storage planning +### 3. Storage planning Decide where to store CI build traces on GitLab server. GitLab CI uses files on disk to store CI build traces. The default path for these build @@ -111,34 +111,34 @@ traces is `/var/opt/gitlab/gitlab-ci/builds` (Omnibus) or a special location, or if you are using NFS, you should make sure that you store build traces on the same storage as your Git repositories. -### I. Upgrading +## I. Upgrading From this point on, GitLab CI will be unavailable for your end users. -#### 1. Upgrade GitLab to 8.0 +### 1. Upgrade GitLab to 8.0 First upgrade your GitLab server to version 8.0: https://about.gitlab.com/update/ -#### 2. Disable CI on the GitLab server during the migration +### 2. Disable CI on the GitLab server during the migration After you update, go to the admin panel and temporarily disable CI. As an administrator, go to **Admin Area** -> **Settings**, and under **Continuous Integration** uncheck **Disable to prevent CI usage until rake ci:migrate is run (8.0 only)**. -#### 3. CI settings are now in GitLab +### 3. CI settings are now in GitLab If you want to use custom CI settings (e.g. change where builds are stored), please update `/etc/gitlab/gitlab.rb` (Omnibus) or `/home/git/gitlab/config/gitlab.yml` (Source). -#### 4. Upgrade GitLab CI to 8.0 +### 4. Upgrade GitLab CI to 8.0 Now upgrade GitLab CI to version 8.0. If you are using Omnibus packages, this may have already happened when you upgraded GitLab to 8.0. -#### 5. Disable GitLab CI on the CI server +### 5. Disable GitLab CI on the CI server Disable GitLab CI after upgrading to 8.0. @@ -154,9 +154,9 @@ cd /home/gitlab_ci/gitlab-ci sudo -u gitlab_ci -H bundle exec whenever --clear-crontab RAILS_ENV=production ``` -### II. Moving data +## II. Moving data -#### 1. Database encryption key +### 1. Database encryption key Move the database encryption key from your CI server to your GitLab server. The command below will show you what you need to copy-paste to your @@ -174,7 +174,7 @@ cd /home/gitlab_ci/gitlab-ci sudo -u gitlab_ci -H bundle exec rake backup:show_secrets RAILS_ENV=production ``` -#### 2. SQL data and build traces +### 2. SQL data and build traces Create your final CI data export. If you are converting from MySQL to PostgreSQL, add ` MYSQL_TO_POSTGRESQL=1` to the end of the rake command. When @@ -192,7 +192,7 @@ cd /home/gitlab_ci/gitlab-ci sudo -u gitlab_ci -H bundle exec rake backup:create RAILS_ENV=production ``` -#### 3. Copy data to the GitLab server +### 3. Copy data to the GitLab server If you were running GitLab and GitLab CI on the same server you can skip this step. @@ -209,7 +209,7 @@ ssh -A ci_admin@ci_server.example scp /path/to/12345_gitlab_ci_backup.tar gitlab_admin@gitlab_server.example:~ ``` -#### 4. Move data to the GitLab backups folder +### 4. Move data to the GitLab backups folder Make the CI data archive discoverable for GitLab. We assume below that you store backups in the default path, adjust the command if necessary. @@ -223,7 +223,7 @@ sudo mv /path/to/12345_gitlab_ci_backup.tar /var/opt/gitlab/backups/ sudo mv /path/to/12345_gitlab_ci_backup.tar /home/git/gitlab/tmp/backups/ ``` -#### 5. Import the CI data into GitLab. +### 5. Import the CI data into GitLab. This step will delete any existing CI data on your GitLab server. There should be no CI data yet because you turned CI on the GitLab server off earlier. @@ -239,7 +239,7 @@ cd /home/git/gitlab sudo -u git -H bundle exec rake ci:migrate RAILS_ENV=production ``` -#### 6. Restart GitLab +### 6. Restart GitLab ``` # On your GitLab server: @@ -251,7 +251,7 @@ sudo gitlab-ctl restart sidekiq sudo service gitlab reload ``` -### III. Redirecting traffic +## III. Redirecting traffic If you were running GitLab CI with Omnibus packages and you were using the internal NGINX configuration your CI service should now be available both at @@ -261,7 +261,7 @@ If you installed GitLab CI from source we now need to configure a redirect in NGINX so that existing CI runners can keep using the old CI server address, and so that existing links to your CI server keep working. -#### 1. Update Nginx configuration +### 1. Update Nginx configuration To ensure that your existing CI runners are able to communicate with the migrated installation, and that existing build triggers still work, you'll need @@ -317,22 +317,22 @@ You should also make sure that you can: 1. `curl https://YOUR_GITLAB_SERVER_FQDN/` from your previous GitLab CI server. 1. `curl https://YOUR_CI_SERVER_FQDN/` from your GitLab CE (or EE) server. -#### 2. Check Nginx configuration +### 2. Check Nginx configuration sudo nginx -t -#### 3. Restart Nginx +### 3. Restart Nginx sudo /etc/init.d/nginx restart -#### Restore from backup +### Restore from backup If something went wrong and you need to restore a backup, consult the [Backup restoration](../raketasks/backup_restore.md) guide. -### Troubleshooting +## Troubleshooting -#### show:secrets problem (Omnibus-only) +### show:secrets problem (Omnibus-only) If you see errors like this: ``` Missing `secret_key_base` or `db_key_base` for 'production' environment. The secrets will be generated and stored in `config/secrets.yml` @@ -343,7 +343,7 @@ Errno::EACCES: Permission denied @ rb_sysopen - config/secrets.yml This can happen if you are updating from versions prior to 7.13 straight to 8.0. The fix for this is to update to Omnibus 7.14 first and then update it to 8.0. -#### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds +### Permission denied when accessing /var/opt/gitlab/gitlab-ci/builds To fix that issue you have to change builds/ folder permission before doing final backup: ``` sudo chown -R gitlab-ci:gitlab-ci /var/opt/gitlab/gitlab-ci/builds @@ -354,7 +354,7 @@ Then before executing `ci:migrate` you need to fix builds folder permission: sudo chown git:git /var/opt/gitlab/gitlab-ci/builds ``` -#### Problems when importing CI database to GitLab +### Problems when importing CI database to GitLab If you were migrating CI database from MySQL to PostgreSQL manually you can see errors during import about missing sequences: ``` ALTER SEQUENCE diff --git a/doc/profile/README.md b/doc/profile/README.md index 54e44d65959..aed64ac1228 100644 --- a/doc/profile/README.md +++ b/doc/profile/README.md @@ -2,3 +2,4 @@ - [Preferences](../user/profile/preferences.md) - [Two-factor Authentication (2FA)](../user/profile/account/two_factor_authentication.md) +- [Deleting your account](../user/profile/account/delete_account.md) diff --git a/doc/raketasks/backup_restore.md b/doc/raketasks/backup_restore.md index 65fcfc77ab1..5be6053b76e 100644 --- a/doc/raketasks/backup_restore.md +++ b/doc/raketasks/backup_restore.md @@ -1,39 +1,52 @@ -# Backup restore +# Backing up and restoring GitLab  An application data backup creates an archive file that contains the database, all repositories and all attachments. -This archive will be saved in `backup_path`, which is specified in the -`config/gitlab.yml` file. -The filename will be `[TIMESTAMP]_gitlab_backup.tar`, where `TIMESTAMP` -identifies the time at which each backup was created. - -> In GitLab 8.15 we changed the timestamp format from `EPOCH` (`1393513186`) -> to `EPOCH_YYYY_MM_DD` (`1393513186_2014_02_27`) -You can only restore a backup to exactly the same version of GitLab on which it -was created. The best way to migrate your repositories from one server to +You can only restore a backup to **exactly the same version** of GitLab on which +it was created. The best way to migrate your repositories from one server to another is through backup restore. -To restore a backup, you will also need to restore `/etc/gitlab/gitlab-secrets.json` -(for omnibus packages) or `/home/git/gitlab/.secret` (for installations -from source). This file contains the database encryption key and CI secret -variables used for two-factor authentication. If you fail to restore this -encryption key file along with the application data backup, users with two-factor -authentication enabled will lose access to your GitLab server. +## Backup + +GitLab provides a simple command line interface to backup your whole installation, +and is flexible enough to fit your needs. + +### Backup timestamp + +>**Note:** +In GitLab 9.2 the timestamp format was changed from `EPOCH_YYYY_MM_DD` to +`EPOCH_YYYY_MM_DD_GitLab version`, for example `1493107454_2017_04_25` +would become `1493107454_2017_04_25_9.1.0`. + +The backup archive will be saved in `backup_path`, which is specified in the +`config/gitlab.yml` file. +The filename will be `[TIMESTAMP]_gitlab_backup.tar`, where `TIMESTAMP` +identifies the time at which each backup was created, plus the GitLab version. +The timestamp is needed if you need to restore GitLab and multiple backups are +available. + +For example, if the backup name is `1493107454_2017_04_25_9.1.0_gitlab_backup.tar`, +then the timestamp is `1493107454_2017_04_25_9.1.0`. -## Create a backup of the GitLab system +### Creating a backup of the GitLab system Use this command if you've installed GitLab with the Omnibus package: + ``` sudo gitlab-rake gitlab:backup:create ``` + Use this if you've installed GitLab from source: + ``` sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production ``` + If you are running GitLab within a Docker container, you can run the backup from the host: + ``` docker exec -t <container name> gitlab-rake gitlab:backup:create ``` @@ -67,9 +80,9 @@ Deleting tmp directories...[DONE] Deleting old backups... [SKIPPING] ``` -## Backup Strategy Option +### Backup strategy option -> **Note:** Introduced as an option in 8.17 +> **Note:** Introduced as an option in GitLab 8.17. The default backup strategy is to essentially stream data from the respective data locations to the backup using the Linux command `tar` and `gzip`. This works @@ -89,7 +102,7 @@ To use the `copy` strategy instead of the default streaming strategy, specify `STRATEGY=copy` in the Rake task command. For example, `sudo gitlab-rake gitlab:backup:create STRATEGY=copy`. -## Exclude specific directories from the backup +### Excluding specific directories from the backup You can choose what should be backed up by adding the environment variable `SKIP`. The available options are: @@ -113,7 +126,7 @@ sudo gitlab-rake gitlab:backup:create SKIP=db,uploads sudo -u git -H bundle exec rake gitlab:backup:create SKIP=db,uploads RAILS_ENV=production ``` -## Upload backups to remote (cloud) storage +### Uploading backups to a remote (cloud) storage Starting with GitLab 7.4 you can let the backup script upload the '.tar' file it creates. It uses the [Fog library](http://fog.io/) to perform the upload. @@ -257,7 +270,7 @@ For installations from source: remote_directory: 'gitlab_backups' ``` -## Backup archive permissions +### Backup archive permissions The backup archives created by GitLab (`1393513186_2014_02_27_gitlab_backup.tar`) will have owner/group git:git and 0600 permissions by default. @@ -275,11 +288,11 @@ gitlab_rails['backup_archive_permissions'] = 0644 # Makes the backup archives wo archive_permissions: 0644 # Makes the backup archives world-readable ``` -## Storing configuration files +### Storing configuration files Please be informed that a backup does not store your configuration -files. One reason for this is that your database contains encrypted -information for two-factor authentication. Storing encrypted +files. One reason for this is that your database contains encrypted +information for two-factor authentication. Storing encrypted information along with its key in the same place defeats the purpose of using encryption in the first place! @@ -292,11 +305,74 @@ At the very **minimum** you should backup `/etc/gitlab/gitlab.rb` and `/home/git/gitlab/config/secrets.yml` (source) to preserve your database encryption key. -## Restore a previously created backup +### Configuring cron to make daily backups -You can only restore a backup to exactly the same version of GitLab that you created it on, for example 7.2.1. +>**Note:** +The following cron jobs do not [backup your GitLab configuration files](#storing-configuration-files) +or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). -### Prerequisites +**For Omnibus installations** + +To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: + +``` +sudo su - +crontab -e +``` + +There, add the following line to schedule the backup for everyday at 2 AM: + +``` +0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1 +``` + +You may also want to set a limited lifetime for backups to prevent regular +backups using all your disk space. To do this add the following lines to +`/etc/gitlab/gitlab.rb` and reconfigure: + +``` +# limit backup lifetime to 7 days - 604800 seconds +gitlab_rails['backup_keep_time'] = 604800 +``` + +Note that the `backup_keep_time` configuration option only manages local +files. GitLab does not automatically prune old files stored in a third-party +object storage (e.g., AWS S3) because the user may not have permission to list +and delete files. We recommend that you configure the appropriate retention +policy for your object storage. For example, you can configure [the S3 backup +policy as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). + +**For installation from source** + +``` +cd /home/git/gitlab +sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups +sudo -u git crontab -e # Edit the crontab for the git user +``` + +Add the following lines at the bottom: + +``` +# Create a full backup of the GitLab repositories and SQL database every day at 4am +0 4 * * * cd /home/git/gitlab && PATH=/usr/local/bin:/usr/bin:/bin bundle exec rake gitlab:backup:create RAILS_ENV=production CRON=1 +``` + +The `CRON=1` environment setting tells the backup script to suppress all progress output if there are no errors. +This is recommended to reduce cron spam. + +## Restore + +GitLab provides a simple command line interface to backup your whole installation, +and is flexible enough to fit your needs. + +The [restore prerequisites section](#restore-prerequisites) includes crucial +information. Make sure to read and test the whole restore process at least once +before attempting to perform it in a production environment. + +You can only restore a backup to **exactly the same version** of GitLab that +you created it on, for example 9.1.0. + +### Restore prerequisites You need to have a working GitLab installation before you can perform a restore. This is mainly because the system user performing the @@ -305,13 +381,23 @@ the SQL database it needs to import data into ('gitlabhq_production'). All existing data will be either erased (SQL) or moved to a separate directory (repositories, uploads). -If some or all of your GitLab users are using two-factor authentication (2FA) -then you must also make sure to restore `/etc/gitlab/gitlab.rb` and -`/etc/gitlab/gitlab-secrets.json` (Omnibus), or -`/home/git/gitlab/config/secrets.yml` (installations from source). Note that you -need to run `gitlab-ctl reconfigure` after changing `gitlab-secrets.json`. +To restore a backup, you will also need to restore `/etc/gitlab/gitlab-secrets.json` +(for Omnibus packages) or `/home/git/gitlab/.secret` (for installations +from source). This file contains the database encryption key, +[CI secret variables](../ci/variables/README.md#secret-variables), and +secret variables used for [two-factor authentication](../user/profile/account/two_factor_authentication.md). +If you fail to restore this encryption key file along with the application data +backup, users with two-factor authentication enabled and GitLab Runners will +lose access to your GitLab server. + +Depending on your case, you might want to run the restore command with one or +more of the following options: + +- `BACKUP=timestamp_of_backup` - Required if more than one backup exists. + Read what the [backup timestamp is about](#backup-timestamp). +- `force=yes` - Do not ask if the authorized_keys file should get regenerated. -### Installation from source +### Restore for installation from source ``` # Stop processes that are connected to the database @@ -320,13 +406,6 @@ sudo service gitlab stop bundle exec rake gitlab:backup:restore RAILS_ENV=production ``` -Options: - -``` -BACKUP=timestamp_of_backup (required if more than one backup exists) -force=yes (do not ask if the authorized_keys file should get regenerated) -``` - Example output: ``` @@ -358,13 +437,13 @@ Restoring repositories: Deleting tmp directories...[DONE] ``` -### Omnibus installations +### Restore for Omnibus installations This procedure assumes that: -- You have installed the exact same version of GitLab Omnibus with which the - backup was created -- You have run `sudo gitlab-ctl reconfigure` at least once +- You have installed the **exact same version** of GitLab Omnibus with which the + backup was created. +- You have run `sudo gitlab-ctl reconfigure` at least once. - GitLab is running. If not, start it using `sudo gitlab-ctl start`. First make sure your backup tar file is in the backup directory described in the @@ -372,7 +451,7 @@ First make sure your backup tar file is in the backup directory described in the `/var/opt/gitlab/backups`. ```shell -sudo cp 1393513186_2014_02_27_gitlab_backup.tar /var/opt/gitlab/backups/ +sudo cp 1493107454_2017_04_25_9.1.0_gitlab_backup.tar /var/opt/gitlab/backups/ ``` Stop the processes that are connected to the database. Leave the rest of GitLab @@ -390,7 +469,7 @@ restore: ```shell # This command will overwrite the contents of your GitLab database! -sudo gitlab-rake gitlab:backup:restore BACKUP=1393513186_2014_02_27 +sudo gitlab-rake gitlab:backup:restore BACKUP=1493107454_2017_04_25_9.1.0 ``` Restart and check GitLab: @@ -402,59 +481,7 @@ sudo gitlab-rake gitlab:check SANITIZE=true If there is a GitLab version mismatch between your backup tar file and the installed version of GitLab, the restore command will abort with an error. Install the -[correct GitLab version](https://about.gitlab.com/downloads/archives/) and try again. - -## Configure cron to make daily backups - -### For installation from source: -``` -cd /home/git/gitlab -sudo -u git -H editor config/gitlab.yml # Enable keep_time in the backup section to automatically delete old backups -sudo -u git crontab -e # Edit the crontab for the git user -``` - -Add the following lines at the bottom: - -``` -# Create a full backup of the GitLab repositories and SQL database every day at 4am -0 4 * * * cd /home/git/gitlab && PATH=/usr/local/bin:/usr/bin:/bin bundle exec rake gitlab:backup:create RAILS_ENV=production CRON=1 -``` - -The `CRON=1` environment setting tells the backup script to suppress all progress output if there are no errors. -This is recommended to reduce cron spam. - -### For omnibus installations - -To schedule a cron job that backs up your repositories and GitLab metadata, use the root user: - -``` -sudo su - -crontab -e -``` - -There, add the following line to schedule the backup for everyday at 2 AM: - -``` -0 2 * * * /opt/gitlab/bin/gitlab-rake gitlab:backup:create CRON=1 -``` - -You may also want to set a limited lifetime for backups to prevent regular -backups using all your disk space. To do this add the following lines to -`/etc/gitlab/gitlab.rb` and reconfigure: - -``` -# limit backup lifetime to 7 days - 604800 seconds -gitlab_rails['backup_keep_time'] = 604800 -``` - -Note that the `backup_keep_time` configuration option only manages local -files. GitLab does not automatically prune old files stored in a third-party -object storage (e.g. AWS S3) because the user may not have permission to list -and delete files. We recommend that you configure the appropriate retention -policy for your object storage. For example, you can configure [the S3 backup -policy here as described here](http://stackoverflow.com/questions/37553070/gitlab-omnibus-delete-backup-from-amazon-s3). - -NOTE: This cron job does not [backup your omnibus-gitlab configuration](#backup-and-restore-omnibus-gitlab-configuration) or [SSH host keys](https://superuser.com/questions/532040/copy-ssh-keys-from-one-server-to-another-server/532079#532079). +[correct GitLab version](https://packages.gitlab.com/gitlab/) and try again. ## Alternative backup strategies @@ -479,6 +506,19 @@ Example: LVM snapshots + rsync If you are running GitLab on a virtualized server you can possibly also create VM snapshots of the entire GitLab server. It is not uncommon however for a VM snapshot to require you to power down the server, so this approach is probably of limited practical use. +## Additional notes + +This documentation is for GitLab Community and Enterprise Edition. We backup +GitLab.com and make sure your data is secure, but you can't use these methods +to export / backup your data yourself from GitLab.com. + +Issues are stored in the database. They can't be stored in Git itself. + +To migrate your repositories from one server to another with an up-to-date version of +GitLab, you can use the [import rake task](import.md) to do a mass import of the +repository. Note that if you do an import rake task, rather than a backup restore, you +will have all your repositories, but not any other data. + ## Troubleshooting ### Restoring database backup using omnibus packages outputs warnings @@ -488,7 +528,6 @@ If you are using backup restore procedures you might encounter the following war psql:/var/opt/gitlab/backups/db/database.sql:22: ERROR: must be owner of extension plpgsql psql:/var/opt/gitlab/backups/db/database.sql:2931: WARNING: no privileges could be revoked for "public" (two occurrences) psql:/var/opt/gitlab/backups/db/database.sql:2933: WARNING: no privileges were granted for "public" (two occurrences) - ``` Be advised that, backup is successfully restored in spite of these warnings. @@ -497,14 +536,3 @@ The rake task runs this as the `gitlab` user which does not have the superuser a Those objects have no influence on the database backup/restore but they give this annoying warning. For more information see similar questions on postgresql issue tracker[here](http://www.postgresql.org/message-id/201110220712.30886.adrian.klaver@gmail.com) and [here](http://www.postgresql.org/message-id/2039.1177339749@sss.pgh.pa.us) as well as [stack overflow](http://stackoverflow.com/questions/4368789/error-must-be-owner-of-language-plpgsql). - -## Note -This documentation is for GitLab CE. -We backup GitLab.com and make sure your data is secure, but you can't use these methods to export / backup your data yourself from GitLab.com. - -Issues are stored in the database. They can't be stored in Git itself. - -To migrate your repositories from one server to another with an up-to-date version of -GitLab, you can use the [import rake task](import.md) to do a mass import of the -repository. Note that if you do an import rake task, rather than a backup restore, you -will have all your repositories, but not any other data. diff --git a/doc/security/img/two_factor_authentication_group_settings.png b/doc/security/img/two_factor_authentication_group_settings.png Binary files differnew file mode 100644 index 00000000000..a1b3c58bfdc --- /dev/null +++ b/doc/security/img/two_factor_authentication_group_settings.png diff --git a/doc/security/two_factor_authentication.md b/doc/security/two_factor_authentication.md index c8499380c18..f02f7b807cf 100644 --- a/doc/security/two_factor_authentication.md +++ b/doc/security/two_factor_authentication.md @@ -8,7 +8,7 @@ their phone. You can read more about it here: [Two-factor Authentication (2FA)](../profile/two_factor_authentication.md) -## Enabling 2FA +## Enforcing 2FA for all users Users on GitLab, can enable it without any admin's intervention. If you want to enforce everyone to setup 2FA, you can choose from two different ways: @@ -28,6 +28,21 @@ period to `0`. --- +## Enforcing 2FA for all users in a group + +If you want to enforce 2FA only for certain groups, you can enable it in the +group settings and specify a grace period as above. To change this setting you +need to be administrator or owner of the group. + +If there are multiple 2FA requirements (i.e. group + all users, or multiple +groups) the shortest grace period will be used. + +--- + + + +--- + ## Disabling 2FA for everyone There may be some special situations where you want to disable 2FA for everyone diff --git a/doc/system_hooks/system_hooks.md b/doc/system_hooks/system_hooks.md index ad5ffc84473..583ec5522fd 100644 --- a/doc/system_hooks/system_hooks.md +++ b/doc/system_hooks/system_hooks.md @@ -266,7 +266,8 @@ X-Gitlab-Event: System Hook ## Push events -Triggered when you push to the repository except when pushing tags. +Triggered when you push to the repository, except when pushing tags. +It generates one event per modified branch. **Request header**: @@ -332,6 +333,7 @@ X-Gitlab-Event: System Hook ## Tag events Triggered when you create (or delete) tags to the repository. +It generates one event per modified tag. **Request header**: @@ -381,3 +383,49 @@ X-Gitlab-Event: System Hook "total_commits_count": 0 } ``` +## Repository Update events + +Triggered only once when you push to the repository (including tags). + +**Request header**: + +``` +X-Gitlab-Event: System Hook +``` + +**Request body:** + +```json +{ + "event_name": "repository_update", + "user_id": 1, + "user_name": "John Smith", + "user_email": "admin@example.com", + "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", + "project_id": 1, + "project": { + "name":"Example", + "description":"", + "web_url":"http://example.com/jsmith/example", + "avatar_url":null, + "git_ssh_url":"git@example.com:jsmith/example.git", + "git_http_url":"http://example.com/jsmith/example.git", + "namespace":"Jsmith", + "visibility_level":0, + "path_with_namespace":"jsmith/example", + "default_branch":"master", + "homepage":"http://example.com/jsmith/example", + "url":"git@example.com:jsmith/example.git", + "ssh_url":"git@example.com:jsmith/example.git", + "http_url":"http://example.com/jsmith/example.git", + }, + "changes": [ + { + "before":"8205ea8d81ce0c6b90fbe8280d118cc9fdad6130", + "after":"4045ea7a3df38697b3730a20fb73c8bed8a3e69e", + "ref":"refs/heads/master" + } + ], + "refs":["refs/heads/master"] +} +``` diff --git a/doc/topics/authentication/index.md b/doc/topics/authentication/index.md new file mode 100644 index 00000000000..0c0d482499a --- /dev/null +++ b/doc/topics/authentication/index.md @@ -0,0 +1,48 @@ +# Authentication + +This page gathers all the resources for the topic **Authentication** within GitLab. + +## GitLab users + +- [SSH](../../ssh/README.md) +- [Two-Factor Authentication (2FA)](../../user/profile/account/two_factor_authentication.md#two-factor-authentication) +- **Articles:** + - [Support for Universal 2nd Factor Authentication - YubiKeys](https://about.gitlab.com/2016/06/22/gitlab-adds-support-for-u2f/) + - [Security Webcast with Yubico](https://about.gitlab.com/2016/08/31/gitlab-and-yubico-security-webcast/) +- **Integrations:** + - [GitLab as OAuth2 authentication service provider](../../integration/oauth_provider.md#introduction-to-oauth) + +## GitLab administrators + +- [LDAP (Community Edition)](../../administration/auth/ldap.md) +- [LDAP (Enterprise Edition)](https://docs.gitlab.com/ee/administration/auth/ldap-ee.html) +- [Enforce Two-factor Authentication (2FA)](../../security/two_factor_authentication.md#enforce-two-factor-authentication-2fa) +- **Articles:** + - [How to Configure LDAP with GitLab CE](../../articles/how_to_configure_ldap_gitlab_ce/index.md) + - [How to Configure LDAP with GitLab EE](https://docs.gitlab.com/ee/articles/how_to_configure_ldap_gitlab_ee/) + - [Feature Highlight: LDAP Integration](https://about.gitlab.com/2014/07/10/feature-highlight-ldap-sync/) + - [Debugging LDAP](https://about.gitlab.com/handbook/support/workflows/ldap/debugging_ldap.html) +- **Integrations:** + - [OmniAuth](../../integration/omniauth.md) + - [Authentiq OmniAuth Provider](../../administration/auth/authentiq.md#authentiq-omniauth-provider) + - [Atlassian Crowd OmniAuth Provider](../../administration/auth/crowd.md) + - [CAS OmniAuth Provider](../../integration/cas.md) + - [SAML OmniAuth Provider](../../integration/saml.md) + - [Okta SSO provider](../../administration/auth/okta.md) + - [Kerberos integration (GitLab EE)](https://docs.gitlab.com/ee/integration/kerberos.html) + +## API + +- [OAuth 2 Tokens](../../api/README.md#oauth-2-tokens) +- [Private Tokens](../../api/README.md#private-tokens) +- [Impersonation tokens](../../api/README.md#impersonation-tokens) +- [GitLab as an OAuth2 provider](../../api/oauth2.md#gitlab-as-an-oauth2-provider) +- [GitLab Runner API - Authentication](../../api/ci/runners.md#authentication) + +## Third-party resources + +- [Kanboard Plugin GitLab Authentication](https://kanboard.net/plugin/gitlab-auth) +- [Jenkins GitLab OAuth Plugin](https://wiki.jenkins-ci.org/display/JENKINS/GitLab+OAuth+Plugin) +- [Setup Gitlab CE with Active Directory authentication](https://www.caseylabs.com/setup-gitlab-ce-with-active-directory-authentication/) +- [How to customize GitLab to support OpenID authentication](http://eric.van-der-vlist.com/blog/2013/11/23/how-to-customize-gitlab-to-support-openid-authentication/) +- [Openshift - Configuring Authentication and User Agent](https://docs.openshift.org/latest/install_config/configuring_authentication.html#GitLab) diff --git a/doc/topics/git/index.md b/doc/topics/git/index.md new file mode 100644 index 00000000000..604f9375714 --- /dev/null +++ b/doc/topics/git/index.md @@ -0,0 +1,66 @@ +# Git documentation + +Git is a [free and open source](https://git-scm.com/about/free-and-open-source) +distributed version control system designed to handle everything from small to +very large projects with speed and efficiency. + +[GitLab](https://about.gitlab.com) is a Git-based fully integrated platform for +software development. Besides Git's functionalities, GitLab has a lot of +powerful [features](https://about.gitlab.com/features/) to enhance your +[workflow](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/). + +We've gathered some resources to help you to get the best from Git with GitLab. + +## Getting started + +- [Git concepts](../../university/training/user_training.md#git-concepts) +- [Start using Git on the command line](../../gitlab-basics/start-using-git.md) +- [Command Line basic commands](../../gitlab-basics/command-line-commands.md) +- [GitLab Git Cheat Sheet (download)](https://gitlab.com/gitlab-com/marketing/raw/master/design/print/git-cheatsheet/print-pdf/git-cheatsheet.pdf) +- Commits + - [Revert a commit](../../user/project/merge_requests/revert_changes.md#reverting-a-commit) + - [Cherry-picking a commit](../../user/project/merge_requests/cherry_pick_changes.md#cherry-picking-a-commit) + - [Squashing commits](../../workflow/gitlab_flow.md#squashing-commits-with-rebase) +- **Articles:** + - [How to install Git](../../articles/how_to_install_git/index.md) + - [Git Tips & Tricks](https://about.gitlab.com/2016/12/08/git-tips-and-tricks/) + - [Eight Tips to help you work better with Git](https://about.gitlab.com/2015/02/19/8-tips-to-help-you-work-better-with-git/) +- **Presentations:** + - [GLU Course: About Version Control](https://docs.google.com/presentation/d/16sX7hUrCZyOFbpvnrAFrg6tVO5_yT98IgdAqOmXwBho/edit?usp=sharing) +- **Third-party resources:** + - What is [Git](https://git-scm.com) + - [Version control](https://git-scm.com/book/en/v2/Getting-Started-About-Version-Control) + - [Getting Started - Git Basics](https://git-scm.com/book/en/v2/Getting-Started-Git-Basics) + - [Getting Started - Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) + - [Git on the Server - GitLab](https://git-scm.com/book/en/v2/Git-on-the-Server-GitLab) + +## Branching strategies + +- **Articles:** + - [GitLab Flow](https://about.gitlab.com/2014/09/29/gitlab-flow/) +- **Third-party resources:** + - [Git Branching - Branches in a Nutshell](https://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell) + - [Git Branching - Branching Workflows](https://git-scm.com/book/en/v2/Git-Branching-Branching-Workflows) + +## Advanced use + +- [Custom Git Hooks](../../administration/custom_hooks.md) +- [Git Attributes](../../user/project/git_attributes.md) +- Git Submodules: [Using Git submodules with GitLab CI](../../ci/git_submodules.md#using-git-submodules-with-gitlab-ci) + +## API + +- [Gitignore templates](../../api/templates/gitignores.md) + +## Git LFS + +- [Git LFS](../../workflow/lfs/manage_large_binaries_with_git_lfs.md) +- [Git-Annex to Git-LFS migration guide](https://docs.gitlab.com/ee/workflow/lfs/migrate_from_git_annex_to_git_lfs.html) +- **Articles:** + - [Getting Started with Git LFS](https://about.gitlab.com/2017/01/30/getting-started-with-git-lfs-tutorial/) + - [Towards a production quality open source Git LFS server](https://about.gitlab.com/2015/08/13/towards-a-production-quality-open-source-git-lfs-server/) + +## General information + +- **Articles:** + - [The future of SaaS hosted Git repository pricing](https://about.gitlab.com/2016/05/11/git-repository-pricing/) diff --git a/doc/topics/index.md b/doc/topics/index.md index 6de13d79554..ad388dff822 100644 --- a/doc/topics/index.md +++ b/doc/topics/index.md @@ -7,10 +7,10 @@ you through better understanding GitLab's concepts through our regular docs, and, when available, through articles (guides, tutorials, technical overviews, blog posts) and videos. -- [GitLab Installation](../install/README.md) +- [Authentication](authentication/index.md) - [Continuous Integration (GitLab CI)](../ci/README.md) +- [Git](git/index.md) +- [GitLab Installation](../install/README.md) - [GitLab Pages](../user/project/pages/index.md) ->**Note:** -Non-linked topics are currently under development and subjected to change. -More topics will be available soon. +>**Note:** More topics will be available soon. diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index ec565c3e7bf..591d1524061 100644 --- a/doc/university/glossary/README.md +++ b/doc/university/glossary/README.md @@ -333,7 +333,7 @@ A [platform](https://www.meteor.com) for building javascript apps. ### Milestones -Allow you to [organize issues](https://docs.gitlab.com/ce/workflow/milestones.html) and merge requests in GitLab into a cohesive group, optionally setting a due date. A common use is keeping track of an upcoming software version. Milestones are created per-project. +Allow you to [organize issues](../../user/project/milestones/index.md) and merge requests in GitLab into a cohesive group, optionally setting a due date. A common use is keeping track of an upcoming software version. Milestones are created per-project. ### Mirror Repositories @@ -411,6 +411,10 @@ An [object-relational](https://en.wikipedia.org/wiki/PostgreSQL) database. Toute A [feature](https://docs.gitlab.com/ce/user/project/protected_branches.html) that protects branches from unauthorized pushes, force pushing or deletion. +### Protected Tags + +A [feature](https://docs.gitlab.com/ce/user/project/protected_tags.html) that protects tags from unauthorized creation, update or deletion + ### Pull Git command to [synchronize](https://git-scm.com/docs/git-pull) the local repository with the remote repository, by fetching all remote changes and merging them into the local repository. diff --git a/doc/university/high-availability/aws/README.md b/doc/university/high-availability/aws/README.md index 088f1cd7290..6b8f3cd3d1d 100644 --- a/doc/university/high-availability/aws/README.md +++ b/doc/university/high-availability/aws/README.md @@ -159,19 +159,21 @@ subnet and security group and *** -## Elastic File System +## Network File System -This new AWS offering allows us to create a file system accessible by
-EC2 instances within a VPC. Choose our VPC and the subnets will be -
automatically configured assuming we don't need to set explicit IPs. -The
next section allows us to add tags and choose between General -Purpose or
Max I/O which is a good option when being accessed by a -large number of
EC2 instances. +GitLab requires a shared filesystem such as NFS. The file share(s) will be +mounted on all application servers. There are a variety of ways to build an +NFS server on AWS. -
 +One option is to use a third-party AMI that offers NFS as a service. A [search +for 'NFS' in the AWS Marketplace](https://aws.amazon.com/marketplace/search/results?x=0&y=0&searchTerms=NFS&page=1&ref_=nav_search_box) +shows options such as NetApp, SoftNAS and others. -To actually mount and install the NFS client we'll use the User Data -section when adding our Launch Configuration. +Another option is to build a simple NFS server using a vanilla Linux server backed +by AWS Elastic Block Storage (EBS). + +> **Note:** GitLab does not recommend using AWS Elastic File System (EFS). See + details in [High Availability NFS documentation](../../../administration/high_availability/nfs.md#aws-elastic-file-system) *** diff --git a/doc/update/8.10-to-8.11.md b/doc/update/8.10-to-8.11.md index e5e3cd395df..e538983e603 100644 --- a/doc/update/8.10-to-8.11.md +++ b/doc/update/8.10-to-8.11.md @@ -49,6 +49,8 @@ sudo gem install bundler --no-ri --no-rdoc ### 4. Get latest code ```bash +cd /home/git/gitlab + sudo -u git -H git fetch --all sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically ``` diff --git a/doc/update/8.11-to-8.12.md b/doc/update/8.11-to-8.12.md index d6b3b0ffa5a..604166beb56 100644 --- a/doc/update/8.11-to-8.12.md +++ b/doc/update/8.11-to-8.12.md @@ -49,6 +49,8 @@ sudo gem install bundler --no-ri --no-rdoc ### 4. Get latest code ```bash +cd /home/git/gitlab + sudo -u git -H git fetch --all sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically ``` diff --git a/doc/update/8.12-to-8.13.md b/doc/update/8.12-to-8.13.md index ed0e668d854..d83965131f5 100644 --- a/doc/update/8.12-to-8.13.md +++ b/doc/update/8.12-to-8.13.md @@ -49,6 +49,8 @@ sudo gem install bundler --no-ri --no-rdoc ### 4. Get latest code ```bash +cd /home/git/gitlab + sudo -u git -H git fetch --all sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically ``` diff --git a/doc/update/8.13-to-8.14.md b/doc/update/8.13-to-8.14.md index aa1c659717e..aaadcec8ac0 100644 --- a/doc/update/8.13-to-8.14.md +++ b/doc/update/8.13-to-8.14.md @@ -49,6 +49,8 @@ sudo gem install bundler --no-ri --no-rdoc ### 4. Get latest code ```bash +cd /home/git/gitlab + sudo -u git -H git fetch --all sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically ``` diff --git a/doc/update/8.2-to-8.3.md b/doc/update/8.2-to-8.3.md index f28896c2227..4b3c5bf6d64 100644 --- a/doc/update/8.2-to-8.3.md +++ b/doc/update/8.2-to-8.3.md @@ -120,6 +120,14 @@ There are new configuration options available for [`gitlab.yml`][yaml]. View the git diff origin/8-2-stable:config/gitlab.yml.example origin/8-3-stable:config/gitlab.yml.example ``` +#### GitLab default file + +The value of the `gitlab_workhorse_options` variable should be updated within the default gitlab file (`/etc/default/gitlab`) according to the following diff: + +```sh +git diff origin/8-2-stable:lib/support/init.d/gitlab.default.example origin/8-3-stable:lib/support/init.d/gitlab.default.example +``` + #### Nginx configuration GitLab 8.3 introduces major changes in the NGINX configuration. diff --git a/doc/update/9.0-to-9.1.md b/doc/update/9.0-to-9.1.md index 53cddb3f290..2b582d4eefd 100644 --- a/doc/update/9.0-to-9.1.md +++ b/doc/update/9.0-to-9.1.md @@ -1,9 +1,5 @@ # From 9.0 to 9.1 -** TODO: ** - -# TODO clean out 9.0-specific stuff - Make sure you view this update guide from the tag (version) of GitLab you would like to install. In most cases this should be the highest numbered production tag (without rc in it). You can select the tag in the version dropdown at the @@ -108,6 +104,7 @@ cd /home/git/gitlab-shell sudo -u git -H git fetch --all --tags sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile ``` ### 7. Update gitlab-workhorse @@ -297,7 +294,10 @@ during your 9.1 upgrade **you can skip this step**. If you have not yet set up Gitaly then follow [Gitaly section of the installation guide](../install/installation.md#install-gitaly). -If you installed Gitaly in GitLab 9.0 you need to make some changes in gitlab.yml. +If you installed Gitaly in GitLab 9.0 you need to make some changes in +gitlab.yml, and create a new config.toml file. + +#### Gitaly gitlab.yml changes Look for `socket_path:` the `gitaly:` section. Its value is usually `/home/git/gitlab/tmp/sockets/private/gitaly.socket`. Note what socket @@ -318,6 +318,31 @@ the socket path, but with `unix:` in front. Each entry under `storages:` should use the same `gitaly_address`. +#### Compile Gitaly + +This step will also create `config.toml.example` which you need below. + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +#### Gitaly config.toml + +In GitLab 9.1 we are replacing environment variables in Gitaly with a +TOML configuration file. + +```shell +cd /home/git/gitaly + +sudo mv env env.old +sudo -u git cp config.toml.example config.toml +# If you are using custom repository storage paths they need to be in config.toml +sudo -u git -H editor config.toml +``` + ### 11. Start application ```bash diff --git a/doc/update/9.1-to-9.2.md b/doc/update/9.1-to-9.2.md new file mode 100644 index 00000000000..19db6e5763e --- /dev/null +++ b/doc/update/9.1-to-9.2.md @@ -0,0 +1,288 @@ +# From 9.1 to 9.2 + +Make sure you view this update guide from the tag (version) of GitLab you would +like to install. In most cases this should be the highest numbered production +tag (without rc in it). You can select the tag in the version dropdown at the +top left corner of GitLab (below the menu bar). + +If the highest number stable branch is unclear please check the +[GitLab Blog](https://about.gitlab.com/blog/archives.html) for installation +guide links by version. + +### 1. Stop server + +```bash +sudo service gitlab stop +``` + +### 2. Backup + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:backup:create RAILS_ENV=production +``` + +### 3. Update Ruby + +NOTE: GitLab 9.0 and higher only support Ruby 2.3.x and dropped support for Ruby 2.1.x. Be +sure to upgrade your interpreter if necessary. + +You can check which version you are running with `ruby -v`. + +Download and compile Ruby: + +```bash +mkdir /tmp/ruby && cd /tmp/ruby +curl --remote-name --progress https://cache.ruby-lang.org/pub/ruby/2.3/ruby-2.3.3.tar.gz +echo '1014ee699071aa2ddd501907d18cbe15399c997d ruby-2.3.3.tar.gz' | shasum -c - && tar xzf ruby-2.3.3.tar.gz +cd ruby-2.3.3 +./configure --disable-install-rdoc +make +sudo make install +``` + +Install Bundler: + +```bash +sudo gem install bundler --no-ri --no-rdoc +``` + +### 4. Update Node + +GitLab now runs [webpack](http://webpack.js.org) to compile frontend assets and +it has a minimum requirement of node v4.3.0. + +You can check which version you are running with `node -v`. If you are running +a version older than `v4.3.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. + +<https://nodejs.org/en/download/> + + +Since 8.17, GitLab requires the use of yarn `>= v0.17.0` to manage +JavaScript dependencies. + +```bash +curl --location https://yarnpkg.com/install.sh | bash - +``` + +More information can be found on the [yarn website](https://yarnpkg.com/en/docs/install). + +### 5. Get latest code + +```bash +cd /home/git/gitlab + +sudo -u git -H git fetch --all +sudo -u git -H git checkout -- db/schema.rb # local changes will be restored automatically +``` + +For GitLab Community Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 9-2-stable +``` + +OR + +For GitLab Enterprise Edition: + +```bash +cd /home/git/gitlab + +sudo -u git -H git checkout 9-2-stable-ee +``` + +### 6. Update gitlab-shell + +```bash +cd /home/git/gitlab-shell + +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_SHELL_VERSION) +sudo -u git -H bin/compile +``` + +### 7. Update gitlab-workhorse + +Install and compile gitlab-workhorse. This requires +[Go 1.5](https://golang.org/dl) which should already be on your system from +GitLab 8.1. GitLab-Workhorse uses [GNU Make](https://www.gnu.org/software/make/). +If you are not using Linux you may have to run `gmake` instead of +`make` below. + +```bash +cd /home/git/gitlab-workhorse + +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v$(</home/git/gitlab/GITLAB_WORKHORSE_VERSION) +sudo -u git -H make +``` + +### 8. Update configuration files + +#### 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`: + +```sh +cd /home/git/gitlab + +git diff origin/9-1-stable:config/gitlab.yml.example origin/9-2-stable:config/gitlab.yml.example +``` + +#### Nginx configuration + +Ensure you're still up-to-date with the latest NGINX configuration changes: + +```sh +cd /home/git/gitlab + +# For HTTPS configurations +git diff origin/9-1-stable:lib/support/nginx/gitlab-ssl origin/9-2-stable:lib/support/nginx/gitlab-ssl + +# For HTTP configurations +git diff origin/9-1-stable:lib/support/nginx/gitlab origin/9-2-stable:lib/support/nginx/gitlab +``` + +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]. +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]. + +[Apache templates]: https://gitlab.com/gitlab-org/gitlab-recipes/tree/master/web-server/apache +[/etc/default/gitlab]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-2-stable/lib/support/init.d/gitlab.default.example#L38 + +#### SMTP configuration + +If you're installing from source and use SMTP to deliver mail, you will need to add the following line +to config/initializers/smtp_settings.rb: + +```ruby +ActionMailer::Base.delivery_method = :smtp +``` + +See [smtp_settings.rb.sample] as an example. + +[smtp_settings.rb.sample]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-1-stable/config/initializers/smtp_settings.rb.sample#L13 + +#### 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`: + +```sh +cd /home/git/gitlab + +git diff origin/9-1-stable:lib/support/init.d/gitlab.default.example origin/9-2-stable:lib/support/init.d/gitlab.default.example +``` + +Ensure you're still up-to-date with the latest init script changes: + +```bash +cd /home/git/gitlab + +sudo cp lib/support/init.d/gitlab /etc/init.d/gitlab +``` + +For Ubuntu 16.04.1 LTS: + +```bash +sudo systemctl daemon-reload +``` + +### 9. Install libs, migrations, etc. + +```bash +cd /home/git/gitlab + +# MySQL installations (note: the line below states '--without postgres') +sudo -u git -H bundle install --without postgres development test --deployment + +# PostgreSQL installations (note: the line below states '--without mysql') +sudo -u git -H bundle install --without mysql development test --deployment + +# Optional: clean up old gems +sudo -u git -H bundle clean + +# Run database migrations +sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production + +# Update node dependencies and recompile assets +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile RAILS_ENV=production NODE_ENV=production + +# Clean up cache +sudo -u git -H bundle exec rake cache:clear RAILS_ENV=production +``` + +**MySQL installations**: Run through the `MySQL strings limits` and `Tables and data conversion to utf8mb4` [tasks](../install/database_mysql.md). + +### 10. Optional: install Gitaly + +Gitaly is still an optional component of GitLab. If you want to save time +during your 9.2 upgrade **you can skip this step**. + +If you have not yet set up Gitaly then follow [Gitaly section of the installation +guide](../install/installation.md#install-gitaly). + +#### Compile Gitaly + +```shell +cd /home/git/gitaly +sudo -u git -H git fetch --all --tags +sudo -u git -H git checkout v$(</home/git/gitlab/GITALY_SERVER_VERSION) +sudo -u git -H make +``` + +### 11. Start application + +```bash +sudo service gitlab start +sudo service nginx restart +``` + +### 12. Check application status + +Check if GitLab and its environment are configured correctly: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:env:info RAILS_ENV=production +``` + +To make sure you didn't miss anything run a more thorough check: + +```bash +cd /home/git/gitlab + +sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production +``` + +If all items are green, then congratulations, the upgrade is complete! + +## Things went south? Revert to previous version (9.1) + +### 1. Revert the code to the previous version + +Follow the [upgrade guide from 9.0 to 9.1](9.0-to-9.1.md), except for the +database migration (the backup is already migrated to the previous version). + +### 2. Restore from the backup + +```bash +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-ce/blob/9-2-stable/config/gitlab.yml.example +[gl-example]: https://gitlab.com/gitlab-org/gitlab-ce/blob/9-2-stable/lib/support/init.d/gitlab.default.example diff --git a/doc/update/README.md b/doc/update/README.md index 837b31abb97..d024a809f24 100644 --- a/doc/update/README.md +++ b/doc/update/README.md @@ -48,6 +48,20 @@ GitLab provides official Docker images for both Community and Enterprise editions. They are based on the Omnibus package and instructions on how to update them are in [a separate document][omnidocker]. +## Upgrading without downtime + +Starting with GitLab 9.1.0 it's possible to upgrade to a newer major, minor, or patch version of GitLab +without having to take your GitLab instance offline. However, for this to work +there are the following requirements: + +1. You can only upgrade 1 minor release at a time. So from 9.1 to 9.2, not to 9.3. +2. You have to be on the most recent patch release. For example, if 9.1.15 is the last + release of 9.1 then you can safely upgrade from that version to any 9.2.x version. + However, if you are running 9.1.14 you first need to upgrade to 9.1.15. +2. You have to use [post-deployment + migrations](../development/post_deployment_migrations.md). +3. You are using PostgreSQL. If you are using MySQL please look at the release post to see if downtime is required. + ## 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 154a0f817da..ac1bcb8f241 100644 --- a/doc/update/patch_versions.md +++ b/doc/update/patch_versions.md @@ -57,7 +57,7 @@ sudo -u git -H bundle clean sudo -u git -H bundle exec rake db:migrate RAILS_ENV=production # Clean up assets and cache -sudo -u git -H bundle exec rake gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production +sudo -u git -H bundle exec rake yarn:install gitlab:assets:clean gitlab:assets:compile cache:clear RAILS_ENV=production NODE_ENV=production ``` ### 4. Update gitlab-workhorse to the corresponding version @@ -75,6 +75,7 @@ cd /home/git/gitlab-shell sudo -u git -H git fetch --all --tags sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` -b v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` +sudo -u git -H sh -c 'if [ -x bin/compile ]; then bin/compile; fi' ``` ### 6. Start application diff --git a/doc/update/upgrader.md b/doc/update/upgrader.md index 5fa39ef1b0a..eb7f14a96d5 100644 --- a/doc/update/upgrader.md +++ b/doc/update/upgrader.md @@ -60,6 +60,7 @@ GitLab Shell might be outdated, running the commands below ensures you're using cd /home/git/gitlab-shell sudo -u git -H git fetch sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION` +sudo -u git -H sh -c 'if [ -x bin/compile ] ; then bin/compile ; fi' ``` ## One line upgrade command @@ -78,6 +79,7 @@ cd /home/git/gitlab; \ cd /home/git/gitlab-shell; \ sudo -u git -H git fetch; \ sudo -u git -H git checkout v`cat /home/git/gitlab/GITLAB_SHELL_VERSION`; \ + sudo -u git -H sh -c 'if [ -x bin/compile ] ; then bin/compile ; fi'; \ cd /home/git/gitlab; \ sudo service gitlab start; \ sudo service nginx restart; \ diff --git a/doc/user/admin_area/img/cohorts.png b/doc/user/admin_area/img/cohorts.png Binary files differnew file mode 100644 index 00000000000..8bae7faff07 --- /dev/null +++ b/doc/user/admin_area/img/cohorts.png diff --git a/doc/user/admin_area/monitoring/health_check.md b/doc/user/admin_area/monitoring/health_check.md index eac57bc3de4..a954840b8a6 100644 --- a/doc/user/admin_area/monitoring/health_check.md +++ b/doc/user/admin_area/monitoring/health_check.md @@ -1,36 +1,78 @@ # Health Check -> [Introduced][ce-3888] in GitLab 8.8. - -GitLab provides a health check endpoint for uptime monitoring on the `health_check` web -endpoint. The health check reports on the overall system status based on the status of -the database connection, the state of the database migrations, and the ability to write -and access the cache. This endpoint can be provided to uptime monitoring services like -[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health]. +>**Notes:** + - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1. + - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and will + be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior) + section. + +GitLab provides liveness and readiness probes to indicate service health and +reachability to required services. These probes report on the status of the +database connection, Redis connection, and access to the filesystem. These +endpoints [can be provided to schedulers like Kubernetes][kubernetes] to hold +traffic until the system is ready or restart the container as needed. ## Access Token -An access token needs to be provided while accessing the health check endpoint. The current -accepted token can be found on the `admin/health_check` page of your GitLab instance. +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** +(`admin/health_check`) page of your GitLab instance.  The access token can be passed as a URL parameter: ``` -https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN +https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN ``` -or as an HTTP header: +which will then provide a report of system health in JSON format: -```bash -curl --header "TOKEN: ACCESS_TOKEN" https://gitlab.example.com/health_check.json +``` +{ + "db_check": { + "status": "ok" + }, + "redis_check": { + "status": "ok" + }, + "fs_shards_check": { + "status": "ok", + "labels": { + "shard": "default" + } + } +} ``` ## Using the Endpoint -Once you have the access token, health information can be retrieved as plain text, JSON, -or XML using the `health_check` endpoint: +Once you have the access token, the probes can be accessed: + +- `https://gitlab.example.com/-/readiness?token=ACCESS_TOKEN` +- `https://gitlab.example.com/-/liveness?token=ACCESS_TOKEN` + +## Status + +On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint +will return a valid successful HTTP status code, and a `success` message. + +## Old behavior + +>**Notes:** + - Liveness and readiness probes were [introduced][ce-10416] in GitLab 9.1. + - The `health_check` endpoint was [introduced][ce-3888] in GitLab 8.8 and will + be deprecated in GitLab 9.1. Read more in the [old behavior](#old-behavior) + section. + +GitLab provides a health check endpoint for uptime monitoring on the `health_check` web +endpoint. The health check reports on the overall system status based on the status of +the database connection, the state of the database migrations, and the ability to write +and access the cache. This endpoint can be provided to uptime monitoring services like +[Pingdom][pingdom], [Nagios][nagios-health], and [NewRelic][newrelic-health]. + +Once you have the [access token](#access-token), health information can be +retrieved as plain text, JSON, or XML using the `health_check` endpoint: - `https://gitlab.example.com/health_check?token=ACCESS_TOKEN` - `https://gitlab.example.com/health_check.json?token=ACCESS_TOKEN` @@ -54,13 +96,13 @@ would be like: {"healthy":true,"message":"success"} ``` -## Status - On failure, the endpoint will return a `500` HTTP status code. On success, the endpoint will return a valid successful HTTP status code, and a `success` message. Ideally your uptime monitoring should look for the success message. +[ce-10416]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10416 [ce-3888]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/3888 [pingdom]: https://www.pingdom.com [nagios-health]: https://nagios-plugins.org/doc/man/check_http.html [newrelic-health]: https://docs.newrelic.com/docs/alerts/alert-policies/downtime-alerts/availability-monitoring +[kubernetes]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/ diff --git a/doc/user/admin_area/settings/usage_statistics.md b/doc/user/admin_area/settings/usage_statistics.md new file mode 100644 index 00000000000..f3745d0efa7 --- /dev/null +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -0,0 +1,65 @@ +# Usage statistics + +GitLab Inc. will periodically collect information about your instance in order +to perform various actions. + +All statistics are opt-out, you can disable them from the admin panel. + +## Version check + +GitLab can inform you when an update is available and the importance of it. + +No information other than the GitLab version and the instance's hostname (through the HTTP referer) +are collected. + +In the **Overview** tab you can see if your GitLab version is up to date. There +are three cases: 1) you are up to date (green), 2) there is an update available +(yellow) and 3) your version is vulnerable and a security fix is released (red). + +In any case, you will see a message informing you of the state and the +importance of the update. + +If enabled, the version status will also be shown in the help page (`/help`) +for all signed in users. + +## Usage ping + +> [Introduced][ee-557] in GitLab Enterprise Edition 8.10. More statistics +[were added][ee-735] in GitLab Enterprise Edition +8.12. [Moved to GitLab Community Edition][ce-23361] in 9.1. + +GitLab sends a weekly payload containing usage data to GitLab Inc. The usage +ping uses high-level data to help our product, support, and sales teams. It does +not send any project names, usernames, or any other specific data. The +information from the usage ping is not anonymous, it is linked to the hostname +of the instance. + +You can view the exact JSON payload in the administration panel. + +### Deactivate the usage ping + +The usage ping is opt-out. If you want to deactivate this feature, go to +the Settings page of your administration panel and uncheck the Usage ping +checkbox. + +To disable the usage ping and prevent it from being configured in future through +the administration panel, Omnibus installs can set the following in +[`gitlab.rb`](https://docs.gitlab.com/omnibus/settings/configuration.html#configuration-options): + +```ruby +gitlab_rails['usage_ping_enabled'] = false +``` + +And source installs can set the following in `gitlab.yml`: + +```yaml +production: &base + # ... + gitlab: + # ... + usage_ping_enabled: false +``` + +[ee-557]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/557 +[ee-735]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/735 +[ce-23361]: https://gitlab.com/gitlab-org/gitlab-ce/issues/23361 diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md new file mode 100644 index 00000000000..e25e7a8bbc3 --- /dev/null +++ b/doc/user/admin_area/user_cohorts.md @@ -0,0 +1,37 @@ +# Cohorts + +> **Notes:** +> [Introduced][ce-23361] in GitLab 9.1. + +As a benefit of having the [usage ping active](settings/usage_statistics.md), +GitLab lets you analyze the users' activities of your GitLab installation. +Under `/admin/cohorts`, when the usage ping is active, GitLab will show the +monthly cohorts of new users and their activities over time. + +## Overview + +How do we read the user cohorts table? Let's take an example with the following +user cohorts. + + + +For the cohort of June 2016, 163 users have been added on this server and have +been active since this month. One month later, in July 2016, out of +these 163 users, 155 users (or 95% of the June cohort) are still active. Two +months later, 139 users (or 85%) are still active. 9 months later, we can see +that only 6% of this cohort are still active. + +The Inactive users column shows the number of users who have been added during +the month, but who have never actually had any activity in the instance. + +How do we measure the activity of users? GitLab considers a user active if: + +* the user signs in +* the user has Git activity (whether push or pull). + +## Setup + +1. [Activate the usage ping](settings/usage_statistics.md) +2. Go to `/admin/cohorts` to see the user cohorts of the server + +[ce-23361]: https://gitlab.com/gitlab-org/gitlab-ce/issues/23361 diff --git a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png Binary files differindex b15447ec290..b15447ec290 100644 --- a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png +++ b/doc/user/discussions/img/btn_new_issue_for_all_discussions.png diff --git a/doc/user/discussions/img/comment_type_toggle.gif b/doc/user/discussions/img/comment_type_toggle.gif Binary files differnew file mode 100644 index 00000000000..b73c197b97f --- /dev/null +++ b/doc/user/discussions/img/comment_type_toggle.gif diff --git a/doc/user/discussions/img/discussion_comment.png b/doc/user/discussions/img/discussion_comment.png Binary files differnew file mode 100644 index 00000000000..8f66d138922 --- /dev/null +++ b/doc/user/discussions/img/discussion_comment.png diff --git a/doc/user/project/merge_requests/img/discussion_view.png b/doc/user/discussions/img/discussion_view.png Binary files differindex 2ee1db2eab3..2ee1db2eab3 100644 --- a/doc/user/project/merge_requests/img/discussion_view.png +++ b/doc/user/discussions/img/discussion_view.png diff --git a/doc/user/project/merge_requests/img/discussions_resolved.png b/doc/user/discussions/img/discussions_resolved.png Binary files differindex 3fd496f6da5..3fd496f6da5 100644 --- a/doc/user/project/merge_requests/img/discussions_resolved.png +++ b/doc/user/discussions/img/discussions_resolved.png diff --git a/doc/user/project/merge_requests/img/new_issue_for_discussion.png b/doc/user/discussions/img/new_issue_for_discussion.png Binary files differindex 93c9dad8921..93c9dad8921 100644 --- a/doc/user/project/merge_requests/img/new_issue_for_discussion.png +++ b/doc/user/discussions/img/new_issue_for_discussion.png diff --git a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png Binary files differindex 928c7d33898..928c7d33898 100644 --- a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved.png +++ b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved.png diff --git a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved_msg.png b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png Binary files differindex bcdc0250d7c..bcdc0250d7c 100644 --- a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved_msg.png +++ b/doc/user/discussions/img/only_allow_merge_if_all_discussions_are_resolved_msg.png diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png b/doc/user/discussions/img/preview_issue_for_discussion.png Binary files differindex 2ee0653b2ba..2ee0653b2ba 100644 --- a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png +++ b/doc/user/discussions/img/preview_issue_for_discussion.png diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png b/doc/user/discussions/img/preview_issue_for_discussions.png Binary files differindex 3fe0a666678..3fe0a666678 100644 --- a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png +++ b/doc/user/discussions/img/preview_issue_for_discussions.png diff --git a/doc/user/project/merge_requests/img/resolve_comment_button.png b/doc/user/discussions/img/resolve_comment_button.png Binary files differindex 70340108874..70340108874 100644 --- a/doc/user/project/merge_requests/img/resolve_comment_button.png +++ b/doc/user/discussions/img/resolve_comment_button.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_button.png b/doc/user/discussions/img/resolve_discussion_button.png Binary files differindex ab454f661e0..ab454f661e0 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_button.png +++ b/doc/user/discussions/img/resolve_discussion_button.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png b/doc/user/discussions/img/resolve_discussion_issue_notice.png Binary files differindex e0ee6a39ffd..e0ee6a39ffd 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png +++ b/doc/user/discussions/img/resolve_discussion_issue_notice.png diff --git a/doc/user/project/merge_requests/img/resolve_discussion_open_issue.png b/doc/user/discussions/img/resolve_discussion_open_issue.png Binary files differindex 98d63278326..98d63278326 100644 --- a/doc/user/project/merge_requests/img/resolve_discussion_open_issue.png +++ b/doc/user/discussions/img/resolve_discussion_open_issue.png diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md new file mode 100644 index 00000000000..59e343ebe51 --- /dev/null +++ b/doc/user/discussions/index.md @@ -0,0 +1,150 @@ +# Discussions + +The ability to contribute conversationally is offered throughout GitLab. + +You can leave a comment in the following places: + +- issues +- merge requests +- snippets +- commits +- commit diffs + +The comment area supports [Markdown] and [slash commands]. One can edit their +own comment at any time, and anyone with [Master access level][permissions] or +higher can also edit a comment made by someone else. + +Apart from the standard comments, you also have the option to create a comment +in the form of a resolvable or threaded discussion. + +## Resolvable discussions + +>**Notes:** +- The main feature was [introduced][ce-5022] in GitLab 8.11. +- Resolvable discussions can be added only to merge request diffs. + +Discussion resolution helps keep track of progress during planning or code review. +Resolving comments prevents you from forgetting to address feedback and lets you +hide discussions that are no longer relevant. + +!["A discussion between two people on a piece of code"][discussion-view] + +Comments and discussions can be resolved by anyone with at least Developer +access to the project or the author of the merge request. + +### Jumping between unresolved discussions + +When a merge request has a large number of comments it can be difficult to track +what remains unresolved. You can jump between unresolved discussions with the +Jump button next to the Reply field on a discussion. + +You can also jump to the first unresolved discussion from the button next to the +resolved discussions tracker. + +!["3/4 discussions resolved"][discussions-resolved] + +### Marking a comment or discussion as resolved + +You can mark a discussion as resolved by clicking the **Resolve discussion** +button at the bottom of the discussion. + +!["Resolve discussion" button][resolve-discussion-button] + +Alternatively, you can mark each comment as resolved individually. + +!["Resolve comment" button][resolve-comment-button] + +### Move all unresolved discussions in a merge request to an issue + +> [Introduced][ce-8266] in GitLab 9.1 + +To continue all open discussions from a merge request in a new issue, click the +**Resolve all discussions in new issue** button. + + + +Alternatively, when your project only accepts merge requests [when all discussions +are resolved](#only-allow-merge-requests-to-be-merged-if-all-discussions-are-resolved), +there will be an **open an issue to resolve them later** link in the merge +request widget. + + + +This will prepare an issue with its content referring to the merge request and +the unresolved discussions. + + + +Hitting **Submit issue** will cause all discussions to be marked as resolved and +add a note referring to the newly created issue. + + + +You can now proceed to merge the merge request from the UI. + +### Moving a single discussion to a new issue + +> [Introduced][ce-8266] in GitLab 9.1 + +To create a new issue for a single discussion, you can use the **Resolve this +discussion in a new issue** button. + + + +This will direct you to a new issue prefilled with the content of the +discussion, similar to the issues created for delegating multiple +discussions at once. Saving the issue will mark the discussion as resolved and +add a note to the merge request discussion referencing the new issue. + + + +### Only allow merge requests to be merged if all discussions are resolved + +> [Introduced][ce-7125] in GitLab 8.14. + +You can prevent merge requests from being merged until all discussions are +resolved. + +Navigate to your project's settings page, select the +**Only allow merge requests to be merged if all discussions are resolved** check +box and hit **Save** for the changes to take effect. + + + +From now on, you will not be able to merge from the UI until all discussions +are resolved. + + + +## Threaded discussions + +> [Introduced][ce-7527] in GitLab 9.1. + +While resolvable discussions are only available to merge request diffs, +discussions can also be added without a diff. You can start a specific +discussion which will look like a thread, on issues, commits, snippets, and +merge requests. + +To start a threaded discussion, click on the **Comment** button toggle dropdown, +select **Start discussion** and click **Start discussion** when you're ready to +post the comment. + + + +This will post a comment with a single thread to allow you to discuss specific +comments in greater detail. + + + +[ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 +[ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 +[ce-7527]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7527 +[ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180 +[ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266 +[resolve-discussion-button]: img/resolve_discussion_button.png +[resolve-comment-button]: img/resolve_comment_button.png +[discussion-view]: img/discussion_view.png +[discussions-resolved]: img/discussions_resolved.png +[markdown]: ../markdown.md +[slash commands]: ../project/slash_commands.md +[permissions]: ../permissions.md diff --git a/doc/user/group/subgroups/index.md b/doc/user/group/subgroups/index.md index ce5da07c61a..a4726673fc4 100644 --- a/doc/user/group/subgroups/index.md +++ b/doc/user/group/subgroups/index.md @@ -71,8 +71,10 @@ structure. - You need to be an Owner of a group in order to be able to create a subgroup. For more information check the [permissions table][permissions]. - For a list of words that are not allowed to be used as group names see the - [`namespace_validator.rb` file][reserved] under the `RESERVED` and - `WILDCARD_ROUTES` lists. + [`dynamic_path_validator.rb` file][reserved] under the `TOP_LEVEL_ROUTES`, `WILDCARD_ROUTES` and `GROUP_ROUTES` lists: + - `TOP_LEVEL_ROUTES`: are names that are reserved as usernames or top level groups + - `WILDCARD_ROUTES`: are names that are reserved for child groups or projects. + - `GROUP_ROUTES`: are names that are reserved for all groups or projects. To create a subgroup: @@ -161,4 +163,4 @@ Here's a list of what you can't do with subgroups: [ce-2772]: https://gitlab.com/gitlab-org/gitlab-ce/issues/2772 [permissions]: ../../permissions.md#group -[reserved]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/validators/namespace_validator.rb +[reserved]: https://gitlab.com/gitlab-org/gitlab-ce/blob/master/app/validators/dynamic_path_validator.rb diff --git a/doc/user/img/gitlab_snippet.png b/doc/user/img/gitlab_snippet.png Binary files differnew file mode 100644 index 00000000000..718347fc2d4 --- /dev/null +++ b/doc/user/img/gitlab_snippet.png diff --git a/doc/user/markdown.md b/doc/user/markdown.md index 97de428d11d..0d29b471d52 100644 --- a/doc/user/markdown.md +++ b/doc/user/markdown.md @@ -431,7 +431,7 @@ Emphasis, aka italics, with *asterisks* or _underscores_. Strong emphasis, aka bold, with **asterisks** or __underscores__. -Combined emphasis with **_asterisks and underscores_**. +Combined emphasis with **asterisks and _underscores_**. Strikethrough uses two tildes. ~~Scratch this.~~ ``` @@ -640,10 +640,11 @@ Here's a line for us to start with. This line is separated from the one above by two newlines, so it will be a *separate paragraph*. This line is also a separate paragraph, but... -This line is only separated by a single newline, so it's a separate line in the *same paragraph*. +This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. + +This line is also a separate paragraph, and... +This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) -This line is also a separate paragraph, and... -This line is on its own line, because the previous line ends with two spaces. ``` @@ -651,11 +652,12 @@ Here's a line for us to start with. This line is separated from the one above by two newlines, so it will be a *separate paragraph*. -This line is also begins a separate paragraph, but... -This line is only separated by a single newline, so it's a separate line in the *same paragraph*. +This line is also a separate paragraph, but... +This line is only separated by a single newline, so it *does not break* and just follows the previous line in the *same paragraph*. + +This line is also a separate paragraph, and... +This line is *on its own line*, because the previous line ends with two spaces. (but still in the *same paragraph*) -This line is also a separate paragraph, and... -This line is on its own line, because the previous line ends with two spaces. ### Tables diff --git a/doc/user/permissions.md b/doc/user/permissions.md index 0ea6d01411f..b0145b0a759 100644 --- a/doc/user/permissions.md +++ b/doc/user/permissions.md @@ -7,6 +7,9 @@ project itself, the highest permission level is used. On public and internal projects the Guest role is not enforced. All users will be able to create issues, leave comments, and pull or download the project code. +When a member leaves the team the all assigned Issues and Merge Requests +will be unassigned automatically. + GitLab administrators receive all permissions. To add or import a user, you can follow the [project users and members @@ -55,6 +58,7 @@ The following table depicts the various user permission levels in a project. | Push to protected branches | | | | ✓ | ✓ | | Enable/disable branch protection | | | | ✓ | ✓ | | Turn on/off protected branch push for devs| | | | ✓ | ✓ | +| Enable/disable tag protections | | | | ✓ | ✓ | | Rewrite/remove Git tags | | | | ✓ | ✓ | | Edit project | | | | ✓ | ✓ | | Add deploy keys to project | | | | ✓ | ✓ | @@ -170,7 +174,7 @@ users: | Push container images to other projects | | | | | [^1]: Guest users can only view the confidential issues they created themselves -[^2]: If **Public pipelines** is enabled in **Project Settings > CI/CD Pipelines** +[^2]: If **Public pipelines** is enabled in **Project Settings > Pipelines** [^3]: Not allowed for Guest, Reporter, Developer, Master, or Owner [^4]: Only if user is not external one. [^5]: Only if user is a member of the project. diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md new file mode 100644 index 00000000000..b5d3b009044 --- /dev/null +++ b/doc/user/profile/account/delete_account.md @@ -0,0 +1,25 @@ +# Deleting a User Account + +- As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account** +- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Remove user** + +## Associated Records + +> Introduced for issues in [GitLab 9.0][ce-7393], and for merge requests, award emoji, notes, and abuse reports in [GitLab 9.1][ce-10467]. + +When a user account is deleted, not all associated records are deleted with it. Here's a list of things that will not be deleted: + +- Issues that the user created +- Merge requests that the user created +- Notes that the user created +- Abuse reports that the user reported +- Award emoji that the user craeted + + +Instead of being deleted, these records will be moved to a system-wide "Ghost User", whose sole purpose is to act as a container for such records. + + +[ce-7393]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393 +[ce-10467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467 + + diff --git a/doc/user/profile/account/two_factor_authentication.md b/doc/user/profile/account/two_factor_authentication.md index 63a3d3c472e..fb69d934ae1 100644 --- a/doc/user/profile/account/two_factor_authentication.md +++ b/doc/user/profile/account/two_factor_authentication.md @@ -143,7 +143,7 @@ into the password field. To disable two-factor authentication on your account (for example, if you have lost your code generation device) you can: * [Use a saved recovery code](#use-a-saved-recovery-code) -* [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-SSH) +* [Generate new recovery codes using SSH](#generate-new-recovery-codes-using-ssh) * [Ask a GitLab administrator to disable two-factor authentication on your account](#ask-a-gitlab-administrator-to-disable-two-factor-authentication-on-your-account) ### Use a saved recovery code diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index b6221620e58..6a2ca7fb428 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -10,6 +10,7 @@ - Starting from GitLab 8.12, if you have 2FA enabled in your account, you need to pass a personal access token instead of your password in order to login to GitLab's Container Registry. +- Multiple level image names support was added in GitLab 9.1 With the Docker Container Registry integrated into GitLab, every project can have its own space to store its Docker images. @@ -54,18 +55,25 @@ sure that you are using the Registry URL with the namespace and project name that is hosted on GitLab: ``` -docker build -t registry.example.com/group/project . -docker push registry.example.com/group/project +docker build -t registry.example.com/group/project/image . +docker push registry.example.com/group/project/image ``` Your image will be named after the following scheme: ``` -<registry URL>/<namespace>/<project> +<registry URL>/<namespace>/<project>/<image> ``` -As such, the name of the image is unique, but you can differentiate the images -using tags. +GitLab supports up to three levels of image repository names. + +Following examples of image tags are valid: + +``` +registry.example.com/group/project:some-tag +registry.example.com/group/project/image:latest +registry.example.com/group/project/my/image:rc1 +``` ## Use images from GitLab Container Registry @@ -73,7 +81,7 @@ To download and run a container from images hosted in GitLab Container Registry, use `docker run`: ``` -docker run [options] registry.example.com/group/project [arguments] +docker run [options] registry.example.com/group/project/image [arguments] ``` For more information on running Docker containers, visit the @@ -136,7 +144,7 @@ A user attempted to enable an S3-backed Registry. The `docker login` step went fine. However, when pushing an image, the output showed: ``` -The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test] +The push refers to a repository [s3-testing.myregistry.com:4567/root/docker-test/docker-image] dc5e59c14160: Pushing [==================================================>] 14.85 kB 03c20c1a019a: Pushing [==================================================>] 2.048 kB a08f14ef632e: Pushing [==================================================>] 2.048 kB @@ -229,7 +237,7 @@ a container image. You may need to run as root to do this. For example: ```sh docker login s3-testing.myregistry.com:4567 -docker push s3-testing.myregistry.com:4567/root/docker-test +docker push s3-testing.myregistry.com:4567/root/docker-test/docker-image ``` In the example above, we see the following trace on the mitmproxy window: diff --git a/doc/user/project/cycle_analytics.md b/doc/user/project/cycle_analytics.md index 62afd8cf247..8f6b530c033 100644 --- a/doc/user/project/cycle_analytics.md +++ b/doc/user/project/cycle_analytics.md @@ -5,10 +5,10 @@ Cycle Analytics measures the time it takes to go from an [idea to production] for each project you have. This is achieved by not only indicating the total time it -takes to reach at that point, but the total time is broken down into the +takes to reach that point, but the total time is broken down into the multiple stages an idea has to pass through to be shipped. -Cycle Analytics is that it is tightly coupled with the [GitLab flow] and +Cycle Analytics is tightly coupled with the [GitLab flow] and calculates a separate median for each stage. ## Overview diff --git a/doc/user/project/img/project_repository_settings.png b/doc/user/project/img/project_repository_settings.png Binary files differnew file mode 100644 index 00000000000..1aa7efc36f1 --- /dev/null +++ b/doc/user/project/img/project_repository_settings.png diff --git a/doc/user/project/img/protected_tag_matches.png b/doc/user/project/img/protected_tag_matches.png Binary files differnew file mode 100644 index 00000000000..a36a11a1271 --- /dev/null +++ b/doc/user/project/img/protected_tag_matches.png diff --git a/doc/user/project/img/protected_tags_list.png b/doc/user/project/img/protected_tags_list.png Binary files differnew file mode 100644 index 00000000000..c5e42dc0705 --- /dev/null +++ b/doc/user/project/img/protected_tags_list.png diff --git a/doc/user/project/img/protected_tags_page.png b/doc/user/project/img/protected_tags_page.png Binary files differnew file mode 100644 index 00000000000..3848d91ebd6 --- /dev/null +++ b/doc/user/project/img/protected_tags_page.png diff --git a/doc/user/project/img/protected_tags_permissions_dropdown.png b/doc/user/project/img/protected_tags_permissions_dropdown.png Binary files differnew file mode 100644 index 00000000000..9e0fc4e2a43 --- /dev/null +++ b/doc/user/project/img/protected_tags_permissions_dropdown.png diff --git a/doc/user/project/integrations/bamboo.md b/doc/user/project/integrations/bamboo.md index cad4757f287..1e28646bc97 100644 --- a/doc/user/project/integrations/bamboo.md +++ b/doc/user/project/integrations/bamboo.md @@ -51,9 +51,9 @@ service in GitLab. ## Troubleshooting -If builds are not triggered, these are a couple of things to keep in mind. +If builds are not triggered, ensure you entered the right GitLab IP address in +Bamboo under 'Trigger IP addresses'. + +>**Note:** +- Starting with GitLab 8.14.0, builds are triggered on push events. -1. Ensure you entered the right GitLab IP address in Bamboo under 'Trigger - IP addresses'. -1. Remember that GitLab only triggers builds on push events. A commit via the - web interface will not trigger CI currently. diff --git a/doc/user/project/integrations/img/jira_project_settings.png b/doc/user/project/integrations/img/jira_project_settings.png Binary files differnew file mode 100644 index 00000000000..cb6a6ba14ce --- /dev/null +++ b/doc/user/project/integrations/img/jira_project_settings.png diff --git a/doc/user/project/integrations/img/merge_request_performance.png b/doc/user/project/integrations/img/merge_request_performance.png Binary files differnew file mode 100644 index 00000000000..93b2626fed7 --- /dev/null +++ b/doc/user/project/integrations/img/merge_request_performance.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 differnew file mode 100644 index 00000000000..b5c9efc3dd9 --- /dev/null +++ b/doc/user/project/integrations/img/microsoft_teams_configuration.png diff --git a/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png b/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png Binary files differdeleted file mode 100644 index 1f5a44f8820..00000000000 --- a/doc/user/project/integrations/img/prometheus_environment_detail_with_metrics.png +++ /dev/null diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 4c64d1e0907..f611029afdc 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -101,7 +101,7 @@ in the table below. | `Project key` | The short identifier for your JIRA project, all uppercase, e.g., `PROJ`. | | `Username` | The user name created in [configuring JIRA step](#configuring-jira). | | `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | -| `JIRA issue transition` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). | +| `JIRA issue transition` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | After saving the configuration, your GitLab project will be able to interact with the linked JIRA project. @@ -157,6 +157,11 @@ the same goal: where `PROJECT-1` is the issue ID of the JIRA project. +>**Note:** +- Only commits and merges into the project's default branch (usually **master**) will + close an issue in Jira. You can change your projects default branch under + [project settings](img/jira_project_settings.png). + ### JIRA issue closing example Let's consider the following example: diff --git a/doc/user/project/integrations/kubernetes.md b/doc/user/project/integrations/kubernetes.md index 2a890acde4d..73fa83d72a8 100644 --- a/doc/user/project/integrations/kubernetes.md +++ b/doc/user/project/integrations/kubernetes.md @@ -48,8 +48,12 @@ GitLab CI build environment: - `KUBE_URL` - equal to the API URL - `KUBE_TOKEN` -- `KUBE_NAMESPACE` -- `KUBE_CA_PEM_FILE` - only present if a custom CA bundle was specified. Path to a file containing PEM data. +- `KUBE_NAMESPACE` - The Kubernetes namespace is auto-generated if not specified. + The default value is `<project_name>-<project_id>`. You can overwrite it to + use different one if needed, otherwise the `KUBE_NAMESPACE` variable will + receive the default value. +- `KUBE_CA_PEM_FILE` - only present if a custom CA bundle was specified. Path + to a file containing PEM data. - `KUBE_CA_PEM` (deprecated)- only if a custom CA bundle was specified. Raw PEM data. ## Web terminals @@ -60,7 +64,7 @@ to use terminals. Support is currently limited to the first container in the first pod of your environment. When enabled, the Kubernetes service adds [web terminal](../../../ci/environments.md#web-terminals) -support to your environments. This is based on the `exec` functionality found in +support to your [environments](../../../ci/environments.md). This is based on the `exec` functionality found in Docker and Kubernetes, so you get a new shell session within your existing containers. To use this integration, you should deploy to Kubernetes using the deployment variables above, ensuring any pods you create are labelled with diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md new file mode 100644 index 00000000000..eaad2d5138a --- /dev/null +++ b/doc/user/project/integrations/microsoft_teams.md @@ -0,0 +1,33 @@ +# Microsoft Teams service + +## On Microsoft Teams + +To enable Microsoft Teams integration you must create an incoming webhook integration on Microsoft Teams by following the steps described in this [document](https://msdn.microsoft.com/en-us/microsoft-teams/connectors). + +## On GitLab + +After you set up Microsoft Teams, it's time to set up GitLab. + +Navigate to the [Integrations page](project_services.md#accessing-the-project-services) +and select the **Microsoft Teams Notification** service to configure it. +There, you will see a checkbox with the following events that can be triggered: + +- Push +- Issue +- Confidential issue +- Merge request +- Note +- Tag push +- Pipeline +- Wiki page + +At the end fill in your Microsoft Teams details: + +| Field | Description | +| ----- | ----------- | +| **Webhook** | The incoming webhook URL which you have to setup on Microsoft Teams. | +| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | + +After you are all done, click **Save changes** for the changes to take effect. + + diff --git a/doc/user/project/integrations/project_services.md b/doc/user/project/integrations/project_services.md index 25400633de5..31baea507d7 100644 --- a/doc/user/project/integrations/project_services.md +++ b/doc/user/project/integrations/project_services.md @@ -47,9 +47,10 @@ Click on the service links to see further configuration instructions and details | [Kubernetes](kubernetes.md) | A containerized deployment service | | [Mattermost slash commands](mattermost_slash_commands.md) | Mattermost chat and ChatOps slash commands | | [Mattermost Notifications](mattermost.md) | Receive event notifications in Mattermost | +| [Microsoft teams](microsoft_teams.md) | Receive notifications for actions that happen on GitLab into a room on Microsoft Teams using Office 365 Connectors | | Pipelines emails | Email the pipeline status to a list of recipients | -| [Slack Notifications](slack.md) | Receive event notifications in Slack | -| [Slack slash commands](slack_slash_commands.md) | Slack chat and ChatOps slash commands | +| [Slack Notifications](slack.md) | Send GitLab events (e.g. issue created) to Slack as notifications | +| [Slack slash commands](slack_slash_commands.md) | Use slash commands in Slack to control GitLab | | PivotalTracker | Project Management Software (Source Commits Endpoint) | | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps | | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 12d7700176c..d3fb5916dc6 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -17,6 +17,7 @@ the settings page with a default template. To configure the template, see the Integration with Prometheus requires the following: 1. GitLab 9.0 or higher +1. The [Kubernetes integration must be enabled][kube] on your project 1. Your app must be deployed on [Kubernetes][] 1. Prometheus must be configured to collect Kubernetes metrics 1. Each metric must be have a label to indicate the environment @@ -159,24 +160,33 @@ The queries utilized by GitLab are shown in the following table. ## Monitoring CI/CD Environments Once configured, GitLab will attempt to retrieve performance metrics for any -environment which has had a successful deployment. If monitoring data was -successfully retrieved, a metrics button will appear on the environment's -detail page. +environment which has had a successful deployment. - +[Learn more about monitoring environments.](../../../ci/environments.md#monitoring-environments) -Clicking on the metrics button will display a new page, showing up to the last -8 hours of performance data. It may take a minute or two for data to appear -after initial deployment. +## Determining the performance impact of a merge + +> [Introduced][ce-10408] in GitLab 9.2. + +Developers can view the performance impact of their changes within the merge +request workflow. When a source branch has been deployed to an environment, a +sparkline will appear showing the average memory consumption of the app. The dot +indicates when the current changes were deployed, with up to 30 minutes of +performance data displayed before and after. The sparkline will be updated after +each commit has been deployed. + +Once merged and the target branch has been redeployed, the sparkline will switch +to show the new environments this revision has been deployed to. + +Performance data will be available for the duration it is persisted on the +Prometheus server. + + ## Troubleshooting -If the metrics button is not appearing, then one of a few issues may be -occurring: +If the "Attempting to load performance data" screen continues to appear, it could be due to: -- GitLab is not able to reach the Prometheus server. A test request can be sent - to the Prometheus server from the [Prometheus Service](#configuration-in-gitlab) - configuration screen. - No successful deployments have occurred to this environment. - Prometheus does not have performance data for this environment, or the metrics are not labeled correctly. To test this, connect to the Prometheus server and @@ -185,6 +195,7 @@ occurring: [autodeploy]: ../../../ci/autodeploy/index.md [kubernetes]: https://kubernetes.io +[kube]: ./kubernetes.md [prometheus-k8s-sd]: https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config> [prometheus]: https://prometheus.io [gitlab-prometheus-k8s-monitor]: ../../../administration/monitoring/prometheus/index.md#configuring-prometheus-to-monitor-kubernetes @@ -193,4 +204,5 @@ occurring: [gitlab.com-ip-range]: https://gitlab.com/gitlab-com/infrastructure/issues/434 [ci-environment-slug]: https://docs.gitlab.com/ce/ci/variables/#predefined-variables-environment-variables [ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935 +[ce-10408]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10408 [promgldocs]: ../../../administration/monitoring/prometheus/index.md diff --git a/doc/user/project/integrations/slack.md b/doc/user/project/integrations/slack.md index e8b238351ca..af4ca35a215 100644 --- a/doc/user/project/integrations/slack.md +++ b/doc/user/project/integrations/slack.md @@ -1,51 +1,26 @@ # Slack Notifications Service -## On Slack +The Slack Notifications Service allows your GitLab project to send events (e.g. issue created) to your existing Slack team as notifications. This requires configurations in both Slack and GitLab. -To enable Slack integration you must create an incoming webhook integration on -Slack: +> Note: You can also use Slack slash commands to control GitLab inside Slack. This is the separately configured [Slack slash commands](slack_slash_commands.md). -1. [Sign in to Slack](https://slack.com/signin) -1. Visit [Incoming WebHooks](https://my.slack.com/services/new/incoming-webhook/) -1. Choose the channel name you want to send notifications to. -1. Click **Add Incoming WebHooks Integration** -1. Copy the **Webhook URL**, we'll need this later for GitLab. +## Slack Configuration -## On GitLab +1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook/). +1. Select the Slack channel where notifications will be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration. +1. Copy the **Webhook URL**, which we'll use later in the GitLab configuration. -After you set up Slack, it's time to set up GitLab. +## GitLab Configuration -Navigate to the [Integrations page](project_services.md#accessing-the-project-services) -and select the **Slack notifications** service to configure it. -There, you will see a checkbox with the following events that can be triggered: +1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings, i.e. **Project > Settings > Integrations**. +1. Select the **Slack notifications** project service to configure it. +1. Check the **Active** checkbox to turn on the service. +1. Check the checkboxes corresponding to the GitLab events you want to send to Slack as a notification. +1. For each event, optionally enter the Slack channel where you want to send the event. (Do _not_ include the `#` symbol.) If left empty, the event will be sent to the default channel that you configured in the Slack Configuration step. +1. Paste the **Webhook URL** that you copied from the Slack Configuration step. +1. Optionally customize the Slack bot username that will be sending the notifications. +1. Configure the remaining options and click `Save changes`. -- Push -- Issue -- Confidential issue -- Merge request -- Note -- Tag push -- Pipeline -- Wiki page +Your Slack team will now start receiving GitLab event notifications as configured. -Below each of these event checkboxes, you have an input field to enter -which Slack channel you want to send that event message. Enter your preferred channel name **without** the hash sign (`#`). - -At the end, fill in your Slack details: - -| Field | Description | -| ----- | ----------- | -| **Webhook** | The [incoming webhook URL][slackhook] which you have to setup on Slack. | -| **Username** | Optional username which can be on messages sent to Slack. Fill this in if you want to change the username of the bot. | -| **Notify only broken pipelines** | If you choose to enable the **Pipeline** event and you want to be only notified about failed pipelines. | - -After you are all done, click **Save changes** for the changes to take effect. - ->**Note:** -You can set "branch,pushed,Compare changes" as highlight words on your Slack -profile settings, so that you can be aware of new commits when somebody pushes -them. - - - -[slackhook]: https://my.slack.com/services/new/incoming-webhook +
\ No newline at end of file diff --git a/doc/user/project/integrations/slack_slash_commands.md b/doc/user/project/integrations/slack_slash_commands.md index 56f1ba7311e..54e0ee611cb 100644 --- a/doc/user/project/integrations/slack_slash_commands.md +++ b/doc/user/project/integrations/slack_slash_commands.md @@ -2,23 +2,22 @@ > Introduced in GitLab 8.15 -Slack commands give users an extra interface to perform common operations -from the chat environment. This allows one to, for example, create an issue as -soon as the idea was discussed in chat. -For all available commands try the help subcommand, for example: `/gitlab help`, -all review the [full list of commands](../../../integration/chat_commands.md). +Slack slash commands (also known as chat commmands) allow you to control GitLab and view content right inside Slack, without having to leave it. This requires configurations in both Slack and GitLab. -## Prerequisites - -A [team](https://get.slack.help/hc/en-us/articles/217608418-Creating-a-team) in -Slack should be created beforehand, GitLab cannot create it for you. +> Note: GitLab can also send events (e.g. issue created) to Slack as notifications. This is the separately configured [Slack Notifications Service](slack.md). ## Configuration -Go to your project's [Integrations page](project_services.md#accessing-the-project-services) -and select the **Slack slash commands** service to configure it. +1. Slack slash commands are scoped to a project. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings, i.e. **Project > Settings > Integrations**. +1. Select the **Slack slash commands** project service to configure it. This page contains required information to complete the configuration in Slack. Leave this browser tab open. +1. Open a new browser tab and sign in to your Slack team. [Start a new Slash Commands integration](https://my.slack.com/services/new/slash-commands). +1. Enter a trigger term. We suggest you use the project name. Click **Add Slash Command Integration**. +1. Complete the rest of the fields in the Slack configuration page using information from the GitLab browser tab. In particular, the URL needs to be copied and pasted. Click **Save Integration** to complete the configuration in Slack. +1. While still on the Slack configuration page, copy the **token**. Go back to the GitLab browser tab and paste in the **token**. +1. Check the **Active** checkbox and click **Save changes** to complete the configuration in GitLab.  -Once you've followed the instructions, mark the service as active and insert the token -you've received from Slack. After saving the service you are good to go! +## Usage + +You can now use the [Slack slash commands](../../../integration/chat_commands.md).
\ No newline at end of file diff --git a/doc/user/project/integrations/webhooks.md b/doc/user/project/integrations/webhooks.md index dbdc93a77a8..48d49c5d40c 100644 --- a/doc/user/project/integrations/webhooks.md +++ b/doc/user/project/integrations/webhooks.md @@ -74,6 +74,7 @@ X-Gitlab-Event: Push Hook "checkout_sha": "da1560886d4f094c3e6c9ef40349f7d38b5d27d7", "user_id": 4, "user_name": "John Smith", + "user_username": "jsmith", "user_email": "john@example.com", "user_avatar": "https://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=8://s.gravatar.com/avatar/d4c74594d841139328695756648b6bd6?s=80", "project_id": 15, @@ -232,6 +233,7 @@ X-Gitlab-Event: Issue Hook "object_attributes": { "id": 301, "title": "New API: create/update/delete file", + "assignee_ids": [51], "assignee_id": 51, "author_id": 51, "project_id": 14, @@ -246,6 +248,11 @@ X-Gitlab-Event: Issue Hook "url": "http://example.com/diaspora/issues/23", "action": "open" }, + "assignees": [{ + "name": "User1", + "username": "user1", + "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=40\u0026d=identicon" + }], "assignee": { "name": "User1", "username": "user1", @@ -265,6 +272,9 @@ X-Gitlab-Event: Issue Hook }] } ``` + +**Note**: `assignee` and `assignee_id` keys are deprecated and now show the first assignee only. + ### Comment events Triggered when a new comment is made on commits, merge requests, issues, and code snippets. @@ -544,6 +554,7 @@ X-Gitlab-Event: Note Hook "issue": { "id": 92, "title": "test", + "assignee_ids": [], "assignee_id": null, "author_id": 1, "project_id": 5, @@ -559,6 +570,8 @@ X-Gitlab-Event: Note Hook } ``` +**Note**: `assignee_id` field is deprecated and now shows the first assignee only. + #### Comment on code snippet **Request header**: diff --git a/doc/user/project/issues/closing_issues.md b/doc/user/project/issues/closing_issues.md new file mode 100644 index 00000000000..dcfa5ff59b2 --- /dev/null +++ b/doc/user/project/issues/closing_issues.md @@ -0,0 +1,59 @@ +# Closing Issues + +Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. + +## Directly + +Whenever you decide that's no longer need for that issue, +close the issue using the close button: + + + +## Via Merge Request + +When a merge request resolves the discussion over an issue, you can +make it close that issue(s) when merged. + +All you need is to use a [keyword](automatic_issue_closing.md) +accompanying the issue number, add to the description of that MR. + +In this example, the keyword "closes" prefixing the issue number will create a relationship +in such a way that the merge request will close the issue when merged. + +Mentioning various issues in the same line also works for this purpose: + +```md +Closes #333, #444, #555 and #666 +``` + +If the issue is in a different repository rather then the MR's, +add the full URL for that issue(s): + +```md +Closes #333, #444, and https://gitlab.com/<username>/<projectname>/issues/<xxx> +``` + +All the following keywords will produce the same behaviour: + +- Close, Closes, Closed, Closing, close, closes, closed, closing +- Fix, Fixes, Fixed, Fixing, fix, fixes, fixed, fixing +- Resolve, Resolves, Resolved, Resolving, resolve, resolves, resolved, resolving + + + +If you use any other word before the issue number, the issue and the MR will +link to each other, but the MR will NOT close the issue(s) when merged. + + + +## From the Issue Board + +You can close an issue from [Issue Boards](../issue_board.md) by draging an issue card +from its list and dropping into **Closed**. + + + +## Customizing the issue closing patern + +Alternatively, a GitLab **administrator** can +[customize the issue closing patern](../../../administration/issue_closing_pattern.md). diff --git a/doc/user/project/issues/create_new_issue.md b/doc/user/project/issues/create_new_issue.md new file mode 100644 index 00000000000..9af088374a1 --- /dev/null +++ b/doc/user/project/issues/create_new_issue.md @@ -0,0 +1,38 @@ +# Create a new Issue + +Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. + +When you create a new issue, you'll be prompted to fill in +the information illustrated on the image below. + + + +Read through the [issues functionalities documentation](issues_functionalities.md#issues-functionalities) +to understand these fields one by one. + +## New issue from the Issue Tracker + +Navigate to your **Project's Dashboard** > **Issues** > **New Issue** to create a new issue: + + + +## New issue from an opened issue + +From an **opened issue** in your project, click **New Issue** to create a new +issue in the same project: + + + +## New issue from the project's dashboard + +From your **Project's Dashboard**, click the plus sign (**+**) to open a dropdown +menu with a few options. Select **New Issue** to create an issue in that project: + + + +## New issue from the Issue Board + +From an Issue Board, create a new issue by clicking on the plus sign (**+**) on the top of a list. +It opens a new issue for that project labeled after its respective list. + + diff --git a/doc/user/project/issues/crosslinking_issues.md b/doc/user/project/issues/crosslinking_issues.md new file mode 100644 index 00000000000..5cc7ea383ae --- /dev/null +++ b/doc/user/project/issues/crosslinking_issues.md @@ -0,0 +1,63 @@ +# Crosslinking Issues + +Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. + +## From Commit Messages + +Every time you mention an issue in your commit message, you're creating +a relationship between the two stages of the development workflow: the +issue itself and the first commit related to that issue. + +If the issue and the code you're committing are both in the same project, +you simply add `#xxx` to the commit message, where `xxx` is the issue number. +If they are not in the same project, you can add the full URL to the issue +(`https://gitlab.com/<username>/<projectname>/issues/<xxx>`). + +```shell +git commit -m "this is my commit message. Ref #xxx" +``` + +or + +```shell +git commit -m "this is my commit message. Related to https://gitlab.com/<username>/<projectname>/issues/<xxx>" +``` + +Of course, you can replace `gitlab.com` with the URL of your own GitLab instance. + +**Note:** Linking your first commit to your issue is going to be relevant +for tracking your process far ahead with +[GitLab Cycle Analytics](https://about.gitlab.com/features/cycle-analytics/)). +It will measure the time taken for planning the implementation of that issue, +which is the time between creating an issue and making the first commit. + +## From Related Issues + +Mentioning related issues in merge requests and other issues is useful +for your team members and collaborators to know that there are opened +issues around that same idea. + +You do that as explained above, when +[mentioning an issue from a commit message](#from-commit-messages). + +When mentioning the issue "A" in a issue "B", the issue "A" will also +display a notification in its tracker. The same is valid for mentioning +issues in merge requests. + + + +## From Merge Requests + +Mentioning issues in merge request comments work exactly the same way +they do for [related issues](#from-related-issues). + +When you mention an issue in a merge request description, you can either +[close the issue as soon as the merge request is merged](closing_issues.md#via-merge-request), +or simply link both issue and merge request as described in the +[closing issues documentation](closing_issues.md#from-related-issues). + + + +### Close an issue by merging a merge request + +To [close an issue when a merge request is merged](closing_issues.md#via-merge-request), use the [automatic issue closing patern](automatic_issue_closing.md). diff --git a/doc/user/project/issues/due_dates.md b/doc/user/project/issues/due_dates.md index b516d47ffa3..e0c405353ce 100644 --- a/doc/user/project/issues/due_dates.md +++ b/doc/user/project/issues/due_dates.md @@ -2,6 +2,8 @@ > [Introduced][ce-3614] in GitLab 8.7. +Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. + Due dates can be used in issues to keep track of deadlines and make sure features are shipped on time. Due dates require at least [Reporter permissions][permissions] to be able to edit them. On the contrary, they can be seen by everybody. @@ -22,8 +24,8 @@ Changes are saved immediately. ## Making use of due dates -Issues that have a due date can be distinctively seen in the issues index page -with a calendar icon next to them. Issues where the date is past due will have +Issues that have a due date can be distinctively seen in the issue tracker +displaying a date next to them. Issues where the date is overdue will have the icon and the date colored red. You can sort issues by those that are _Due soon_ or _Due later_ from the dropdown menu in the right. diff --git a/doc/user/project/issues/img/button_close_issue.png b/doc/user/project/issues/img/button_close_issue.png Binary files differnew file mode 100755 index 00000000000..8fb2e23f58a --- /dev/null +++ b/doc/user/project/issues/img/button_close_issue.png diff --git a/doc/user/project/issues/img/close_issue_from_board.gif b/doc/user/project/issues/img/close_issue_from_board.gif Binary files differnew file mode 100644 index 00000000000..4814b42687b --- /dev/null +++ b/doc/user/project/issues/img/close_issue_from_board.gif diff --git a/doc/user/project/issues/img/closing_and_related_issues.png b/doc/user/project/issues/img/closing_and_related_issues.png Binary files differnew file mode 100755 index 00000000000..c6543e85fdb --- /dev/null +++ b/doc/user/project/issues/img/closing_and_related_issues.png diff --git a/doc/user/project/issues/img/confidential_issues_create.png b/doc/user/project/issues/img/confidential_issues_create.png Binary files differindex d259255599d..0a141eb39f8 100644..100755 --- a/doc/user/project/issues/img/confidential_issues_create.png +++ b/doc/user/project/issues/img/confidential_issues_create.png diff --git a/doc/user/project/issues/img/confidential_issues_index_page.png b/doc/user/project/issues/img/confidential_issues_index_page.png Binary files differindex 042461e2451..e4b492a2769 100644..100755 --- a/doc/user/project/issues/img/confidential_issues_index_page.png +++ b/doc/user/project/issues/img/confidential_issues_index_page.png diff --git a/doc/user/project/issues/img/confidential_issues_issue_page.png b/doc/user/project/issues/img/confidential_issues_issue_page.png Binary files differindex b3568e9303a..f04ec8ff32b 100644..100755 --- a/doc/user/project/issues/img/confidential_issues_issue_page.png +++ b/doc/user/project/issues/img/confidential_issues_issue_page.png diff --git a/doc/user/project/issues/img/confidential_issues_search_guest.png b/doc/user/project/issues/img/confidential_issues_search_guest.png Binary files differindex b85de90b4d5..dc1b4ba8ad7 100644..100755 --- a/doc/user/project/issues/img/confidential_issues_search_guest.png +++ b/doc/user/project/issues/img/confidential_issues_search_guest.png diff --git a/doc/user/project/issues/img/confidential_issues_search_master.png b/doc/user/project/issues/img/confidential_issues_search_master.png Binary files differindex bf2b9428875..fc01f4da9db 100644..100755 --- a/doc/user/project/issues/img/confidential_issues_search_master.png +++ b/doc/user/project/issues/img/confidential_issues_search_master.png diff --git a/doc/user/project/issues/img/confidential_issues_system_notes.png b/doc/user/project/issues/img/confidential_issues_system_notes.png Binary files differindex 4005f9350f7..82e0dd8e85e 100644..100755 --- a/doc/user/project/issues/img/confidential_issues_system_notes.png +++ b/doc/user/project/issues/img/confidential_issues_system_notes.png diff --git a/doc/user/project/issues/img/due_dates_create.png b/doc/user/project/issues/img/due_dates_create.png Binary files differindex d2fe1172bab..ece35d44213 100644..100755 --- a/doc/user/project/issues/img/due_dates_create.png +++ b/doc/user/project/issues/img/due_dates_create.png diff --git a/doc/user/project/issues/img/due_dates_edit_sidebar.png b/doc/user/project/issues/img/due_dates_edit_sidebar.png Binary files differindex 6b37150e7db..d1c7d1eb7e9 100644..100755 --- a/doc/user/project/issues/img/due_dates_edit_sidebar.png +++ b/doc/user/project/issues/img/due_dates_edit_sidebar.png diff --git a/doc/user/project/issues/img/due_dates_issues_index_page.png b/doc/user/project/issues/img/due_dates_issues_index_page.png Binary files differindex defcd5eca39..94679436b32 100644..100755 --- a/doc/user/project/issues/img/due_dates_issues_index_page.png +++ b/doc/user/project/issues/img/due_dates_issues_index_page.png diff --git a/doc/user/project/issues/img/due_dates_todos.png b/doc/user/project/issues/img/due_dates_todos.png Binary files differindex 92c9fd4021b..4c124c97f67 100644..100755 --- a/doc/user/project/issues/img/due_dates_todos.png +++ b/doc/user/project/issues/img/due_dates_todos.png diff --git a/doc/user/project/issues/img/issue_board.png b/doc/user/project/issues/img/issue_board.png Binary files differnew file mode 100755 index 00000000000..1759b28a9ef --- /dev/null +++ b/doc/user/project/issues/img/issue_board.png diff --git a/doc/user/project/issues/img/issue_template.png b/doc/user/project/issues/img/issue_template.png Binary files differnew file mode 100755 index 00000000000..c63229a4af2 --- /dev/null +++ b/doc/user/project/issues/img/issue_template.png diff --git a/doc/user/project/issues/img/issue_tracker.png b/doc/user/project/issues/img/issue_tracker.png Binary files differnew file mode 100755 index 00000000000..ab25cb64d13 --- /dev/null +++ b/doc/user/project/issues/img/issue_tracker.png diff --git a/doc/user/project/issues/img/issues_main_view.png b/doc/user/project/issues/img/issues_main_view.png Binary files differnew file mode 100644 index 00000000000..4faa42e40ee --- /dev/null +++ b/doc/user/project/issues/img/issues_main_view.png diff --git a/doc/user/project/issues/img/issues_main_view_numbered.jpg b/doc/user/project/issues/img/issues_main_view_numbered.jpg Binary files differnew file mode 100644 index 00000000000..4b5d7fba459 --- /dev/null +++ b/doc/user/project/issues/img/issues_main_view_numbered.jpg diff --git a/doc/user/project/issues/img/mention_in_issue.png b/doc/user/project/issues/img/mention_in_issue.png Binary files differnew file mode 100755 index 00000000000..c762a812138 --- /dev/null +++ b/doc/user/project/issues/img/mention_in_issue.png diff --git a/doc/user/project/issues/img/mention_in_merge_request.png b/doc/user/project/issues/img/mention_in_merge_request.png Binary files differnew file mode 100755 index 00000000000..681e086d6e0 --- /dev/null +++ b/doc/user/project/issues/img/mention_in_merge_request.png diff --git a/doc/user/project/issues/img/merge_request_closes_issue.png b/doc/user/project/issues/img/merge_request_closes_issue.png Binary files differnew file mode 100755 index 00000000000..6fd27738843 --- /dev/null +++ b/doc/user/project/issues/img/merge_request_closes_issue.png diff --git a/doc/user/project/issues/img/new_issue.png b/doc/user/project/issues/img/new_issue.png Binary files differnew file mode 100755 index 00000000000..e72ac49d6b9 --- /dev/null +++ b/doc/user/project/issues/img/new_issue.png diff --git a/doc/user/project/issues/img/new_issue_from_issue_board.png b/doc/user/project/issues/img/new_issue_from_issue_board.png Binary files differnew file mode 100755 index 00000000000..9c2b3ff50fa --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_issue_board.png diff --git a/doc/user/project/issues/img/new_issue_from_open_issue.png b/doc/user/project/issues/img/new_issue_from_open_issue.png Binary files differnew file mode 100755 index 00000000000..2aed5372830 --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_open_issue.png diff --git a/doc/user/project/issues/img/new_issue_from_projects_dashboard.png b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png Binary files differnew file mode 100755 index 00000000000..cddf36b7457 --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_projects_dashboard.png diff --git a/doc/user/project/issues/img/new_issue_from_tracker_list.png b/doc/user/project/issues/img/new_issue_from_tracker_list.png Binary files differnew file mode 100755 index 00000000000..7e5413f0b7d --- /dev/null +++ b/doc/user/project/issues/img/new_issue_from_tracker_list.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md new file mode 100644 index 00000000000..9598cb801be --- /dev/null +++ b/doc/user/project/issues/index.md @@ -0,0 +1,104 @@ +# GitLab Issues Documentation + +The GitLab Issue Tracker is an advanced and complete tool +for tracking the evolution of a new idea or the process +of solving a problem. + +It allows you, your team, and your collaborators to share +and discuss proposals, before and while implementing them. + +Issues and the GitLab Issue Tracker are available in all +[GitLab Products](https://about.gitlab.com/products/) as +part of the [GitLab Workflow](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/). + +## Use-Cases + +Issues can have endless applications. Just to exemplify, these are +some cases for which creating issues are most used: + +- Discussing the implementation of a new idea +- Submitting feature proposals +- Asking questions +- Reporting bugs and malfunction +- Obtaining support +- Elaborating new code implementations + +See also the blog post [Always start a discussion with an issue](https://about.gitlab.com/2016/03/03/start-with-an-issue/). + +## Issue Tracker + +The issue tracker is the collection of opened and closed issues created in a project. + + + +Find the issue tracker by navigating to your **Project's Dashboard** > **Issues**. + +## GitLab Issues Functionalities + +The image bellow illustrates how an issue looks like: + + + +Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md). + +## New Issue + +Read through the [documentation on creating issues](create_new_issue.md). + +## Closing issues + +Read through the distinct ways to [close issues](closing_issues.md) on GitLab. + +## Create a merge request from an issue + +Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md#18-new-merge-request). + +## Search for an issue + +Learn how to [find an issue](../../search/index.md) by searching for and filtering them. + +## Advanced features + +### Confidential Issues + +Whenever you want to keep the discussion presented in a +issue within your team only, you can make that +[issue confidential](confidential_issues.md). Even if your project +is public, that issue will be preserved. The browser will +respond with a 404 error whenever someone who is not a project +member with at least [Reporter level](../../permissions.md#project) tries to +access that issue's URL. + +Learn more about them on the [confidential issues documentation](confidential_issues.md). + +### Issue templates + +Create templates for every new issue. They will be available from +the dropdown menu **Choose a template** when you create a new issue: + + + +Learn more about them on the [issue templates documentation](../../project/description_templates.md#creating-issue-templates). + +### Crosslinking issues + +Learn more about [crosslinking](crosslinking_issues.md) issues and merge requests. + +### GitLab Issue Board + +The [GitLab Issue Board](https://about.gitlab.com/features/issueboard/) is a way to +enhance your workflow by organizing and prioritizing issues in GitLab. + + + +Find GitLab Issue Boards by navigating to your **Project's Dashboard** > **Issues** > **Board**. + +Read through the documentation for [Issue Boards](../issue_board.md) +to find out more about this feature. + +[Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards) +are available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/). + +### Issue's API + +Read through the [API documentation](../../../api/issues.md). diff --git a/doc/user/project/issues/issues_functionalities.md b/doc/user/project/issues/issues_functionalities.md new file mode 100644 index 00000000000..ba843201e1a --- /dev/null +++ b/doc/user/project/issues/issues_functionalities.md @@ -0,0 +1,176 @@ +# GitLab Issues Functionalities + +Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. + +## Issues Functionalities + +The image bellow illustrates how an issue looks like: + + + +You can find all the information on that issue on one screen. + +### Issue screen + +An issue starts with its status (open or closed), followed by its author, +and includes many other functionalities, numbered on the image above to +explain what they mean, one by one. + +Many of the elements of the issue screen refresh automatically, such as the title and description, when they are changed by another user. +Comments and system notes also appear automatically in response to various actions and content updates. + +#### 1. New Issue, close issue, edit + +- New issue: create a new issue in the same project +- Close issue: close this issue +- Edit: edit the same fields available when you create an issue. + +#### 2. Todos + +- Add todo: add that issue to your [GitLab Todo](../../../workflow/todos.html) list +- Mark done: mark that issue as done (reflects on the Todo list) + +#### 3. Assignee + +Whenever someone starts to work on an issue, it can be assigned +to that person. The assignee can be changed as much as needed. +The idea is that the assignee is responsible for that issue until +it's reassigned to someone else to take it from there. + +> **Tip:** +if a user is not member of that project, it can only be +assigned to them if they created the issue themselves. + +##### 3.1. Multiple Assignees (EES/EEP) + +Issue Weights are only available in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/). + +Often multiple people likely work on the same issue together, +which can especially be difficult to track in large teams +where there is shared ownership of an issue. + +In GitLab Enterprise Edition, you can also select multiple assignees +to an issue. + +> **Note:** +Multiple Assignees was [introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/1904) +in [GitLab Enterprise Edition 9.2](https://about.gitlab.com/2017/05/22/gitlab-9-2-released/#multiple-assignees-for-issues). + +#### 4. Milestone + +- Select a [milestone](../milestones/index.md) to attribute that issue to. + +#### 5. Time Tracking (EES/EEP) + +This feature is available only in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/). + +- Estimate time: add an estimate time in which the issue will be implemented +- Spend: add the time spent on the implementation of that issue + +> **Note:** +both estimate and spend times are set via [GitLab Slash Commands](../slash_commands.md). + +Learn more on the [Time Tracking documentation](https://docs.gitlab.com/ee/workflow/time_tracking.html). + +#### 6. Due date + +When you work on a tight schedule, and it's important to +have a way to setup a deadline for implementations and for solving +problems. This can be facilitated by the [due date](due_dates.md)). Due dates +can be changed as many times as needed. + +#### 7. Labels + +Categorize issues by giving them [labels](../labels.md). They help to +organize team's workflows, once they enable you to work with the +[GitLab Issue Board](index.md#gitlab-issue-board). + +Group Labels, which allow you to use the same labels per +group of projects, can be also given to issues. They work exactly the same, +but they are immediately available to all projects in the group. + +> **Tip:** +if the label doesn't exist yet, when you click **Edit**, it opens a dropdown menu from which you can select **Create new label**. + +#### 8. Weight (EES/EEP) + +Issue Weights are only available in [GitLab Enterprise Edition](https://about.gitlab.com/gitlab-ee/). + +- Attribute a weight (in a 0 to 9 range) to that issue. Easy to complete +should weight 1 and very hard to complete should weight 9. + +Learn more on the [Issue Weight documentation](https://docs.gitlab.com/ee/workflow/issue_weight.html). + +#### 9. Participants + +- People involved in that issue (mentioned in the description or in the [discussion](../../discussions/index.md)). + +#### 10. Notifications + +- Subscribe: if you are not a participant of the discussion on that issue, but +want to receive notifications on each new input, subscribe to it. +- Unsubscribe: if you are receiving notifications on that issue but no +longer want to receive them, unsubscribe to it. + +Read more on the [notifications documentation](../../../workflow/notifications.md#issue-merge-request-events). + +#### 11. Reference + +- A quick "copy to clipboard" button to that issue's reference, `foo/bar#xxx`, where `foo` is the `username` or `groupname`, `bar` +is the `project-name`, and `xxx` is the issue number. + +#### 12. Title and description + +- Title: a plain text title describing the issue's subject. +- Description: a text field which fully supports [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +#### 13. @mentions + +- Mentions: you can either `@mention` a user or a group present in your +GitLab instance and they will be notified via todos and email, unless that +person has disabled all notifications in their profile settings. + +To change your [notification settings](../../../workflow/notifications.md) navigate to +**Profile Settings** > **Notifications** > **Global notification level** +and choose your preferences from the dropdown menu. + +> **Tip:** +Avoid mentioning `@all` in issues and merge requests, +as it sends an email notification +to all the members of that project's group, which can be +interpreted as spam. + +#### 14. Related Merge Requests + +- Any merge requests mentioned in that issue's description +or in the issue thread. + +#### 15. Award emoji + +- Award an emoji to that issue. + +> **Tip:** +Posting "+1" as comments in threads spam all +participants of that issue. Awarding an emoji is a way to let them +know you like it without spamming them. + +#### 16. Thread + +- Comments: collaborate to that issue by posting comments in its thread. +These text fields also fully support +[GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm). + +#### 17. Comment, start a discusion, or comment and close + +Once you wrote your comment, you can either: + +- Click "Comment" and your comment will be published. +- Click "Start discussion": start a thread within that issue's thread to discuss specific points. +- Click "Comment and close issue": post your comment and close that issue in one click. + +#### 18. New Merge Request + +- Create a new merge request (with a new source branch named after the issue) in one action. +The merge request will automatically close that issue as soon as merged. +- Optionally, you can just create a [new branch](../repository/web_editor.md#create-a-new-branch-from-an-issue) +named after that issue. diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index c759b7aaa4a..954454f7e7a 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -34,7 +34,7 @@ Keep track of the progress during a code review with resolving comments. Resolving comments prevents you from forgetting to address feedback and lets you hide discussions that are no longer relevant. -[Read more about resolving discussion comments in merge requests reviews.](merge_request_discussion_resolution.md) +[Read more about resolving discussion comments in merge requests reviews.](../../discussions/index.md) ## Resolve conflicts diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md index 230e957f045..200965875a1 100644 --- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md +++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md @@ -1,106 +1 @@ -# Merge Request discussion resolution - -> [Introduced][ce-5022] in GitLab 8.11. - -Discussion resolution helps keep track of progress during code review. -Resolving comments prevents you from forgetting to address feedback and lets you -hide discussions that are no longer relevant. - -!["A discussion between two people on a piece of code"][discussion-view] - -Comments and discussions can be resolved by anyone with at least Developer -access to the project, as well as by the author of the merge request. - -## Marking a comment or discussion as resolved - -You can mark a discussion as resolved by clicking the "Resolve discussion" -button at the bottom of the discussion. - -!["Resolve discussion" button][resolve-discussion-button] - -Alternatively, you can mark each comment as resolved individually. - -!["Resolve comment" button][resolve-comment-button] - -## Jumping between unresolved discussions - -When a merge request has a large number of comments it can be difficult to track -what remains unresolved. You can jump between unresolved discussions with the -Jump button next to the Reply field on a discussion. - -You can also jump to the first unresolved discussion from the button next to the -resolved discussions tracker. - -!["3/4 discussions resolved"][discussions-resolved] - -## Only allow merge requests to be merged if all discussions are resolved - -> [Introduced][ce-7125] in GitLab 8.14. - -You can prevent merge requests from being merged until all discussions are -resolved. - -Navigate to your project's settings page, select the -**Only allow merge requests to be merged if all discussions are resolved** check -box and hit **Save** for the changes to take effect. - - - -From now on, you will not be able to merge from the UI until all discussions -are resolved. - - - -## Move all unresolved discussions in a merge request to an issue - -> [Introduced][ce-8266] - -To continue all open discussions in a merge request, click the button **Resolve -all discussions in new issue** - - - -Alternatively, when your project only accepts merge requests when all discussions -are resolved, there will be an **open an issue to resolve them later** link in -the merge request-widget. - - - -This will prepare an issue with content referring to the merge request and -discussions. - - - -Hitting **Submit issue** will cause all discussions to be marked as resolved and -add a note referring to the newly created issue. - - - -You can now proceed to merge the merge request from the UI. - -## Moving a single discussion to a new issue - -> [Introduced][ce-8266] - -To create a new issue for a single discussion, you can use the **Resolve this -discussion in a new issue** button. - - - -This will direct you to a new issue prefilled with the content of the -discussion, similar to the issues created for delegating multiple -discussions at once. - - - -Saving the issue will mark the discussion as resolved and add a note -to the discussion referencing the new issue. - -[ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022 -[ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125 -[ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180 -[ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266 -[resolve-discussion-button]: img/resolve_discussion_button.png -[resolve-comment-button]: img/resolve_comment_button.png -[discussion-view]: img/discussion_view.png -[discussions-resolved]: img/discussions_resolved.png +This document was moved to [another location](../../discussions/index.md). diff --git a/doc/user/project/milestones/img/milestone_create.png b/doc/user/project/milestones/img/milestone_create.png Binary files differnew file mode 100644 index 00000000000..beb2caa897f --- /dev/null +++ b/doc/user/project/milestones/img/milestone_create.png diff --git a/doc/user/project/milestones/img/milestone_group_create.png b/doc/user/project/milestones/img/milestone_group_create.png Binary files differnew file mode 100644 index 00000000000..7aaa7c56c15 --- /dev/null +++ b/doc/user/project/milestones/img/milestone_group_create.png diff --git a/doc/user/project/milestones/index.md b/doc/user/project/milestones/index.md new file mode 100644 index 00000000000..a43a42a8fe8 --- /dev/null +++ b/doc/user/project/milestones/index.md @@ -0,0 +1,46 @@ +# Milestones + +Milestones allow you to organize issues and merge requests into a cohesive group, +optionally setting a due date. A common use is keeping track of an upcoming +software version. Milestones can be created per-project or per-group. + +## Creating a project milestone + +>**Note:** +You need [Master permissions](../../permissions.md) in order to create a milestone. + +You can find the milestones page under your project's **Issues ➔ Milestones**. +To create a new milestone, simply click the **New milestone** button when in the +milestones page. A milestone can have a title, a description and start/due dates. +Once you fill in all the details, hit the **Create milestone** button. + + + +## Creating a group milestone + +>**Note:** +You need [Master permissions](../../permissions.md) in order to create a milestone. + +You can create a milestone for several projects in the same group simultaneously. +On the group's **Issues ➔ Milestones** page, you will be able to see the status +of that milestone across all of the selected projects. To create a new milestone +for selected projects in the group, click the **New milestone** button. The +form is the same as when creating a milestone for a specific project with the +addition of the selection of the projects you want to inherit this milestone. + + + +## Special milestone filters + +In addition to the milestones that exist in the project or group, there are some +special options available when filtering by milestone: + +* **No Milestone** - only show issues or merge requests without a milestone. +* **Upcoming** - show issues or merge request that belong to the next open + milestone with a due date, by project. (For example: if project A has + milestone v1 due in three days, and project B has milestone v2 due in a week, + then this will show issues or merge requests from milestone v1 in project A + and milestone v2 in project B.) +* **Started** - show issues or merge requests from any milestone with a start + date less than today. Note that this can return results from several + milestones in the same project. diff --git a/doc/user/project/new_ci_build_permissions_model.md b/doc/user/project/new_ci_build_permissions_model.md index f846736028f..e9512497d6c 100644 --- a/doc/user/project/new_ci_build_permissions_model.md +++ b/doc/user/project/new_ci_build_permissions_model.md @@ -89,7 +89,7 @@ to steal the tokens of other jobs. ## Pipeline triggers -Since 9.0 [pipelnie triggers][triggers] do support the new permission model. +Since 9.0 [pipeline triggers][triggers] do support the new permission model. The new triggers do impersonate their associated user including their access to projects and their project permissions. To migrate trigger to use new permisison model use **Take ownership**. @@ -100,7 +100,7 @@ In versions before GitLab 8.12, all CI jobs would use the CI Runner's token to checkout project sources. The project's Runner's token was a token that you could find under the -project's **Settings > CI/CD Pipelines** and was limited to access only that +project's **Settings > Pipelines** and was limited to access only that project. It could be used for registering new specific Runners assigned to the project and to checkout project sources. diff --git a/doc/user/project/pages/getting_started_part_four.md b/doc/user/project/pages/getting_started_part_four.md index 50767095aa0..bd0cb437924 100644 --- a/doc/user/project/pages/getting_started_part_four.md +++ b/doc/user/project/pages/getting_started_part_four.md @@ -1,8 +1,9 @@ # GitLab Pages from A to Z: Part 4 -> **Type**: user guide || +> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || > **Level**: intermediate || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || +> **Publication date:** 2017/02/22 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) diff --git a/doc/user/project/pages/getting_started_part_one.md b/doc/user/project/pages/getting_started_part_one.md index e92549aa0df..2f104c7becc 100644 --- a/doc/user/project/pages/getting_started_part_one.md +++ b/doc/user/project/pages/getting_started_part_one.md @@ -1,15 +1,16 @@ # GitLab Pages from A to Z: Part 1 -> **Type**: user guide || +> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || > **Level**: beginner || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || +> **Publication date:** 2017/02/22 - **Part 1: Static sites and GitLab Pages domains** - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) - [Part 3: Setting Up Custom Domains - DNS Records and SSL/TLS Certificates](getting_started_part_three.md) - [Part 4: Creating and tweaking `.gitlab-ci.yml` for GitLab Pages](getting_started_part_four.md) -## GitLab Pages form A to Z +## GitLab Pages from A to Z This is a comprehensive guide, made for those who want to publish a website with GitLab Pages but aren't familiar with diff --git a/doc/user/project/pages/getting_started_part_three.md b/doc/user/project/pages/getting_started_part_three.md index 80f16e43e20..53fd1786cfa 100644 --- a/doc/user/project/pages/getting_started_part_three.md +++ b/doc/user/project/pages/getting_started_part_three.md @@ -1,8 +1,9 @@ # GitLab Pages from A to Z: Part 3 -> **Type**: user guide || +> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || > **Level**: beginner || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || +> **Publication date:** 2017/02/22 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - [Part 2: Quick start guide - Setting up GitLab Pages](getting_started_part_two.md) diff --git a/doc/user/project/pages/getting_started_part_two.md b/doc/user/project/pages/getting_started_part_two.md index 578ad13f5df..64de0463dad 100644 --- a/doc/user/project/pages/getting_started_part_two.md +++ b/doc/user/project/pages/getting_started_part_two.md @@ -1,8 +1,9 @@ # GitLab Pages from A to Z: Part 2 -> **Type**: user guide || +> **Article [Type](../../../development/writing_documentation.html#types-of-technical-articles)**: user guide || > **Level**: beginner || -> **Author**: [Marcia Ramos](https://gitlab.com/marcia) +> **Author**: [Marcia Ramos](https://gitlab.com/marcia) || +> **Publication date:** 2017/02/22 - [Part 1: Static sites and GitLab Pages domains](getting_started_part_one.md) - **Part 2: Quick start guide - Setting up GitLab Pages** @@ -56,7 +57,7 @@ created for the steps below.  -1. Enable Shared Runners for your fork: navigate to your **Project**'s **Settings** > **CI/CD Pipelines** +1. Enable Shared Runners for your fork: navigate to your **Project**'s **Settings** > **Pipelines** 1. Trigger a build (push a change to any file) 1. As soon as the build passes, your website will have been deployed with GitLab Pages. Your website URL will be available under your **Project**'s **Settings** > **Pages** diff --git a/doc/user/project/pipelines/img/pipeline_schedules_list.png b/doc/user/project/pipelines/img/pipeline_schedules_list.png Binary files differnew file mode 100644 index 00000000000..50d9d184b05 --- /dev/null +++ b/doc/user/project/pipelines/img/pipeline_schedules_list.png diff --git a/doc/user/project/pipelines/img/pipeline_schedules_new_form.png b/doc/user/project/pipelines/img/pipeline_schedules_new_form.png Binary files differnew file mode 100644 index 00000000000..ea5394fa8a6 --- /dev/null +++ b/doc/user/project/pipelines/img/pipeline_schedules_new_form.png diff --git a/doc/user/project/pipelines/img/pipeline_schedules_ownership.png b/doc/user/project/pipelines/img/pipeline_schedules_ownership.png Binary files differnew file mode 100644 index 00000000000..31ed83abb4d --- /dev/null +++ b/doc/user/project/pipelines/img/pipeline_schedules_ownership.png diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index 5ce99843301..151ee4728ad 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -41,6 +41,10 @@ For more examples on artifacts, follow the artifacts reference in ## Browsing job artifacts +>**Note:** +With GitLab 9.2, PDFs, images, videos and other formats can be previewed directly +in the job artifacts browser without the need to download them. + After a job finishes, if you visit the job's specific page, you can see that there are two buttons. One is for downloading the artifacts archive and the other for browsing its contents. diff --git a/doc/user/project/pipelines/schedules.md b/doc/user/project/pipelines/schedules.md new file mode 100644 index 00000000000..641876f948f --- /dev/null +++ b/doc/user/project/pipelines/schedules.md @@ -0,0 +1,62 @@ +# Pipeline Schedules + +> **Notes**: +- This feature was introduced in 9.1 as [Trigger Schedule][ce-10533]. +- In 9.2, the feature was [renamed to Pipeline Schedule][ce-10853]. +- Cron notation is parsed by [Rufus-Scheduler](https://github.com/jmettraux/rufus-scheduler). + +Pipeline schedules can be used to run pipelines only once, or for example every +month on the 22nd for a certain branch. + +## Using Pipeline schedules + +In order to schedule a pipeline: + +1. Navigate to your project's **Pipelines ➔ Schedules** and click the + **New Schedule** button. +1. Fill in the form +1. Hit **Save pipeline schedule** for the changes to take effect. + + + +>**Attention:** +The pipelines won't be executed precisely, because schedules are handled by +Sidekiq, which runs according to its interval. +See [advanced admin configuration](#advanced-admin-configuration) for more +information. + +In the **Schedules** index page you can see a list of the pipelines that are +scheduled to run. The next run is automatically calculated by the server GitLab +is installed on. + + + +## Taking ownership + +Pipelines are executed as a user, who owns a schedule. This influences what +projects and other resources the pipeline has access to. If a user does not own +a pipeline, you can take ownership by clicking the **Take ownership** button. +The next time a pipeline is scheduled, your credentials will be used. + + + +>**Note:** +When the owner of the schedule doesn't have the ability to create pipelines +anymore, due to e.g., being blocked or removed from the project, the schedule +is deactivated. Another user can take ownership and activate it, so the +schedule can be run again. + +## Advanced admin configuration + +The pipelines won't be executed precisely, because schedules are handled by +Sidekiq, which runs according to its interval. For example, if you set a +schedule to create a pipeline every minute (`* * * * *`) and the Sidekiq worker +runs on 00:00 and 12:00 every day (`0 */12 * * *`), only 2 pipelines will be +created per day. To change the Sidekiq worker's frequency, you have to edit the +`trigger_schedule_worker_cron` value in your `gitlab.rb` and restart GitLab. +For GitLab.com, you can check the [dedicated settings page][settings]. If you +don't have admin access to the server, ask your administrator. + +[ce-10533]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533 +[ce-10853]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10853 +[settings]: https://about.gitlab.com/gitlab-com/settings/#cron-jobs diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index c398ac2eb25..1b42c43cf8f 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -1,4 +1,4 @@ -# CI/CD pipelines settings +# Pipelines settings To reach the pipelines settings: @@ -6,7 +6,7 @@ To reach the pipelines settings:  -1. Select **CI/CD Pipelines** from the menu. +1. Select **Pipelines** from the menu. The following settings can be configured per project. @@ -60,6 +60,14 @@ anyone and those logged in respectively. If you wish to hide it so that only the members of the project or group have access to it, uncheck the **Public pipelines** checkbox and save the changes. +## Auto-cancel pending pipelines + +> [Introduced][ce-9362] in GitLab 9.1. + +If you want to auto-cancel all pending non-HEAD pipelines on branch, when +new pipeline will be created (after your git push or manually from UI), +check **Auto-cancel pending pipelines** checkbox and save the changes. + ## Badges In the pipelines settings page you can find pipeline status and test coverage @@ -111,3 +119,4 @@ into your `README.md`: [var]: ../../../ci/yaml/README.md#git-strategy [coverage report]: #test-coverage-parsing +[ce-9362]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9362 diff --git a/doc/user/project/protected_tags.md b/doc/user/project/protected_tags.md new file mode 100644 index 00000000000..0cb7aefdb2f --- /dev/null +++ b/doc/user/project/protected_tags.md @@ -0,0 +1,60 @@ +# Protected Tags + +> [Introduced][ce-10356] in GitLab 9.1. + +Protected Tags allow control over who has permission to create tags as well as preventing accidental update or deletion once created. Each rule allows you to match either an individual tag name, or use wildcards to control multiple tags at once. + +This feature evolved out of [Protected Branches](protected_branches.md) + +## Overview + +Protected tags will prevent anyone from updating or deleting the tag, as and will prevent creation of matching tags based on the permissions you have selected. By default, anyone without Master permission will be prevented from creating tags. + + +## Configuring protected tags + +To protect a tag, you need to have at least Master permission level. + +1. Navigate to the project's Settings -> Repository page + +  + +1. From the **Tag** dropdown menu, select the tag you want to protect or type and click `Create wildcard`. In the screenshot below, we chose to protect all tags matching `v*`. + +  + +1. From the `Allowed to create` dropdown, select who will have permission to create matching tags and then click `Protect`. + +  + +1. Once done, the protected tag will appear in the "Protected tags" list. + +  + +## Wildcard protected tags + +You can specify a wildcard protected tag, which will protect all tags +matching the wildcard. For example: + +| Wildcard Protected Tag | Matching Tags | +|------------------------+-------------------------------| +| `v*` | `v1.0.0`, `version-9.1` | +| `*-deploy` | `march-deploy`, `1.0-deploy` | +| `*gitlab*` | `gitlab`, `gitlab/v1` | +| `*` | `v1.0.1rc2`, `accidental-tag` | + + +Two different wildcards can potentially match the same tag. For example, +`*-stable` and `production-*` would both match a `production-stable` tag. +In that case, if _any_ of these protected tags have a setting like +"Allowed to create", then `production-stable` will also inherit this setting. + +If you click on a protected tag's name, you will be presented with a list of +all matching tags: + + + + +--- + +[ce-10356]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10356 "Protected Tags" diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 7a4f9f408f1..58d2fd76c61 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -27,7 +27,8 @@ with all their related data and be moved into a new GitLab instance. | GitLab version | Import/Export version | | -------- | -------- | -| 8.17.0 to current | 0.1.6 | +| 9.2.0 to current | 0.1.7 | +| 8.17.0 | 0.1.6 | | 8.13.0 | 0.1.5 | | 8.12.0 | 0.1.4 | | 8.10.3 | 0.1.3 | diff --git a/doc/user/project/slash_commands.md b/doc/user/project/slash_commands.md index 45176fde9db..08452ca75cd 100644 --- a/doc/user/project/slash_commands.md +++ b/doc/user/project/slash_commands.md @@ -36,3 +36,4 @@ do. | `/remove_time_spent` | Remove time spent | | `/target_branch <Branch Name>` | Set target branch for current merge request | | `/award :emoji:` | Toggle award for :emoji: | +| `/board_move ~column` | Move issue to column on the board | diff --git a/doc/user/project/wiki/img/wiki_create_home_page.png b/doc/user/project/wiki/img/wiki_create_home_page.png Binary files differnew file mode 100644 index 00000000000..f50f564034c --- /dev/null +++ b/doc/user/project/wiki/img/wiki_create_home_page.png diff --git a/doc/user/project/wiki/img/wiki_create_new_page.png b/doc/user/project/wiki/img/wiki_create_new_page.png Binary files differnew file mode 100644 index 00000000000..c19124a8923 --- /dev/null +++ b/doc/user/project/wiki/img/wiki_create_new_page.png diff --git a/doc/user/project/wiki/img/wiki_create_new_page_modal.png b/doc/user/project/wiki/img/wiki_create_new_page_modal.png Binary files differnew file mode 100644 index 00000000000..ece437967dc --- /dev/null +++ b/doc/user/project/wiki/img/wiki_create_new_page_modal.png diff --git a/doc/user/project/wiki/img/wiki_page_history.png b/doc/user/project/wiki/img/wiki_page_history.png Binary files differnew file mode 100644 index 00000000000..0e6af1b468d --- /dev/null +++ b/doc/user/project/wiki/img/wiki_page_history.png diff --git a/doc/user/project/wiki/img/wiki_sidebar.png b/doc/user/project/wiki/img/wiki_sidebar.png Binary files differnew file mode 100644 index 00000000000..59814e2a06e --- /dev/null +++ b/doc/user/project/wiki/img/wiki_sidebar.png diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md new file mode 100644 index 00000000000..e9ee1abc6c1 --- /dev/null +++ b/doc/user/project/wiki/index.md @@ -0,0 +1,97 @@ +# Wiki + +A separate system for documentation called Wiki, is built right into each +GitLab project. It is enabled by default on all new projects and you can find +it under **Wiki** in your project. + +Wikis are very convenient if you don't want to keep you documentation in your +repository, but you do want to keep it in the same project where your code +resides. + +You can create Wiki pages in the web interface or +[locally using Git](#adding-and-editing-wiki-pages-locally) since every Wiki is +a separate Git repository. + +>**Note:** +A [permission level][permissions] of **Guest** is needed to view a Wiki and +**Developer** is needed to create and edit Wiki pages. + +## First time creating the Home page + +The first time you visit a Wiki, you will be directed to create the Home page. +The Home page is necessary to be created since it serves as the landing page +when viewing a Wiki. You only have to fill in the **Content** section and click +**Create page**. You can always edit it later, so go ahead and write a welcome +message. + + + +## Creating a new wiki page + +Create a new page by clicking the **New page** button that can be found +in all wiki pages. You will be asked to fill in the page name from which GitLab +will create the path to the page. You can specify a full path for the new file +and any missing directories will be created automatically. + + + +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 +[Markdown features](../../markdown.md) are supported and for links there is +some [wiki specific](../../markdown.md#wiki-specific-markdown) behavior. + +>**Note:** +The wiki is based on a Git repository and contains only text files. Uploading +files via the web interface will upload them in GitLab itself, and they will +not be available if you clone the wiki repo locally. + +In the web interface the commit message is optional, but the GitLab Wiki is +based on Git and needs a commit message, so one will be created for you if you +do not enter one. + +When you're ready, click the **Create page** and the new page will be created. + + + +## Editing a wiki page + +To edit a page, simply click on the **Edit** button. From there on, you can +change its content. When done, click **Save changes** for the changes to take +effect. + +## Deleting a wiki page + +You can find the **Delete** button only when editing a page. Click on it and +confirm you want the page to be deleted. + +## Viewing a list of all created wiki pages + +Every wiki has a sidebar from which a short list of the created pages can be +found. The list is ordered alphabetically. + + + +If you have many pages, not all will be listed in the sidebar. Click on +**More pages** to see all of them. + +## Viewing the history of a wiki page + +The changes of a wiki page over time are recorded in the wiki's Git repository, +and you can view them by clicking the **Page history** button. + +From the history page you can see the revision of the page (Git commit SHA), its +author, the commit message, when it was last updated and the page markup format. +To see how a previous version of the page looked like, click on a revision +number. + + + +## Adding and editing wiki pages locally + +Since wikis are based on Git repositories, you can clone them locally and edit +them like you would do with every other Git repository. + +On the right sidebar, click on **Clone repository** and follow the on-screen +instructions. + +[permissions]: ../../permissions.md diff --git a/doc/user/search/img/issue_search_filter.png b/doc/user/search/img/issue_search_filter.png Binary files differnew file mode 100644 index 00000000000..f357abd6bac --- /dev/null +++ b/doc/user/search/img/issue_search_filter.png diff --git a/doc/user/search/img/issues_any_assignee.png b/doc/user/search/img/issues_any_assignee.png Binary files differnew file mode 100755 index 00000000000..2f902bcc66c --- /dev/null +++ b/doc/user/search/img/issues_any_assignee.png diff --git a/doc/user/search/img/issues_assigned_to_you.png b/doc/user/search/img/issues_assigned_to_you.png Binary files differnew file mode 100755 index 00000000000..36c670eedd5 --- /dev/null +++ b/doc/user/search/img/issues_assigned_to_you.png diff --git a/doc/user/search/img/issues_author.png b/doc/user/search/img/issues_author.png Binary files differnew file mode 100755 index 00000000000..792f9746db6 --- /dev/null +++ b/doc/user/search/img/issues_author.png diff --git a/doc/user/search/img/issues_mrs_shortcut.png b/doc/user/search/img/issues_mrs_shortcut.png Binary files differnew file mode 100755 index 00000000000..6380b337b54 --- /dev/null +++ b/doc/user/search/img/issues_mrs_shortcut.png diff --git a/doc/user/search/img/left_menu_bar.png b/doc/user/search/img/left_menu_bar.png Binary files differnew file mode 100755 index 00000000000..d68a71cba8e --- /dev/null +++ b/doc/user/search/img/left_menu_bar.png diff --git a/doc/user/search/img/project_search.png b/doc/user/search/img/project_search.png Binary files differnew file mode 100755 index 00000000000..3150b40de29 --- /dev/null +++ b/doc/user/search/img/project_search.png diff --git a/doc/user/search/img/search_history.gif b/doc/user/search/img/search_history.gif Binary files differnew file mode 100644 index 00000000000..4cfa48ee0ab --- /dev/null +++ b/doc/user/search/img/search_history.gif diff --git a/doc/user/search/img/search_issues_board.png b/doc/user/search/img/search_issues_board.png Binary files differnew file mode 100755 index 00000000000..84048ae6a02 --- /dev/null +++ b/doc/user/search/img/search_issues_board.png diff --git a/doc/user/search/img/sort_projects.png b/doc/user/search/img/sort_projects.png Binary files differnew file mode 100755 index 00000000000..9bf2770b299 --- /dev/null +++ b/doc/user/search/img/sort_projects.png diff --git a/doc/user/search/index.md b/doc/user/search/index.md new file mode 100644 index 00000000000..6d59dcc6c75 --- /dev/null +++ b/doc/user/search/index.md @@ -0,0 +1,104 @@ +# Search through GitLab + +## Issues and merge requests + +To search through issues and merge requests in multiple projects, you can use the left-sidebar. + +Click the menu bar, then **Issues** or **Merge Requests**, which work in the same way, +therefore, the following notes are valid for both. + +The number displayed on their right represents the number of issues and merge requests assigned to you. + + + +When you click **Issues**, you'll see the opened issues assigned to you straight away: + + + +You can filter them by **Author**, **Assignee**, **Milestone**, and **Labels**, +searching through **Open**, **Closed**, and **All** issues. + +Of course, you can combine all filters together. + +### Issues and MRs assigned to you or created by you + +You'll find a shortcut to issues and merge requests create by you or assigned to you +on the search field on the top-right of your screen: + + + +## Issues and merge requests per project + +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, label, +and weight. When done, press **Enter** on your keyboard to filter the issues. + + + +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, +milestone, and label. + +## 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. + + + +## Removing search filters + +Individual filters can be removed by clicking on the filter's (x) button or backspacing. The entire search filter can be cleared by clicking on the search box's (x) button. + +### Shortcut + +You'll also find a shortcut on the search field on the top-right of the project's dashboard to +quickly access issues and merge requests created or assigned to you within that project: + + + +## Todos + +Your [todos](../../workflow/todos.md#gitlab-todos) can be searched by "to do" and "done". +You can [filter](../../workflow/todos.md#filtering-your-todos) them per project, +author, type, and action. Also, you can sort them by +[**Label priority**](../../user/project/labels.md#prioritize-labels), +**Last created** and **Oldest created**. + +## Projects + +You can search through your projects from the left menu, by clicking the menu bar, then **Projects**. +On the field **Filter by name**, type the project or group name you want to find, and GitLab +will filter them for you as you type. + +You can also look for the projects you starred (**Starred projects**), and **Explore** all +public and internal projects available in GitLab.com, from which you can filter by visibitily, +through **Trending**, best rated with **Most starts**, or **All** of them. + +You can also sort them by **Name**, **Last created**, **Oldest created**, **Last updated**, +**Oldest updated**, **Owner**, and choose to hide or show **archived projects**: + + + +## Groups + +Similarly to [projects search](#projects), you can search through your groups from +the left menu, by clicking the menu bar, then **Groups**. + +On the field **Filter by name**, type the group name you want to find, and GitLab +will filter them for you as you type. + +You can also **Explore** all public and internal groups available in GitLab.com, +and sort them by **Last created**, **Oldest created**, **Last updated**, or **Oldest updated**. + +## Issue Boards + +From an [Issue Board](../../user/project/issue_board.md), you can filter issues by **Author**, **Assignee**, **Milestone**, and **Labels**. +You can also filter them by name (issue title), from the field **Filter by name**, which is loaded as you type. + +When you want to search for issues to add to lists present in your Issue Board, click +the button **Add issues** on the top-right of your screen, opening a modal window from which +you'll be able to, besides filtering them by **Name**, **Author**, **Assignee**, **Milestone**, +and **Labels**, select multiple issues to add to a list of your choice: + + diff --git a/doc/user/snippets.md b/doc/user/snippets.md index 417360e08ac..78861625f8a 100644 --- a/doc/user/snippets.md +++ b/doc/user/snippets.md @@ -2,8 +2,18 @@ Snippets are little bits of code or text. + + There are 2 types of snippets - project snippets and personal snippets. +## Comments + +With GitLab Snippets you engage in a conversation about that piece of code, +facilitating the collaboration among users. + +> **Note:** +Comments on snippets was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/12910) in [GitLab Community Edition 9.2](https://about.gitlab.com/2017/05/22/gitlab-9-2-released/#comments-for-personal-snippets). + ## Project snippets Project snippets are always related to a specific project - see [Project features](../workflow/project_features.md) for more information. diff --git a/doc/workflow/README.md b/doc/workflow/README.md index 6a8de51a199..604c7d5cefb 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -20,18 +20,19 @@ - [Project forking workflow](forking_workflow.md) - [Project users](add-user/add-user.md) - [Protected branches](../user/project/protected_branches.md) +- [Protected tags](../user/project/protected_tags.md) - [Slash commands](../user/project/slash_commands.md) - [Sharing a project with a group](share_with_group.md) - [Share projects with other groups](share_projects_with_other_groups.md) - [Time tracking](time_tracking.md) - [Web Editor](../user/project/repository/web_editor.md) - [Releases](releases.md) -- [Milestones](milestones.md) +- [Milestones](../user/project/milestones/index.md) - [Merge Requests](../user/project/merge_requests/index.md) - [Authorization for merge requests](../user/project/merge_requests/authorization_for_merge_requests.md) - [Cherry-pick changes](../user/project/merge_requests/cherry_pick_changes.md) - [Merge when pipeline succeeds](../user/project/merge_requests/merge_when_pipeline_succeeds.md) - - [Resolve discussion comments in merge requests reviews](../user/project/merge_requests/merge_request_discussion_resolution.md) + - [Resolve discussion comments in merge requests reviews](../user/discussions/index.md) - [Resolve merge conflicts in the UI](../user/project/merge_requests/resolve_conflicts.md) - [Revert changes in the UI](../user/project/merge_requests/revert_changes.md) - [Merge requests versions](../user/project/merge_requests/versions.md) diff --git a/doc/workflow/gitlab_flow.md b/doc/workflow/gitlab_flow.md index d12c0c6d0c4..1b172b21f3d 100644 --- a/doc/workflow/gitlab_flow.md +++ b/doc/workflow/gitlab_flow.md @@ -313,5 +313,4 @@ Merging only when needed prevents creating merge commits in your feature branch ### References -- [Sketch file](https://www.dropbox.com/s/58dvsj5votbwrzv/git_flows.sketch?dl=0) with vectors of images in this article - [Git Flow by Vincent Driessen](http://nvie.com/posts/a-successful-git-branching-model/) diff --git a/doc/workflow/groups.md b/doc/workflow/groups.md index 6237a5d5e18..1cb3c940f00 100644 --- a/doc/workflow/groups.md +++ b/doc/workflow/groups.md @@ -1,6 +1,6 @@ # GitLab Groups -GitLab groups allow you to group projects into directories and give users to several projects at once. +GitLab groups allow you to group projects into directories and give users access to several projects at once. When you create a new project in GitLab, the default namespace for the project is the personal namespace associated with your GitLab user. In this document we will see how to create groups, put projects in groups and manage who can access the projects in a group. @@ -11,9 +11,9 @@ You can create a group by going to the 'Groups' tab of the GitLab dashboard and  -Next, enter the name (required) and the optional description and group avatar. +Next, enter the path and name (required) and the optional description and group avatar. - + When your group has been created you are presented with the group dashboard feed, which will be empty. diff --git a/doc/workflow/groups/new_group_form.png b/doc/workflow/groups/new_group_form.png Binary files differindex 0d798cd4b84..91727ab5336 100644 --- a/doc/workflow/groups/new_group_form.png +++ b/doc/workflow/groups/new_group_form.png diff --git a/doc/workflow/notifications/settings.png b/doc/workflow/img/notification_global_settings.png Binary files differindex 8a5494d16a8..8a5494d16a8 100644 --- a/doc/workflow/notifications/settings.png +++ b/doc/workflow/img/notification_global_settings.png diff --git a/doc/workflow/img/notification_group_settings.png b/doc/workflow/img/notification_group_settings.png Binary files differnew file mode 100644 index 00000000000..fc096f46901 --- /dev/null +++ b/doc/workflow/img/notification_group_settings.png diff --git a/doc/workflow/img/notification_project_settings.png b/doc/workflow/img/notification_project_settings.png Binary files differnew file mode 100644 index 00000000000..006432f65c9 --- /dev/null +++ b/doc/workflow/img/notification_project_settings.png diff --git a/doc/workflow/img/todos_icon.png b/doc/workflow/img/todos_icon.png Binary files differindex 1ed16b09669..9fee4337a75 100644 --- a/doc/workflow/img/todos_icon.png +++ b/doc/workflow/img/todos_icon.png diff --git a/doc/workflow/img/todos_index.png b/doc/workflow/img/todos_index.png Binary files differindex 902a5aa6bd3..99c1575d157 100644 --- a/doc/workflow/img/todos_index.png +++ b/doc/workflow/img/todos_index.png diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md index aece4ab34ba..8ed1d98d05b 100644 --- a/doc/workflow/importing/import_projects_from_github.md +++ b/doc/workflow/importing/import_projects_from_github.md @@ -10,6 +10,11 @@ in your GitLab instance sitewide. This configuration is optional, users will still be able to import their GitHub repositories with a
[personal access token][gh-token].
+>**Note:**
+Administrators of a GitLab instance (Community or Enterprise Edition) can also
+use the [GitHub rake task][gh-rake] to import projects from GitHub without the
+constrains of a Sidekiq worker.
+
- At its current state, GitHub importer can import:
- the repository description (GitLab 7.7+)
- the Git repository data (GitLab 7.7+)
@@ -112,5 +117,6 @@ You can also choose a different name for the project and a different namespace, if you have the privileges to do so.
[gh-import]: ../../integration/github.md "GitHub integration"
+[gh-rake]: ../../administration/raketasks/github_import.md "GitHub rake task"
[gh-integration]: #authorize-access-to-your-repositories-using-the-github-integration
[gh-token]: #authorize-access-to-your-repositories-using-a-personal-access-token
diff --git a/doc/workflow/milestones.md b/doc/workflow/milestones.md index 37afe553e55..69eb6b286b0 100644 --- a/doc/workflow/milestones.md +++ b/doc/workflow/milestones.md @@ -1,28 +1 @@ -# Milestones - -Milestones allow you to organize issues and merge requests into a cohesive group, optionally setting a due date. -A common use is keeping track of an upcoming software version. Milestones are created per-project. - - - -## Groups and milestones - -You can create a milestone for several projects in the same group simultaneously. -On the group's milestones page, you will be able to see the status of that milestone across all of the selected projects. - - - -## Special milestone filters - -In addition to the milestones that exist in the project or group, there are some -special options available when filtering by milestone: - -* **No Milestone** - only show issues or merge requests without a milestone. -* **Upcoming** - show issues or merge request that belong to the next open - milestone with a due date, by project. (For example: if project A has - milestone v1 due in three days, and project B has milestone v2 due in a week, - then this will show issues or merge requests from milestone v1 in project A - and milestone v2 in project B.) -* **Started** - show issues or merge requests from any milestone with a start - date less than today. Note that this can return results from several - milestones in the same project. +This document was moved to [another location](../user/project/milestones/index.md). diff --git a/doc/workflow/milestones/form.png b/doc/workflow/milestones/form.png Binary files differdeleted file mode 100644 index c4731d88543..00000000000 --- a/doc/workflow/milestones/form.png +++ /dev/null diff --git a/doc/workflow/milestones/group_form.png b/doc/workflow/milestones/group_form.png Binary files differdeleted file mode 100644 index dccdb019703..00000000000 --- a/doc/workflow/milestones/group_form.png +++ /dev/null diff --git a/doc/workflow/notifications.md b/doc/workflow/notifications.md index 4c52974e103..3e2e7d0f7b6 100644 --- a/doc/workflow/notifications.md +++ b/doc/workflow/notifications.md @@ -6,7 +6,7 @@ GitLab has a notification system in place to notify a user of events that are im You can find notification settings under the user profile. - + Notification settings are divided into three groups: @@ -32,19 +32,23 @@ anything that is set at Global Settings. #### Group Settings + + Group Settings are taking precedence over Global Settings but are on a level below Project Settings. This means that you can set a different level of notifications per group while still being able to have a finer level setting per project. Organization like this is suitable for users that belong to different groups but don't have the same need for being notified for every group they are member of. -These settings can be configured on group page or user profile notifications dropdown. +These settings can be configured on group page under the name of the group. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. #### Project Settings + + Project Settings are at the top level and any setting placed at this level will take precedence of any other setting. This is suitable for users that have different needs for notifications per project basis. -These settings can be configured on project page or user profile notifications dropdown. +These settings can be configured on project page under the name of the project. It will be the dropdown with the bell icon. They can also be configured on the user profile notifications dropdown. ## Notification events @@ -66,14 +70,13 @@ Below is the table of events users can be notified of: In all of the below cases, the notification will be sent to: - Participants: - the author and assignee of the issue/merge request - - the author of the pipeline - authors of comments on the issue/merge request - anyone mentioned by `@username` in the issue/merge request title or description - anyone mentioned by `@username` in any of the comments on the issue/merge request ...with notification level "Participating" or higher -- Watchers: users with notification level "Watch" (however successful pipeline would be off for watchers) +- Watchers: users with notification level "Watch" - Subscribers: anyone who manually subscribed to the issue/merge request - Custom: Users with notification level "custom" who turned on notifications for any of the events present in the table below @@ -89,8 +92,8 @@ In all of the below cases, the notification will be sent to: | Reopen merge request | | | Merge merge request | | | New comment | The above, plus anyone mentioned by `@username` in the comment, with notification level "Mention" or higher | -| Failed pipeline | The above, plus the author of the pipeline | -| Successful pipeline | The above, plus the author of the pipeline | +| Failed pipeline | The author of the pipeline | +| Successful pipeline | The author of the pipeline, if they have the custom notification setting for successful pipelines set | In addition, if the title or description of an Issue or Merge Request is diff --git a/doc/workflow/project_features.md b/doc/workflow/project_features.md index f19e7df8c9a..3f5de2bd4b1 100644 --- a/doc/workflow/project_features.md +++ b/doc/workflow/project_features.md @@ -26,6 +26,8 @@ This is a separate system for documentation, built right into GitLab. It is source controlled and is very convenient if you don't want to keep you documentation in your source code, but you do want to keep it in your GitLab project. +[Read more about Wikis.](../user/project/wiki/index.md) + ## Snippets Snippets are little bits of code or text. diff --git a/doc/workflow/shortcuts.md b/doc/workflow/shortcuts.md index f94357abec9..c5b7488be69 100644 --- a/doc/workflow/shortcuts.md +++ b/doc/workflow/shortcuts.md @@ -75,3 +75,9 @@ You can see GitLab's keyboard shortcuts by using 'shift + ?' | <kbd>r</kbd> | Reply (quoting selected text) | | <kbd>e</kbd> | Edit issue/merge request | | <kbd>l</kbd> | Change label | + +## Wiki pages + +| Keyboard Shortcut | Description | +| ----------------- | ----------- | +| <kbd>e</kbd> | Edit wiki page| diff --git a/doc/workflow/todos.md b/doc/workflow/todos.md index 4b0fba842e9..3d8d3ce8f13 100644 --- a/doc/workflow/todos.md +++ b/doc/workflow/todos.md @@ -111,7 +111,7 @@ There are four kinds of filters you can use on your Todos dashboard. | Type | Filter by issue or merge request | | Action | Filter by the action that triggered the Todo | -You can also filter by more than one of these at the same time. +You can also filter by more than one of these at the same time. The possible Actions are `Any Action`, `Assigned`, `Mentioned`, `Added`, `Pipelines`, and `Directly Addressed`, [as described above](#what-triggers-a-todo). [ce-2817]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/2817 [ce-7926]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7926 |
