Using the Migrations API, you can export an organization's repositories. After exporting your repositories, you'll download the migration archive that's used for the import process.

Note: Fork relationships do not persist after a migration.

To export repository data from GitHub.com, use the Migrations API.

The Migrations API is currently in a preview period, which means that the endpoints and parameters may change in the future. To access the Migrations API, you must provide a custom media type in the Accept header: application/vnd.github.wyandotte-preview+json. The examples below include the custom media type.

Generating a migration archive

Note: Locking a repository prevents users from pushing to the repository or modifying a repository's resources, like issues, labels, milestones, wikis, and comments. New teams and collaborators can't be associated with a locked repository.

If you're performing a trial run, you don't need to lock repositories. Otherwise, it's highly recommended.

  1. Notify members of your organization that you'll be performing a migration. The export can take several minutes, depending on the number of repositories being exported. The full migration including import may take several hours so we recommend doing a trial run in order to determine how long the full process will take.

  2. Start a migration by POSTing to the migration endpoint. You'll need:

    • Your access token for authentication

    • A list of the repositories you want to migrate

      curl -H "Authorization: token GITHUB_ACCESS_TOKEN" -X POST \
-H "Accept: application/vnd.github.wyandotte-preview+json" \
-d'{"lock_repositories":true,"repositories":["orgname/reponame", "orgname/reponame"]}' \
https://api.github.com/orgs/orgname/migrations

    • If you want to lock the repositories before migrating them, make sure lock_repositories is set to true. This is highly recommended.

    • You can exclude file attachments by passing exclude_attachments: true to the endpoint. File attachments can be large and may needlessly bloat your final migration archive. The final archive size must be less than 5 GB.

    This request returns a unique id which represents your migration. You'll need it for subsequent calls to the Migrations API.

  3. Send a GET request to the migration status endpoint to fetch the status of a migration. You'll need:

    • Your access token for authentication
    • The unique id of the migration 
      curl -H "Authorization: token GITHUB_ACCESS_TOKEN" \
-H "Accept: application/vnd.github.wyandotte-preview+json" \
https://api.github.com/orgs/orgname/migrations/id

    A migration can be in one of the following states:

    • pending, which means the migration hasn't started yet.
    • exporting, which means the migration is in progress.
    • exported, which means the migration finished successfully.
    • failed, which means the migration failed.

  4. After your migration has exported, download the migration archive by sending a GET request to the migration download endpoint. You'll need:

    • Your access token for authentication
    • The unique id of the migration 
      curl -H "Accept: application/vnd.github.wyandotte-preview+json" \
-u GITHUB_USERNAME:GITHUB_ACCESS_TOKEN \
-L -o migration_archive.tar.gz \
https://api.github.com/orgs/orgname/migrations/id/archive

  5. The migration archive is automatically deleted after seven days. If you would prefer to delete it sooner, you can send a DELETE request to the migration archive delete endpoint. You'll need:

    • Your access token for authentication
    • The unique id of the migration 
      curl -H "Authorization: token GITHUB_ACCESS_TOKEN" -X DELETE \
-H "Accept: application/vnd.github.wyandotte-preview+json" \
https://api.github.com/orgs/orgname/migrations/id/archive

  6. To import the archived migration data to a GitHub Enterprise instance, see "Importing migration data to GitHub Enterprise".