diff options
Diffstat (limited to 'doc/README.md')
| -rw-r--r-- | doc/README.md | 300 |
1 files changed, 176 insertions, 124 deletions
diff --git a/doc/README.md b/doc/README.md index ab8ea192a26..be805a2ccc4 100644 --- a/doc/README.md +++ b/doc/README.md @@ -1,188 +1,240 @@ -# GitLab Community Edition +--- +comments: false +--- -[GitLab](https://about.gitlab.com/) is a Git-based fully featured platform -for software development. +# GitLab Documentation -**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/). +Welcome to [GitLab](https://about.gitlab.com/), a Git-based fully featured +platform for software development! ----- +GitLab offers the most scalable Git-based fully integrated platform for +software development, with flexible products and subscriptions. +To understand what features you have access to, check the [GitLab subscriptions](#gitlab-subscriptions) below. -Shortcuts to GitLab's most visited docs: +**Shortcuts to GitLab's most visited docs:** -| [GitLab CI](ci/README.md) | Other | +| General documentation | GitLab CI/CD docs | | :----- | :----- | -| [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). +| [User documentation](user/index.md) | [GitLab CI/CD](ci/README.md) | +| [Administrator documentation](administration/index.md) | [GitLab CI/CD quick start guide](ci/quick_start/README.md) | +| [Contributor documentation](#contributor-documentation) | [Configuring `.gitlab-ci.yml`](ci/yaml/README.md) | +| [Getting started with GitLab](#getting-started-with-gitlab) | [Using Docker images](ci/docker/using_docker_images.md) | +| [API](api/README.md) | [Auto DevOps](topics/autodevops/index.md) | +| [SSH authentication](ssh/README.md) | [Kubernetes integration](user/project/clusters/index.md)| +| [GitLab Pages](user/project/pages/index.md) | [GitLab Container Registry](user/project/container_registry.md) | + +## Complete DevOps with GitLab + +GitLab is the first single application for software development, security, +and operations that enables Concurrent DevOps, making the software lifecycle +three times faster and radically improving the speed of business. GitLab +provides solutions for all the stages of the DevOps lifecycle: +[plan](#plan), [create](#create), [verify](#verify), [package](#package), +[release](#release), [configure](#configure), [monitor](#monitor). + + + +### Plan + +Whether you use Waterfall, Agile, or Conversational Development, +GitLab streamlines your collaborative workflows. Visualize, prioritize, +coordinate, and track your progress your way with GitLab’s flexible project +management tools. + +- Chat operations + - [Mattermost slash commands](user/project/integrations/mattermost_slash_commands.md) + - [Slack slash commands](user/project/integrations/slack_slash_commands.md) +- [Discussions](user/discussions/index.md): Threads, comments, and resolvable discussions in issues, commits, and merge requests. +- [Issues](user/project/issues/index.md) +- [Project Issue Board](user/project/issue_board.md) +- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests. +- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles. +- [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. - [GitLab Quick Actions](user/project/quick_actions.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. +#### Migrate and import your projects from other platforms -### Projects and groups +- [Importing to GitLab](user/project/import/index.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. -- [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). -- [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) +### Create + +Consolidate source code into a single [DVCS](https://en.wikipedia.org/wiki/Distributed_version_control) +that’s easily managed and controlled without disrupting your workflow. +GitLab’s git repositories come complete with branching tools and access +controls, providing a scalable, single source of truth for collaborating +on projects and code. + +#### Projects and groups + +- [Projects](user/project/index.md): + - [Project settings](user/project/settings/index.md) + - [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). + - [Project access](public_access/public_access.md): Setting up your project's visibility to public, internal, or private. + - [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages. +- [Groups](user/group/index.md): Organize your projects in groups. + - [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. - [Wikis](user/project/wiki/index.md): Enhance your repository documentation with built-in wikis. -- [GitLab Pages](user/project/pages/index.md): Build, test, and deploy your static website with GitLab Pages. -### Repository +#### Repositories -Manage files and branches from the UI (user interface): +Manage your [repositories](user/project/repository/index.md) from the UI (user interface): -- Files +- [Files](user/project/repository/index.md#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 +- [Branches](user/project/repository/branches/index.md) + - [Default branch](user/project/repository/branches/index.md#default-branch) - [Create a branch](user/project/repository/web_editor.md#create-a-new-branch) - [Protected branches](user/project/protected_branches.md#protected-branches) - [Delete merged branches](user/project/repository/branches/index.md#delete-merged-branches) +- [Commits](user/project/repository/index.md#commits) + - [Signing commits](user/project/repository/gpg_signed_commits/index.md): use GPG to sign your commits. -### Issues and Merge Requests (MRs) +#### 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. +- [Trello Power-Up](integration/trello_power_up.md): Integrate with GitLab's Trello Power-Up + +#### 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. + +### Verify + +Spot errors sooner and shorten feedback cycles with built-in code review, code testing, +Code Quality, and Review Apps. Customize your approval workflow controls, automatically +test the quality of your code, and spin up a staging environment for every code change. +GitLab Continuous Integration is the most popular next generation testing system that +auto scales to run your tests faster. -- [Discussions](user/discussions/index.md) Threads, comments, and resolvable discussions in issues, commits, and merge requests. -- [Issues](user/project/issues/index.md) -- [Issue Board](user/project/issue_board.md) -- [Issues and merge requests templates](user/project/description_templates.md): Create templates for submitting new issues and merge requests. -- [Labels](user/project/labels.md): Categorize your issues or merge requests based on descriptive titles. - [Merge Requests](user/project/merge_requests/index.md) - [Work In Progress Merge Requests](user/project/merge_requests/work_in_progress_merge_requests.md) - [Merge Request discussion resolution](user/discussions/index.md#moving-a-single-discussion-to-a-new-issue): Resolve discussions, move discussions in a merge request to an issue, only allow merge requests to be merged if all discussions are resolved. - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally) - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md) -- [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date. -- [Todos](workflow/todos.md): A chronological list of to-dos that are waiting for your input, all in a simple dashboard. +- [Review Apps](ci/review_apps/index.md): Preview changes to your app right from a merge request. -### Git and GitLab +### Package -- [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. +GitLab Container Registry gives you the enhanced security and access controls of +custom Docker images without 3rd party add-ons. Easily upload and download images +from GitLab CI/CD with full Git repository management integration. -### Migrate and import your projects from other platforms +- [GitLab CI/CD](ci/README.md): Explore the features and capabilities of Continuous Integration, Continuous Delivery, and Continuous Deployment with GitLab. +- [GitLab Container Registry](user/project/container_registry.md): Learn how to use GitLab's built-in Container Registry. -- [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. +### Release -### Continuous Integration, Delivery, and Deployment +Spend less time configuring your tools, and more time creating. Whether you’re +deploying to one server or thousands, build, test, and release your code +confidently and securely with GitLab’s built-in Continuous 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. +- [GitLab Pages](user/project/pages/index.md): Build, test, and deploy a static site directly from GitLab. +- [Auto Deploy](topics/autodevops/index.md#auto-deploy): Configure GitLab CI for the deployment of your application. +- [Environments and deployments](ci/environments.md): With environments, you can control the continuous deployment of your software within GitLab. -### Automation +### Configure -- [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. +Automate your entire workflow from build to deploy and monitoring with GitLab +Auto Devops. Best practice templates get you started with minimal to zero +configuration. Then customize everything from buildpacks to CI/CD. -### Integrations +- [Auto DevOps](topics/autodevops/index.md) -- [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. +### Monitor ----- +Measure how long it takes to go from planning to monitoring and ensure your +applications are always responsive and available. GitLab collects and displays +performance metrics for deployed apps using Prometheus so you can know in an +instant how code changes impact your production environment. -## Administrator documentation +- [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 Performance Monitoring](administration/monitoring/performance/index.md) -Learn how to administer your GitLab instance. Regular users don't -have access to GitLab administration tools and settings. +## Getting started with GitLab -### Install, update, upgrade, migrate +- [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). -- [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 account -### User permissions +- [User account](user/profile/index.md): Manage your 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](user/profile/index.md#profile-settings): 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. -- [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. +### 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. + +## Administrator documentation + +[Administration documentation](administration/index.md) applies to admin users of GitLab +self-hosted instances. -### GitLab admins' superpowers +Learn how to install, configure, update, upgrade, integrate, and maintain your own instance. +Regular users don't have access to GitLab administration tools and settings. -- [Container Registry](administration/container_registry.md): Configure Docker Registry with GitLab. -- [Custom Git hooks](administration/custom_hooks.md): Custom Git hooks (on the filesystem) for when webhooks aren't enough. -- [Git LFS configuration](workflow/lfs/lfs_administration.md): Learn how to use LFS under GitLab. -- [GitLab Pages configuration](administration/pages/index.md): Configure GitLab Pages. -- [High Availability](administration/high_availability/README.md): Configure multiple servers for scaling or high availability. -- [User cohorts](user/admin_area/user_cohorts.md) View user activity over time. -- [Web terminals](administration/integration/terminal.md): Provide terminal access to environments from within GitLab. -- GitLab CI - - [CI admin settings](user/admin_area/settings/continuous_integration.md): Define max artifacts size and expiration time. +## Contributor documentation -### Integrations +GitLab Community Edition is [open source](https://gitlab.com/gitlab-org/gitlab-ce/) +and GitLab Enterprise Edition is [open-core](https://gitlab.com/gitlab-org/gitlab-ee/). +Learn how to contribute to GitLab: -- [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. +- [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. -### Monitoring +## GitLab subscriptions -- [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. +You have two options to use GitLab: -### Performance +- GitLab self-hosted: Install, administer, and maintain your own GitLab instance. +- GitLab.com: GitLab's SaaS offering. You don't need to install anything to use GitLab.com, +you only need to [sign up](https://gitlab.com/users/sign_in) and start using GitLab +straight away. -- [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. +### GitLab self-hosted -### Customization +With GitLab self-hosted, you deploy your own GitLab instance on-premises or on a private cloud of your choice. GitLab self-hosted is available for [free and with paid subscriptions](https://about.gitlab.com/products/): Libre, Starter, Premium, and Ultimate. -- [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. +Every feature available in Libre is also available in Starter, Premium, and Ultimate. +Starter features are also available in Premium and Ultimate, and Premium features are also +available in Ultimate. -### Admin tools +### GitLab.com -- [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. +GitLab.com is hosted, managed, and administered by GitLab, Inc., with +[free and paid subscriptions](https://about.gitlab.com/gitlab-com/) for individuals +and teams: Free, Bronze, Silver, and Gold. -### Troubleshooting +GitLab.com subscriptions grants access +to the same features available in GitLab self-hosted, **expect +[administration](administration/index.md) tools and settings**: -- [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. +- GitLab.com Free includes the same features available in GitLab Libre +- GitLab.com Bronze includes the same features available in GitLab Starter +- GitLab.com Silver includes the same features available in GitLab Premium +- GitLab.com Gold includes the same features available in GitLab Ultimate -## Contributor documentation +For supporting the open source community and encouraging the development of +open source projects, GitLab grants access to **Gold** features +for all GitLab.com **public** projects, regardless of the subscription. -- [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. +To know more about GitLab subscriptions and licensing, please refer to the +[GitLab Product Marketing Handbook](https://about.gitlab.com/handbook/marketing/product-marketing/#tiers). |