From 71b52bc8d7c614a484162da2c23262693786a535 Mon Sep 17 00:00:00 2001 From: Pavan Kemparaju Date: Tue, 4 Aug 2026 14:41:55 -0700 Subject: [PATCH] docs: clarify create-app git prerequisites Document Git Credential Manager, credential helper, and author identity prerequisites for app scaffolding. Add recovery guidance and bump the plugin version. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 3a27990b-648b-4a72-8970-0fe16565bd1d --- .claude-plugin/marketplace.json | 2 +- .../.claude-plugin/plugin.json | 2 +- .../skills/create-app/SKILL.md | 21 ++++++++++ .../references/prerequisites-reference.md | 41 ++++++++++++++++++- .../create-app/references/troubleshooting.md | 3 +- 5 files changed, 65 insertions(+), 4 deletions(-) diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 5e2eb80..80665cb 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -13,7 +13,7 @@ "name": "microsoft-managed-apps", "source": "./plugins/microsoft-managed-apps", "description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.", - "version": "2.0.2" + "version": "2.0.3" } ] } diff --git a/plugins/microsoft-managed-apps/.claude-plugin/plugin.json b/plugins/microsoft-managed-apps/.claude-plugin/plugin.json index dec4388..b292360 100644 --- a/plugins/microsoft-managed-apps/.claude-plugin/plugin.json +++ b/plugins/microsoft-managed-apps/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "microsoft-managed-apps", - "version": "2.0.2", + "version": "2.0.3", "description": "[Preview] Create and manage Microsoft Managed Apps using the @microsoft/managed-apps-cli (ms) toolchain.", "author": { "name": "Microsoft", diff --git a/plugins/microsoft-managed-apps/skills/create-app/SKILL.md b/plugins/microsoft-managed-apps/skills/create-app/SKILL.md index ff30647..e568e72 100644 --- a/plugins/microsoft-managed-apps/skills/create-app/SKILL.md +++ b/plugins/microsoft-managed-apps/skills/create-app/SKILL.md @@ -38,11 +38,32 @@ The commands below are shown in bash syntax. If you are running PowerShell on Wi ```bash node --version # Must be v22+ git --version # Required (used by `ms app create` to init the repo) +git credential-manager --version # Required for browser-based remote authentication +git config --system --get-regexp '^credential(\..*)?\.helper$' # Check system-level helpers +git config --global --get-regexp '^credential(\..*)?\.helper$' # Check user-level helpers +git config --global --get user.name # Required for the initial scaffold commit +git config --global --get user.email # Required for the initial scaffold commit ms --version 2>/dev/null # Probe the bin name ``` - **Missing Node.js or below v22**: Report "Node.js 22+ is required. Install from https://nodejs.org/ or switch with `nvm use 22`." STOP. - **Missing Git**: Report "Git is required — `ms app create` initializes a repo. Install from https://git-scm.com/." STOP. +- **Missing Git Credential Manager**: + 1. Warn: "Git Credential Manager is not installed. Without it, Git may prompt for a username instead of opening browser authentication. I can install and configure GCM for you." + 2. Ask: "Is it okay to install Git Credential Manager on this machine?" Wait for explicit approval. + 3. If declined, STOP and link to https://aka.ms/gcm. + 4. If approved, install GCM using the official OS-appropriate method: + - Windows with WinGet: `winget install --id Git.GCM --exact --source winget --accept-package-agreements --accept-source-agreements` + - macOS with Homebrew: `brew install --cask git-credential-manager` + - Linux: use an official package from the GCM release/install documentation. Do not pipe a remote install script directly into a shell. + 5. Run `git credential-manager configure`, then repeat the version and helper checks. If either still fails, surface the error and STOP. +- **GCM is installed but no system or global helper entry contains `manager` or `credential-manager`**: + 1. Warn: "Git Credential Manager is installed but Git is not configured to use it. Without this configuration, Git may prompt for a username instead of opening browser authentication." + 2. Ask: "Is it okay to configure Git Credential Manager as Git's credential helper?" Wait for explicit approval. + 3. If approved, run `git credential-manager configure`, then repeat both helper checks. If configuration still cannot be detected, surface the error and STOP. + 4. If declined, STOP. + Ignore nonzero exit codes from an individual config-scope query when that scope has no matching entries. +- **Missing global `user.name` or `user.email`**: Report the missing value and ask the user to configure it with `git config --global user.name ""` or `git config --global user.email ""`. STOP. Never invent either value. - **Missing `ms`**: proceed to the global install block below. Confirm with the user before running `npm install -g`. - **One of them resolves**: record which binary name resolved (`$BIN`); use it in every subsequent step. diff --git a/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md b/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md index 5b3643b..acec8d1 100644 --- a/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md +++ b/plugins/microsoft-managed-apps/skills/create-app/references/prerequisites-reference.md @@ -6,7 +6,10 @@ | --------------------- | --------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | | Node.js | **v22+** | `node --version` | https://nodejs.org/ | | Git | Any 2.x | `git --version` | https://git-scm.com/ — required (`ms app create` initializes a repo). | -| Git Credential Manager | Bundled with Git for Windows | `git credential-manager --version` | First `ms app create` triggers an interactive browser flow against the remote git endpoint. See [troubleshooting.md](./troubleshooting.md#first-run-git-credential-manager-trap). | +| Git Credential Manager | Current release | `git credential-manager --version` | Required for browser-based remote authentication. Bundled with Git for Windows; otherwise install from https://aka.ms/gcm. | +| GCM credential helper | Configured at system or global scope | `git config --system --get-regexp '^credential(\..*)?\.helper$'` and `git config --global --get-regexp '^credential(\..*)?\.helper$'` | Combined output must contain `manager` or `credential-manager`. Run `git credential-manager configure` if it does not. | +| Git author name | Configured globally | `git config --global --get user.name` | Required for the initial scaffold commit. | +| Git author email | Configured globally | `git config --global --get user.email` | Required for the initial scaffold commit. | | `@microsoft/managed-apps-cli` | `@latest` tag | `ms --version` | Install globally only — see below. | ## Required Account @@ -14,6 +17,40 @@ - A Microsoft work/school account with access to a Microsoft Apps-enabled tenant. - `ms app create` resolves an environment automatically — you do not need to know or provide one. (Advanced users who already have a specific environment ID can pass it via `--environment-id`.) +## Git prerequisite checks + +Run these checks before `ms app create`: + +```bash +git credential-manager --version +git config --system --get-regexp '^credential(\..*)?\.helper$' +git config --global --get-regexp '^credential(\..*)?\.helper$' +git config --global --get user.name +git config --global --get user.email +``` + +- If GCM is missing, warn that Git may fall back to a username prompt and ask for approval to install it. On approval, use the official OS-appropriate installation method, run `git credential-manager configure`, and repeat the checks. If declined, stop. +- If GCM exists but the combined system/global helper output does not contain `manager` or `credential-manager`, warn the user and ask for approval to run `git credential-manager configure`. Repeat the checks after configuration. An individual scope returning no entries is not itself a failure. +- If either author value is empty, ask the user for the correct value before configuring it. Never infer an email address or name. + +### GCM repair commands + +Use these only after explicit user approval: + +```bash +# Windows with WinGet +winget install --id Git.GCM --exact --source winget \ + --accept-package-agreements --accept-source-agreements + +# macOS with Homebrew +brew install --cask git-credential-manager + +# After installation, or when GCM is installed but not configured +git credential-manager configure +``` + +For Linux, use an official package from the [GCM installation documentation](https://aka.ms/gcm). Do not pipe a remote install script directly into a shell. Always repeat the GCM version and system/global helper checks after a repair. + ## Installing `@microsoft/managed-apps-cli` The CLI is published on the public npm registry: [`@microsoft/managed-apps-cli`](https://www.npmjs.com/package/@microsoft/managed-apps-cli). @@ -59,6 +96,8 @@ When using plan mode, include these in `allowedPrompts`: { "allowedPrompts": [ { "tool": "Bash", "prompt": "check tool versions (node, git, ms)" }, + { "tool": "Bash", "prompt": "check Git Credential Manager, credential helper, and author identity" }, + { "tool": "Bash", "prompt": "install or configure Git Credential Manager and Git author identity" }, { "tool": "Bash", "prompt": "install @microsoft/managed-apps-cli globally" }, { "tool": "Bash", "prompt": "ms auth status / ms auth login" }, { "tool": "Bash", "prompt": "ms app create / ms app delete (recovery)" }, diff --git a/plugins/microsoft-managed-apps/skills/create-app/references/troubleshooting.md b/plugins/microsoft-managed-apps/skills/create-app/references/troubleshooting.md index dddc27a..a68c48f 100644 --- a/plugins/microsoft-managed-apps/skills/create-app/references/troubleshooting.md +++ b/plugins/microsoft-managed-apps/skills/create-app/references/troubleshooting.md @@ -39,7 +39,8 @@ Match `Could not commit and push the initial scaffold` together with `Authentica | `defau.lt.environment.api.powerplatform.com: no such host` (or similar DNS error) | A malformed `--environment-id` value was passed (this only happens when the user supplied one). | Surface the error. Drop the explicit `--environment-id` and let `ms app create` auto-route, or have the user supply a valid environment ID. | | `Could not provision a Developer environment for your tenant (status 403)` | Routing service rejected the account. Tenant Governance may block Developer envs. | Surface the error to the user — provisioning is blocked at the tenant level and the plugin cannot work around it. The user (or their tenant admin) needs to resolve the governance/access issue. | | `Directory not empty; pass --force` | Current project folder has prior files. | Run `/create-app` from an empty folder, or confirm using `--force` only when you intend to overwrite. | -| Repo init fails (`fatal: not in a git repository`) | Git is missing or `git config user.email` / `user.name` are unset. | Install Git; run `git config --global user.email "@microsoft.com"` and `... user.name ""`. | +| Git prompts for a username instead of opening a browser | GCM is missing or is not configured as a system/global Git credential helper. | Warn the user and ask permission to repair it. If missing, install GCM using the official OS-appropriate method; if unconfigured, run `git credential-manager configure`. Repeat the version and helper checks afterward. | +| Initial scaffold commit reports an unknown author identity | Global `user.name` or `user.email` is unset. | Ask the user for the correct values, then run `git config --global user.name ""` and `git config --global user.email ""`. | ## Common Build / Dev Failures