Migrating to GitHub

This walkthrough will help you migrate a project's source code, license, documentation, and issues from CodePlex to GitHub.

GitHub is centered around your repository. Where CodePlex has a project with various metadata pivots, almost everything in GitHub is handled by files in your source code. So, we've written a few new features that will prepare your CodePlex project to become a GitHub repository.

Source code

First, let's move your source code. In this step, you'll use the GitHub source code import tools to create a new GitHub repository that contains your source code and history. If you're currently using TFS, SVN, or Mercurial, the import tools will convert you to Git along the way.

1. Log into GitHub.

2. Log into CodePlex.

3. Go to your project's Source Code tab and click the GitHub button. 

4. Back on GitHub, fill in a repository name and click Begin import.

5. (TFS users only) Provide your TFS username and CodePlex password and click Submit.

You can get your TFS username (which is different from your CodePlex username) by clicking Connect on your project's Source Code page.

6. (TFS users only) Select the project to import and click Submit.

7. Match CodePlex authors to GitHub users by clicking Match authors, or click the link to go to your new repo.

License, Documentation, and Home

Next, let's move your license, documentation, and home page. GitHub recommends using a /docs folder in your repository. You can put either Markdown or HTML content in this folder.

CodePlex supports both a custom wiki markup and HTML markup. When you export your documentation, if you used our wiki markup, we'll do a best-effort migration from that to Markdown. Otherwise, we'll just give you your HTML.

1. Go to your project's License tab and click the Download license button.

2. Go to your project's Home tab and click the Download Wiki button. 


3. Open and extract the downloaded ZIP file. It will contain two folders, "docs" and "raw".

4. Go back to your GitHub repository and click the Upload files button to upload your license and docs.

5. Drag-and-drop or select the file you downloaded earlier (1), write a commit message like "Add LICENSE and docs exported from CodePlex" (2), and click Commit changes (3).

6. Add a README to your project by clicking Add a README. If you're new to GitHub-style README files, there's lots of great advice out there to help you get started. You can also link to files in your /docs folder from your README.

Issues

Now, let's move your issues.

1. Download the latest release of the migration tool from GitHub. Locate the downloaded file.

2. On Windows, right-click the downloaded ZIP and click Properties. In the resulting dialog, check the Unblock checkbox before clicking OK.

 

3. Extract the ZIP file to a folder.

4. Open a shell and navigate to the folder from the previous step.

5. Run the following command, replacing each [placeholder] with your project's information.

Microsoft.CodePlex.Migration.WorkItemMigrator.exe -p [CodePlexProject] -o [GitHubRepoOwner] -r [GitHubRepo] -t [GitHubPersonalAccessToken]

I've moved

Finally, tell people you've moved to GitHub by adding a banner to your CodePlex project. This will also disable new issue and discussion creation.

Go to your project's Settings tab and put your GitHub repository's URL in the New Project Location textbox and click Save.

What's next

GitHub has some great tools and documentation that can help you get started with GitHub and Git:

Using ClickOnce to distribute your app? GitHub recommends using Squirrel.Windows instead:

Alternatively, the following users have had some success using ClickOnce from GitHub:

If you'd like to use GitHub wikis instead a /docs folder for your documentation, this blog post can help:

FAQ

Why can't I import my source code to GitHub using Subversion?

CodePlex doesn't support the SVN APIs needed by GitHub's source code import tools. Instead, sign into CodePlex before clicking the GitHub button; this will let GitHub use the TFS endpoint to import your code.

Last edited Oct 31 at 8:15 PM by CodePlexAdmin, version 5