Blame · Line-by-line history

`migration.md`

Each line is annotated with the commit that last touched it. Click any SHA to jump to that commit and see the surrounding change.

migration.mdBlame73 lines · 1 contributor

Normal view Raw

fa08f54Test User	1	# Migration guide
	2
	3	This document covers the rough edges that come up when moving an existing
	4	repo onto Gluecron. The git history side is easy — `git clone --bare` does
	5	the work. The tricky bits live around things GitHub _doesn't_ expose
	6	through its API.
	7
	8	## Migrating GitHub Actions secrets
	9
	10	GitHub's API exposes the names of a repo's Actions secrets but never
	11	the values — even an authenticated repo owner cannot read them back
	12	through the API. (This is deliberate on GitHub's part. The same constraint
	13	applies to `gh secret list` and any third-party tool.) So when you move a
	14	repo from GitHub to Gluecron, you have to re-paste each secret value
	15	once. We make this as painless as we can.
	16
	17	The flow:
	18
	19	1. Import your repo at [`/import`](/import) (Option 2 — single-repo URL).
	20	Paste your repository URL and a GitHub personal access token with
	21	the `repo` scope. The token is used to:
	22	- clone private repositories (existing behaviour);
	23	- list the secret names on the GitHub repo (new in Block T1) so we
	24	can pre-create empty placeholder rows in Gluecron's encrypted
	25	`workflow_secrets` table.
	26	2. After the import completes, if any secrets were found you'll be
	27	redirected to the secrets-checklist page at
	28	`/:owner/:repo/import/secrets`. Each row shows the secret name and a
	29	status pill — "Empty" (yellow) for placeholders we just created and
	30	"Pasted" (green) for ones you've already filled in.
	31	3. For each secret, paste the value into the password input and click
	32	Save. The value is encrypted with AES-256-GCM under the per-host
	33	`WORKFLOW_SECRETS_KEY` and stored in the existing `workflow_secrets`
	34	table — exactly the same code path as the regular secrets-settings
	35	UI. We never log plaintext values anywhere.
	36	4. When you're done — or partway through if you need to find more values
	37	later — click Done — take me to my repo. You can optionally tick
	38	the "Also delete the N empty placeholders on my way out" box to clean
	39	up any rows you haven't filled. Either way you can come back and edit
	40	any time via `/:owner/:repo/settings/secrets`.
	41	5. Reference your secrets in `.gluecron/workflows/*.yml` as
	42	`${{ secrets.NAME }}` — the same syntax as GitHub Actions. The
	43	workflow runner does the substitution at step-execution time; tokens
	44	pointing at missing names are left intact in the run log as a loud
	45	"this secret is unset" failure signal.
	46
	47	### Where do I find each value?
	48
	49	GitHub doesn't let you read it back. Look in:
	50
	51	- the password manager (1Password, Bitwarden, etc.) you used when you
	52	first added the secret to GitHub
	53	- the `.env` / `.env.production` file in your local checkout
	54	- the original provisioning script that minted the credential
	55	- the upstream service's dashboard (Stripe, AWS, etc.) — most providers
	56	let you regenerate the credential, which is a good security hygiene
	57	step anyway
	58
	59	### Skipping the checklist
	60
	61	The checklist step is opt-in via the token field. If you import a
	62	repo without supplying a GitHub PAT (or supply one that lacks the
	63	`repo` scope) we silently skip the secrets step and drop you on the
	64	imported repo's main page. Adding the secrets later by hand at
	65	`/:owner/:repo/settings/secrets` works exactly the same way.
	66
	67	### What gets logged
	68
	69	Just the secret name (e.g. `STRIPE_API_KEY`) and a hash of the
	70	audit-log row — never the value, never any byte of the encrypted blob.
	71	The audit-log actions are `workflow.secret.import_pasted` (per-secret
	72	save) and `workflow.secret.import_cleanup` (cleanup of remaining empty
	73	placeholders on Done).