diff options
Diffstat (limited to 'doc')
86 files changed, 1544 insertions, 606 deletions
diff --git a/doc/README.md b/doc/README.md index 9e6a5b4ed44..6406040da4b 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,79 +1,195 @@ # 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 -- [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. -- [Container Registry](user/project/container_registry.md) Learn how to use GitLab Container Registry. -- [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. -- [GitLab as OAuth2 authentication service provider](integration/oauth_provider.md). It allows you to login to other applications from GitLab. -- [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. +[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). -- [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab. -- [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. +- [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. -- [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. + +### 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 + - [Create an issue](gitlab-basics/create-issue.md#how-to-create-an-issue-in-gitlab) + - [Confidential Issues](user/project/issues/confidential_issues.md) + - [Automatic issue closing](user/project/issues/automatic_issue_closing.md) + - [Issue Boards](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](workflow/project_features.md#wiki): 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. -- [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. -- [Debugging Tips](administration/troubleshooting/debug.md) Tips to debug problems when things go wrong -- [Environment Variables](administration/environment_variables.md) to configure GitLab. -- [Git LFS configuration](workflow/lfs/lfs_administration.md) -- [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. -- [Header logo](customization/branded_page_and_email_header.md) Change the logo on the overall page and email header. -- [High Availability](administration/high_availability/README.md) Configure multiple servers for scaling or high availability. -- [Housekeeping](administration/housekeeping.md) Keep your Git repository tidy and fast. -- [Install](install/README.md) Requirements, directory structures and installation from source. -- [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. -- [Libravatar](customization/libravatar.md) Use Libravatar instead of Gravatar for user avatars. -- [Log system](administration/logs.md) Log system. -- [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. -- [Monitoring uptime](user/admin_area/monitoring/health_check.md) Check the server status using the health check endpoint. -- [Operations](administration/operations.md) Keeping GitLab up and running. -- [Polling](administration/polling.md) Configure how often the GitLab UI polls for updates -- [Raketasks](raketasks/README.md) Backups, maintenance, automatic webhook setup and the importing of projects. -- [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. -- [Request Profiling](administration/monitoring/performance/request_profiling.md) Get a detailed profile on slow requests. -- [Restart GitLab](administration/restart_gitlab.md) Learn how to restart GitLab and its components. -- [Security](security/README.md) Learn what you can do to further secure your GitLab instance. -- [Sidekiq Troubleshooting](administration/troubleshooting/sidekiq.md) Debug when Sidekiq appears hung and is not processing jobs. -- [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. +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. -- [Welcome message](customization/welcome_message.md) Add a custom welcome message to the sign-in page. +- [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/gitaly/index.md b/doc/administration/gitaly/index.md index 2e22212ddde..6c6942a7bfe 100644 --- a/doc/administration/gitaly/index.md +++ b/doc/administration/gitaly/index.md @@ -1,6 +1,6 @@ # 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.1 it is still an optional component with limited scope. 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..c5125dc6d5a 100644 --- a/doc/administration/high_availability/nfs.md +++ b/doc/administration/high_availability/nfs.md @@ -7,21 +7,20 @@ 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. - ### 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..4638a9c9782 100644 --- a/doc/administration/high_availability/redis.md +++ b/doc/administration/high_availability/redis.md @@ -492,7 +492,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/api/deployments.md b/doc/api/deployments.md index 0273c819614..ab9e63e01d3 100644 --- a/doc/api/deployments.md +++ b/doc/api/deployments.md @@ -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", @@ -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/issues.md b/doc/api/issues.md index 5f01fcdd396..6c10b5ab0e7 100644 --- a/doc/api/issues.md +++ b/doc/api/issues.md @@ -823,6 +823,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 bea2b96c97a..404da3dc603 100644 --- a/doc/api/jobs.md +++ b/doc/api/jobs.md @@ -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,7 +118,7 @@ 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 | @@ -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": "", @@ -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": "", diff --git a/doc/api/keys.md b/doc/api/keys.md index 3b55c2baf56..3ace1040f38 100644 --- a/doc/api/keys.md +++ b/doc/api/keys.md @@ -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/merge_requests.md b/doc/api/merge_requests.md index ff956add348..dde855b2bd4 100644 --- a/doc/api/merge_requests.md +++ b/doc/api/merge_requests.md @@ -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 or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user -- `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 [ diff --git a/doc/api/projects.md b/doc/api/projects.md index 63f88a464f5..51de4fef7ff 100644 --- a/doc/api/projects.md +++ b/doc/api/projects.md @@ -859,6 +859,17 @@ Parameters: | `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 +879,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 diff --git a/doc/api/services.md b/doc/api/services.md index 7d4779f1137..0f42c256099 100644 --- a/doc/api/services.md +++ b/doc/api/services.md @@ -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, + "build_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/users.md b/doc/api/users.md index ff5bffa178f..86027bcc05c 100644 --- a/doc/api/users.md +++ b/doc/api/users.md @@ -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": "", @@ -95,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": "", @@ -169,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": "", @@ -200,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": "", @@ -325,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": "", @@ -1029,7 +1024,7 @@ Parameters: | `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/v3/user/activities +curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" https://gitlab.example.com/api/v4/user/activities ``` Example response: diff --git a/doc/articles/index.md b/doc/articles/index.md new file mode 100644 index 00000000000..67eab36bf2c --- /dev/null +++ b/doc/articles/index.md @@ -0,0 +1,16 @@ +# 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/). + +## 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/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/triggers/README.md b/doc/ci/triggers/README.md index e380282f910..5f611314d09 100644 --- a/doc/ci/triggers/README.md +++ b/doc/ci/triggers/README.md @@ -227,3 +227,31 @@ branch of project with ID `9` every night at `00:30`: ``` [ci-229]: https://gitlab.com/gitlab-org/gitlab-ci/merge_requests/229 + +## Using scheduled triggers + +> [Introduced][ci-10533] in GitLab CE 9.1 as experimental. + +In order to schedule a trigger, navigate to your project's **Settings ➔ CI/CD Pipelines ➔ Triggers** and edit an existing trigger token. + + + +To set up a scheduled trigger: + +1. Check the **Schedule trigger (experimental)** checkbox +1. Enter a cron value for the frequency of the trigger ([learn more about cron notation](http://www.nncron.ru/help/EN/working/cron-format.htm)) +1. Enter the timezone of the cron trigger ([see a list of timezones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones)) +1. Enter the branch or tag that the trigger will target +1. Hit **Save trigger** for the changes to take effect + + + +You can check a next execution date of the scheduled trigger, which is automatically calculated by a server. + + + +> **Notes**: +- Those triggers won't be executed precicely. Because scheduled triggers are handled by Sidekiq, which runs according to its interval. For exmaple, if you set a trigger to be executed every minute (`* * * * *`) and the Sidekiq worker performs 00:00 and 12:00 o'clock every day (`0 */12 * * *`), then your trigger will be executed only 00:00 and 12:00 o'clock every day. To change the Sidekiq worker's frequency, you have to edit the `trigger_schedule_worker` value in `config/gitlab.yml` and restart GitLab. The Sidekiq worker's configuration on GiLab.com is able to be looked up at [here](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/config/gitlab.yml.example#L185). +- Cron notation is parsed by [Rufus-Scheduler](https://github.com/jmettraux/rufus-scheduler). + +[ci-10533]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10533 diff --git a/doc/ci/triggers/img/trigger_schedule_create.png b/doc/ci/triggers/img/trigger_schedule_create.png Binary files differnew file mode 100644 index 00000000000..3cfdc00b7a7 --- /dev/null +++ b/doc/ci/triggers/img/trigger_schedule_create.png diff --git a/doc/ci/triggers/img/trigger_schedule_edit.png b/doc/ci/triggers/img/trigger_schedule_edit.png Binary files differnew file mode 100644 index 00000000000..647eac0a5d0 --- /dev/null +++ b/doc/ci/triggers/img/trigger_schedule_edit.png diff --git a/doc/ci/triggers/img/trigger_schedule_updated_next_run_at.png b/doc/ci/triggers/img/trigger_schedule_updated_next_run_at.png Binary files differnew file mode 100644 index 00000000000..71d08d04c37 --- /dev/null +++ b/doc/ci/triggers/img/trigger_schedule_updated_next_run_at.png diff --git a/doc/development/README.md b/doc/development/README.md index 3c797505aa9..77bb0263374 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) 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/doc_styleguide.md b/doc/development/doc_styleguide.md index bb78a0de0c5..1e81905c081 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/`. --- 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/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 c7d4f2e9c23..a08694fb66a 100644 --- a/doc/development/fe_guide/index.md +++ b/doc/development/fe_guide/index.md @@ -27,6 +27,59 @@ 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. diff --git a/doc/development/fe_guide/style_guide_js.md b/doc/development/fe_guide/style_guide_js.md index abd241c0bc8..1d2b0558948 100644 --- a/doc/development/fe_guide/style_guide_js.md +++ b/doc/development/fe_guide/style_guide_js.md @@ -58,7 +58,7 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. import Bar from './bar'; ``` -- **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. +- **Never** disable the `no-undef` rule. Declare globals with `/* global Foo */` instead. - When declaring multiple globals, always use one `/* global [name] */` line per variable. @@ -71,6 +71,16 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. /* global Cookies */ /* global jQuery */ ``` + +- Use up to 3 parameters for a function or class. If you need more accept an Object instead. + + ```javascript + // bad + fn(p1, p2, p3, p4) {} + + // good + fn(options) {} + ``` #### Modules, Imports, and Exports - Use ES module syntax to import modules @@ -168,6 +178,23 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. - Avoid constructors with side-effects +- 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' } ]; + + // 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 - `parseInt()` is preferable over `Number()` or `+` @@ -183,6 +210,19 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. parseInt('10', 10); ``` +#### CSS classes used for JavaScript +- 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 @@ -200,6 +240,7 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. #### Naming - **Extensions**: Use `.vue` extension for Vue components. - **Reference Naming**: Use PascalCase for Vue components and camelCase for their instances: + ```javascript // bad import cardBoard from 'cardBoard'; @@ -217,6 +258,7 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. cardBoard: CardBoard }; ``` + - **Props Naming:** - Avoid using DOM component prop names. - Use kebab-case instead of camelCase to provide props in templates. @@ -243,12 +285,18 @@ See [our current .eslintrc][eslintrc] for specific rules and patterns. <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" /> ``` diff --git a/doc/development/fe_guide/testing.md b/doc/development/fe_guide/testing.md index a4631fd0073..157c13352ca 100644 --- a/doc/development/fe_guide/testing.md +++ b/doc/development/fe_guide/testing.md @@ -14,8 +14,10 @@ for more information on general testing practices at GitLab. 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. +manipulation, we generate HTML files using RSpec suites (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`). +Those will be migrated over time. +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` @@ -26,6 +28,10 @@ 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. +### Writing tests +### Vue.js unit tests +See this [section][vue-test]. + ### Running frontend tests `rake karma` runs the frontend-only (JavaScript) tests. @@ -134,3 +140,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..73d2ffc1bdc 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,114 @@ 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); + }); + }); +}); +``` + +### 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); + }); +``` + [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 +426,8 @@ 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 [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/migration_style_guide.md b/doc/development/migration_style_guide.md index 3e8b709c18f..77ba2a5fd87 100644 --- a/doc/development/migration_style_guide.md +++ b/doc/development/migration_style_guide.md @@ -270,3 +270,28 @@ 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/testing.md b/doc/development/testing.md index ad540ec13db..9b0b9808827 100644 --- a/doc/development/testing.md +++ b/doc/development/testing.md @@ -202,6 +202,7 @@ Please consult the [dedicated "Frontend testing" guide](./fe_guide/testing.md). - 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 @@ -225,6 +226,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 @@ -448,13 +463,22 @@ is used for Spinach tests as well. ### Monitoring -The GitLab test suite is [monitored] and a [public dashboard] is available for -everyone to see. Feel free to look at the slowest test files and try to improve -them. +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) diff --git a/doc/development/writing_documentation.md b/doc/development/writing_documentation.md index 482ec54207b..2814c18e0b6 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 @@ -70,3 +70,27 @@ 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:check:links`: Check that all internal (relative) links work correctly +1. `docs:check:apilint`: Check that the API docs follow some conventions + +If your contribution contains **only** documentation changes, you can speed up +the CI process by prepending to the name of your branch: `docs/`. For example, +a valid name would be `docs/update-api-issues` and it will run only the docs +tests. If the name is `docs-update-api-issues`, 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/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_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/installation.md b/doc/install/installation.md index 1f61a4f67bb..dc807d93bbb 100644 --- a/doc/install/installation.md +++ b/doc/install/installation.md @@ -423,6 +423,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 @@ -466,14 +471,18 @@ 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 - cd /home/git/gitaly - sudo -u git cp config.toml.example config.toml # 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 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/intro/README.md b/doc/intro/README.md index 1df6a52ce8a..d52b180a076 100644 --- a/doc/intro/README.md +++ b/doc/intro/README.md @@ -13,7 +13,7 @@ Create issues, labels, milestones, cast your vote, and review issues. - [Create a new issue](../gitlab-basics/create-issue.md) - [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/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/topics/git/index.md b/doc/topics/git/index.md index b99ba317a43..d13066c9015 100644 --- a/doc/topics/git/index.md +++ b/doc/topics/git/index.md @@ -17,6 +17,10 @@ We've gathered some resources to help you to get the best from Git with GitLab. - [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:** - [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/) diff --git a/doc/university/glossary/README.md b/doc/university/glossary/README.md index 0b17e4ff7c1..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 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/9.0-to-9.1.md b/doc/update/9.0-to-9.1.md index 1191662ee14..2d597894517 100644 --- a/doc/update/9.0-to-9.1.md +++ b/doc/update/9.0-to-9.1.md @@ -317,6 +317,17 @@ 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 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 index c3f3179d99e..733e70ca9bf 100644 --- a/doc/user/admin_area/settings/usage_statistics.md +++ b/doc/user/admin_area/settings/usage_statistics.md @@ -3,7 +3,7 @@ GitLab Inc. will periodically collect information about your instance in order to perform various actions. -All statistics are opt-in and you can always disable them from the admin panel. +All statistics are opt-out, you can disable them from the admin panel. ## Version check diff --git a/doc/user/admin_area/user_cohorts.md b/doc/user/admin_area/user_cohorts.md index 1671487bc8c..e25e7a8bbc3 100644 --- a/doc/user/admin_area/user_cohorts.md +++ b/doc/user/admin_area/user_cohorts.md @@ -1,30 +1,37 @@ # Cohorts > **Notes:** -- [Introduced][ce-23361] in GitLab 9.1. +> [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 created on this server. One -month later, in July 2016, 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. +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 +## Setup -1. Activate the usage ping as defined [in the documentation](settings/usage_statistics.md) +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/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 3122e95fc0e..637967510f3 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 diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md index 505248536c8..b5d3b009044 100644 --- a/doc/user/profile/account/delete_account.md +++ b/doc/user/profile/account/delete_account.md @@ -1,7 +1,7 @@ # 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 **Remvoe user** +- 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 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/kubernetes.md b/doc/user/project/integrations/kubernetes.md index f7d5e3a8ab2..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 diff --git a/doc/user/project/integrations/microsoft_teams.md b/doc/user/project/integrations/microsoft_teams.md index fbf9c1de443..eaad2d5138a 100644 --- a/doc/user/project/integrations/microsoft_teams.md +++ b/doc/user/project/integrations/microsoft_teams.md @@ -1,8 +1,8 @@ -# Microsoft Teams Service +# 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) +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 @@ -30,4 +30,4 @@ At the end fill in your Microsoft Teams details: After you are all done, click **Save changes** for the changes to take effect. -
\ No newline at end of file + 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/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/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/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/workflow/README.md b/doc/workflow/README.md index a1852650cfb..604c7d5cefb 100644 --- a/doc/workflow/README.md +++ b/doc/workflow/README.md @@ -27,12 +27,12 @@ - [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/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 |
