@rathnasgala/cli 0.0.20 → 0.0.22

package/README.md

@@ -32,14 +32,15 @@ One command, run inside an empty folder named after the publication you want:
 
 ```console
 mkdir field-notes && cd field-notes
-npx --yes @rathnasgala/cli@latest scaffold --target ./ --mode build-and-deploy
+npx --yes @rathnasgala/cli@latest scaffold --target ./
 ```
 
 That single command does all of the following, and asks only for what it cannot work out:
 
 1. **Signs you in to Gala** if no valid token is stored, showing a code to enter in the browser.
-2. **Signs you in to GitHub** the same way, requesting `repo` to create the publication and install
-   its Actions secret, and `workflow` for the initial scaffold. Ordinary publishing needs neither.
+2. **Signs you in to GitHub** the same way, as the Gala GitHub App. It requests no scopes: a GitHub
+   App's permissions are fixed on the app and granted when you install it, so Gala reaches only the
+   repositories you have shared with it — never every repository you can access.
 3. **Reads your GitHub account** from that token, so there is no username to type.
 4. **Finds the Gala GitHub App installation** for your account. If the App is not installed yet it
    prints the installation page, waits while you install it, and carries on — the installation ID
@@ -75,8 +76,7 @@ npx --yes @rathnasgala/cli@latest scaffold \
   --owner YOUR_GITHUB_USERNAME \
   --repository YOUR_REPOSITORY_NAME \
   --target ./YOUR_REPOSITORY_NAME \
