Merge branch 'master' of gitlab.com:gitlab-org/gitlab-ce

7 files changed, 108 insertions, 35 deletions

diff --git a/doc/workflow/README.md b/doc/workflow/README.md
index dcb9c32ad58..e8ecb8d8fb4 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -1,6 +1,7 @@
 # Workflow
 
 - [Change your time zone](timezone.md)
+- [Cycle Analytics](../user/project/cycle_analytics.md)
 - [Description templates](../user/project/description_templates.md)
 - [Feature branch workflow](workflow.md)
 - [GitLab Flow](gitlab_flow.md)
diff --git a/doc/workflow/importing/img/import_projects_from_github_importer.png b/doc/workflow/importing/img/import_projects_from_github_importer.png
index b6ed8dd692a..eadd33c695f 100644
--- a/doc/workflow/importing/img/import_projects_from_github_importer.png
+++ b/doc/workflow/importing/img/import_projects_from_github_importer.png
diff --git a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png
index c8f35a50f48..6e91c430a33 100644
--- a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png
+++ b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png
diff --git a/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png b/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png
new file mode 100644
index 00000000000..c11863ab10c
--- /dev/null
+++ b/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png
diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md
index 370d885d366..c36dfdb78ec 100644
--- a/doc/workflow/importing/import_projects_from_github.md
+++ b/doc/workflow/importing/import_projects_from_github.md
@@ -1,54 +1,118 @@
 # Import your project from GitHub to GitLab

 

+Import your projects from GitHub to GitLab with minimal effort.

+

+## Overview

+

 >**Note:**

-In order to enable the GitHub import setting, you may also want to

-enable the [GitHub integration][gh-import] in your GitLab instance. This

-configuration is optional, you will be able import your GitHub repositories

-with a Personal Access Token.

+If you are an administrator you can enable the [GitHub integration][gh-import]

+in your GitLab instance sitewide. This configuration is optional, users will be

+able import their GitHub repositories with a [personal access token][gh-token].

 

-At its current state, GitHub importer can import:

+- 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.

 

-- the repository description (introduced in GitLab 7.7)

-- the git repository data (introduced in GitLab 7.7)

-- the issues (introduced in GitLab 7.7)

-- the pull requests (introduced in GitLab 8.4)

-- the wiki pages (introduced in GitLab 8.4)

-- the milestones (introduced in GitLab 8.7)

-- the labels (introduced in GitLab 8.7)

-- the release note descriptions (introduced in GitLab 8.12)

+## How it works

 

-With GitLab 8.7+, references to pull requests and issues are preserved.

+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**][social sign-in]. 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 page is visible when you [create a new project][new-project].

-Click on the **GitHub** link and, if you are logged in via the GitHub

-integration, you will be redirected to GitHub for permission to access your

-projects. After accepting, you'll be automatically redirected to the importer.

+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.

 

-If you are not using the GitHub integration, you can still perform a one-off

-authorization with GitHub to access your projects.

+## Importing your GitHub repositories

 

-Alternatively, you can also enter a GitHub Personal Access Token. Once you enter

-your token, you'll be taken to the importer.

+The importer page is visible when you create a new project.

 

 ![New project page on GitLab](img/import_projects_from_github_new_project_page.png)

 

----

+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.

+

+![Select authentication method](img/import_projects_from_github_select_auth_method.png)

+

+### 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. Follow the [social sign-in] documentation

+   on how to do so.

+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.

 

-While at the GitHub importer page, you can see the import statuses of your

-GitHub projects. Those that are being imported will show a _started_ status,

-those already imported will be green, whereas those that are not yet imported

-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.

+If you want, you can import all your GitHub projects in one go by hitting

+**Import all projects** in the upper left corner.

 

 ![GitHub importer page](img/import_projects_from_github_importer.png)

 

 ---

 

-The importer will create any new namespaces if they don't exist or in the

-case the namespace is taken, the project will be imported on the user's

-namespace.

+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"

-[ee-gh]: http://docs.gitlab.com/ee/integration/github.html "GitHub integration for GitLab EE"

 [new-project]: ../../gitlab-basics/create-project.md "How to create a new project in GitLab"

+[gh-integration]: #authorize-access-to-your-repositories-using-the-github-integration

+[gh-token]: #authorize-access-to-your-repositories-using-a-personal-access-token

+[social sign-in]: ../../profile/account/social_sign_in.md

diff --git a/doc/workflow/lfs/lfs_administration.md b/doc/workflow/lfs/lfs_administration.md
index 9dc1e9b47e3..b3c73e947f0 100644
--- a/doc/workflow/lfs/lfs_administration.md
+++ b/doc/workflow/lfs/lfs_administration.md
@@ -45,5 +45,5 @@ In `config/gitlab.yml`:
 * Currently, storing GitLab Git LFS objects on a non-local storage (like S3 buckets)
   is not supported
 * Currently, removing LFS objects from GitLab Git LFS storage is not supported
-* LFS authentications via SSH is not supported for the time being
-* Only compatible with the GitLFS client versions 1.1.0 or 1.0.2.
+* LFS authentications via SSH was added with GitLab 8.12
+* Only compatible with the GitLFS client versions 1.1.0 and up, or 1.0.2.
diff --git a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md
index 9fe065fa680..1a4f213a792 100644
--- a/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md
+++ b/doc/workflow/lfs/manage_large_binaries_with_git_lfs.md
@@ -35,6 +35,10 @@ Documentation for GitLab instance administrators is under [LFS administration do
   credentials store is recommended
 * Git LFS always assumes HTTPS so if you have GitLab server on HTTP you will have
   to add the URL to Git config manually (see #troubleshooting)
+  
+>**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication
+ still goes over HTTP, but now the SSH client passes the correct credentials
+ to the Git LFS client, so no action is required by the user.
 
 ## Using Git LFS
 
@@ -132,6 +136,10 @@ git config --add lfs.url "http://gitlab.example.com/group/project.git/info/lfs"
 
 ### Credentials are always required when pushing an object
 
+>**Note**: With 8.12 GitLab added LFS support to SSH. The Git LFS communication
+ still goes over HTTP, but now the SSH client passes the correct credentials
+ to the Git LFS client, so no action is required by the user.
+
 Given that Git LFS uses HTTP Basic Authentication to authenticate the user pushing
 the LFS object on every push for every object, user HTTPS credentials are required.