You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
|`backup-users-{timestamp}.json`|`backup-users`|**All** users (password field excluded) |
106
106
|`users-email-{timestamp}.csv`|`backup-users`|**All** users as `username,email` template for CSV apply |
107
107
108
108
`backup-urls` does **not** dump every repo: the JSON array contains only documents that appear in `changes` (missing `.git`) or `issues` (blank / unsupported URL), each with `backupReason` metadata. If nothing needs migration and there are no URL issues, **no**`backup-urls-*.json` is created and the script exits 0.
@@ -123,18 +123,25 @@ CSV validation errors from `--apply --csv` are recorded in YAML (`report.csv.err
123
123
124
124
### Exit codes
125
125
126
-
| Script | Exit 0 when | Exit 1 when |
127
-
| ----------------| ----------- | ----------- |
128
-
|`migrate-urls`| no apply errors and no URL issues | URL issues and/or apply errors |
129
-
|`migrate-users`| no blocking email issues, no ACL orphans, apply OK, no post-apply email conflicts, no CSV errors | any of the above fail |
130
-
|`backup-urls`| always (including “nothing to backup”) | fatal error only |
|`migrate-urls`| no apply errors and no URL issues| URL issues and/or apply errors |
129
+
|`migrate-users`| no blocking email issues, no ACL orphans, apply OK, no post-apply email conflicts, no CSV errors | any of the above fail|
130
+
|`backup-urls`| always (including “nothing to backup”) | fatal error only|
131
+
|`backup-users`| success | fatal error only|
132
132
133
133
After a successful URL apply, a follow-up dry-run should show `reposNeedingUpdate: 0`, but exit code is still **1** if URL **issues** remain (blank or non-http(s) URLs).
134
134
135
-
### Manual test fixtures
135
+
### Read-only issue reports (manual fix in the database)
136
+
137
+
Some CSV files are **audit output only** — no migration script reads them back as input:
136
138
137
-
Local MongoDB seed data and per-repo ACL/URL test-case tables: [`fixtures/README.md`](fixtures/README.md).
|`url-issues-*.csv`| Repos whose `url` is blank or not `http`/`https` — fix in the DB, then re-run `migrate:urls`|
142
+
|`acl-orphans-*.csv`| Repo ACL entries whose username does not match any `users.username` — fix in the DB, then re-run `migrate:users`|
143
+
144
+
Only `migrate-users --apply --csv` consumes a CSV (`username,email` for `users.email`). `email-changes-*.csv` is an apply **log**, not a re-import format.
138
145
139
146
---
140
147
@@ -157,15 +164,15 @@ npm run backup:urls
157
164
npm run migrate:urls -- --apply
158
165
```
159
166
160
-
Notes: trailing `/` is normalized (`.../repo/` → `.../repo.git`). Blank/non-http(s) URLs are reported as issues and require manual fixing.
167
+
Notes: trailing `/` is normalized (`.../repo/` → `.../repo.git`). Blank/non-http(s) URLs are reported as issues and require **manual** correction in the database; `url-issues-*.csv` is a checklist only (see [Read-only issue reports](#read-only-issue-reports-manual-fix-in-the-database)).
**Goal:** unblock v2 pushes: valid **unique**`users.email` (audit + CSV apply fallback); surface **ACL orphan**entries that must be corrected **manually** in the database (scripts never rewrite repo ACL).
`backup-users.js` is separate (not invoked by `migrate-users`) and writes a **full** users JSON snapshot plus `users-email-*.csv` for all users (see [Report artifacts](#report-artifacts)).
179
186
187
+
### Recommended order (emails → ACL → verify)
188
+
189
+
1.**Emails** — run `npm run migrate:users` (dry-run). Resolve every blocking row in `users-audit-*.csv` / YAML `users.issues` (missing/invalid/duplicate email). Where CSV apply is appropriate, run `npm run migrate:users -- --apply --csv ./mappings.csv` and confirm `apply.ok` in the report.
190
+
2.**ACL orphans** — while `acl.orphanCount` (console: `ACL orphans`) is greater than zero, fix each orphan listed in `acl-orphans-*.csv` or YAML `acl.orphans` in the database. Migration tools **do not** update `repos.users.canPush` or `repos.users.canAuthorise`.
191
+
3.**Verify** — run `npm run migrate:users` (dry-run) again after each batch of fixes. Phase 2 is complete only when `blockingIssueCount` is **0**, `orphanCount` is **0**, and the process exits **0** (see [Exit codes](#exit-codes)).
192
+
180
193
```bash
181
194
npm run migrate:users
182
195
npm run backup:users
183
196
npm run migrate:users -- --apply --csv ./mappings.csv
197
+
# … manual ACL fixes in the database …
198
+
npm run migrate:users # repeat until ACL orphans: 0 and exit 0
184
199
```
185
200
201
+
### ACL orphans (manual fix required)
202
+
203
+
An **orphan** is a username string stored under a repo’s `users.canPush` or `users.canAuthorise` that does not match any document in `users` (match is trimmed, case-insensitive on `username`). These stale or mistyped ACL entries keep `migrate-users` in a failing state until they are removed or aligned with a real user record.
204
+
205
+
`acl-orphans-{timestamp}.csv` columns: `RepoID`, `RepoName`, `RepoURL`, `Field` (`canPush` / `canAuthorise`), `OrphanUsername`, `NormalizedOrphan`, `Index`. Like `url-issues-*.csv`, this file is **read-only** — it cannot be “loaded back” or applied by any script; use it as a work list, fix data in your environment, then re-run the dry-run (see [Read-only issue reports](#read-only-issue-reports-manual-fix-in-the-database)).
206
+
186
207
For **apply** (`migrate-users --apply --csv ...`): CSV header must be `username,email` (`lib/csv.js`). The command exits `1` on blocking email issues, ACL orphans, CSV/apply failures, or duplicate-email simulation (see [Exit codes](#exit-codes)).
187
208
188
209
CSV input: UTF‑8, one row per line, only those two columns; parser is minimal (quoted commas OK, **`""`** escapes inside fields not supported). Prefer export without BOM.
@@ -207,4 +228,6 @@ npm run migrate:urls # expect reposNeedingUpdate: 0; exit 1 if URL issues rema
207
228
npm run migrate:users
208
229
npm run backup:users
209
230
npm run migrate:users -- --apply --csv ./mappings.csv
231
+
# fix ACL orphans manually (acl-orphans-*.csv is not re-importable)
232
+
npm run migrate:users # repeat until orphanCount: 0 and exit 0
0 commit comments