cloudflare/kumo
Publicmirrored fromhttps://github.com/cloudflare/kumoAvailable
GITHUB_MIGRATION_PLAN.md
303lines · modecode
| 1 | # GitHub Migration Plan: Kumo Repository |
| 2 | |
| 3 | > **Generated:** January 22, 2026 |
| 4 | > **Status:** IMPLEMENTED |
| 5 | > **Purpose:** Guide for migrating Kumo from internal GitLab to public GitHub |
| 6 | |
| 7 | ## Implementation Summary |
| 8 | |
| 9 | All migration tasks have been completed. The following changes were made: |
| 10 | |
| 11 | ### Files Removed |
| 12 | |
| 13 | - `.gitlab-ci.yml` - Replaced with GitHub Actions workflows |
| 14 | - `ci/utils/gitlab-api.ts` - Replaced with `github-api.ts` |
| 15 | - `ci/scripts/create-release-mr.ts` - Replaced with `create-release-pr.ts` |
| 16 | - `CODEOWNERS` (root) - Moved to `.github/CODEOWNERS` |
| 17 | |
| 18 | ### Files Created |
| 19 | |
| 20 | - `.github/CODEOWNERS` - GitHub-format code owners |
| 21 | - `.github/workflows/ci.yml` - CI workflow (build, lint, test, typecheck) |
| 22 | - `.github/workflows/preview.yml` - Preview deployments and beta releases |
| 23 | - `.github/workflows/release.yml` - Production releases and staging deployments |
| 24 | - `ci/utils/github-api.ts` - GitHub API utilities using Octokit |
| 25 | - `ci/scripts/create-release-pr.ts` - GitHub PR creation script |
| 26 | |
| 27 | ### Files Modified |
| 28 | |
| 29 | - `packages/kumo/package.json` - Updated repository URL and publishConfig |
| 30 | - `.npmrc` - Updated for public npm registry |
| 31 | - `README.md` - Removed wiki links, updated npm instructions, updated CI references |
| 32 | - `ci/README.md` - Rewritten for GitHub Actions |
| 33 | - `ci/utils/mr-reporter.ts` - Updated for GitHub PRs |
| 34 | - `ci/utils/git-operations.ts` - Updated for GitHub Actions environment |
| 35 | - `ci/reporters/types.ts` - Updated for GitHub context |
| 36 | - `ci/versioning/publish-beta.sh` - Updated npm registry and git config |
| 37 | - `ci/versioning/release-production.sh` - Updated for GitHub |
| 38 | - `packages/kumo-docs-astro/src/layouts/DocLayout.astro` - GitLab → GitHub |
| 39 | - `packages/kumo-docs-astro/src/components/docs/StickyDocHeader.tsx` - GitLab → GitHub |
| 40 | - `packages/kumo-docs-astro/src/pages/installation.astro` - Removed internal registry docs |
| 41 | - `packages/kumo-docs-astro/src/pages/contributing.astro` - GitLab → GitHub |
| 42 | - `packages/kumo/scripts/figma/README.md` - Added internal file note |
| 43 | - `packages/figma/src/README.md` - Added internal file note |
| 44 | |
| 45 | ### Dependencies Added |
| 46 | |
| 47 | - `@octokit/rest` - For GitHub API interactions |
| 48 | |
| 49 | --- |
| 50 | |
| 51 | ## Executive Summary |
| 52 | |
| 53 | **The repository is safe for migration** - no actual secrets or credentials are committed. The main work involves: |
| 54 | |
| 55 | 1. Removing/replacing GitLab-specific CI/CD configuration |
| 56 | 2. Updating internal URLs (GitLab, wiki, npm registry) |
| 57 | 3. Converting CODEOWNERS format |
| 58 | 4. Documenting internal Figma file references |
| 59 | |
| 60 | --- |
| 61 | |
| 62 | ## Security Assessment |
| 63 | |
| 64 | ### Files NOT Found (Confirming Good Hygiene) |
| 65 | |
| 66 | | File Type | Status | |
| 67 | | ------------------------------------------ | ----------------------------------- | |
| 68 | | `.env` files | Not committed (properly gitignored) | |
| 69 | | `.dev.vars` files | Not committed (properly gitignored) | |
| 70 | | Private keys (`*.pem`, `*.key`, `id_rsa*`) | None found | |
| 71 | | Certificates (`*.crt`, `*.cert`) | None found | |
| 72 | | Hardcoded passwords or API tokens | None found | |
| 73 | | AWS credentials or service account files | None found | |
| 74 | |
| 75 | ### Risk Assessment |
| 76 | |
| 77 | | Risk | Level | Notes | |
| 78 | | --------------------- | ---------- | ----------------------------------------- | |
| 79 | | Secrets exposure | **NONE** | No secrets found in codebase | |
| 80 | | Internal URLs in code | **LOW** | All identified, straightforward to update | |
| 81 | | CI/CD downtime | **MEDIUM** | Plan GitHub Actions before migration | |
| 82 | | npm publish issues | **LOW** | Test with beta release first | |
| 83 | |
| 84 | --- |
| 85 | |
| 86 | ## Phase 1: Files to REMOVE |
| 87 | |
| 88 | | File | Reason | |
| 89 | | ---------------- | ----------------------------------------------- | |
| 90 | | `.gitlab-ci.yml` | GitLab-specific CI, replace with GitHub Actions | |
| 91 | |
| 92 | --- |
| 93 | |
| 94 | ## Phase 2: Files to MODIFY |
| 95 | |
| 96 | ### 2.1 Critical Path (Must complete before migration) |
| 97 | |
| 98 | #### `packages/kumo/package.json` |
| 99 | |
| 100 | | Line | Current | Change To | |
| 101 | | ---- | ------------------------------------------------------------------ | ------------------------------------------ | |
| 102 | | 9 | `"url": "https://gitlab.cfdata.org/cloudflare/fe/kumo.git"` | GitHub repository URL | |
| 103 | | 349 | `"access": "restricted"` | `"access": "public"` | |
| 104 | | 350 | `"registry": "https://registry-gateway.cloudflare-ui.workers.dev"` | `"registry": "https://registry.npmjs.org"` | |
| 105 | |
| 106 | #### `.npmrc` |
| 107 | |
| 108 | ```diff |
| 109 | - @cloudflare:registry=https://registry-gateway.cloudflare-ui.workers.dev |
| 110 | - //registry-gateway.cloudflare-ui.workers.dev/:_authToken="${NPM_TOKEN}" |
| 111 | + @cloudflare:registry=https://registry.npmjs.org |
| 112 | + //registry.npmjs.org/:_authToken="${NPM_TOKEN}" |
| 113 | ``` |
| 114 | |
| 115 | #### `CODEOWNERS` |
| 116 | |
| 117 | Convert from GitLab format to GitHub format: |
| 118 | |
| 119 | | GitLab Syntax | GitHub Equivalent | |
| 120 | | ------------------------------------- | --------------------------------------- | |
| 121 | | `[Repo Maintainers][2] @user1 @user2` | `* @org/team-name` or `* @user1 @user2` | |
| 122 | | `!pnpm-lock.yaml` (exclusion) | Not directly supported - remove | |
| 123 | | `^[Notification]` syntax | Not supported - remove | |
| 124 | |
| 125 | Also: |
| 126 | |
| 127 | - Remove internal wiki link (line 6) |
| 128 | - Remove GitLab group reference (line 11) |
| 129 | - Update usernames to GitHub usernames (lines 20, 27) |
| 130 | |
| 131 | --- |
| 132 | |
| 133 | ### 2.2 CI Scripts (Functional changes required) |
| 134 | |
| 135 | | File | Changes Required | |
| 136 | | ------------------------------------- | ---------------------------------------------------------------------------- | |
| 137 | | `ci/utils/gitlab-api.ts` | Rewrite for GitHub API (Octokit) - export `GITHUB_API`, `GITHUB_REPO` | |
| 138 | | `ci/utils/mr-reporter.ts` | Convert from GitLab MR comments to GitHub PR comments | |
| 139 | | `ci/utils/git-operations.ts` | Replace `CI_MERGE_REQUEST_*` env vars with `GITHUB_*` equivalents | |
| 140 | | `ci/scripts/create-release-mr.ts` | Convert to GitHub PR creation | |
| 141 | | `ci/scripts/post-mr-report.ts` | Update for GitHub Actions context | |
| 142 | | `ci/reporters/types.ts` | Update CI environment variable references | |
| 143 | | `ci/versioning/publish-beta.sh` | Update npm registry (lines 11-12), change git email from `ci@cloudflare.com` | |
| 144 | | `ci/versioning/release-production.sh` | Convert GitLab push/MR logic to GitHub | |
| 145 | |
| 146 | --- |
| 147 | |
| 148 | ### 2.3 Documentation Updates |
| 149 | |
| 150 | | File | Line(s) | Change | |
| 151 | | ------------------------------------------------------------------ | -------- | --------------------------------------------------------------------------- | |
| 152 | | `README.md` | 88 | Remove `wiki.cfdata.org` link | |
| 153 | | `README.md` | 94-95 | Update npm registry instructions for public npm | |
| 154 | | `ci/README.md` | Multiple | Document GitHub Actions equivalents, remove Vault paths, remove account IDs | |
| 155 | | `packages/kumo-docs-astro/src/layouts/DocLayout.astro` | 30 | Change GitLab source links to GitHub format | |
| 156 | | `packages/kumo-docs-astro/src/pages/installation.astro` | 22 | Remove wiki link | |
| 157 | | `packages/kumo-docs-astro/src/pages/installation.astro` | 46-47 | Update npm registry instructions | |
| 158 | | `packages/kumo-docs-astro/src/pages/contributing.astro` | 723 | Update to GitHub URL | |
| 159 | | `packages/kumo-docs-astro/src/components/docs/StickyDocHeader.tsx` | 179 | Update to GitHub URL | |
| 160 | |
| 161 | --- |
| 162 | |
| 163 | ### 2.4 Figma Documentation Updates |
| 164 | |
| 165 | These files reference an internal Cloudflare Figma file (`sKKZc6pC6W1TtzWBLxDGSU`). The file key is **not a secret**, but external users won't have access to this file. |
| 166 | |
| 167 | | File | Line(s) | Change | |
| 168 | | --------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------- | |
| 169 | | `packages/figma/src/code.ts` | 7 | Add comment noting this is an internal Figma file | |
| 170 | | `packages/figma/src/README.md` | 26, 162-163 | Add note: "This Figma file is internal to Cloudflare. External users would need to create their own Figma file and run the token sync." | |
| 171 | | `packages/kumo/scripts/figma/README.md` | 71, 85 | Add note about internal Figma file | |
| 172 | | `AGENTS.md` | 911 | Add note about internal Figma file | |
| 173 | |
| 174 | --- |
| 175 | |
| 176 | ## Phase 3: Files to KEEP (No Changes) |
| 177 | |
| 178 | ### Configuration Files |
| 179 | |
| 180 | | File | Reason | |
| 181 | | ------------------------------------------ | --------------------------------------------- | |
| 182 | | `.gitignore` | Already excludes sensitive files | |
| 183 | | `.vscode/settings.json` | Editor config only | |
| 184 | | `lefthook.yml` | Platform-agnostic git hooks | |
| 185 | | `.changeset/config.json` | Standard changeset config | |
| 186 | | `packages/kumo/wrangler.jsonc` | Account ID is public identifier, safe to keep | |
| 187 | | `packages/kumo-docs-astro/wrangler.jsonc` | Same as above | |
| 188 | | `packages/kumo/scripts/figma/.env.example` | Template with empty values | |
| 189 | |
| 190 | ### Source Code |
| 191 | |
| 192 | | Directory | Notes | |
| 193 | | ----------------------------------- | ------------------------------ | |
| 194 | | `packages/kumo/src/**/*` | No internal references | |
| 195 | | `packages/kumo-docs-astro/src/**/*` | Except files listed in Phase 2 | |
| 196 | | `packages/figma/src/**/*` | No secrets, plugin is clean | |
| 197 | |
| 198 | ### Generated/Build Files |
| 199 | |
| 200 | | File | Notes | |
| 201 | | ------------------------------------------ | --------------------------------------- | |
| 202 | | `packages/kumo/ai/component-registry.json` | Auto-generated, contains demo data only | |
| 203 | | `packages/kumo/ai/component-registry.md` | Same as above | |
| 204 | |
| 205 | ### Mock/Demo Data (Safe) |
| 206 | |
| 207 | | File | Content | Status | |
| 208 | | ---------------------------------------------- | ---------------------------------------- | ---------------- | |
| 209 | | `src/components/sensitive-input/*.stories.tsx` | `"secret-api-key-123"` | Demo data - KEEP | |
| 210 | | `src/pages/active-sessions/*-mocks.ts` | RFC 1918 IPs (`192.168.x.x`, `10.0.0.x`) | Mock data - KEEP | |
| 211 | |
| 212 | --- |
| 213 | |
| 214 | ## Phase 4: New Files to Create |
| 215 | |
| 216 | ### GitHub Actions Workflows |
| 217 | |
| 218 | ``` |
| 219 | .github/ |
| 220 | ├── workflows/ |
| 221 | │ ├── ci.yml # PR checks: build, lint, test, typecheck |
| 222 | │ ├── preview.yml # Deploy Storybook/docs previews |
| 223 | │ └── release.yml # Production releases |
| 224 | ├── CODEOWNERS # Converted from GitLab format |
| 225 | └── dependabot.yml # (Optional) Dependency updates |
| 226 | ``` |
| 227 | |
| 228 | ### Required GitHub Secrets |
| 229 | |
| 230 | | Secret Name | Purpose | Source | |
| 231 | | ----------------------- | ------------------------ | ------------------------------- | |
| 232 | | `NPM_TOKEN` | Publishing to public npm | npm access token | |
| 233 | | `CLOUDFLARE_API_TOKEN` | Workers deployments | Cloudflare dashboard | |
| 234 | | `CLOUDFLARE_ACCOUNT_ID` | Workers deployments | (Optional - can keep in config) | |
| 235 | |
| 236 | --- |
| 237 | |
| 238 | ## Vault → GitHub Secrets Migration |
| 239 | |
| 240 | These Vault paths in `.gitlab-ci.yml` need equivalent GitHub Secrets: |
| 241 | |
| 242 | | Vault Path | GitHub Secret | |
| 243 | | -------------------------------------------------------------- | --------------------------------------- | |
| 244 | | `gitlab/_ci_components/_dev/npm/kv_token@kv` | `NPM_TOKEN` | |
| 245 | | `gitlab/cloudflare/fe/kumo/_dev/cloudflare_api_token/data@kv` | `CLOUDFLARE_API_TOKEN` | |
| 246 | | `gitlab/cloudflare/fe/kumo/_dev/cloudflare_account_id/data@kv` | `CLOUDFLARE_ACCOUNT_ID` | |
| 247 | | `gitlab/cloudflare/fe/kumo/_dev/kumo_preview_bot_v2/data@kv` | `GITHUB_TOKEN` (built-in) or custom PAT | |
| 248 | | `gitlab/cloudflare/fe/kumo/_dev/ci_release_token_v2/data@kv` | `RELEASE_TOKEN` | |
| 249 | |
| 250 | --- |
| 251 | |
| 252 | ## Internal URL Reference Summary |
| 253 | |
| 254 | | Type | Current Value | Files Affected | |
| 255 | | --------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------- | |
| 256 | | GitLab Host | `gitlab.cfdata.org` | `.gitlab-ci.yml`, `ci/utils/gitlab-api.ts`, `ci/utils/mr-reporter.ts`, `package.json`, docs files | |
| 257 | | Vault URL | `vault.cfdata.org` | `.gitlab-ci.yml` | |
| 258 | | NPM Registry | `registry-gateway.cloudflare-ui.workers.dev` | `.npmrc`, `.gitlab-ci.yml`, `package.json`, `publish-beta.sh`, docs files | |
| 259 | | Wiki | `wiki.cfdata.org` | `README.md`, `CODEOWNERS` | |
| 260 | | Workers Subdomain | `design-engineering.workers.dev` | `deploy-storybook-preview.sh`, `deploy-kumo-docs-preview.sh`, `ci/README.md` | |
| 261 | | Cloudflare Account ID | `61e3887ff0554f81e1e175d106c3926f` | `wrangler.jsonc` files, `ci/README.md` | |
| 262 | | Figma File Key | `sKKZc6pC6W1TtzWBLxDGSU` | `packages/figma/src/code.ts`, Figma READMEs, `AGENTS.md` | |
| 263 | |
| 264 | --- |
| 265 | |
| 266 | ## Migration Checklist |
| 267 | |
| 268 | ### Pre-Migration |
| 269 | |
| 270 | - [ ] Create new GitHub repository |
| 271 | - [ ] Set up GitHub Secrets (`NPM_TOKEN`, `CLOUDFLARE_API_TOKEN`) |
| 272 | - [x] Prepare GitHub CODEOWNERS file |
| 273 | - [x] Plan GitHub Actions workflows |
| 274 | |
| 275 | ### File Modifications |
| 276 | |
| 277 | - [x] Update `packages/kumo/package.json` - repository URL, publishConfig |
| 278 | - [x] Update `.npmrc` - public npm registry |
| 279 | - [x] Rewrite `CODEOWNERS` for GitHub format |
| 280 | - [x] Update `README.md` - remove wiki links, update npm instructions |
| 281 | - [x] Update docs site files - GitLab → GitHub URLs |
| 282 | - [x] Update Figma documentation with internal file notes |
| 283 | - [x] Update CI scripts for GitHub API/environment |
| 284 | |
| 285 | ### Post-Migration |
| 286 | |
| 287 | - [x] Create GitHub Actions workflows (`ci.yml`, `preview.yml`, `release.yml`) |
| 288 | - [x] Remove `.gitlab-ci.yml` |
| 289 | - [ ] Test npm publish workflow with beta release |
| 290 | - [ ] Test preview deployments |
| 291 | - [ ] Verify CODEOWNERS works correctly |
| 292 | - [ ] Update any remaining internal links found during testing |
| 293 | |
| 294 | --- |
| 295 | |
| 296 | ## Appendix: Files by Action Summary |
| 297 | |
| 298 | | Action | Count | Files | |
| 299 | | ---------- | ---------- | ------------------------------------ | |
| 300 | | **REMOVE** | 1 | `.gitlab-ci.yml` | |
| 301 | | **MODIFY** | 18 | See Phase 2 sections | |
| 302 | | **KEEP** | All others | Source code, configs, assets | |
| 303 | | **CREATE** | 3-4 | GitHub Actions workflows, CODEOWNERS | |
| 304 | |