microsoft · Pavan (pavankm) · Aug 4, 2026
@@ -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"
     }
   ]
 }
@@ -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",

@@ -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 "<name>"` or `git config --global user.email "<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.
 

@@ -6,14 +6,51 @@
 | --------------------- | --------------- | --------------------------------------------------- | ---------------------------------------------------------------------------- |
 | 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
 
 - 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)" },

@@ -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 "<you>@microsoft.com"` and `... user.name "<You>"`.                       |
+| 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 "<name>"` and `git config --global user.email "<email>"`. |
 
 ## Common Build / Dev Failures