diff options
| author | Kamil Trzciński <ayufan@ayufan.eu> | 2018-02-28 20:06:12 +0100 |
|---|---|---|
| committer | Kamil Trzciński <ayufan@ayufan.eu> | 2018-02-28 20:06:12 +0100 |
| commit | 5a69b51bc870f5b42ee3406ba77de02f44ef8d32 (patch) | |
| tree | c2a6e5b2c171826236b5d0f5e1ed8d02bd1554d2 /doc/user/project | |
| parent | b1f8d8a1739ff48412c8205f0007a2af8399d097 (diff) | |
| parent | b39d0c318921bae2e3a11df9ee6828291dad9864 (diff) | |
| download | gitlab-ce-5a69b51bc870f5b42ee3406ba77de02f44ef8d32.tar.gz | |
Merge commit 'b39d0c318921bae2e3a11df9ee6828291dad9864' into object-storage-ee-to-ce-backport
Diffstat (limited to 'doc/user/project')
87 files changed, 1407 insertions, 54 deletions
diff --git a/doc/user/project/container_registry.md b/doc/user/project/container_registry.md index 629d69d8aea..5c615daf464 100644 --- a/doc/user/project/container_registry.md +++ b/doc/user/project/container_registry.md @@ -120,6 +120,11 @@ If a project is private, credentials will need to be provided for authorization. The preferred way to do this, is by using [personal access tokens][pat]. The minimal scope needed is `read_registry`. +Example of using a personal access token: +``` +docker login registry.example.com -u <your_username> -p <your_personal_access_token> +``` + ## Troubleshooting the GitLab Container Registry ### Basic Troubleshooting diff --git a/doc/user/project/description_templates.md b/doc/user/project/description_templates.md index ea7496af089..7c94f4ef4d8 100644 --- a/doc/user/project/description_templates.md +++ b/doc/user/project/description_templates.md @@ -39,4 +39,58 @@ changes you made after picking the template and return it to its initial status.  +## Description template example + +We make use of Description Templates for Issues and Merge Requests within the GitLab Community Edition project. Please refer to the [`.gitlab` folder][gitlab-ce-templates] for some examples. + +> **Tip:** +It is possible to use [quick actions](./quick_actions.md) within description templates to quickly add labels, assignees, and milestones. The quick actions will only be executed if the user submitting the Issue or Merge Request has the permissions perform the relevant actions. + +Here is an example for a Bug report template: + +``` +Summary + +(Summarize the bug encountered concisely) + + +Steps to reproduce + +(How one can reproduce the issue - this is very important) + + +Example Project + +(If possible, please create an example project here on GitLab.com that exhibits the problematic behaviour, and link to it here in the bug report) + +(If you are using an older version of GitLab, this will also determine whether the bug has been fixed in a more recent version) + + +What is the current bug behavior? + +(What actually happens) + + +What is the expected correct behavior? + +(What you should see instead) + + +Relevant logs and/or screenshots + +(Paste any relevant logs - please use code blocks (```) to format console output, +logs, and code as it's very hard to read otherwise.) + + +Possible fixes + +(If you can, link to the line of code that might be responsible for the problem) + +/label ~bug ~reproduced ~needs-investigation +/cc @project-manager +/assign @qa-tester +``` + [ce-4981]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/4981 +[gitlab-ce-templates]: https://gitlab.com/gitlab-org/gitlab-ce/tree/master/.gitlab + diff --git a/doc/user/project/gpg_signed_commits/index.md b/doc/user/project/gpg_signed_commits/index.md new file mode 100644 index 00000000000..261eedeb412 --- /dev/null +++ b/doc/user/project/gpg_signed_commits/index.md @@ -0,0 +1 @@ +This document was moved to [another location](../repository/gpg_signed_commits/index.md). diff --git a/doc/user/project/import/bitbucket.md b/doc/user/project/import/bitbucket.md new file mode 100644 index 00000000000..b22c7db0047 --- /dev/null +++ b/doc/user/project/import/bitbucket.md @@ -0,0 +1,62 @@ +# Import your project from Bitbucket to GitLab + +Import your projects from Bitbucket to GitLab with minimal effort. + +## Overview + +>**Note:** +The [Bitbucket integration][bb-import] must be first enabled in order to be +able to import your projects from Bitbucket. Ask your GitLab administrator +to enable this if not already. + +- At its current state, the Bitbucket importer can import: + - the repository description (GitLab 7.7+) + - the Git repository data (GitLab 7.7+) + - the issues (GitLab 7.7+) + - the issue comments (GitLab 8.15+) + - the pull requests (GitLab 8.4+) + - the pull request comments (GitLab 8.15+) + - the milestones (GitLab 8.15+) + - the wiki (GitLab 8.15+) +- References to pull requests and issues are preserved (GitLab 8.7+) +- Repository public access is retained. If a repository is private in Bitbucket + it will be created as private in GitLab as well. + + +## How it works + +When issues/pull requests are being imported, the Bitbucket importer tries to find +the Bitbucket author/assignee in GitLab's database using the Bitbucket ID. For this +to work, the Bitbucket author/assignee should have signed in beforehand in GitLab +and **associated their Bitbucket account**. If the user is not +found in GitLab's database, the project creator (most of the times the current +user that started the import process) is set as the author, but a reference on +the issue about the original Bitbucket author is kept. + +The importer will create any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository will be imported under the user's +namespace that started the import process. + +## Importing your Bitbucket repositories + +1. Sign in to GitLab and go to your dashboard. +1. Click on **New project**. + +  + +1. Click on the "Bitbucket" button + +  + +1. Grant GitLab access to your Bitbucket account + +  + +1. Click on the projects that you'd like to import or **Import all projects**. + You can also select the namespace under which each project will be + imported. + +  + +[bb-import]: ../../../integration/bitbucket.md +[social sign-in]: ../../profile/account/social_sign_in.md diff --git a/doc/user/project/import/clearcase.md b/doc/user/project/import/clearcase.md new file mode 100644 index 00000000000..f23623ed485 --- /dev/null +++ b/doc/user/project/import/clearcase.md @@ -0,0 +1,47 @@ +# Migrating from ClearCase + +[ClearCase](https://www-03.ibm.com/software/products/en/clearcase/) is a set of +tools developed by IBM which also include a centralized version control system +similar to Git. + +A good read of ClearCase's basic concepts is can be found in this [StackOverflow +post](https://stackoverflow.com/a/645771/974710). + +The following table illustrates the main differences between ClearCase and Git: + +| Aspect | ClearCase | Git | +| ------ | --------- | --- | +| Repository model | Client-server | Distributed | +| Revision IDs | Branch + number | Global alphanumeric ID | +| Scope of Change | File | Directory tree snapshot | +| Concurrency model | Merge | Merge | +| Storage Method | Deltas | Full content | +| Client | CLI, Eclipse, CC Client | CLI, Eclipse, Git client/GUIs | +| Server | UNIX, Windows legacy systems | UNIX, macOS | +| License | Proprietary | GPL | + +_Taken from the slides [ClearCase and the journey to Git](https://www.open.collab.net/media/pdfs/ClearCase-and-the-journey-to-Git.pdf) provided by collab.net_ + +## Why migrate + +ClearCase can be difficult to manage both from a user and an admin perspective. +Migrating to Git/GitLab there is: + +- **No licensing costs**, Git is GPL while ClearCase is proprietary. +- **Shorter learning curve**, Git has a big community and a vast number of + tutorials to get you started. +- **Integration with modern tools**, migrating to Git and GitLab you can have + an open source end-to-end software development platform with built-in version + control, issue tracking, code review, CI/CD, and more. + +## How to migrate + +While there doesn't exist a tool to fully migrate from ClearCase to Git, here +are some useful links to get you started: + +- [Bridge for Git and ClearCase](https://github.com/charleso/git-cc) +- [Slides "ClearCase and the journey to Git"](https://www.open.collab.net/media/pdfs/ClearCase-and-the-journey-to-Git.pdf) +- [ClearCase to Git](https://therub.org/2013/07/19/clearcase-to-git/) +- [Dual syncing ClearCase to Git](https://therub.org/2013/10/22/dual-syncing-clearcase-and-git/) +- [Moving to Git from ClearCase](https://sateeshkumarb.wordpress.com/2011/01/15/moving-to-git-from-clearcase/) +- [ClearCase to Git webinar](https://www.brighttalk.com/webcast/11817/162473/clearcase-to-git) diff --git a/doc/user/project/import/cvs.md b/doc/user/project/import/cvs.md new file mode 100644 index 00000000000..cabd0eef8d6 --- /dev/null +++ b/doc/user/project/import/cvs.md @@ -0,0 +1,68 @@ +# Migrating from CVS + +[CVS](https://savannah.nongnu.org/projects/cvs) is an old centralized version +control system similar to [SVN](svn.md). + +## CVS vs Git + +The following list illustrates the main differences between CVS and Git: + +- **Git is distributed.** On the other hand, CVS is centralized using a client-server + architecture. This translates to Git having a more flexible workflow since + your working area is a copy of the entire repository. This decreases the + overhead when switching branches or merging for example, since you don't have + to communicate with a remote server. +- **Atomic operations.** In Git all operations are + [atomic](https://en.wikipedia.org/wiki/Atomic_commit), either they succeed as + whole, or they fail without any changes. In CVS, commits (and other operations) + are not atomic. If an operation on the repository is interrupted in the middle, + the repository can be left in an inconsistent state. +- **Storage method.** Changes in CVS are per file (changeset), while in Git + a committed file(s) is stored in its entirety (snapshot). That means that's + very easy in Git to revert or undo a whole change. +- **Revision IDs.** The fact that in CVS changes are per files, the revision ID + is depicted by version numbers, for example `1.4` reflects how many time a + given file has been changed. In Git, each version of a project as a whole + (each commit) has its unique name given by SHA-1. +- **Merge tracking.** Git uses a commit-before-merge approach rather than + merge-before-commit (or update-then-commit) like CVS. If while you were + preparing to create a new commit (new revision) somebody created a + new commit on the same branch and pushed to the central repository, CVS would + force you to first update your working directory and resolve conflicts before + allowing you to commit. This is not the case with Git. You first commit, save + your state in version control, then you merge the other developer's changes. + You can also ask the other developer to do the merge and resolve any conflicts + themselves. +- **Signed commits.** Git supports signing your commits with GPG for additional + security and verification that the commit indeed came from its original author. + GitLab can [integrate with GPG](../repository/gpg_signed_commits/index.md) + and show whether a signed commit is correctly verified. + +_Some of the items above were taken from this great +[Stack Overflow post](https://stackoverflow.com/a/824241/974710). For a more +complete list of differences, consult the +Wikipedia article on [comparing the different version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software)._ + +## Why migrate + +CVS is old with no new release since 2008. Git provides more tools to work +with (`git bisect` for one) which makes for a more productive workflow. +Migrating to Git/GitLab there is: + +- **Shorter learning curve**, Git has a big community and a vast number of + tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). +- **Integration with modern tools**, migrating to Git and GitLab you can have + an open source end-to-end software development platform with built-in version + control, issue tracking, code review, CI/CD, and more. +- **Support for many network protocols**. Git supports SSH, HTTP/HTTPS and rsync + among others, whereas CVS supports only SSH and its own insecure pserver + protocol with no user authentication. + +## How to migrate + +Here's a few links to get you started with the migration: + +- [Migrate using the `cvs-fast-export` tool](http://www.catb.org/~esr/reposurgeon/dvcs-migration-guide.html) ([_source code_](https://gitlab.com/esr/cvs-fast-export)) +- [Stack Overflow post on importing the CVS repo](https://stackoverflow.com/a/11490134/974710) +- [Convert a CVS repository to Git](http://www.techrepublic.com/blog/linux-and-open-source/convert-cvs-repositories-to-git/) +- [Man page of the `git-cvsimport` tool](https://www.kernel.org/pub/software/scm/git/docs/git-cvsimport.html) diff --git a/doc/user/project/import/fogbugz.md b/doc/user/project/import/fogbugz.md new file mode 100644 index 00000000000..17222c53675 --- /dev/null +++ b/doc/user/project/import/fogbugz.md @@ -0,0 +1,28 @@ +# Import your project from FogBugz to GitLab + +It only takes a few simple steps to import your project from FogBugz. +The importer will import all of your cases and comments with original case +numbers and timestamps. You will also have the opportunity to map FogBugz +users to GitLab users. + +1. From your GitLab dashboard click 'New project' +1. Click on the 'FogBugz' button + +  + +1. Enter your FogBugz URL, email address, and password. + +  + +1. Create mapping from FogBugz users to GitLab users. + +  + +1. Select the projects you wish to import by clicking the Import buttons + +  + +1. Once the import has finished click the link to take you to the project +dashboard. Follow the directions to push your existing repository. + +  diff --git a/doc/user/project/import/gitea.md b/doc/user/project/import/gitea.md new file mode 100644 index 00000000000..f5746a0fb31 --- /dev/null +++ b/doc/user/project/import/gitea.md @@ -0,0 +1,77 @@ +# Import your project from Gitea to GitLab + +Import your projects from Gitea to GitLab with minimal effort. + +## Overview + +>**Note:** +This requires Gitea `v1.0.0` or newer. + +- At its current state, Gitea importer can import: + - the repository description (GitLab 8.15+) + - the Git repository data (GitLab 8.15+) + - the issues (GitLab 8.15+) + - the pull requests (GitLab 8.15+) + - the milestones (GitLab 8.15+) + - the labels (GitLab 8.15+) +- Repository public access is retained. If a repository is private in Gitea + it will be created as private in GitLab as well. + +## How it works + +Since Gitea is currently not an OAuth provider, author/assignee cannot be mapped +to users in your GitLab's instance. This means that the project creator (most of +the times the current user that started the import process) is set as the author, +but a reference on the issue about the original Gitea author is kept. + +The importer will create any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository will be imported under the user's +namespace that started the import process. + +## Importing your Gitea repositories + +The importer page is visible when you create a new project. + + + +Click on the **Gitea** link and the import authorization process will start. + + + +### Authorize access to your repositories using a personal access token + +With this method, you will perform a one-off authorization with Gitea to grant +GitLab access your repositories: + +1. Go to <https://you-gitea-instance/user/settings/applications> (replace + `you-gitea-instance` with the host of your Gitea instance). +1. Click **Generate New Token**. +1. Enter a token description. +1. Click **Generate Token**. +1. Copy the token hash. +1. Go back to GitLab and provide the token to the Gitea importer. +1. Hit the **List Your Gitea Repositories** button and wait while GitLab reads + your repositories' information. Once done, you'll be taken to the importer + page to select the repositories to import. + +### Select which repositories to import + +After you've authorized access to your Gitea repositories, you will be +redirected to the Gitea importer page. + +From there, you can see the import statuses of your Gitea repositories. + +- Those that are being imported will show a _started_ status, +- those already successfully imported will be green with a _done_ status, +- whereas those that are not yet imported will have an **Import** button on the + right side of the table. + +If you want, you can import all your Gitea projects in one go by hitting +**Import all projects** in the upper left corner. + + + +--- + +You can also choose a different name for the project and a different namespace, +if you have the privileges to do so. diff --git a/doc/user/project/import/github.md b/doc/user/project/import/github.md new file mode 100644 index 00000000000..016f98966e3 --- /dev/null +++ b/doc/user/project/import/github.md @@ -0,0 +1,122 @@ +# Import your project from GitHub to GitLab + +Import your projects from GitHub to GitLab with minimal effort. + +## Overview + +>**Note:** +If you are an administrator you can enable the [GitHub integration][gh-import] +in your GitLab instance sitewide. This configuration is optional, users will +still be able to import their GitHub repositories with a +[personal access token][gh-token]. + +>**Note:** +Administrators of a GitLab instance (Community or Enterprise Edition) can also +use the [GitHub rake task][gh-rake] to import projects from GitHub without the +constrains of a Sidekiq worker. + +- At its current state, GitHub importer can import: + - the repository description (GitLab 7.7+) + - the Git repository data (GitLab 7.7+) + - the issues (GitLab 7.7+) + - the pull requests (GitLab 8.4+) + - the wiki pages (GitLab 8.4+) + - the milestones (GitLab 8.7+) + - the labels (GitLab 8.7+) + - the release note descriptions (GitLab 8.12+) +- References to pull requests and issues are preserved (GitLab 8.7+) +- Repository public access is retained. If a repository is private in GitHub + it will be created as private in GitLab as well. + +## How it works + +When issues/pull requests are being imported, the GitHub importer tries to find +the GitHub author/assignee in GitLab's database using the GitHub ID. For this +to work, the GitHub author/assignee should have signed in beforehand in GitLab +and **associated their GitHub account**. If the user is not +found in GitLab's database, the project creator (most of the times the current +user that started the import process) is set as the author, but a reference on +the issue about the original GitHub author is kept. + +The importer will create any new namespaces (groups) if they don't exist or in +the case the namespace is taken, the repository will be imported under the user's +namespace that started the import process. + +## Importing your GitHub repositories + +The importer page is visible when you create a new project. + + + +Click on the **GitHub** link and the import authorization process will start. +There are two ways to authorize access to your GitHub repositories: + +1. [Using the GitHub integration][gh-integration] (if it's enabled by your + GitLab administrator). This is the preferred way as it's possible to + preserve the GitHub authors/assignees. Read more in the [How it works](#how-it-works) + section. +1. [Using a personal access token][gh-token] provided by GitHub. + + + +### Authorize access to your repositories using the GitHub integration + +If the [GitHub integration][gh-import] is enabled by your GitLab administrator, +you can use it instead of the personal access token. + +1. First you may want to connect your GitHub account to GitLab in order for + the username mapping to be correct. +1. Once you connect GitHub, click the **List your GitHub repositories** button + and you will be redirected to GitHub for permission to access your projects. +1. After accepting, you'll be automatically redirected to the importer. + +You can now go on and [select which repositories to import](#select-which-repositories-to-import). + +### Authorize access to your repositories using a personal access token + +>**Note:** +For a proper author/assignee mapping for issues and pull requests, the +[GitHub integration][gh-integration] should be used instead of the +[personal access token][gh-token]. If the GitHub integration is enabled by your +GitLab administrator, it should be the preferred method to import your repositories. +Read more in the [How it works](#how-it-works) section. + +If you are not using the GitHub integration, you can still perform a one-off +authorization with GitHub to grant GitLab access your repositories: + +1. Go to <https://github.com/settings/tokens/new>. +1. Enter a token description. +1. Check the `repo` scope. +1. Click **Generate token**. +1. Copy the token hash. +1. Go back to GitLab and provide the token to the GitHub importer. +1. Hit the **List Your GitHub Repositories** button and wait while GitLab reads + your repositories' information. Once done, you'll be taken to the importer + page to select the repositories to import. + +### Select which repositories to import + +After you've authorized access to your GitHub repositories, you will be +redirected to the GitHub importer page. + +From there, you can see the import statuses of your GitHub repositories. + +- Those that are being imported will show a _started_ status, +- those already successfully imported will be green with a _done_ status, +- whereas those that are not yet imported will have an **Import** button on the + right side of the table. + +If you want, you can import all your GitHub projects in one go by hitting +**Import all projects** in the upper left corner. + + + +--- + +You can also choose a different name for the project and a different namespace, +if you have the privileges to do so. + +[gh-import]: ../../../integration/github.md "GitHub integration" +[gh-rake]: ../../../administration/raketasks/github_import.md "GitHub rake task" +[gh-integration]: #authorize-access-to-your-repositories-using-the-github-integration +[gh-token]: #authorize-access-to-your-repositories-using-a-personal-access-token diff --git a/doc/user/project/import/gitlab_com.md b/doc/user/project/import/gitlab_com.md new file mode 100644 index 00000000000..3b37da67a5b --- /dev/null +++ b/doc/user/project/import/gitlab_com.md @@ -0,0 +1,20 @@ +# Project importing from GitLab.com to your private GitLab instance + +You can import your existing GitLab.com projects to your GitLab instance. But keep in mind that it is possible only if +GitLab support is enabled on your GitLab instance. +You can read more about GitLab support [here](http://docs.gitlab.com/ce/integration/gitlab.html) +To get to the importer page you need to go to "New project" page. + +>**Note:** +If you are interested in importing Wiki and Merge Request data to your new +instance, you'll need to follow the instructions for [project export](../settings/import_export.md) + + + +Click on the "Import projects from GitLab.com" link and you will be redirected to GitLab.com +for permission to access your projects. After accepting, you'll be automatically redirected to the importer. + + + +To import a project, you can simple click "Import". The importer will import your repository and issues. +Once the importer is done, a new GitLab project will be created with your imported data. diff --git a/doc/user/project/import/img/bitbucket_import_grant_access.png b/doc/user/project/import/img/bitbucket_import_grant_access.png Binary files differnew file mode 100644 index 00000000000..429904e621d --- /dev/null +++ b/doc/user/project/import/img/bitbucket_import_grant_access.png diff --git a/doc/user/project/import/img/bitbucket_import_new_project.png b/doc/user/project/import/img/bitbucket_import_new_project.png Binary files differnew file mode 100644 index 00000000000..8ed528c2f09 --- /dev/null +++ b/doc/user/project/import/img/bitbucket_import_new_project.png diff --git a/doc/user/project/import/img/bitbucket_import_select_project.png b/doc/user/project/import/img/bitbucket_import_select_project.png Binary files differnew file mode 100644 index 00000000000..1bca6166ec8 --- /dev/null +++ b/doc/user/project/import/img/bitbucket_import_select_project.png diff --git a/doc/user/project/import/img/fogbugz_import_finished.png b/doc/user/project/import/img/fogbugz_import_finished.png Binary files differnew file mode 100644 index 00000000000..62c5c86c9b3 --- /dev/null +++ b/doc/user/project/import/img/fogbugz_import_finished.png diff --git a/doc/user/project/import/img/fogbugz_import_login.png b/doc/user/project/import/img/fogbugz_import_login.png Binary files differnew file mode 100644 index 00000000000..96bce70b74d --- /dev/null +++ b/doc/user/project/import/img/fogbugz_import_login.png diff --git a/doc/user/project/import/img/fogbugz_import_select_fogbogz.png b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png Binary files differnew file mode 100644 index 00000000000..b26c652e382 --- /dev/null +++ b/doc/user/project/import/img/fogbugz_import_select_fogbogz.png diff --git a/doc/user/project/import/img/fogbugz_import_select_project.png b/doc/user/project/import/img/fogbugz_import_select_project.png Binary files differnew file mode 100644 index 00000000000..ccc82f9d4cd --- /dev/null +++ b/doc/user/project/import/img/fogbugz_import_select_project.png diff --git a/doc/user/project/import/img/fogbugz_import_user_map.png b/doc/user/project/import/img/fogbugz_import_user_map.png Binary files differnew file mode 100644 index 00000000000..28ff55a8d89 --- /dev/null +++ b/doc/user/project/import/img/fogbugz_import_user_map.png diff --git a/doc/user/project/import/img/gitlab_importer.png b/doc/user/project/import/img/gitlab_importer.png Binary files differnew file mode 100644 index 00000000000..27d42eb492e --- /dev/null +++ b/doc/user/project/import/img/gitlab_importer.png diff --git a/doc/user/project/import/img/gitlab_new_project_page.png b/doc/user/project/import/img/gitlab_new_project_page.png Binary files differnew file mode 100644 index 00000000000..c673724f436 --- /dev/null +++ b/doc/user/project/import/img/gitlab_new_project_page.png diff --git a/doc/user/project/import/img/import_projects_from_gitea_new_import.png b/doc/user/project/import/img/import_projects_from_gitea_new_import.png Binary files differnew file mode 100644 index 00000000000..a3f603cbd0a --- /dev/null +++ b/doc/user/project/import/img/import_projects_from_gitea_new_import.png diff --git a/doc/user/project/import/img/import_projects_from_github_importer.png b/doc/user/project/import/img/import_projects_from_github_importer.png Binary files differnew file mode 100644 index 00000000000..d8effaf6075 --- /dev/null +++ b/doc/user/project/import/img/import_projects_from_github_importer.png diff --git a/doc/user/project/import/img/import_projects_from_github_select_auth_method.png b/doc/user/project/import/img/import_projects_from_github_select_auth_method.png Binary files differnew file mode 100644 index 00000000000..1ccb38a815e --- /dev/null +++ b/doc/user/project/import/img/import_projects_from_github_select_auth_method.png diff --git a/doc/user/project/import/img/import_projects_from_new_project_page.png b/doc/user/project/import/img/import_projects_from_new_project_page.png Binary files differnew file mode 100644 index 00000000000..97ca30b2087 --- /dev/null +++ b/doc/user/project/import/img/import_projects_from_new_project_page.png diff --git a/doc/user/project/import/index.md b/doc/user/project/import/index.md new file mode 100644 index 00000000000..8da6e2a8207 --- /dev/null +++ b/doc/user/project/import/index.md @@ -0,0 +1,24 @@ +# Migrating projects to a GitLab instance + +1. [From Bitbucket.org](bitbucket.md) +1. [From ClearCase](clearcase.md) +1. [From CVS](cvs.md) +1. [From FogBugz](fogbugz.md) +1. [From GitHub.com of GitHub Enterprise](github.md) +1. [From GitLab.com](gitlab_com.md) +1. [From Gitea](gitea.md) +1. [From Perforce](perforce.md) +1. [From SVN](svn.md) +1. [From TFS](tfs.md) + +In addition to the specific migration documentation above, you can import any +Git repository via HTTP from the New Project page. Be aware that if the +repository is too large the import can timeout. + +## Migrating from self-hosted GitLab to GitLab.com + +You can copy your repos by changing the remote and pushing to the new server, +but issues and merge requests can't be imported. + +If you want to retain all metadata like issues and merge requests, you can use +the [import/export feature](../settings/import_export.md). diff --git a/doc/user/project/import/perforce.md b/doc/user/project/import/perforce.md new file mode 100644 index 00000000000..aa7508e1e8e --- /dev/null +++ b/doc/user/project/import/perforce.md @@ -0,0 +1,50 @@ +# Migrating from Perforce Helix + +[Perforce Helix](https://www.perforce.com/) provides a set of tools which also +include a centralized, proprietary version control system similar to Git. + +## Perforce vs Git + +The following list illustrates the main differences between Perforce Helix and +Git: + +1. In general the biggest difference is that Perforce branching is heavyweight + compared to Git's lightweight branching. When you create a branch in Perforce, + it creates an integration record in their proprietary database for every file + in the branch, regardless how many were actually changed. Whereas Git was + implemented with a different architecture so that a single SHA acts as a pointer + to the state of the whole repo after the changes, making it very easy to branch. + This is what made feature branching workflows so easy to adopt with Git. +1. Also, context switching between branches is much easier in Git. If your manager + said 'You need to stop work on that new feature and fix this security + vulnerability' you can do so very easily in Git. +1. Having a complete copy of the project and its history on your local machine + means every transaction is superfast and Git provides that. You can branch/merge + and experiment in isolation, then clean up your mess before sharing your new + cool stuff with everyone. +1. Git also made code review simple because you could share your changes without + merging them to master, whereas Perforce had to implement a Shelving feature on + the server so others could review changes before merging. + +## Why migrate + +Perforce Helix can be difficult to manage both from a user and an admin +perspective. Migrating to Git/GitLab there is: + +- **No licensing costs**, Git is GPL while Perforce Helix is proprietary. +- **Shorter learning curve**, Git has a big community and a vast number of + tutorials to get you started. +- **Integration with modern tools**, migrating to Git and GitLab you can have + an open source end-to-end software development platform with built-in version + control, issue tracking, code review, CI/CD, and more. + +## How to migrate + +Git includes a built-in mechanism (`git p4`) to pull code from Perforce and to +submit back from Git to Perforce. + +Here's a few links to get you started: + +- [git-p4 manual page](https://www.kernel.org/pub/software/scm/git/docs/git-p4.html) +- [git-p4 example usage](https://git.wiki.kernel.org/index.php/Git-p4_Usage) +- [Git book migration guide](https://git-scm.com/book/en/v2/Git-and-Other-Systems-Migrating-to-Git#_perforce_import) diff --git a/doc/user/project/import/svn.md b/doc/user/project/import/svn.md new file mode 100644 index 00000000000..7a3628a39d7 --- /dev/null +++ b/doc/user/project/import/svn.md @@ -0,0 +1,183 @@ +# Migrating from SVN to GitLab + +Subversion (SVN) is a central version control system (VCS) while +Git is a distributed version control system. There are some major differences +between the two, for more information consult your favorite search engine. + +## Overview + +There are two approaches to SVN to Git migration: + +1. [Git/SVN Mirror](#smooth-migration-with-a-gitsvn-mirror-using-subgit) which: + - Makes the GitLab repository to mirror the SVN project. + - Git and SVN repositories are kept in sync; you can use either one. + - Smoothens the migration process and allows to manage migration risks. + +1. [Cut over migration](#cut-over-migration-with-svn2git) which: + - Translates and imports the existing data and history from SVN to Git. + - Is a fire and forget approach, good for smaller teams. + +## Smooth migration with a Git/SVN mirror using SubGit + +[SubGit](https://subgit.com) is a tool for a smooth, stress-free SVN to Git +migration. It creates a writable Git mirror of a local or remote Subversion +repository and that way you can use both Subversion and Git as long as you like. +It requires access to your GitLab server as it talks with the Git repositories +directly in a filesystem level. + +### SubGit prerequisites + +1. Install Oracle JRE 1.8 or newer. On Debian-based Linux distributions you can + follow [this article](http://www.webupd8.org/2012/09/install-oracle-java-8-in-ubuntu-via-ppa.html). +1. Download SubGit from https://subgit.com/download/. +1. Unpack the downloaded SubGit zip archive to the `/opt` directory. The `subgit` + command will be available at `/opt/subgit-VERSION/bin/subgit`. + +### SubGit configuration + +The first step to mirror you SVN repository in GitLab is to create a new empty +project which will be used as a mirror. For Omnibus installations the path to +the repository will be located at +`/var/opt/gitlab/git-data/repositories/USER/REPO.git` by default. For +installations from source, the default repository directory will be +`/home/git/repositories/USER/REPO.git`. For convenience, assign this path to a +variable: + +``` +GIT_REPO_PATH=/var/opt/gitlab/git-data/repositories/USER/REPOS.git +``` + +SubGit will keep this repository in sync with a remote SVN project. For +convenience, assign your remote SVN project URL to a variable: + +``` +SVN_PROJECT_URL=http://svn.company.com/repos/project +``` + +Next you need to run SubGit to set up a Git/SVN mirror. Make sure the following +`subgit` command is ran on behalf of the same user that keeps ownership of +GitLab Git repositories (by default `git`): + +``` +subgit configure --layout auto $SVN_PROJECT_URL $GIT_REPO_PATH +``` + +Adjust authors and branches mappings, if necessary. Open with your favorite +text editor: + +``` +edit $GIT_REPO_PATH/subgit/authors.txt +edit $GIT_REPO_PATH/subgit/config +``` + +For more information regarding the SubGit configuration options, refer to +[SubGit's documentation](https://subgit.com/documentation.html) website. + +### Initial translation + +Now that SubGit has configured the Git/SVN repos, run `subgit` to perform the +initial translation of existing SVN revisions into the Git repository: + +``` +subgit install $GIT_REPO_PATH +``` + +After the initial translation is completed, the Git repository and the SVN +project will be kept in sync by `subgit` - new Git commits will be translated to +SVN revisions and new SVN revisions will be translated to Git commits. Mirror +works transparently and does not require any special commands. + +If you would prefer to perform one-time cut over migration with `subgit`, use +the `import` command instead of `install`: + +``` +subgit import $GIT_REPO_PATH +``` + +### SubGit licensing + +Running SubGit in a mirror mode requires a +[registration](https://subgit.com/pricing.html). Registration is free for open +source, academic and startup projects. + +We're currently working on deeper GitLab/SubGit integration. You may track our +progress at [this issue](https://gitlab.com/gitlab-org/gitlab-ee/issues/990). + +### SubGit support + +For any questions related to SVN to GitLab migration with SubGit, you can +contact the SubGit team directly at [support@subgit.com](mailto:support@subgit.com). + +## Cut over migration with svn2git + +If you are currently using an SVN repository, you can migrate the repository +to Git and GitLab. We recommend a hard cut over - run the migration command once +and then have all developers start using the new GitLab repository immediately. +Otherwise, it's hard to keep changing in sync in both directions. The conversion +process should be run on a local workstation. + +Install `svn2git`. On all systems you can install as a Ruby gem if you already +have Ruby and Git installed. + +```bash +sudo gem install svn2git +``` + +On Debian-based Linux distributions you can install the native packages: + +```bash +sudo apt-get install git-core git-svn ruby +``` + +Optionally, prepare an authors file so `svn2git` can map SVN authors to Git authors. +If you choose not to create the authors file then commits will not be attributed +to the correct GitLab user. Some users may not consider this a big issue while +others will want to ensure they complete this step. If you choose to map authors +you will be required to map every author that is present on changes in the SVN +repository. If you don't, the conversion will fail and you will have to update +the author file accordingly. The following command will search through the +repository and output a list of authors. + +```bash +svn log --quiet | grep -E "r[0-9]+ \| .+ \|" | cut -d'|' -f2 | sed 's/ //g' | sort | uniq +``` + +Use the output from the last command to construct the authors file. +Create a file called `authors.txt` and add one mapping per line. + +``` +janedoe = Jane Doe <janedoe@example.com> +johndoe = John Doe <johndoe@example.com> +``` + +If your SVN repository is in the standard format (trunk, branches, tags, +not nested) the conversion is simple. For a non-standard repository see +[svn2git documentation](https://github.com/nirvdrum/svn2git). The following +command will checkout the repository and do the conversion in the current +working directory. Be sure to create a new directory for each repository before +running the `svn2git` command. The conversion process will take some time. + +```bash +svn2git https://svn.example.com/path/to/repo --authors /path/to/authors.txt +``` + +If your SVN repository requires a username and password add the +`--username <username>` and `--password <password` flags to the above command. +`svn2git` also supports excluding certain file paths, branches, tags, etc. See +[svn2git documentation](https://github.com/nirvdrum/svn2git) or run +`svn2git --help` for full documentation on all of the available options. + +Create a new GitLab project, where you will eventually push your converted code. +Copy the SSH or HTTP(S) repository URL from the project page. Add the GitLab +repository as a Git remote and push all the changes. This will push all commits, +branches and tags. + +```bash +git remote add origin git@gitlab.com:<group>/<project>.git +git push --all origin +git push --tags origin +``` + +## Contribute to this guide +We welcome all contributions that would expand this guide with instructions on +how to migrate from SVN and other version control systems. diff --git a/doc/user/project/import/tfs.md b/doc/user/project/import/tfs.md new file mode 100644 index 00000000000..8727c2ff6c3 --- /dev/null +++ b/doc/user/project/import/tfs.md @@ -0,0 +1,42 @@ +# Migrating from TFS + +[TFS](https://www.visualstudio.com/tfs/) is a set of tools developed by Microsoft +which also includes a centralized version control system (TFVC) similar to Git. + +In this document, we emphasize on the TFVC to Git migration. + +## TFVC vs Git + +The following list illustrates the main differences between TFVC and Git: + +- **Git is distributed** whereas TFVC is centralized using a client-server + architecture. This translates to Git having a more flexible workflow since + your working area is a copy of the entire repository. This decreases the + overhead when switching branches or merging for example, since you don't have + to communicate with a remote server. +- **Storage method.** Changes in CVS are per file (changeset), while in Git + a committed file(s) is stored in its entirety (snapshot). That means that's + very easy in Git to revert or undo a whole change. + +_Check also Microsoft's documentation on the +[comparison of Git and TFVC](https://www.visualstudio.com/en-us/docs/tfvc/comparison-git-tfvc) +and the Wikipedia article on +[comparing the different version control software](https://en.wikipedia.org/wiki/Comparison_of_version_control_software)._ + +## Why migrate + +Migrating to Git/GitLab there is: + +- **No licensing costs**, Git is GPL while TFVC is proprietary. +- **Shorter learning curve**, Git has a big community and a vast number of + tutorials to get you started (see our [Git topic](../../../topics/git/index.md)). +- **Integration with modern tools**, migrating to Git and GitLab you can have + an open source end-to-end software development platform with built-in version + control, issue tracking, code review, CI/CD, and more. + +## How to migrate + +The best option to migrate from TFVC to Git is to use the +[`git-tfs`](https://github.com/git-tfs/git-tfs) tool. A specific guide for the +migration exists: +[Migrate TFS to Git](https://github.com/git-tfs/git-tfs/blob/master/doc/usecases/migrate_tfs_to_git.md). diff --git a/doc/user/project/index.md b/doc/user/project/index.md index 91a19600951..d6b3d59d407 100644 --- a/doc/user/project/index.md +++ b/doc/user/project/index.md @@ -24,6 +24,7 @@ integrated platform from messing with history or pushing code without review - [Protected tags](protected_tags.md): Control over who has permission to create tags, and prevent accidental update or deletion + - [Signing commits](gpg_signed_commits/index.md): use GPG to sign your commits - [Merge Requests](merge_requests/index.md): Apply your branching strategy and get reviewed by your team - [Merge Request Approvals](https://docs.gitlab.com/ee/user/project/merge_requests/merge_request_approvals.html) (**EES/EEP**): Ask for approval before @@ -66,8 +67,6 @@ website with GitLab Pages **Other features:** - [Cycle Analytics](cycle_analytics.md): Review your development lifecycle -- [Koding integration](koding.md) (not available on GitLab.com): Integrate -with Koding to have access to a web terminal right from the GitLab UI - [Syntax highlighting](highlighting.md): An alternative to customize your code blocks, overriding GitLab's default choice of language @@ -90,15 +89,19 @@ from your fork to the upstream project ## Import or export a project -- Import a project from: - - [GitHub to GitLab](../../workflow/importing/import_projects_from_github.md) - - [BitBucket to GitLab](../../workflow/importing/import_projects_from_bitbucket.md) - - [Gitea to GitLab](../../workflow/importing/import_projects_from_gitea.md) - - [FogBugz to GitLab](../../workflow/importing/import_projects_from_fogbugz.md) +- [Import a project](import/index.md) from: + - [GitHub to GitLab](import/github.md) + - [BitBucket to GitLab](import/bitbucket.md) + - [Gitea to GitLab](import/gitea.md) + - [FogBugz to GitLab](import/fogbugz.md) - [Export a project from GitLab](settings/import_export.md#exporting-a-project-and-its-data) - [Importing and exporting projects between GitLab instances](settings/import_export.md) -## Leave a project +## Project's members + +Learn how to [add members to your projects](members/index.md). + +### Leave a project **Leave project** will only display on the project's dashboard when a project is part of a group (under a diff --git a/doc/user/project/integrations/img/jira_service_page.png b/doc/user/project/integrations/img/jira_service_page.png Binary files differindex e69376f74c4..63aa0e99a50 100644 --- a/doc/user/project/integrations/img/jira_service_page.png +++ b/doc/user/project/integrations/img/jira_service_page.png diff --git a/doc/user/project/integrations/jira.md b/doc/user/project/integrations/jira.md index 4f583879a4e..93aec56f8dc 100644 --- a/doc/user/project/integrations/jira.md +++ b/doc/user/project/integrations/jira.md @@ -10,7 +10,12 @@ JIRA](https://www.programmableweb.com/news/how-and-why-to-integrate-gitlab-jira/ ## Configuration -Each GitLab project can be configured to connect to a different JIRA instance. +Each GitLab project can be configured to connect to a different JIRA instance. That +means one GitLab project maps to _all_ JIRA projects in that JIRA instance once +the configuration is set up. Therefore, you don't have to explicitly associate +one GitLab project to any JIRA project. Once the configuration is set up, any JIRA +projects in the JIRA instance are already mapped to the GitLab project. + If you have one JIRA instance you can pre-fill the settings page with a default template, see the [Services Templates][services-templates] docs. @@ -103,7 +108,6 @@ in the table below. | ----- | ----------- | | `Web URL` | The base URL to the JIRA instance web interface which is being linked to this GitLab project. E.g., `https://jira.example.com`. | | `JIRA API URL` | The base URL to the JIRA instance API. Web URL value will be used if not set. E.g., `https://jira-api.example.com`. | -| `Project key` | Put a JIRA project key (in uppercase), e.g. `MARS` in this field. This is only for testing the configuration settings. JIRA integration in GitLab works with _all_ JIRA projects in your JIRA instance. This field will be removed in a future release. | | `Username` | The user name created in [configuring JIRA step](#configuring-jira). | | `Password` |The password of the user created in [configuring JIRA step](#configuring-jira). | | `Transition ID` | This is the ID of a transition that moves issues to a closed state. You can find this number under JIRA workflow administration ([see screenshot](img/jira_workflow_screenshot.png)). **Closing JIRA issues via commits or Merge Requests won't work if you don't set the ID correctly.** | diff --git a/doc/user/project/integrations/prometheus.md b/doc/user/project/integrations/prometheus.md index 6f15765751c..5fefb3b69c4 100644 --- a/doc/user/project/integrations/prometheus.md +++ b/doc/user/project/integrations/prometheus.md @@ -40,7 +40,7 @@ Installing and configuring Prometheus to monitor applications is fairly straight ### Configuring Omnibus GitLab Prometheus to monitor Kubernetes deployments With Omnibus GitLab running inside of Kubernetes, you can leverage the bundled -version of Prometheus to collect the supported metrics. Once enabled, Prometheus will automatically begin monitoring Kubernetes Nodes and any [annotated Pods](https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config>). +version of Prometheus to collect the supported metrics. Once enabled, Prometheus will automatically begin monitoring Kubernetes Nodes and any [annotated Pods](https://prometheus.io/docs/operating/configuration/#<kubernetes_sd_config>). 1. Read how to configure the bundled Prometheus server in the [Administration guide][gitlab-prometheus-k8s-monitor]. @@ -133,6 +133,8 @@ to integrate with. Once configured, GitLab will attempt to retrieve performance metrics for any environment which has had a successful deployment. +GitLab will automatically scan the Prometheus server for known metrics and attempt to identify the metrics for a particular environment. The supported metrics and scan process is detailed in our [Prometheus Metric Library documentation](prometheus_library/metrics.html). + [Learn more about monitoring environments.](../../../ci/environments.md#monitoring-environments) ## Determining the performance impact of a merge @@ -174,7 +176,7 @@ If the "Attempting to load performance data" screen continues to appear, it coul [prometheus-docker-image]: https://hub.docker.com/r/prom/prometheus/ [prometheus-yml]:samples/prometheus.yml [gitlab.com-ip-range]: https://gitlab.com/gitlab-com/infrastructure/issues/434 -[ci-environment-slug]: https://docs.gitlab.com/ce/ci/variables/#predefined-variables-environment-variables +[ci-environment-slug]: ../../../ci/variables/#predefined-variables-environment-variables [ce-8935]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8935 [ce-10408]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10408 [promgldocs]: ../../../administration/monitoring/prometheus/index.md diff --git a/doc/user/project/integrations/prometheus_library/kubernetes.md b/doc/user/project/integrations/prometheus_library/kubernetes.md index eb8cd821ddc..9f0308d8111 100644 --- a/doc/user/project/integrations/prometheus_library/kubernetes.md +++ b/doc/user/project/integrations/prometheus_library/kubernetes.md @@ -23,4 +23,4 @@ Prometheus server up and running. You have two options here: In order to isolate and only display relevant metrics for a given environment however, GitLab needs a method to detect which labels are associated. To do this, GitLab will [look for an `environment` label](metrics.md#identifying-environments). -If you are using [GitLab Auto-Deploy][autodeploy] and one of the two [provided Kubernetes monitoring solutions](../prometheus.md#getting-started-with-prometheus-monitoring), the `environment` label will be automatically added. +If you are using [GitLab Auto-Deploy][../../../ci/autodeploy/index.md] and one of the two [provided Kubernetes monitoring solutions](../prometheus.md#getting-started-with-prometheus-monitoring), the `environment` label will be automatically added. diff --git a/doc/user/project/integrations/prometheus_library/metrics.md b/doc/user/project/integrations/prometheus_library/metrics.md index 6bdffce9c55..f09ecf9ff2d 100644 --- a/doc/user/project/integrations/prometheus_library/metrics.md +++ b/doc/user/project/integrations/prometheus_library/metrics.md @@ -4,6 +4,7 @@ GitLab offers automatic detection of select [Prometheus exporters](https://prometheus.io/docs/instrumenting/exporters/). Currently supported exporters are: * [Kubernetes](kubernetes.md) * [NGINX](nginx.md) +* [NGINX Ingress Controller](nginx_ingress.md) * [HAProxy](haproxy.md) * [Amazon Cloud Watch](cloudwatch.md) @@ -14,10 +15,7 @@ We have tried to surface the most important metrics for each exporter, and will GitLab retrieves performance data from the configured Prometheus server, and attempts to identifying the presence of known metrics. Once identified, GitLab then needs to be able to map the data to a particular environment. In order to isolate and only display relevant metrics for a given environment, GitLab needs a method to detect which labels are associated. To do that, -GitLab will look for the required metrics which have a label that -matches the [$CI_ENVIRONMENT_SLUG][ci-environment-slug]. - -For example if you are deploying to an environment named `production`, there must be a label for the metric with the value of `production`. +GitLab uses the defined queries and fills in the environment specific variables. Typically this involves looking for the [$CI_ENVIRONMENT_SLUG](https://docs.gitlab.com/ee/ci/variables/#predefined-variables-environment-variables), but may also include other information such as the project's Kubernetes namespace. Each search query is defined in the [exporter specific documentation](#prometheus-metrics-library). ## Adding to the library diff --git a/doc/user/project/integrations/prometheus_library/nginx.md b/doc/user/project/integrations/prometheus_library/nginx.md index b3470773996..12e3321f5f3 100644 --- a/doc/user/project/integrations/prometheus_library/nginx.md +++ b/doc/user/project/integrations/prometheus_library/nginx.md @@ -8,8 +8,8 @@ GitLab has support for automatically detecting and monitoring NGINX. This is pro | Name | Query | | ---- | ----- | | Throughput (req/sec) | sum(rate(nginx_requests_total{server_zone!="*", server_zone!="_", %{environment_filter}}[2m])) | -| Latency (ms) | avg(nginx_upstream_response_msecs_avg{%{environment_filter}}) * 1000 | -| HTTP Error Rate (%) | sum(rate(haproxy_frontend_http_responses_total{code="5xx",%{environment_filter}}[2m])) / sum(rate(haproxy_frontend_http_responses_total{%{environment_filter}}[2m])) | +| Latency (ms) | avg(nginx_upstream_response_msecs_avg{%{environment_filter}}) | +| HTTP Error Rate (HTTP Errors / sec) | rate(nginx_responses_total{status_code="5xx", %{environment_filter}}[2m])) | ## Configuring Prometheus to monitor for NGINX metrics diff --git a/doc/user/project/integrations/prometheus_library/nginx_ingress.md b/doc/user/project/integrations/prometheus_library/nginx_ingress.md new file mode 100644 index 00000000000..84ee8bc45e5 --- /dev/null +++ b/doc/user/project/integrations/prometheus_library/nginx_ingress.md @@ -0,0 +1,25 @@ +# Monitoring NGINX Ingress Controller +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438) in GitLab 9.5 + +GitLab has support for automatically detecting and monitoring the Kubernetes NGINX ingress controller. This is provided by leveraging the built in Prometheus metrics included in [version 0.9.0](https://github.com/kubernetes/ingress/blob/master/controllers/nginx/Changelog.md#09-beta1) of the ingress. + +## Metrics supported + +| Name | Query | +| ---- | ----- | +| Throughput (req/sec) | sum(rate(nginx_upstream_requests_total{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) | +| Latency (ms) | avg(nginx_upstream_response_msecs_avg{upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}) | +| HTTP Error Rate (HTTP Errors / sec) | sum(rate(nginx_upstream_responses_total{status_code="5xx", upstream=~"%{kube_namespace}-%{ci_environment_slug}-.*"}[2m])) | + +## Configuring Prometheus to monitor for NGINX ingress metrics + +The easiest way to get started is to use at least version 0.9.0 of [NGINX ingress](https://github.com/kubernetes/ingress/tree/master/controllers/nginx). If you are using NGINX as your Kubernetes ingress, there is [direct support](https://github.com/kubernetes/ingress/pull/423) for enabling Prometheus monitoring in the 0.9.0 release. + +If you have deployed with the [gitlab-omnibus](https://docs.gitlab.com/ee/install/kubernetes/gitlab_omnibus.md) Helm chart, these metrics will be automatically enabled and annotated for Prometheus monitoring. + +## Specifying the Environment label + +In order to isolate and only display relevant metrics for a given environment +however, GitLab needs a method to detect which labels are associated. To do this, GitLab will search metrics with appropriate labels. In this case, the `upstream` label must be of the form `<Kubernetes Namespace>-<CI_ENVIRONMENT_SLUG>-*`. + +If you have used [Auto Deploy](https://docs.gitlab.com/ee/ci/autodeploy/index.html) to deploy your app, this format will be used automatically and metrics will be detected with no action on your part. diff --git a/doc/user/project/issues/confidential_issues.md b/doc/user/project/issues/confidential_issues.md index 1760b182114..0bf1f396f9d 100644 --- a/doc/user/project/issues/confidential_issues.md +++ b/doc/user/project/issues/confidential_issues.md @@ -9,7 +9,7 @@ keep security vulnerabilities private or prevent surprises from leaking out. ## Making an issue confidential -You can make an issue confidential either by creating a new issue or editing +You can make an issue confidential during issue creation or by editing an existing one. When you create a new issue, a checkbox right below the text area is available @@ -19,11 +19,19 @@ confidential checkbox and hit **Save changes**.  -## Making an issue non-confidential +## Modifying issue confidentiality -To make an issue non-confidential, all you have to do is edit it and unmark -the confidential checkbox. Once you save the issue, it will gain the default -visibility level you have chosen for your project. +There are two ways to change an issue's confidentiality. + +The first way is to edit the issue and mark/unmark the confidential checkbox. +Once you save the issue, it will change the confidentiality of the issue. + +The second way is to locate the Confidentiality section in the sidebar and click +**Edit**. A popup should appear and give you the option to turn on or turn off confidentiality. + +| Turn off confidentiality | Turn on confidentiality | +| :-----------: | :----------: | +|  |  | Every change from regular to confidential and vice versa, is indicated by a system note in the issue's comments. @@ -49,6 +57,12 @@ issue you are commenting on is confidential.  +There is also an indicator on the sidebar denoting confidentiality. + +| Confidential issue | Not confidential issue | +| :-----------: | :----------: | +|  |  | + ## Permissions and access to confidential issues There are two kinds of level access for confidential issues. The general rule diff --git a/doc/user/project/issues/img/confidential_issues_index_page.png b/doc/user/project/issues/img/confidential_issues_index_page.png Binary files differindex e4b492a2769..f3efe0ce04e 100755..100644 --- a/doc/user/project/issues/img/confidential_issues_index_page.png +++ b/doc/user/project/issues/img/confidential_issues_index_page.png diff --git a/doc/user/project/issues/img/confidential_issues_issue_page.png b/doc/user/project/issues/img/confidential_issues_issue_page.png Binary files differindex f04ec8ff32b..0f5c774d258 100755..100644 --- a/doc/user/project/issues/img/confidential_issues_issue_page.png +++ b/doc/user/project/issues/img/confidential_issues_issue_page.png diff --git a/doc/user/project/issues/img/confidential_issues_system_notes.png b/doc/user/project/issues/img/confidential_issues_system_notes.png Binary files differindex 82e0dd8e85e..355be80ecb6 100755..100644 --- a/doc/user/project/issues/img/confidential_issues_system_notes.png +++ b/doc/user/project/issues/img/confidential_issues_system_notes.png diff --git a/doc/user/project/issues/img/group_issues_list_view.png b/doc/user/project/issues/img/group_issues_list_view.png Binary files differnew file mode 100644 index 00000000000..5d20e8cbc89 --- /dev/null +++ b/doc/user/project/issues/img/group_issues_list_view.png diff --git a/doc/user/project/issues/img/issue_tracker.png b/doc/user/project/issues/img/issue_tracker.png Binary files differdeleted file mode 100755 index ab25cb64d13..00000000000 --- a/doc/user/project/issues/img/issue_tracker.png +++ /dev/null diff --git a/doc/user/project/issues/img/project_issues_list_view.png b/doc/user/project/issues/img/project_issues_list_view.png Binary files differnew file mode 100644 index 00000000000..2fcc9e8d9da --- /dev/null +++ b/doc/user/project/issues/img/project_issues_list_view.png diff --git a/doc/user/project/issues/img/sidebar_confidential_issue.png b/doc/user/project/issues/img/sidebar_confidential_issue.png Binary files differnew file mode 100755 index 00000000000..d99a1ca756e --- /dev/null +++ b/doc/user/project/issues/img/sidebar_confidential_issue.png diff --git a/doc/user/project/issues/img/sidebar_move_issue.png b/doc/user/project/issues/img/sidebar_move_issue.png Binary files differnew file mode 100644 index 00000000000..111f7861364 --- /dev/null +++ b/doc/user/project/issues/img/sidebar_move_issue.png diff --git a/doc/user/project/issues/img/sidebar_not_confidential_issue.png b/doc/user/project/issues/img/sidebar_not_confidential_issue.png Binary files differnew file mode 100755 index 00000000000..2e6cbbc5b3a --- /dev/null +++ b/doc/user/project/issues/img/sidebar_not_confidential_issue.png diff --git a/doc/user/project/issues/img/turn_off_confidentiality.png b/doc/user/project/issues/img/turn_off_confidentiality.png Binary files differnew file mode 100644 index 00000000000..248ae6522d6 --- /dev/null +++ b/doc/user/project/issues/img/turn_off_confidentiality.png diff --git a/doc/user/project/issues/img/turn_on_confidentiality.png b/doc/user/project/issues/img/turn_on_confidentiality.png Binary files differnew file mode 100644 index 00000000000..fac4c833699 --- /dev/null +++ b/doc/user/project/issues/img/turn_on_confidentiality.png diff --git a/doc/user/project/issues/index.md b/doc/user/project/issues/index.md index 1f78849a92c..0f187946a4a 100644 --- a/doc/user/project/issues/index.md +++ b/doc/user/project/issues/index.md @@ -7,7 +7,7 @@ of solving a problem. It allows you, your team, and your collaborators to share and discuss proposals before and while implementing them. -Issues and the GitLab Issue Tracker are available in all +GitLab Issues and the GitLab Issue Tracker are available in all [GitLab Products](https://about.gitlab.com/products/) as part of the [GitLab Workflow](https://about.gitlab.com/2016/10/25/gitlab-workflow-an-overview/). @@ -48,11 +48,27 @@ for feature proposals and another one for bug reports. ## Issue Tracker -The issue tracker is the collection of opened and closed issues created in a project. +The Issue Tracker is the collection of opened and closed issues created in a project. +It is available for all projects, from the moment the project is created. - +Find the issue tracker by navigating to your **Project's homepage** > **Issues**. -Find the issue tracker by navigating to your **Project's Dashboard** > **Issues**. +### Issues per project + +When you access your project's issues, GitLab will present them in a list, +and you can use the tabs available to quickly filter by open and closed issues. + + + +You can also [search and filter](../../search/index.md#issues-and-merge-requests-per-project) the results more deeply with GitLab's search capacities. + +### Issues per group + +View all the issues in a group (that is, all the issues across all projects in that +group) by navigating to **Group > Issues**. This view also has the open and closed +issue tabs. + + ## GitLab Issues Functionalities @@ -70,6 +86,10 @@ Read through the [documentation on creating issues](create_new_issue.md). Learn distinct ways to [close issues](closing_issues.md) in GitLab. +## Moving issues + +Read through the [documentation on moving issues](moving_issues.md). + ## Create a merge request from an issue Learn more about it on the [GitLab Issues Functionalities documentation](issues_functionalities.md#18-new-merge-request). @@ -120,6 +140,12 @@ to find out more about this feature. With [GitLab Enterprise Edition Starter](https://about.gitlab.com/gitlab-ee/), you can also create various boards per project with [Multiple Issue Boards](https://docs.gitlab.com/ee/user/project/issue_board.html#multiple-issue-boards). +### External Issue Tracker + +Alternatively to GitLab's built-in Issue Tracker, you can also use an [external +tracker](../../../integration/external-issue-tracker.md) such as Jira, Redmine, +or Bugzilla. + ### Issue's API Read through the [API documentation](../../../api/issues.md). diff --git a/doc/user/project/issues/moving_issues.md b/doc/user/project/issues/moving_issues.md new file mode 100644 index 00000000000..211a651b89e --- /dev/null +++ b/doc/user/project/issues/moving_issues.md @@ -0,0 +1,10 @@ +# Moving Issues + +Please read through the [GitLab Issue Documentation](index.md) for an overview on GitLab Issues. + +Moving an issue will close it and duplicate it on the specified project. +There will also be a system note added to both issues indicating where it came from or went to. + +You can move an issue with the "Move issue" button at the bottom of the right-sidebar when viewing the issue. + + diff --git a/doc/user/project/koding.md b/doc/user/project/koding.md index 455e2ee47b4..86e06a39e59 100644 --- a/doc/user/project/koding.md +++ b/doc/user/project/koding.md @@ -1,6 +1,9 @@ # Koding integration -> [Introduced][ce-5909] in GitLab 8.11. +>**Notes:** +- **As of GitLab 10.0, the Koding integration is deprecated and will be removed + in a future version.** +- [Introduced][ce-5909] in GitLab 8.11. This document will guide you through using Koding integration on GitLab in detail. For configuring and installing please follow the diff --git a/doc/user/project/members/img/access_requests_management.png b/doc/user/project/members/img/access_requests_management.png Binary files differnew file mode 100644 index 00000000000..3693bed869b --- /dev/null +++ b/doc/user/project/members/img/access_requests_management.png diff --git a/doc/user/project/members/img/add_new_user_to_project_settings.png b/doc/user/project/members/img/add_new_user_to_project_settings.png Binary files differnew file mode 100644 index 00000000000..40db600455f --- /dev/null +++ b/doc/user/project/members/img/add_new_user_to_project_settings.png diff --git a/doc/user/project/members/img/add_user_email_accept.png b/doc/user/project/members/img/add_user_email_accept.png Binary files differnew file mode 100644 index 00000000000..763b3ff463d --- /dev/null +++ b/doc/user/project/members/img/add_user_email_accept.png diff --git a/doc/user/project/members/img/add_user_email_ready.png b/doc/user/project/members/img/add_user_email_ready.png Binary files differnew file mode 100644 index 00000000000..0066eb3427b --- /dev/null +++ b/doc/user/project/members/img/add_user_email_ready.png diff --git a/doc/user/project/members/img/add_user_email_search.png b/doc/user/project/members/img/add_user_email_search.png Binary files differnew file mode 100644 index 00000000000..66bcd6aad80 --- /dev/null +++ b/doc/user/project/members/img/add_user_email_search.png diff --git a/doc/user/project/members/img/add_user_give_permissions.png b/doc/user/project/members/img/add_user_give_permissions.png Binary files differnew file mode 100644 index 00000000000..376a3eefccc --- /dev/null +++ b/doc/user/project/members/img/add_user_give_permissions.png diff --git a/doc/user/project/members/img/add_user_import_members_from_another_project.png b/doc/user/project/members/img/add_user_import_members_from_another_project.png Binary files differnew file mode 100644 index 00000000000..0c32001098e --- /dev/null +++ b/doc/user/project/members/img/add_user_import_members_from_another_project.png diff --git a/doc/user/project/members/img/add_user_imported_members.png b/doc/user/project/members/img/add_user_imported_members.png Binary files differnew file mode 100644 index 00000000000..51fd7688890 --- /dev/null +++ b/doc/user/project/members/img/add_user_imported_members.png diff --git a/doc/user/project/members/img/add_user_list_members.png b/doc/user/project/members/img/add_user_list_members.png Binary files differnew file mode 100644 index 00000000000..e0fa404288d --- /dev/null +++ b/doc/user/project/members/img/add_user_list_members.png diff --git a/doc/user/project/members/img/add_user_members_menu.png b/doc/user/project/members/img/add_user_members_menu.png Binary files differnew file mode 100644 index 00000000000..8e61d15fe65 --- /dev/null +++ b/doc/user/project/members/img/add_user_members_menu.png diff --git a/doc/user/project/members/img/add_user_search_people.png b/doc/user/project/members/img/add_user_search_people.png Binary files differnew file mode 100644 index 00000000000..41767a9167c --- /dev/null +++ b/doc/user/project/members/img/add_user_search_people.png diff --git a/doc/user/project/members/img/max_access_level.png b/doc/user/project/members/img/max_access_level.png Binary files differnew file mode 100644 index 00000000000..63f33f9d91d --- /dev/null +++ b/doc/user/project/members/img/max_access_level.png diff --git a/doc/user/project/members/img/other_group_sees_shared_project.png b/doc/user/project/members/img/other_group_sees_shared_project.png Binary files differnew file mode 100644 index 00000000000..e4c93a13abb --- /dev/null +++ b/doc/user/project/members/img/other_group_sees_shared_project.png diff --git a/doc/user/project/members/img/request_access_button.png b/doc/user/project/members/img/request_access_button.png Binary files differnew file mode 100644 index 00000000000..608baccb0ca --- /dev/null +++ b/doc/user/project/members/img/request_access_button.png diff --git a/doc/user/project/members/img/share_project_with_groups.png b/doc/user/project/members/img/share_project_with_groups.png Binary files differnew file mode 100644 index 00000000000..0907438cb84 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups.png diff --git a/doc/user/project/members/img/share_project_with_groups_tab.png b/doc/user/project/members/img/share_project_with_groups_tab.png Binary files differnew file mode 100644 index 00000000000..fc489aae003 --- /dev/null +++ b/doc/user/project/members/img/share_project_with_groups_tab.png diff --git a/doc/user/project/members/img/withdraw_access_request_button.png b/doc/user/project/members/img/withdraw_access_request_button.png Binary files differnew file mode 100644 index 00000000000..6edd786b151 --- /dev/null +++ b/doc/user/project/members/img/withdraw_access_request_button.png diff --git a/doc/user/project/members/index.md b/doc/user/project/members/index.md new file mode 100644 index 00000000000..b8dd96087f1 --- /dev/null +++ b/doc/user/project/members/index.md @@ -0,0 +1,116 @@ +# Project's members + +You can manage the groups and users and their access levels in all of your +projects. You can also personalize the access level you give each user, +per-project. + +You should have `master` or `owner` [permissions](../../permissions.md) to add +or import a new user to your project. + +To view, edit, add, and remove project's members, go to your +project's **Settings > Members**. + +--- + +## Add a user + +Right next to **People**, start typing the name or username of the user you +want to add. + + + +--- + +Select the user and the [permission level](../../user/permissions.md) +that you'd like to give the user. Note that you can select more than one user. + + + +--- + +Once done, hit **Add users to project** and they will be immediately added to +your project with the permissions you gave them above. + + + +--- + +From there on, you can either remove an existing user or change their access +level to the project. + +## Import users from another project + +You can import another project's users in your own project by hitting the +**Import members** button on the upper right corner of the **Members** menu. + +In the dropdown menu, you can see only the projects you are Master on. + + + +--- + +Select the one you want and hit **Import project members**. A flash message +notifying you that the import was successful will appear, and the new members +are now in the project's members list. Notice that the permissions that they +had on the project you imported from are retained. + + + +--- + +## Invite people using their e-mail address + +If a user you want to give access to doesn't have an account on your GitLab +instance, you can invite them just by typing their e-mail address in the +user search field. + + + +--- + +As you can imagine, you can mix inviting multiple people and adding existing +GitLab users to the project. + + + +--- + +Once done, hit **Add users to project** and watch that there is a new member +with the e-mail address we used above. From there on, you can resend the +invitation, change their access level or even delete them. + + + +--- + +Once the user accepts the invitation, they will be prompted to create a new +GitLab account using the same e-mail address the invitation was sent to. + +## Request access to a project + +As a project owner you can enable or disable non members to request access to +your project. Go to the project settings and click on **Allow users to request access**. + +As a user, you can request to be a member of a project. Go to the project you'd +like to be a member of, and click the **Request Access** button on the right +side of your screen. + + + +--- + +Project owners & masters will be notified of your request and will be able to approve or +decline it on the members page. + + + +--- + +If you change your mind before your request is approved, just click the +**Withdraw Access Request** button. + + + +## Share project with group + +Alternatively, you can [share a project with an entire group](share_project_with_groups.md) instead of adding users one by one. diff --git a/doc/user/project/members/share_project_with_groups.md b/doc/user/project/members/share_project_with_groups.md new file mode 100644 index 00000000000..f5c748a03b3 --- /dev/null +++ b/doc/user/project/members/share_project_with_groups.md @@ -0,0 +1,43 @@ +# Share Projects with other Groups + +You can share projects with other [groups](../../group/index.md). This makes it +possible to add a group of users to a project with a single action. + +## Groups as collections of users + +Groups are used primarily to [create collections of projects](../../group/index.md), but you can also +take advantage of the fact that groups define collections of _users_, namely the group +members. + +## Sharing a project with a group of users + +The primary mechanism to give a group of users, say 'Engineering', access to a project, +say 'Project Acme', in GitLab is to make the 'Engineering' group the owner of 'Project +Acme'. But what if 'Project Acme' already belongs to another group, say 'Open Source'? +This is where the group sharing feature can be of use. + +To share 'Project Acme' with the 'Engineering' group, go to the project settings page for 'Project Acme' and use the left navigation menu to go to the **Settings > Members** section. + + + +Then select the 'Share with group' tab by clicking it. + +Now you can add the 'Engineering' group with the maximum access level of your choice. Click 'Share' to share it. + + + +After sharing 'Project Acme' with 'Engineering', the project will be listed on the group dashboard. + + + +## Maximum access level + +In the example above, the maximum access level of 'Developer' for members from 'Engineering' means that users with higher access levels in 'Engineering' ('Master' or 'Owner') will only have 'Developer' access to 'Project Acme'. + +## Share project with group lock + +It is possible to prevent projects in a group from [sharing +a project with another group](../members/share_project_with_groups.md). +This allows for tighter control over project access. + +Learn more about [Share with group lock](../../group/index.html#share-with-group-lock). diff --git a/doc/user/project/merge_requests/img/group_merge_requests_list_view.png b/doc/user/project/merge_requests/img/group_merge_requests_list_view.png Binary files differnew file mode 100644 index 00000000000..02a88d0112f --- /dev/null +++ b/doc/user/project/merge_requests/img/group_merge_requests_list_view.png diff --git a/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png Binary files differnew file mode 100644 index 00000000000..9b8aee47411 --- /dev/null +++ b/doc/user/project/merge_requests/img/merge_request_diff_file_navigation.png diff --git a/doc/user/project/merge_requests/img/project_merge_requests_list_view.png b/doc/user/project/merge_requests/img/project_merge_requests_list_view.png Binary files differnew file mode 100644 index 00000000000..702ec1a2949 --- /dev/null +++ b/doc/user/project/merge_requests/img/project_merge_requests_list_view.png diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md index 9bdf2a998d3..26c6277d33a 100644 --- a/doc/user/project/merge_requests/index.md +++ b/doc/user/project/merge_requests/index.md @@ -56,6 +56,23 @@ B. Consider you're a web developer writing a webpage for your company's: 1. Once approved, your merge request is [squashed and merged](https://docs.gitlab.com/ee/user/project/merge_requests/squash_and_merge.html), and [deployed to staging with GitLab Pages](https://about.gitlab.com/2016/08/26/ci-deployment-and-environments/) (Squash and Merge is available in GitLab Enterprise Edition Starter) 1. Your production team [cherry picks](#cherry-pick-changes) the merge commit into production +## Merge requests per project + +View all the merge requests within a project by navigating to **Project > Merge Requests**. + +When you access your project's merge requests, GitLab will present them in a list, +and you can use the tabs available to quickly filter by open and closed. You can also [search and filter the results](../../search/index.md#issues-and-merge-requests-per-project). + + + +## Merge requests per group + +View all the merge requests in a group (that is, all the merge requests across all projects in that +group) by navigating to **Group > Merge Requests**. This view also has the open, merged, and closed +merge request tabs, from which you can [search and filter the results](../../search/index.md#issues-and-merge-requests-per-group). + + + ## Authorization for merge requests There are two main ways to have a merge request flow with GitLab: @@ -120,6 +137,14 @@ have been marked as a **Work In Progress**. [Learn more about settings a merge request as "Work In Progress".](work_in_progress_merge_requests.md) +## Merge request diff file navigation + +The diff view has a persistent dropdown for file navigation. As you scroll through +diffs with a large number of files and/or many changes in those files, you can +easily jump to any changed file through the dropdown navigation. + + + ## Ignore whitespace changes in Merge Request diff view If you click the **Hide whitespace changes** button, you can see the diff @@ -141,7 +166,6 @@ all your changes will be available to preview by anyone with the Review Apps lin [Read more about Review Apps.](../../../ci/review_apps/index.md) - ## Tips Here are some tips that will help you be more efficient with merge requests in @@ -230,4 +254,4 @@ git checkout origin/merge-requests/1 ``` [protected branches]: ../protected_branches.md -[ee]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition" +[ee]: https://about.gitlab.com/gitlab-ee/ "GitLab Enterprise Edition"
\ No newline at end of file diff --git a/doc/user/project/pipelines/job_artifacts.md b/doc/user/project/pipelines/job_artifacts.md index e853bfff444..4e93e680fd2 100644 --- a/doc/user/project/pipelines/job_artifacts.md +++ b/doc/user/project/pipelines/job_artifacts.md @@ -100,16 +100,21 @@ inside GitLab that make that possible. It is possible to download the latest artifacts of a job via a well known URL so you can use it for scripting purposes. +>**Note:** +The latest artifacts are considered as the artifacts created by jobs in the +latest pipeline that succeeded for the specific ref. +Artifacts for other pipelines can be accessed with direct access to them. + The structure of the URL to download the whole artifacts archive is the following: ``` -https://example.com/<namespace>/<project>/builds/artifacts/<ref>/download?job=<job_name> +https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/download?job=<job_name> ``` To download a single file from the artifacts use the following URL: ``` -https://example.com/<namespace>/<project>/builds/artifacts/<ref>/raw/<path_to_file>?job=<job_name> +https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/raw/<path_to_file>?job=<job_name> ``` For example, to download the latest artifacts of the job named `coverage` of @@ -117,26 +122,26 @@ the `master` branch of the `gitlab-ce` project that belongs to the `gitlab-org` namespace, the URL would be: ``` -https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/download?job=coverage +https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/download?job=coverage ``` To download the file `coverage/index.html` from the same artifacts use the following URL: ``` -https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/raw/coverage/index.html?job=coverage +https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/raw/coverage/index.html?job=coverage ``` There is also a URL to browse the latest job artifacts: ``` -https://example.com/<namespace>/<project>/builds/artifacts/<ref>/browse?job=<job_name> +https://example.com/<namespace>/<project>/-/jobs/artifacts/<ref>/browse?job=<job_name> ``` For example: ``` -https://gitlab.com/gitlab-org/gitlab-ce/builds/artifacts/master/browse?job=coverage +https://gitlab.com/gitlab-org/gitlab-ce/-/jobs/artifacts/master/browse?job=coverage ``` The latest builds are also exposed in the UI in various places. Specifically, diff --git a/doc/user/project/pipelines/settings.md b/doc/user/project/pipelines/settings.md index 3ff5a08d72c..dbc1305101f 100644 --- a/doc/user/project/pipelines/settings.md +++ b/doc/user/project/pipelines/settings.md @@ -66,10 +66,30 @@ in the pipelines settings page. ## Visibility of pipelines -For public and internal projects, the pipelines page can be accessed by -anyone and those logged in respectively. If you wish to hide it so that only -the members of the project or group have access to it, uncheck the **Public -pipelines** checkbox and save the changes. +Access to pipelines and job details (including output of logs and artifacts) +is checked against your current user access level and the **Public pipelines** +project setting. + +If **Public pipelines** is enabled (default): + +- for **public** projects, anyone can view the pipelines and access the job details + (output logs and artifacts) +- for **internal** projects, any logged in user can view the pipelines + and access the job details + (output logs and artifacts) +- for **private** projects, any member (guest or higher) can view the pipelines + and access the job details + (output logs and artifacts) + +If **Public pipelines** is disabled: + +- for **public** projects, anyone can view the pipelines, but only members + (reporter or higher) can access the job details (output logs and artifacts) +- for **internal** projects, any logged in user can view the pipelines, + but only members (reporter or higher) can access the job details (output logs + and artifacts) +- for **private** projects, only members (reporter or higher) + can view the pipelines and access the job details (output logs and artifacts) ## Auto-cancel pending pipelines diff --git a/doc/user/project/protected_branches.md b/doc/user/project/protected_branches.md index 0570d9f471f..0cbb0c878c2 100644 --- a/doc/user/project/protected_branches.md +++ b/doc/user/project/protected_branches.md @@ -115,6 +115,14 @@ Deleting a protected branch is only allowed via the web interface, not via Git. This means that you can't accidentally delete a protected branch from your command line or a Git client application. +## Running pipelines on protected branches + +The permission to merge or push to protected branches is used to define if a user can +run CI/CD pipelines and execute actions on jobs that are related to those branches. + +See [Security on protected branches](../../ci/pipelines.md#security-on-protected-branches) +for details about the pipelines security model. + ## Changelog **9.2** diff --git a/doc/user/project/quick_actions.md b/doc/user/project/quick_actions.md index ce4dd4e99d5..6a5d2d40927 100644 --- a/doc/user/project/quick_actions.md +++ b/doc/user/project/quick_actions.md @@ -38,3 +38,4 @@ do. | `/award :emoji:` | Toggle award for :emoji: | | `/board_move ~column` | Move issue to column on the board | | `/duplicate #issue` | Closes this issue and marks it as a duplicate of another issue | +| `/move path/to/project` | Moves issue to another project | diff --git a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png b/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png Binary files differnew file mode 100644 index 00000000000..8e26d98f1b0 --- /dev/null +++ b/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_paste_pub.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png b/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png Binary files differnew file mode 100644 index 00000000000..5c14df36d73 --- /dev/null +++ b/doc/user/project/repository/gpg_signed_commits/img/profile_settings_gpg_keys_single_key.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png b/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png Binary files differnew file mode 100644 index 00000000000..088ecfa6d89 --- /dev/null +++ b/doc/user/project/repository/gpg_signed_commits/img/project_signed_and_unsigned_commits.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png b/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png Binary files differnew file mode 100644 index 00000000000..4e3392406b1 --- /dev/null +++ b/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_unverified_signature.png diff --git a/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png b/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png Binary files differnew file mode 100644 index 00000000000..766970dee81 --- /dev/null +++ b/doc/user/project/repository/gpg_signed_commits/img/project_signed_commit_verified_signature.png diff --git a/doc/user/project/repository/gpg_signed_commits/index.md b/doc/user/project/repository/gpg_signed_commits/index.md new file mode 100644 index 00000000000..20aadb8f7ff --- /dev/null +++ b/doc/user/project/repository/gpg_signed_commits/index.md @@ -0,0 +1,256 @@ +# Signing commits with GPG + +> [Introduced][ce-9546] in GitLab 9.5. + +GitLab can show whether a commit is verified or not when signed with a GPG key. +All you need to do is upload the public GPG key in your profile settings. + +GPG verified tags are not supported yet. + +## Getting started with GPG + +Here are a few guides to get you started with GPG: + +- [Git Tools - Signing Your Work](https://git-scm.com/book/en/v2/Git-Tools-Signing-Your-Work) +- [Managing OpenPGP Keys](https://riseup.net/en/security/message-security/openpgp/gpg-keys) +- [OpenPGP Best Practices](https://riseup.net/en/security/message-security/openpgp/best-practices) +- [Creating a new GPG key with subkeys](https://www.void.gr/kargig/blog/2013/12/02/creating-a-new-gpg-key-with-subkeys/) (advanced) + +## How GitLab handles GPG + +GitLab uses its own keyring to verify the GPG signature. It does not access any +public key server. + +In order to have a commit verified on GitLab the corresponding public key needs +to be uploaded to GitLab. For a signature to be verified three conditions need +to be met: + +1. The public key needs to be added your GitLab account +1. One of the emails in the GPG key matches your **primary** email +1. The committer's email matches the verified email from the gpg key + +## Generating a GPG key + +>**Notes:** +- If your Operating System has `gpg2` installed, replace `gpg` with `gpg2` in + the following commands. +- If Git is using `gpg` and you get errors like `secret key not available` or + `gpg: signing failed: secret key not available`, run the following command to + change to `gpg2`: + ``` + git config --global gpg.program gpg2 + ``` + +If you don't already have a GPG key, the following steps will help you get +started: + +1. [Install GPG](https://www.gnupg.org/download/index.html) for your operating system +1. Generate the private/public key pair with the following command: + + ```sh + gpg --full-gen-key + ``` + + This will spawn a series of questions. + +1. The first question is which algorithm can be used. Select the kind you want + or press <kbd>Enter</kbd> to choose the default (RSA and RSA): + + ``` + Please select what kind of key you want: + (1) RSA and RSA (default) + (2) DSA and Elgamal + (3) DSA (sign only) + (4) RSA (sign only) + Your selection? 1 + ``` + +1. The next question is key length. We recommend to choose the highest value + which is `4096`: + + ``` + RSA keys may be between 1024 and 4096 bits long. + What keysize do you want? (2048) 4096 + Requested keysize is 4096 bits + ``` +1. Next, you need to specify the validity period of your key. This is something + subjective, and you can use the default value which is to never expire: + + ``` + Please specify how long the key should be valid. + 0 = key does not expire + <n> = key expires in n days + <n>w = key expires in n weeks + <n>m = key expires in n months + <n>y = key expires in n years + Key is valid for? (0) 0 + Key does not expire at all + ``` + +1. Confirm that the answers you gave were correct by typing `y`: + + ``` + Is this correct? (y/N) y + ``` + +1. Enter you real name, the email address to be associated with this key (should + match the primary email address you use in GitLab) and an optional comment + (press <kbd>Enter</kbd> to skip): + + ``` + GnuPG needs to construct a user ID to identify your key. + + Real name: Mr. Robot + Email address: mr@robot.sh + Comment: + You selected this USER-ID: + "Mr. Robot <mr@robot.sh>" + + Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O + ``` + +1. Pick a strong password when asked and type it twice to confirm. +1. Use the following command to list the private GPG key you just created: + + ``` + gpg --list-secret-keys mr@robot.sh + ``` + + Replace `mr@robot.sh` with the email address you entered above. + +1. Copy the GPG key ID that starts with `sec`. In the following example, that's + `0x30F2B65B9246B6CA`: + + ``` + sec rsa4096/0x30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <mr@robot.sh> + ssb rsa4096/0xB7ABC0813E4028C0 2017-08-18 [E] + ``` + +1. Export the public key of that ID (replace your key ID from the previous step): + + ``` + gpg --armor --export 0x30F2B65B9246B6CA + ``` + +1. Finally, copy the public key and [add it in your profile settings](#adding-a-gpg-key-to-your-account) + +## Adding a GPG key to your account + +>**Note:** +Once you add a key, you cannot edit it, only remove it. In case the paste +didn't work, you'll have to remove the offending key and re-add it. + +You can add a GPG key in your profile's settings: + +1. On the upper right corner, click on your avatar and go to your **Settings**. + +  + +1. Navigate to the **GPG keys** tab and paste your _public_ key in the 'Key' + box. + +  + +1. Finally, click on **Add key** to add it to GitLab. You will be able to see + its fingerprint, the corresponding email address and creation date. + +  + +## Associating your GPG key with Git + +After you have [created your GPG key](#generating-a-gpg-key) and [added it to +your account](#adding-a-gpg-key-to-your-account), it's time to tell Git which +key to use. + +1. Use the following command to list the private GPG key you just created: + + ``` + gpg --list-secret-keys mr@robot.sh + ``` + + Replace `mr@robot.sh` with the email address you entered above. + +1. Copy the GPG key ID that starts with `sec`. In the following example, that's + `0x30F2B65B9246B6CA`: + + ``` + sec rsa4096/0x30F2B65B9246B6CA 2017-08-18 [SC] + D5E4F29F3275DC0CDA8FFC8730F2B65B9246B6CA + uid [ultimate] Mr. Robot <mr@robot.sh> + ssb rsa4096/0xB7ABC0813E4028C0 2017-08-18 [E] + ``` + +1. Tell Git to use that key to sign the commits: + + ``` + git config --global user.signingkey 0x30F2B65B9246B6CA + ``` + + Replace `0x30F2B65B9246B6CA` with your GPG key ID. + +## Signing commits + +After you have [created your GPG key](#generating-a-gpg-key) and [added it to +your account](#adding-a-gpg-key-to-your-account), you can start signing your +commits: + +1. Commit like you used to, the only difference is the addition of the `-S` flag: + + ``` + git commit -S -m "My commit msg" + ``` + +1. Enter the passphrase of your GPG key when asked. +1. Push to GitLab and check that your commits [are verified](#verifying-commits). + +If you don't want to type the `-S` flag every time you commit, you can tell Git +to sign your commits automatically: + +``` +git config --global commit.gpgsign true +``` + +## Verifying commits + +1. Within a project or [merge request](../../merge_requests/index.md), navigate to + the **Commits** tab. Signed commits will show a badge containing either + "Verified" or "Unverified", depending on the verification status of the GPG + signature. + +  + +1. By clicking on the GPG badge, details of the signature are displayed. + +  + +  + +## Revoking a GPG key + +Revoking a key **unverifies** already signed commits. Commits that were +verified by using this key will change to an unverified state. Future commits +will also stay unverified once you revoke this key. This action should be used +in case your key has been compromised. + +To revoke a GPG key: + +1. On the upper right corner, click on your avatar and go to your **Settings**. +1. Navigate to the **GPG keys** tab. +1. Click on **Revoke** besides the GPG key you want to delete. + +## Removing a GPG key + +Removing a key **does not unverify** already signed commits. Commits that were +verified by using this key will stay verified. Only unpushed commits will stay +unverified once you remove this key. To unverify already signed commits, you need +to [revoke the associated GPG key](#revoking-a-gpg-key) from your account. + +To remove a GPG key from your account: + +1. On the upper right corner, click on your avatar and go to your **Settings**. +1. Navigate to the **GPG keys** tab. +1. Click on the trash icon besides the GPG key you want to delete. + +[ce-9546]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/9546 diff --git a/doc/user/project/repository/index.md b/doc/user/project/repository/index.md index 4b2c435a120..235af83353d 100644 --- a/doc/user/project/repository/index.md +++ b/doc/user/project/repository/index.md @@ -20,7 +20,9 @@ documentation. For security reasons, when using the command line, we strongly recommend you to [connect with GitLab via SSH](../../../ssh/README.md). -## Create and edit files +## Files + +### Create and edit files Host your codebase in GitLab repositories by pushing your files to GitLab. You can either use the user interface (UI), or connect your local computer @@ -47,6 +49,10 @@ it's easier to do so [via GitLab UI](web_editor.md): To get started with the command line, please read through the [command line basics documentation](../../../gitlab-basics/command-line-commands.md). +### Find files + +Use GitLab's [file finder](../../../workflow/file_finder.md) to search for files in a repository. + ## Branches When you submit changes in a new branch, you create a new version @@ -105,6 +111,8 @@ right from the UI. - **Revert a commit:** Easily [revert a commit](../merge_requests/revert_changes.md#reverting-a-commit) from the UI to a selected branch. +- **Sign a commit:** +Use GPG to [sign your commits](gpg_signed_commits/index.md). ## Repository size diff --git a/doc/user/project/settings/import_export.md b/doc/user/project/settings/import_export.md index 35960ade3d4..23b1c61cd16 100644 --- a/doc/user/project/settings/import_export.md +++ b/doc/user/project/settings/import_export.md @@ -9,6 +9,9 @@ > application settings (`/admin/application_settings`) under 'Import sources'. > Ask your administrator if you don't see the **GitLab export** button when > creating a new project. +> - Starting with GitLab 10.0, administrators can disable the project export option +> on the GitLab instance in application settings (`/admin/application_settings`) +> under 'Visibility and Access Controls'. > - You can find some useful raketasks if you are an administrator in the > [import_export](../../../administration/raketasks/project_import_export.md) > raketask. @@ -25,17 +28,18 @@ with all their related data and be moved into a new GitLab instance. ## Version history -| GitLab version | Import/Export version | -| -------- | -------- | -| 9.4.0 to current | 0.1.8 | -| 9.2.0 | 0.1.7 | -| 8.17.0 | 0.1.6 | -| 8.13.0 | 0.1.5 | -| 8.12.0 | 0.1.4 | -| 8.10.3 | 0.1.3 | -| 8.10.0 | 0.1.2 | -| 8.9.5 | 0.1.1 | -| 8.9.0 | 0.1.0 | +| GitLab version | Import/Export version | +| ---------------- | --------------------- | +| 10.0 to current | 0.2.0 | +| 9.4.0 | 0.1.8 | +| 9.2.0 | 0.1.7 | +| 8.17.0 | 0.1.6 | +| 8.13.0 | 0.1.5 | +| 8.12.0 | 0.1.4 | +| 8.10.3 | 0.1.3 | +| 8.10.0 | 0.1.2 | +| 8.9.5 | 0.1.1 | +| 8.9.0 | 0.1.0 | > The table reflects what GitLab version we updated the Import/Export version at. > For instance, 8.10.3 and 8.11 will have the same Import/Export version (0.1.3) diff --git a/doc/user/project/wiki/index.md b/doc/user/project/wiki/index.md index e9ee1abc6c1..c0b8a87f038 100644 --- a/doc/user/project/wiki/index.md +++ b/doc/user/project/wiki/index.md @@ -4,7 +4,7 @@ A separate system for documentation called Wiki, is built right into each GitLab project. It is enabled by default on all new projects and you can find it under **Wiki** in your project. -Wikis are very convenient if you don't want to keep you documentation in your +Wikis are very convenient if you don't want to keep your documentation in your repository, but you do want to keep it in the same project where your code resides. |
