Skip to content

Commit 4554f72

Browse files
offbyoneisaacmbrownboylejj
authored
Update the GHES ELM docs to capture the updated migration process (#62851)
Co-authored-by: Isaac Brown <isaacmbrown@github.com> Co-authored-by: Jim Boyle <95828167+boylejj@users.noreply.github.com> Co-authored-by: Isaac Brown <101839405+isaacmbrown@users.noreply.github.com>
1 parent fa648d3 commit 4554f72

17 files changed

Lines changed: 319 additions & 160 deletions

File tree

‎content/migrations/elm/about-live-migrations.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -9,11 +9,9 @@ versions:
99
contentType: concepts
1010
---
1111

12-
{% data reusables.elm.preview-note %}
13-
1412
## What is {% data variables.product.prodname_elm %}?
1513

16-
{% data variables.product.prodname_elm %} ({% data variables.product.prodname_elm_short %}) is a service for migrating repositories from {% data variables.product.prodname_ghe_server %} to {% data variables.enterprise.data_residency %} ({% data variables.enterprise.data_residency_site %}). It is operated using a command line tool on {% data variables.product.prodname_ghe_server %}.
14+
{% data variables.product.prodname_elm %} ({% data variables.product.prodname_elm_short %}) is a service for migrating repositories from {% data variables.product.prodname_ghe_server %} to {% data variables.enterprise.data_residency %} ({% data variables.enterprise.data_residency_site %}). It is operated using an extension of the {% data variables.product.prodname_cli %}.
1715

1816
Migrations are "live" because users can continue using the source repository during most of the migration process. After the repository data is initially collected, webhooks check for changes to the repository, such as new commits or updates to settings. These changes are reported to {% data variables.product.prodname_elm_short %} and included in the migration.
1917

@@ -35,7 +33,7 @@ You may want to use both tools over the course of a platform migration, prioriti
3533

3634
## Overview of a migration
3735

38-
Typically, a site administrator runs a migration using the `elm` CLI tool, in a terminal session over SSH. The operator must provide {% data variables.product.pat_generic_plural %} with access to both {% data variables.product.prodname_ghe_server %} and the destination enterprise.
36+
A site administrator runs a migration using the {% data variables.product.prodname_cli %}. Before running the migration, the operator must configure the {% data variables.product.prodname_ghe_server %} instance and provide {% data variables.product.pat_generic_plural %} with access to both {% data variables.product.prodname_ghe_server %} and the destination enterprise.
3937

4038
The high-level phases of a migration are:
4139

‎content/migrations/elm/complete-your-migration.md‎

Lines changed: 35 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,9 +10,7 @@ contentType: how-tos
1010
permissions: 'Organization owners on {% data variables.enterprise.data_residency_site %}'
1111
---
1212

13-
{% data reusables.elm.preview-note %}
14-
15-
After you have run a migration with the `elm` CLI tool, there are some follow-up tasks to complete.
13+
After you have run a migration with the {% data variables.product.prodname_elm_cli %} tool, there are some follow-up tasks to complete.
1614

1715
## Restore users' access
1816

@@ -25,15 +23,44 @@ Because {% data variables.product.prodname_ghe_server %} and {% data variables.e
2523

2624
{% data reusables.enterprise-migration-tool.about-mannequins %} For more information, see [AUTOTITLE](/migrations/overview/mannequins-and-user-activity).
2725

28-
Once user accounts have been added to the organization on {% data variables.enterprise.data_residency_site %}, you can invite users to reclaim a mannequin's activity. You can do this in the browser or, with the {% data variables.product.prodname_gei_cli %} tool, reclaim mannequins in bulk without the invite process.
26+
Once user accounts have been added to the organization on {% data variables.enterprise.data_residency_site %}, you can invite users to reclaim a mannequin's activity. You can do this in the browser or, with the {% data variables.product.prodname_elm_cli %} tool, reclaim mannequins in bulk without the invite process.
2927

30-
### Reclaiming mannequins in the browser
28+
### Reclaiming mannequins in bulk using the {% data variables.product.prodname_elm_cli %}
3129

32-
{% data reusables.elm.reclaim-mannequins-in-browser %}
30+
You can use the {% data variables.product.prodname_elm_cli %} to reclaim mannequins in bulk.
31+
32+
1. Generate the list of mannequins in the migration. The following command produces a CSV file that maps mannequins to organization members. Optionally, to include mannequins that have already been reclaimed, add the `--include-reclaimed` flag.
33+
34+
```shell copy
35+
gh target mannequin list ORGANIZATION_NAME
36+
```
37+
38+
This will produce a CSV file of all mannequins in the target organization, in the form `mannequin-user,mannequin-id,target-user`:
3339

34-
### Reclaiming mannequins in bulk
40+
```text
41+
ghe-admin,M_kgDOAAw-zw,
42+
unit-test,M_kgDOAA5FYg,
43+
admin-octoshift,M_kgDOAA5FZw,
44+
```
3545

36-
You can install the {% data variables.product.prodname_gei_cli %} to reclaim mannequins in bulk. See [AUTOTITLE](/migrations/using-github-enterprise-importer/completing-your-migration-with-github-enterprise-importer/reclaiming-mannequins-for-github-enterprise-importer#reclaiming-mannequins-with-the-gei-extension).
46+
1. Output the command to a file that you can edit.
47+
48+
```shell copy
49+
gh elm target mannequin list ORGANIZATION_NAME > MANNEQUINS.csv
50+
```
51+
52+
1. Edit the CSV file, adding the username of the organization member that corresponds to each mannequin. Ensure you save the file after you edit it.
53+
1. Reclaim mannequins using the `mannequin reclaim` command. Use the ORGANIZATION_NAME and filename from the previous step.
54+
55+
```shell copy
56+
gh target mannequin reclaim ORGANIZATION_NAME --csv MANNEQUINS.csv
57+
```
58+
59+
For a full reference of the reclaim command, including options to control invitations and prompting, see [AUTOTITLE](/migrations/elm/elm-cli-reference).
60+
61+
### Reclaiming mannequins in the browser
62+
63+
{% data reusables.elm.reclaim-mannequins-in-browser %}
3764

3865
## Reattribute Git activity
3966

‎content/migrations/elm/elm-cli-reference.md‎

Lines changed: 70 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,67 +1,90 @@
11
---
22
title: Enterprise Live Migrations CLI reference
33
shortTitle: ELM CLI reference
4-
intro: 'Detailed usage information for the {% data variables.product.prodname_elm_short %} CLI tool.'
4+
intro: 'Detailed usage information for the {% data variables.product.prodname_elm_cli %} tool.'
55
versions:
66
fpt: '*'
77
ghes: '*'
88
ghec: '*'
99
contentType: reference
1010
---
1111

12-
{% data reusables.elm.preview-note %}
12+
## Installation
1313

14-
## `elm migration` commands
14+
```shell
15+
gh extension install github/gh-elm
16+
```
17+
18+
The extension requires {% data variables.product.prodname_cli %} (`gh`) version 2.0 or later.
19+
20+
## Setup commands
21+
22+
| Command | Description |
23+
|-----------------------|----------------------------------------------------------------|
24+
| `gh elm config` | Interactively configure the endpoints and tokens for ELM use |
25+
| `gh elm config reset` | Remove stored configuration and credentials |
26+
| `gh elm config show` | Show the current configuration, with tokens redacted |
27+
| `gh elm completion` | Generate a shell autocompletion script for the specified shell |
28+
29+
30+
## Migration commands
1531

1632
| Command | Description |
1733
|---|---|
18-
| `elm migration create` | Creates a new migration for a single source repository |
19-
| `elm migration start --migration-id MIGRATION-ID` | Starts a migration |
20-
| `elm migration status --migration-id MIGRATION-ID` | Shows the status, progress, cutover readiness, and timing of a migration |
21-
| `elm migration list` | Lists all migrations and their statuses |
22-
| `elm migration cancel --migration-id MIGRATION-ID` | Cancels a migration in progress |
23-
| `elm migration cutover-to-destination --migration-id MIGRATION-ID` | Initiates the final cutover, archiving the source repository and completing the migration |
34+
| `gh elm migration list` | List migrations |
35+
| `gh elm migration create` | Create a new migration |
36+
| `gh elm migration start MIGRATION-ID` | Start a previously created migration |
37+
| `gh elm migration status MIGRATION-ID` | Get the status and details of a migration |
38+
| `gh elm migration watch MIGRATION-ID` | Watch migration progress with a live-updating display |
39+
| `gh elm migration pause MIGRATION-ID` | Pause a running migration |
40+
| `gh elm migration resume MIGRATION-ID` | Resume a paused migration |
41+
| `gh elm migration cancel MIGRATION-ID` | Cancel and terminate a migration |
42+
| `gh elm migration target-id MIGRATION-ID` | Look up the target (destination) migration ID for a migration |
43+
| `gh elm migration cutover MIGRATION-ID` | Initiate a cutover to the destination for a migration |
44+
| `gh elm migration cutover status MIGRATION-ID` | Get the cutover status and progress for a migration |
45+
| `gh elm migration cutover revert MIGRATION-ID` | Revert the effects of a cutover so the source repository can be migrated again |
2446

2547
Some of these commands can take additional options. See the later sections in this article.
2648

27-
## `elm migration create` options
49+
## Target commands
50+
51+
| Command | Description |
52+
| ------- | ----------- |
53+
| `gh elm target mannequin reclaim` | Claim (reclaim) one or more mannequins on the target organization |
54+
| `gh elm target mannequin list` | List a target organization's mannequins as CSV |
55+
| `gh elm target report request` | Request a node report for a migration |
56+
| `gh elm target report status` | Query the status of a migration's node report |
57+
| `gh elm target report url` | Get a signed download URL for a finished report |
58+
| `gh elm target resources` | List a migration's resources from the target |
59+
60+
## `gh elm migration create` options
2861

2962
Create a new migration to prepare for repository export and import.
3063

31-
| Flag | Required | Default | Description |
32-
|---|---|---|---|
33-
| `--source-org` | Yes | N/A | Slug of the source organization on {% data variables.product.prodname_ghe_server %} |
34-
| `--source-repo` | Yes | N/A | Name of the source repository |
35-
| `--target-org` | Yes | N/A | Slug of the destination organization on {% data variables.enterprise.data_residency_site %} |
36-
| `--target-repo` | Yes | N/A | Name of the destination repository |
37-
| `--target-api` | Yes | N/A | {% data reusables.elm.ghe-url-description %} |
38-
| `--pat-name` | Yes | N/A | This must be set to a static string: `system-pat` |
39-
| `--target-visibility` | No | `internal` | Visibility of the destination repository. Must be `private` or `internal`. Public repositories are not supported. |
40-
| `--start` | No | `false` | Automatically starts the migration after creating it |
41-
42-
## `elm migration list` options
43-
44-
| Flag | Required | Default | Description |
45-
|---|---|---|---|
46-
| `--status` | No | N/A | Filters results by migration status. Valid values: `created`, `queued`, `in_progress`, `paused`, `completed`, `failed`, `terminated`. |
47-
| `--page-size` | No | N/A | Number of results per page |
48-
| `--after` | No | N/A | Cursor for pagination, from a previous response |
49-
50-
## `elm migration cutover-to-destination` options
51-
52-
| Flag | Required | Default | Description |
53-
|---|---|---|---|
54-
| `--migration-id` | Yes | N/A | The ID of a migration that is ready for cutover. |
55-
| `--force` | No | `false` | By default, the command checks whether the migration target reports readiness before proceeding. Use `--force` to bypass this check when you are certain the migration state is correct. |
56-
57-
## Global flags and variables
58-
59-
The following properties can be provided either as environment variables or as flags on any command, with command flags taking priority. You should set these values _after_ applying the `ghe-config` configuration.
60-
61-
| Variable | Flag | Required | Description |
62-
|----------|------|----------|-------------|
63-
| API_URL | `--api-url` | Yes | Must be set to `{% data reusables.elm.localhost-value %}`. |
64-
| MIGRATION_MANAGER_HMAC_KEY | `--migration-manager-hmac-key` | Yes | Must be set to `{% data reusables.elm.hmac-key-value %}`. |
65-
| MIGRATION_TARGET_URL | `--migration-target-url` | Yes | {% data reusables.elm.ghe-url-description %} |
66-
| MIGRATION_TARGET_TOKEN | `--migration-target-token` | Yes | {% data reusables.elm.ghe-pat-description %} |
67-
| DEBUG_HTTP | `--debug-http` | No | Set to `true` to print the HTTP method, URL, headers, and error response body for each request, for debugging purposes |
64+
| Flag | Required | Default | Description |
65+
|-----------------------|----------|------------|-------------------------------------------------------------------------------------------------------------------|
66+
| `--source-org` | Yes | N/A | Slug of the source organization on {% data variables.product.prodname_ghe_server %} |
67+
| `--source-repo` | Yes | N/A | Name of the source repository |
68+
| `--target-org` | Yes | N/A | Slug of the destination organization on {% data variables.enterprise.data_residency_site %} |
69+
| `--target-repo` | Yes | N/A | Name of the destination repository |
70+
| `--target-visibility` | No | `internal` | Visibility of the destination repository. Must be `private` or `internal`. Public repositories are not supported. |
71+
| `--start` | No | `false` | Automatically starts the migration after creating it |
72+
| `--json` | No | `false` | Output the API's raw JSON response instead of human-readable text |
73+
74+
## `gh elm migration list` options
75+
76+
| Flag | Required | Default | Description |
77+
|---------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------|
78+
| `--status` | No | N/A | Filters results by migration status. Valid values: `created`, `queued`, `in_progress`, `paused`, `completed`, `failed`, `terminated`. |
79+
| `--page-size` | No | N/A | Number of results per page |
80+
| `--after` | No | N/A | Cursor for pagination, from a previous response |
81+
| `--json` | No | `false` | Output the API's raw JSON response instead of human-readable text |
82+
83+
## `gh elm migration cutover` options
84+
85+
| Flag | Required | Default | Description |
86+
|------------------|----------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
87+
| `--migration-id` | Yes | N/A | The ID of a migration that is ready for cutover. |
88+
| `--force` | No | `false` | By default, the command checks whether the migration target reports readiness before proceeding. Use `--force` to bypass this check when you are certain the migration state is correct. |
89+
| `--watch` | No | `false` | After triggering cutover, enter live watch mode |
90+

0 commit comments

Comments
 (0)