# migrate-github-project

> Migrate GitHub projects (https://docs.github.com/en/issues/planning-and-tracking-with-projects) between GitHub products and organizations

Latest version **1.3.1** (published 2023-08-04) · MIT license · 0 weekly downloads

> **Deprecated.** This package is deprecated.

## Install

```sh
npm install migrate-github-project
pnpm add migrate-github-project
yarn add migrate-github-project
bun add migrate-github-project
```

Provides the command `migrate-github-project`.

## Health

**Score 10/100 (F)** — status: deprecated.

Negative: deprecated.

## Facts

| | |
|---|---|
| Version | 1.3.1 |
| Published | 2023-08-04 |
| First published | 2023-07-31 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM |
| Dependencies | 9 |
| Unpacked size | 49.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Tim Rogers |
| Maintainers | timrogers |

## Links

- npm: https://www.npmjs.com/package/migrate-github-project
- Repository: https://github.com/timrogers/migrate-github-project
- Homepage: https://github.com/timrogers/formanator
- Issues: https://github.com/timrogers/migrate-github-project/issues
- npm.io page: https://npm.io/package/migrate-github-project

## Dependencies (9)

- [boxen](https://npm.io/package/boxen.md) ^7.1.1
- [chalk](https://npm.io/package/chalk.md) ^5.3.0
- [octokit](https://npm.io/package/octokit.md) ^3.1.0
- [winston](https://npm.io/package/winston.md) ^3.10.0
- [commander](https://npm.io/package/commander.md) ^11.0.0
- [prompt-sync](https://npm.io/package/prompt-sync.md) ^4.2.0
- [@fast-csv/parse](https://npm.io/package/@fast-csv/parse.md) ^4.3.6
- [@octokit/graphql](https://npm.io/package/@octokit/graphql.md) ^7.0.1
- [@octokit/plugin-paginate-graphql](https://npm.io/package/@octokit/plugin-paginate-graphql.md) ^4.0.0

## Recent versions

- 1.3.1 (latest) — 2023-08-04
- 1.3.0 — 2023-08-03
- 1.2.1 — 2023-08-02
- 1.2.0 — 2023-08-01
- 1.1.0 — 2023-08-01
- 1.0.0 — 2023-07-31

## README

# Migrate GitHub Project

Migrate [GitHub Projects](https://docs.github.com/en/issues/planning-and-tracking-with-projects) between:

* different GitHub products (e.g. GitHub Enterprise Server to GitHub.com)
* organizations using the same GitHub product (e.g. classic GitHub.com organization to [Enterprise Managed Users](https://docs.github.com/en/enterprise-cloud@latest/admin/identity-and-access-management/using-enterprise-managed-users-for-iam/about-enterprise-managed-users) organization).
* users using the same GitHub product

## Requirements

To use `migrate-github-project`, you must be running a [supported release of Node.js](https://github.com/nodejs/release#release-schedule). At the time of writing, v16, v18 and v20 are supported.

## Limitations

The following data is not migrated and will be skipped:

* Views
* The order of project items displayed in your views
* Workflows
* Iteration custom fields
* Draft issues' assignees

Migrated draft issues will show as being created by the person who ran the migration at the time they ran the migration. A note will be prepended to the body with original author login and timestamp.

## Instructions

### Step 1. Migrate your issues and pull requests

Items in GitHub Projects are linked to issues and pull requests. Before you can migrate a project with `migrate-github-project`, you need to migrate the relevant issues and pull requests.

If you're migrating from GitHub Enterprise Server to GitHub.com or between organizations on GitHub.com, you can migrate your issues and pull requests using [GitHub Enterprise Importer](https://docs.github.com/en/migrations/using-github-enterprise-importer).

If you're migrating to GitHub Enterprise Server, you can migrate your issues and pull requests using [`ghe-migrator`](https://docs.github.com/en/enterprise-cloud@latest/migrations/using-ghe-migrator/about-ghe-migrator).

When you run your migrations, make a note of the new owner and repo name for each repository.

### Step 2. Install `migrate-github-project`

Install the Node.js package from `npm` by running `npm install -g migrate-github-project`.

### Step 3: Export your project from migration source

`migrate-github-project` works in two distinct phases: export and import. The first step is to export your project and its items from your migration source.

To export a project, you'll need a token with appropriate permissions. You'll need a classic token with the `read:project` and `repo` scopes, [authorized for SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) if applicable.

You can export your project and its items using the `migrate-github-project export` command:

```bash
migrate-github-project export \
    # A GitHub access token with the permissions described above. This can also be configured using the `GITHUB_TOKEN` environment variable.
    --access-token GITHUB_TOKEN \
    # The organization or user who owns the project you want to export
    --project-owner monalisa \
    # The type of the owner of the project you want to export (defaults to organization; only required if the owner is a user)
    --project-owner-type user \
    # The number of the project you want to export
    --project-number 1337 \
    # OPTIONAL: The base URL of the GitHub API, if you're migrating from a migration source other than GitHub.com.
    --base-url https://github.acme.inc/api/v3
```

When the export finishes, you'll have two files written to your current directory:

* `project.json`: The raw data of your project and all of its project items
* `repository-mappings.csv`: A repository mappings CSV template that you need to fill out with the names of your repositories in the migration target

### Step 4. Complete the repository mappings template

You'll need to complete the `repository-mappings.csv` file outputted from the `export` command with repository mappings, so the tool knows how to match repositories in your migration source to repositories in your migration target.

The CSV will look like this:

```
source_repository,target_repository
corp/widgets,
corp/website,
```

Imagine that you're in the process of migrating from GitHub Enterprise Server to GitHub.com, and you've already moved your repositories into a new GitHub.com organization called `monalisa-emu`. You'd fill out the CSV like this:

```
source_repository,target_repository
corp/widgets,monalisa-emu/widgets
corp/website,monalisa-emu/website
```

If you don't want to map a repository - for example because it hasn't been migrated - just delete the line from the CSV or leave the `target_repository` blank. If a repository hasn't been mapped, project items related to that repository will be skipped during the import.

### Step 5. Import your project into your migration target

You've exported your data and filled out the repository mappings template. You can now import your project into your migration target.

To export a project, you'll need a token with appropriate permissions. You'll need a classic token with the `read:project` and `repo` scopes, [authorized for SSO](https://docs.github.com/en/enterprise-cloud@latest/authentication/authenticating-with-saml-single-sign-on/authorizing-a-personal-access-token-for-use-with-saml-single-sign-on) if applicable. If you're creating an organization project, you'll also need the `read:org` scope.

You can import your project using the `migrate-github-project import` command:

```bash
migrate-github-project import \
    # A GitHub access token with the permissions described above. This can also be configured using the `GITHUB_TOKEN` environment variable.
    --access-token GITHUB_TOKEN \
    # The name of the organization or user that will own the newly-imported project
    --project-owner monalisa \
    # The type of the owner who will own the project (defaults to organization; only required if the owner is a user)
    --project-owner-type user \
    # The path of the project data generated by the `export` command
    --input-path project.json \
    # The path of the repository mappings file generated by the `export` command and completed by you
    --repository-mappings-path repository-mappings.csv \
    # OPTIONAL: The base URL of the GitHub API, if you're migrating to a migration target other than GitHub.com.
    --base-url https://github.acme.inc/api/v3
```

Near the start of the import, the tool will ask you to manually set up your options for the "Status" field. It will explain exactly what to do, and will validate that you've correctly copied the options from your migration source.

Once you've set up the "Status" field, your project will be imported. Watch out for `warn` lines in the logs, which will let you know about data which hasn't been imported.

---
_Source: https://npm.io/package/migrate-github-project · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._