-  --installation-id YOUR_INSTALLATION_ID \
-  --mode build-and-deploy
+  --installation-id YOUR_INSTALLATION_ID
 ```
 
 `--repository` is otherwise taken from `--target`, then from `--site-name`, and only then asked
@@ -97,7 +97,7 @@ Inside the table below, `gala` is shorthand for that prefix.
 | --- | --- | --- |
 | `gala auth` | Authenticate the author with Gala | `--api-base-url URL` for a non-production API |
 | `gala auth github` | Authenticate the CLI with GitHub | Browser device flow; requests `repo workflow` |
-| `gala scaffold` | Sign in if needed, then create and register a publication | All derived; override with `--owner`, `--repository`, `--target`, `--installation-id`, `--mode` |
+| `gala scaffold` | Sign in if needed, then create and register a publication | All derived; override with `--owner`, `--repository`, `--target`, `--installation-id` |
 | `gala configure` | Update author-owned site and design settings | `--root`, plus the configuration options below |
 | `gala new` | Create a Markdown post variant | `--root`, `--title`, `--language`, `--today` |
 | `gala validate` | Validate repository content without publishing | optional root path, `--today` |
@@ -159,14 +159,6 @@ npx --yes @rathnasgala/cli@latest scaffold \
 
 Scaffolding is designed to converge after partial failure. It will not adopt a non-empty unrelated repository.
 
-### Build without deploying
-
-```console
-npx --yes @rathnasgala/cli@latest scaffold ... --mode build-only
-```
-
-`build-only` writes and validates the site but does not provision GitHub Pages. `build-and-deploy` is the default.
-
 ## Everyday workflow
 
 Create another post:
@@ -202,7 +194,7 @@ npx --yes @rathnasgala/cli@latest doctor
 ## Security and ownership
 
 - Your repository remains the canonical source for publication content and configuration.
-- Gala credentials and GitHub OAuth credentials are stored outside the repository.
+- Gala credentials and GitHub App credentials are stored outside the repository.
 - Credential directories are created with private permissions; credential files use mode `0600` on operating systems that support POSIX modes.
 - The site signing secret is returned once by the API and sealed directly into GitHub Actions secrets.
 - Do not copy credential files into the repository, dotfiles, cloud-sync folders, or `/tmp`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rathnasgala/cli",
-  "version": "0.0.20",
+  "version": "0.0.22",
   "type": "module",
   "files": [
     "src"

package/src/git-credentials.js

@@ -0,0 +1,37 @@
+/**
+ * Git operations authenticated as the writer's Gala credential, not as the machine.
+ *
+ * Every git call used to fall through to whatever credential helper the machine had configured,
+ * which is a different identity from the one the CLI just authenticated with. On this machine the
+ * token belonged to `rfai8me` and git's stored credential to `anandrathnas`, so a scaffold created
+ * the repository through the API and was then refused its own push:
+ *
+ *     remote: Permission to rfai8me/pub-231254.git denied to anandrathnas
+ *
+ * The OAuth App hid this because both identities were usually the same person. A writer with none
+ * configured at all — a fresh machine, or someone who only uses SSH — had no chance.
+ *
+ * The token is passed through the environment rather than the argument list, because arguments are
+ * visible to every process on the machine via `ps`, and written nowhere: an ephemeral `-c` helper
+ * leaves no trace in `.git/config`.
+ */
+export const GIT_TOKEN_VARIABLE = 'GALA_GIT_TOKEN';
+
+/** Clears inherited helpers first, or the machine's keychain answers before ours does. */
+export function gitCredentialArguments(accessToken) {
+  if (typeof accessToken !== 'string' || accessToken === '') return [];
+  return [
+    '-c', 'credential.helper=',
+    '-c', `credential.helper=!f() { test "$1" = get && echo username=x-access-token && echo "password=$${GIT_TOKEN_VARIABLE}"; }; f`
+  ];
+}
+
+export function gitEnvironment(accessToken, environment = process.env) {
+  if (typeof accessToken !== 'string' || accessToken === '') return environment;
+  return {
+    ...environment,
+    [GIT_TOKEN_VARIABLE]: accessToken,
+    // Nothing on this path may block waiting for a username at a terminal.
+    GIT_TERMINAL_PROMPT: '0'
+  };
+}

package/src/github-auth-command.js

@@ -1,29 +1,50 @@
 import { pollForAccessToken, requestDeviceCode } from './github-device-flow.js';
 import { writeGithubCredential } from './github-credential-store.js';
 
-export const GITHUB_OAUTH_CLIENT_ID = 'Ov23ligTfectgl2FHJ6c';
-export const GITHUB_SCAFFOLD_SCOPES = Object.freeze(['repo', 'workflow']);
+/**
+ * The Gala GitHub App, not an OAuth App.
+ *
+ * The CLI used to authenticate as a separate OAuth App (`Ov23ligTfectgl2FHJ6c`) while the browser
+ * editor used the GitHub App. They are two different identity systems, and every difference fell on
+ * the CLI: an OAuth token cannot list App installations, is blocked by organisation OAuth App
+ * restrictions, and inherits none of the App's repository grants. The editor hit none of that.
+ *
+ * The one thing that forced an OAuth App — the CLI creating repositories before any installation
+ * covered them — no longer applies: creation moved to the API. So both clients are now the same
+ * GitHub App, and the differences disappear rather than being worked around.
+ *
+ * Client IDs are public; this is the value `GET /apps/gala67-app` publishes.
+ */
+export const GITHUB_APP_CLIENT_ID = 'Iv23liIg7Hi1lMesiaon';
 
 export async function authenticateGithub({
-  clientId = GITHUB_OAUTH_CLIENT_ID, fetchImpl = fetch, sleep, now = Date.now,
-  showScopeWarning, showInstructions, credentialTarget
+  clientId = GITHUB_APP_CLIENT_ID, fetchImpl = fetch, sleep, now = Date.now,
+  showInstructions, credentialTarget
 } = {}) {
-  if (typeof showScopeWarning !== 'function' || typeof showInstructions !== 'function') {
-    throw new TypeError('scope warning and device instructions are required');
+  if (typeof showInstructions !== 'function') {
+    throw new TypeError('device instructions are required');
   }
-  showScopeWarning({
-    scopes: GITHUB_SCAFFOLD_SCOPES,
-    explanation: 'repo grants read/write access to every public and private repository you can access; workflow is used only for scaffold and explicit action-major migration.'
-  });
-  const authorization = await requestDeviceCode({ clientId, scopes: GITHUB_SCAFFOLD_SCOPES, fetchImpl });
+  // No scopes: a GitHub App's permissions are fixed on the app and granted at installation, so
+  // there is nothing to negotiate and nothing to warn about. The broad `repo` scope the OAuth App
+  // had to request — read/write on every repository the writer could reach — is gone with it.
+  const authorization = await requestDeviceCode({ clientId, fetchImpl });
   showInstructions(authorization);
   const token = await pollForAccessToken({
-    ...authorization, clientId, requiredScopes: GITHUB_SCAFFOLD_SCOPES, fetchImpl,
+    ...authorization, clientId, fetchImpl,
     ...(sleep == null ? {} : { sleep }), now
   });
+  /*
+   * The app expires user tokens after eight hours and issues a refresh token with each one.
+   * Exchanging that refresh token requires the app's client secret, which a published CLI cannot
+   * hold — so it is stored for the API-side refresh that will do the exchange, and until that
+   * exists an expired credential asks for one sign-in rather than failing somewhere further down
+   * as an unexplained 401.
+   */
   const target = await writeGithubCredential({
-    accessToken: token.accessToken, scopes: token.scopes,
+    accessToken: token.accessToken,
+    ...(token.expiresAt == null ? {} : { expiresAt: token.expiresAt }),
+    ...(token.refreshToken == null ? {} : { refreshToken: token.refreshToken }),
     ...(credentialTarget == null ? {} : { target: credentialTarget })
   });
-  return Object.freeze({ target, scopes: token.scopes });
+  return Object.freeze({ target, expiresAt: token.expiresAt ?? null });
 }

package/src/github-credential-store.js

@@ -22,10 +22,21 @@ async function regularOrMissing(target) {
   }
 }
 
-export async function writeGithubCredential({ accessToken, scopes, target = githubCredentialPath() }) {
+/**
+ * Schema 2 stores a GitHub App user token, which has no scopes.
+ *
+ * Schema 1 held an OAuth App token and recorded the `repo` and `workflow` scopes it had negotiated.
+ * A GitHub App has neither: its permissions are fixed on the app and granted at installation. The
+ * version bump is what makes the difference visible — a schema-1 file is rejected on read, so a
+ * writer carrying an OAuth token is sent through `auth github` once rather than presenting a
+ * credential the API will refuse in a less obvious way later.
+ */
+export async function writeGithubCredential({
+  accessToken, expiresAt, refreshToken, target = githubCredentialPath()
+}) {
   if (typeof accessToken !== 'string' || accessToken === '') throw new TypeError('accessToken is required');
-  if (!Array.isArray(scopes) || !scopes.includes('repo') || !scopes.includes('workflow')) {
-    throw new TypeError('GitHub credential requires repo and workflow scopes');
+  if (expiresAt != null && Number.isNaN(new Date(expiresAt).getTime())) {
+    throw new TypeError('expiresAt must be a date');
   }
   const directory = path.dirname(path.resolve(target));
   await mkdir(directory, { recursive: true, mode: 0o700 });
@@ -38,7 +49,13 @@ export async function writeGithubCredential({ accessToken, scopes, target = gith
   const temporary = `${target}.gala-${process.pid}`;
   const backup = `${target}.gala-backup-${process.pid}`;
   try {
-    await writeFile(temporary, `${JSON.stringify({ schemaVersion: 1, accessToken, scopes })}\n`, {
+    const record = {
+      schemaVersion: 2,
+      accessToken,
+      ...(expiresAt == null ? {} : { expiresAt: new Date(expiresAt).toISOString() }),
+      ...(refreshToken == null ? {} : { refreshToken })
+    };
+    await writeFile(temporary, `${JSON.stringify(record)}\n`, {
       flag: 'wx', mode: 0o600
     });
     await chmod(temporary, 0o600);
@@ -54,12 +71,34 @@ export async function writeGithubCredential({ accessToken, scopes, target = gith
   }
 }
 
-export async function readGithubCredential({ target = githubCredentialPath() } = {}) {
+export async function readGithubCredential({ target = githubCredentialPath(), now = new Date() } = {}) {
   if (!await regularOrMissing(target)) throw new Error('GitHub authentication is missing; run `gala auth github`');
   const payload = JSON.parse(await readFile(target, 'utf8'));
-  if (payload?.schemaVersion !== 1 || typeof payload.accessToken !== 'string'
-      || !Array.isArray(payload.scopes) || !payload.scopes.includes('repo') || !payload.scopes.includes('workflow')) {
-    throw new TypeError('GitHub credential file has an unsupported schema or missing scopes');
+  if (payload?.schemaVersion === 1) {
+    // An OAuth App token. It cannot list installations and organisations may refuse it outright, so
+    // it is not usable — and saying that here beats a confusing 403 four calls later.
+    throw new Error('GitHub authentication is out of date; run `gala auth github` again');
   }
-  return Object.freeze({ accessToken: payload.accessToken, scopes: [...payload.scopes] });
+  if (payload?.schemaVersion !== 2 || typeof payload.accessToken !== 'string'
+      || payload.accessToken === '') {
+    throw new TypeError('GitHub credential file has an unsupported schema');
+  }
+  /*
+   * The app expires user tokens after eight hours. Refreshing one needs the app's client secret,
+   * which lives on the server, so until that exchange exists the honest answer is to ask for a
+   * sign-in here — rather than hand out a token that fails as a 401 several calls deeper, which is
+   * exactly how the legacy Gala credential wasted a week.
+   */
+  if (typeof payload.expiresAt === 'string') {
+    const expiresAt = new Date(payload.expiresAt);
+    if (Number.isNaN(expiresAt.getTime()) || expiresAt <= now) {
+      throw new Error('GitHub authentication expired; run `gala auth github` again');
+    }
+    return Object.freeze({
+      accessToken: payload.accessToken,
+      expiresAt,
+      ...(typeof payload.refreshToken === 'string' ? { refreshToken: payload.refreshToken } : {})
+    });
+  }
+  return Object.freeze({ accessToken: payload.accessToken });
 }

package/src/github-device-flow.js

@@ -35,15 +35,24 @@ async function postForm(fetchImpl, url, fields) {
   return payload;
 }
 
+/**
+ * `scopes` is optional and must be omitted for a GitHub App.
+ *
+ * OAuth Apps negotiate scopes per authorization; GitHub Apps do not — their permissions are fixed
+ * on the app and granted at installation. Sending a `scope` parameter to an App's device flow asks
+ * for something the grant cannot express.
+ */
 export async function requestDeviceCode({ clientId, scopes, fetchImpl = fetch }) {
   const normalizedClientId = requiredString(clientId, 'clientId');
-  if (!Array.isArray(scopes) || scopes.length === 0) {
-    throw new TypeError('scopes must be a non-empty list');
+  if (scopes != null && (!Array.isArray(scopes) || scopes.length === 0)) {
+    throw new TypeError('scopes must be a non-empty list when supplied');
   }
-  const normalizedScopes = scopes.map((scope) => requiredString(scope, 'scope'));
+  const normalizedScopes = scopes == null
+    ? null
+    : scopes.map((scope) => requiredString(scope, 'scope'));
   const payload = await postForm(fetchImpl, DEVICE_CODE_URL, {
     client_id: normalizedClientId,
-    scope: normalizedScopes.join(' ')
+    ...(normalizedScopes == null ? {} : { scope: normalizedScopes.join(' ') })
   });
 
   return Object.freeze({
@@ -68,7 +77,8 @@ export async function pollForAccessToken({
   const normalizedClientId = requiredString(clientId, 'clientId');
   const normalizedDeviceCode = requiredString(deviceCode, 'deviceCode');
   if (!Array.isArray(requiredScopes)) throw new TypeError('requiredScopes must be a list');
-  const normalizedRequiredScopes = requiredScopes.map((scope) =>
+  // A GitHub App answers with no `scope` field at all; there is nothing to require of it.
+  const normalizedRequiredScopes = (requiredScopes ?? []).map((scope) =>
     requiredString(scope, 'scope').toLowerCase()
   );
   const lifetime = positiveInteger(expiresInSeconds, 'expiresInSeconds') * 1000;
@@ -105,8 +115,21 @@ export async function pollForAccessToken({
       if (missingScopes.length > 0) {
         throw new Error(`GitHub authorization omitted required scope(s): ${missingScopes.join(', ')}`);
       }
+      /*
+       * A GitHub App may be set to expire user tokens after eight hours, in which case GitHub
+       * returns `expires_in` and a refresh token. Refreshing one requires the app's client secret,
+       * which a published CLI cannot hold — so the expiry is reported rather than dropped, and the
+       * caller decides what to do about a credential it has no way to renew.
+       */
+      const expiresInSeconds = Number(payload.expires_in);
       return Object.freeze({
         accessToken: requiredString(payload.access_token, 'access_token'),
+        ...(Number.isFinite(expiresInSeconds) && expiresInSeconds > 0
+          ? { expiresAt: new Date(now() + expiresInSeconds * 1000) }
+          : {}),
+        ...(typeof payload.refresh_token === 'string' && payload.refresh_token !== ''
+          ? { refreshToken: payload.refresh_token }
+          : {}),
         tokenType: 'bearer',
         scopes: grantedScopes
       });

package/src/github-empty-repository.js

@@ -12,6 +12,19 @@ export async function verifyEmptyRepository({ owner, repository, accessToken, fe
   const response = await fetchImpl(repositoryUrl, {
     headers
   });
+  if (response.status === 404) {
+    /*
+     * A GitHub App user token only sees repositories the App is installed on, so "not found" here
+     * usually means "not shared with Gala" rather than "does not exist". The OAuth token this
+     * replaced held `repo` and could see everything, which is exactly the access we stopped asking
+     * for — so the cost is that this needs saying out loud.
+     */
+    throw new Error(
+      `${owner}/${repository} is not visible to Gala. Either it does not exist, or the Gala GitHub `
+      + 'App has not been given access to it — install or share it at '
+      + 'https://github.com/settings/installations, then run scaffold again.'
+    );
+  }
   if (!response.ok) throw new Error(await describeHttpFailure(response, 'GitHub repository lookup'));
   const payload = await response.json();
   if (payload.full_name?.toLowerCase() !== `${owner}/${repository}`.toLowerCase()) {

package/src/github-template-repository.js

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { describeHttpFailure } from './http-failure.js';
+import { gitCredentialArguments, gitEnvironment } from './git-credentials.js';
 
 const GITHUB_API_VERSION = '2026-03-10';
 const REPOSITORY_IDENTITY = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
@@ -135,7 +136,7 @@ export async function awaitRepositoryContent({
   );
 }
 
-export function cloneRepository({ cloneUrl, target, spawnProcess = spawn }) {
+export function cloneRepository({ cloneUrl, target, spawnProcess = spawn, accessToken }) {
   const source = new URL(requiredString(cloneUrl, 'cloneUrl'));
   if (
     source.protocol !== 'https:'
@@ -150,11 +151,16 @@ export function cloneRepository({ cloneUrl, target, spawnProcess = spawn }) {
   const resolvedTarget = path.resolve(requiredString(target, 'target'));
 
   return new Promise((resolve, reject) => {
-    const child = spawnProcess('git', ['clone', source.href, resolvedTarget], {
-      cwd: path.dirname(resolvedTarget),
-      shell: false,
-      stdio: 'inherit'
-    });
+    const child = spawnProcess(
+      'git',
+      [...gitCredentialArguments(accessToken), 'clone', source.href, resolvedTarget],
+      {
+        cwd: path.dirname(resolvedTarget),
+        shell: false,
+        stdio: 'inherit',
+        env: gitEnvironment(accessToken)
+      }
+    );
     child.once('error', reject);
     child.once('exit', (code, signal) => {
       if (signal) reject(new Error(`Git clone terminated by signal ${signal}`));

package/src/index.js

@@ -84,13 +84,12 @@ if (recognizedCommands.has(command)) {
 
 if (command === 'auth') {
   if (args[0] === 'github') {
-    const result = await authenticateGithub({
-      showScopeWarning: ({ explanation }) => process.stdout.write(`GitHub authorization: ${explanation}\n`),
+    await authenticateGithub({
       showInstructions: ({ verificationUri, userCode }) => {
         process.stdout.write(announce(verificationUri, userCode));
       }
     });
-    process.stdout.write(`GitHub authentication stored securely with scopes: ${result.scopes.join(', ')}.\n`);
+    process.stdout.write('GitHub authentication stored securely.\n');
   } else {
     const apiIndex = args.indexOf('--api-base-url');
     const apiBaseUrl = apiIndex === -1 ? 'https://api.gala67.com' : args[apiIndex + 1];
@@ -139,9 +138,7 @@ if (command === 'auth') {
     githubInstallationId: prepared.githubInstallationId,
     topology,
     canonicalBaseUrl: valueFor('--canonical-base-url'),
-    actionRef: valueFor('--action-ref'),
     siteOptions,
-    buildMode: valueFor('--mode') ?? 'build-and-deploy',
     emptyExistingRepository: args.includes('--empty-existing-repository'),
     resumeExistingCheckout: args.includes('--resume')
   });

package/src/publication-creation-client.js

@@ -27,9 +27,12 @@ export async function createPublication({
   ask,
   openUrl = () => false,
   shareAttempts = 3,
-  installationsUrl = 'https://github.com/settings/installations'
+  selfLogin
 }) {
   let created = false;
+  let shareUrl = 'https://github.com/settings/installations';
+  let repositoryOwner = selfLogin ?? '';
+  let repositoryName = name;
   for (let attempt = 0; attempt < Math.max(1, shareAttempts); attempt += 1) {
     const result = await requestPublication({
       apiBaseUrl, galaAccessToken, githubAccessToken, name, fetchImpl, authorize
@@ -47,20 +50,54 @@ export async function createPublication({
      * rather than NEEDS_SHARING — the same situation under a different name.
      */
     const shareable = result.status === 'NEEDS_SHARING' || created;
-    created = created || result.status === 'NEEDS_SHARING';
-    if (!shareable || typeof ask !== 'function') throw result.failure;
+    if (result.status === 'NEEDS_SHARING') {
+      created = true;
+      shareUrl = installationSettingsUrl(result.installationId, result.owner, selfLogin);
+      repositoryName = result.repository ?? repositoryName;
+      repositoryOwner = result.owner ?? repositoryOwner;
+    }
+    if (!shareable) throw result.failure;
+    if (typeof ask !== 'function') {
+      /*
+       * No terminal to prompt at — CI, or a piped run. The repository exists and is one grant from
+       * working, so the failure has to carry everything needed to finish it by hand. Falling back
+       * to the generic message here threw away the deep link that had just been computed.
+       */
+      throw new Error(
+        `${repositoryOwner}/${repositoryName} was created, but the Gala GitHub App cannot reach it `
+        + `yet. Add that one repository to the installation at ${shareUrl}, then run scaffold again.`
+      );
+    }
 
-    notify(`${result.owner ?? ''}/${result.repository ?? name} exists, but the Gala GitHub App `
-      + 'cannot reach it yet — its installation covers only selected repositories.');
-    notify(`${openUrl(installationsUrl) ? 'Opened' : 'Open'} ${installationsUrl}`);
+    notify(`${repositoryOwner}/${repositoryName} was created, but the Gala GitHub App cannot reach `
+      + 'it yet — its installation covers only selected repositories, which is the right way to '
+      + 'have it. Add this one repository to the installation; nothing else needs granting.');
+    notify(`${openUrl(shareUrl) ? 'Opened' : 'Open'} ${shareUrl}`);
     await ask('Press enter once the App can access that repository. ');
   }
   throw new Error(
-    `The Gala GitHub App still cannot reach the repository for ${name}. Give it access at `
-    + `${installationsUrl}, then run scaffold again.`
+    `The Gala GitHub App still cannot reach ${repositoryOwner}/${repositoryName}. Add that `
+    + `repository to the installation at ${shareUrl}, then run scaffold again.`
   );
 }
 
+/**
+ * The page that grants one repository, rather than the list of every app ever installed.
+ *
+ * GitHub keeps user and organisation installation settings on different paths, and only the caller
+ * knows which this is: the created owner differing from the token's own account means the
+ * installation lives on an organisation.
+ */
+export function installationSettingsUrl(installationId, owner, selfLogin) {
+  const generic = 'https://github.com/settings/installations';
+  if (!Number.isSafeInteger(Number(installationId)) || Number(installationId) <= 0) return generic;
+  const isOrganization = typeof owner === 'string' && typeof selfLogin === 'string'
+    && owner.toLowerCase() !== selfLogin.toLowerCase();
+  return isOrganization
+    ? `https://github.com/organizations/${encodeURIComponent(owner)}/settings/installations/${installationId}`
+    : `https://github.com/settings/installations/${installationId}`;
+}
+
 async function requestPublication({
   apiBaseUrl, galaAccessToken, githubAccessToken, name, fetchImpl, authorize
 }) {
@@ -87,6 +124,9 @@ async function requestPublication({
   if (status !== 'READY') {
     return {
       ready: false, status, owner, repository,
+      // Carried even though the repository is not in the installation yet: it is what makes the
+      // grant a deep link rather than a hunt.
+      installationId: payload?.installationId,
       failure: new Error(
         `Gala could not create the publication repository (${payload?.outcome ?? status}). `
         + 'Give the Gala GitHub App access to it at https://github.com/settings/installations, or '

package/src/scaffold-git.js

@@ -1,8 +1,12 @@
 import { spawn } from 'node:child_process';
 
-function run(root, args, spawnProcess, acceptedExitCodes = [0]) {
+import { gitCredentialArguments, gitEnvironment } from './git-credentials.js';
+
+function run(root, args, spawnProcess, acceptedExitCodes = [0], accessToken) {
   return new Promise((resolve, reject) => {
-    const child = spawnProcess('git', ['-C', root, ...args], { cwd: root, shell: false, stdio: 'inherit' });
+    const child = spawnProcess('git', ['-C', root, ...gitCredentialArguments(accessToken), ...args], {
+      cwd: root, shell: false, stdio: 'inherit', env: gitEnvironment(accessToken)
+    });
     child.once('error', reject);
     child.once('exit', (code, signal) => {
       if (signal) reject(new Error(`Git ${args[0]} terminated by signal ${signal}`));
@@ -28,13 +32,44 @@ function capture(root, args, spawnProcess) {
   });
 }
 
-export async function commitScaffold(root, { spawnProcess = spawn } = {}) {
-  await run(root, ['add', '--', 'site.config.yml', '.github/workflows/publish.yml'], spawnProcess);
+/**
+ * Takes the commit registration just pushed, before anything local is written.
+ *
+ * Registering a site makes the server write `site.config.yml` and `.github/workflows/publish.yml`
+ * into the repository. The checkout was taken before that, so the scaffold's own commit lands on a
+ * parent the remote has moved past and the push is rejected:
+ *
+ *     ! [rejected] HEAD -> main (fetch first)
+ *
+ * Integrating here rather than after committing is what keeps it simple: at this point the working
+ * tree is untouched, so the rebase is trivial and cannot conflict with files this process is about
+ * to write. A dirty tree — only reachable via --resume — fails loudly, which is the right answer
+ * for work nobody asked this command to reconcile.
+ */
+export async function syncScaffold(root, { spawnProcess = spawn, accessToken } = {}) {
+  const branch = await capture(root, ['rev-parse', '--abbrev-ref', 'HEAD'], spawnProcess);
+  if (!/^[A-Za-z0-9._/-]+$/.test(branch) || branch === 'HEAD') {
+    throw new Error('Git checkout is not on a named branch');
+  }
+  await run(root, ['fetch', 'origin', branch], spawnProcess, [0], accessToken);
+  await run(root, ['rebase', `origin/${branch}`], spawnProcess);
+  const commitSha = await capture(root, ['rev-parse', 'HEAD'], spawnProcess);
+  if (!/^[0-9a-f]{40}$/.test(commitSha)) throw new Error('Git returned an invalid head SHA');
+  return commitSha;
+}
+
+export async function commitScaffold(root, { spawnProcess = spawn, accessToken } = {}) {
+  /*
+   * Only the site configuration. The publish workflow is written by the server during registration
+   * — the same path the browser editor uses — and staging a file that is not in the checkout yet
+   * fails outright with a pathspec error.
+   */
+  await run(root, ['add', '--', 'site.config.yml'], spawnProcess);
   const unchanged = await run(root, ['diff', '--cached', '--quiet', '--exit-code'], spawnProcess, [0, 1]);
   if (unchanged === 1) {
     await run(root, ['commit', '-m', 'chore(gala): configure site'], spawnProcess);
   }
-  await run(root, ['push', 'origin', 'HEAD'], spawnProcess);
+  await run(root, ['push', 'origin', 'HEAD'], spawnProcess, [0], accessToken);
   const commitSha = await capture(root, ['rev-parse', 'HEAD'], spawnProcess);
   if (!/^[0-9a-f]{40}$/.test(commitSha)) throw new Error('Git returned an invalid scaffold commit SHA');
   return commitSha;

package/src/scaffold-preflight.js

@@ -119,7 +119,6 @@ async function ensureGithub({ notify, readGithub, signInGithub, openUrl }) {
   } catch {
     notify('Signing in to GitHub.');
     await signInGithub({
-      showScopeWarning: ({ explanation }) => notify(`GitHub authorization: ${explanation}`),
       showInstructions: ({ verificationUri, userCode }) =>
         notify(`${openUrl(verificationUri) ? 'Opened' : 'Open'} ${verificationUri}\nEnter code: ${userCode}`)
     });

package/src/scaffold-site.js

@@ -9,9 +9,7 @@ import { createPublication } from './publication-creation-client.js';
 import { installRepositoryVariable } from './github-repository-variable.js';
 import { provisionGithubPages } from './github-pages-provisioning.js';
 import { registerSite } from './site-registration-client.js';
-import { writeRegisteredSiteConfiguration } from './site-config-registration.js';
-import { writePublishWorkflow } from './workflow-command.js';
-import { commitScaffold } from './scaffold-git.js';
+import { commitScaffold, syncScaffold } from './scaffold-git.js';
 import {
   setRepositoryOrigin, verifyEmptyRepository, verifyRepositoryOrigin
 } from './github-empty-repository.js';
@@ -49,16 +47,15 @@ function registrationLocation(owner, topology, canonicalBaseUrl) {
 export async function scaffoldSite({
   owner, repository, target, githubInstallationId, siteOptions, emptyExistingRepository = false,
   notify = (message) => process.stdout.write(`${message}\n`), ask, openUrl,
-  resumeExistingCheckout = false, topology = 'provider-default', canonicalBaseUrl, actionRef,
-  buildMode = 'build-and-deploy', templateOwner = 'rathnasgala',
+  resumeExistingCheckout = false, topology = 'provider-default', canonicalBaseUrl,
+  templateOwner = 'rathnasgala',
   templateRepository = 'site-template',
   readGithub = readGithubCredential, readGala = readGalaCredential,
   createRepository = createPublication, awaitContent = awaitRepositoryContent, clone = cloneRepository,
-  configure = configureSite, register = registerSite, finalize = writeRegisteredSiteConfiguration,
-  writeWorkflow = writePublishWorkflow,
+  configure = configureSite, register = registerSite,
   installVariable = installRepositoryVariable,
   provisionPages = provisionGithubPages,
-  commit = commitScaffold, verifyEmpty = verifyEmptyRepository, setOrigin = setRepositoryOrigin,
+  commit = commitScaffold, sync = syncScaffold, verifyEmpty = verifyEmptyRepository, setOrigin = setRepositoryOrigin,
   verifyCheckout = verifyRepositoryOrigin
 }) {
   const requestedOwner = segment(owner, 'owner');
@@ -112,7 +109,7 @@ export async function scaffoldSite({
     const created = await createRepository({
       apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken,
       githubAccessToken: github.accessToken, name: repositoryName,
-      notify, ask, openUrl
+      notify, ask, openUrl, selfLogin: requestedOwner
     });
     repositoryOwner = segment(created.owner, 'owner');
     repositoryName = segment(created.repository, 'repository');
@@ -125,11 +122,30 @@ export async function scaffoldSite({
     });
   }
   if (!resumeExistingCheckout) {
-    root = await clone({ cloneUrl: generated.cloneUrl, target });
+    root = await clone({ cloneUrl: generated.cloneUrl, target, accessToken: github.accessToken });
     if (emptyExistingRepository) await setOrigin({ root, owner: repositoryOwner, repository: repositoryName });
   }
   const location = registrationLocation(repositoryOwner, topology, canonicalBaseUrl);
-  const configured = await configure(root, siteOptions ?? {});
+  await configure(root, siteOptions ?? {});
+
+  /*
+   * The writer's design choices go up before registration, and nothing goes up after it.
+   *
+   * Registration makes the server write `site.config.yml` and `.github/workflows/publish.yml` into
+   * the repository — the same code path the browser editor uses. The CLI used to write its own
+   * versions of both files afterwards and commit them, which produced a second commit whose whole
+   * content was rewriting `api-base-url` into a `vars` reference and stripping the template's
+   * comments. That second commit triggered a second Publish run, which collided with the first
+   * one's deployment record and failed:
+   *
+   *     Assigned-ID source moved on the remote branch: content/posts/example/index.en.md
+   *
+   * So those two files have one owner now, and it is the server. What is left here is the design
+   * configuration, which only the CLI receives — pushed first so the server provisions on top of
+   * it rather than around it.
+   */
+  await commit(root, { accessToken: github.accessToken });
+
   const idempotencyKey = `scaffold-${createHash('sha256').update(`${repositoryOwner.toLowerCase()}/${repositoryName.toLowerCase()}`).digest('hex')}`;
   const registration = await register({
     apiBaseUrl: gala.apiBaseUrl, galaAccessToken: gala.accessToken,
@@ -137,24 +153,31 @@ export async function scaffoldSite({
     githubInstallationId: resolvedInstallationId, repositoryOwner, repositoryName,
     topology: location.topology, canonicalBaseUrl: location.canonicalBaseUrl
   });
-  await finalize(root, {
-    siteId: registration.siteId,
-    canonicalBaseUrl: registration.canonicalBaseUrl,
-    pathPrefix: registration.pathPrefix,
-    topology
-  });
-  await writeWorkflow({
-    root, siteId: registration.siteId, timezone: configured.site.timezone, buildMode,
-    ...(actionRef == null ? {} : { actionRef })
-  });
+
   await installVariable({
     owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken,
     variableName: 'GALA_API_BASE_URL', variableValue: gala.apiBaseUrl
   });
-  const commitSha = await commit(root);
-  const pages = buildMode === 'build-and-deploy' ? await provisionPages({
+
+  // Brings the server's provisioning commits into the checkout, so the writer's working copy holds
+  // the publication as it actually exists, and reports the commit publishing will run against.
+  const commitSha = await sync(root, { accessToken: github.accessToken });
+
+  /*
+   * Pages is only touched for a custom domain.
+   *
+   * On the provider default it was never doing anything: publishing creates a `gh-pages` branch and
+   * GitHub turns on classic Pages by itself — every scaffold produced a live site with
+   * `build_type: legacy, source: gh-pages` before this step ran, including runs that failed before
+   * reaching it. What the step did cost was up to ten minutes waiting on a workflow run, and a
+   * reported failure for a publication that was already serving.
+   *
+   * A custom domain is different: classic Pages will not point itself at someone's own hostname, so
+   * the API call is the thing that does it.
+   */
+  const pages = location.topology === 'CUSTOM_DOMAIN' ? await provisionPages({
     owner: repositoryOwner, repository: repositoryName, accessToken: github.accessToken, commitSha,
-    customDomain: location.topology === 'CUSTOM_DOMAIN' ? new URL(location.canonicalBaseUrl).hostname : null
+    customDomain: new URL(location.canonicalBaseUrl).hostname
   }) : null;
   return Object.freeze({
     root, fullName: generated.fullName, siteId: registration.siteId, commitSha, pages