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..2082de06f47 100644 Binary files a/doc/workflow/importing/img/import_projects_from_github_importer.png and b/doc/workflow/importing/img/import_projects_from_github_importer.png differ 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 Binary files a/doc/workflow/importing/img/import_projects_from_github_new_project_page.png and b/doc/workflow/importing/img/import_projects_from_github_new_project_page.png differ 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 Binary files /dev/null and b/doc/workflow/importing/img/import_projects_from_github_select_auth_method.png differ diff --git a/doc/workflow/importing/import_projects_from_github.md b/doc/workflow/importing/import_projects_from_github.md index dd33513d9e3..7e5dd628c94 100644 --- a/doc/workflow/importing/import_projects_from_github.md +++ b/doc/workflow/importing/import_projects_from_github.md @@ -1,64 +1,112 @@ # 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: -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. +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, the [GitHub integration][gh-integration] +should be used instead of using a [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. + +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 . +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. ![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. - -### Note - -When we are importing Issues/Pull Requests we try to find the original -author or assignee using the Github Id, but for this to work the original -author or assignee should had signed in before on the GitLab instance and -associated their GitHub account. If we don’t find the user in our database -we set the project creator (most of the times the current user that started -the import process) as the author but we keep a reference on the issue -about the original author. - [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