Docs/readme clarity and diagram colors#34
Merged
arnaudlh merged 15 commits intoAzure:mainfrom Apr 28, 2026
Merged
Conversation
Contributor
There was a problem hiding this comment.
Pull request overview
This PR improves Git-Ape’s onboarding and usage documentation by adding clearer explanations of OIDC authentication, refining “Get Started” installation paths, and upgrading ASCII diagrams to Mermaid diagrams with consistent theming and visual cues.
Changes:
- Expanded
docs/ONBOARDING.mdwith an OIDC explanation plus new Mermaid diagrams for single/multi-environment setups. - Added a deployment lifecycle Mermaid diagram to
docs/DEPLOYMENT_STATE.md. - Refreshed
README.mdanddocs/CODESPACES.mdto be more structured and Git-Ape–branded (installation options, prompts, diagrams/colors).
Show a summary per file
| File | Description |
|---|---|
| docs/ONBOARDING.md | Adds OIDC explanation and replaces ASCII architecture diagrams with themed Mermaid diagrams for onboarding modes. |
| docs/DEPLOYMENT_STATE.md | Introduces a “Deployment Lifecycle” section with a Mermaid state diagram. |
| docs/CODESPACES.md | Updates Codespaces/devcontainer doc branding and example prompts to Git-Ape. |
| README.md | Reorganizes onboarding/usage instructions, adds multiple install options, and enhances Mermaid diagrams with styling. |
Copilot's findings
Comments suppressed due to low confidence (1)
docs/ONBOARDING.md:688
- The federated credential subjects in this architecture diagram are shown as fixed
repo:org/repo:...strings, but this doc’s manual setup supports both name-based and ID-based subject prefixes via$OIDC_PREFIX. Consider using<OIDC_PREFIX>:...in this diagram as well (or adding a note) so it matches the supported onboarding behavior.
APP["<b>App Registration</b><br/>sp-git-ape-{repo}<br/>client_id + tenant_id"]
FC["<b>Federated Credentials</b><br/>• repo:org/repo:ref:refs/heads/main<br/>• repo:org/repo:pull_request<br/>• repo:org/repo:environment:azure-deploy<br/>• repo:org/repo:environment:azure-destroy"]
APP --- FC
- Files reviewed: 4/4 changed files
- Comments generated: 7
Comment on lines
+52
to
+80
| 1. Add the marketplace in your VS Code `settings.json`: | ||
|
|
||
| ```jsonc | ||
| "chat.plugins.marketplaces": [ | ||
| "Azure/git-ape" | ||
| ] | ||
| ``` | ||
|
|
||
| 2. Open the Extensions view (`⇧⌘X` on macOS, `Ctrl+Shift+X` on Windows/Linux), search for `@agentPlugins`, find **git-ape**, and select **Install**. | ||
| 3. Alternatively, open the Command Palette (`⇧⌘P` on macOS, `Ctrl+Shift+P` on Windows/Linux), run **Chat: Install Plugin From Source**, and enter `https://github.com/Azure/git-ape`. | ||
| 4. Verify the agents and skills appear in Copilot Chat (for example, type `@git-ape` or `/prereq-check`). | ||
|
|
||
| #### Option B: Copilot CLI plugin | ||
|
|
||
| ```bash | ||
| copilot plugin marketplace add Azure/git-ape | ||
| copilot plugin install git-ape@git-ape | ||
| copilot plugin list # Should show: git-ape@git-ape | ||
| ``` | ||
|
|
||
| Verify the installation: | ||
| #### Option C: Local development install | ||
|
|
||
| ```bash | ||
| copilot plugin list # Should show: git-ape@git-ape | ||
| ``` | ||
| Clone this repository and register the local checkout as a VS Code plugin in `settings.json`: | ||
|
|
||
| Manual option: | ||
| ```jsonc | ||
| "chat.pluginLocations": { | ||
| "/absolute/path/to/git-ape": true | ||
| } | ||
| ``` |
There was a problem hiding this comment.
The settings.json snippets shown in Options A/C are JSON fragments (missing the surrounding {} and any required commas). Consider either explicitly calling out that these are partial snippets to be merged into an existing settings.json, or show a minimal valid settings.json example to reduce copy/paste errors.
Comment on lines
+29
to
+33
| GH->>GH: Mint OIDC token<br/>subject: repo:org/repo:ref:refs/heads/main | ||
| GH->>Entra: Exchange token<br/>(client_id + federated credential) | ||
| Entra->>Entra: Verify subject matches<br/>federated credential | ||
| Entra-->>GH: Azure access token<br/>(short-lived, ~1h) | ||
| GH->>ARM: az deployment sub create<br/>Authorization: Bearer <token> |
There was a problem hiding this comment.
The OIDC subject shown in this sequence diagram is hard-coded to the name-based format (repo:org/repo:...), but later in this doc you explicitly support org-customized ID-based subjects via $OIDC_PREFIX. Consider changing the diagram label to an example (<OIDC_PREFIX>:ref:refs/heads/main) or noting that the subject claim format may be name-based or ID-based depending on org settings, to avoid contradicting the manual setup section.
This issue also appears on line 686 of the same file.
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
…-and-diagram-colors
…docs/ Port docs/ branch updates to docusaurus website pages so the public site matches the README/docs improvements: - onboarding: add 'How OIDC Authentication Works' section with sequence and trust-graph mermaid diagrams; replace ASCII Single/Multi-Environment Mode diagrams with themed mermaid versions. - deployment/state: add 'Deployment Lifecycle' state diagram covering the full set of metadata.json status values. - codespaces: replace residual AutoCloud references with Git-Ape. - skills/prereq-check: replace AutoCloud / autocloud-onboarding references with Git-Ape / git-ape-onboarding.
- generate-docs.js: rewrite sibling .agent.md links in agent bodies to docusaurus slug links (e.g. [git-ape.agent.md](git-ape.agent.md) → [git-ape.agent.md](git-ape)). - generate-docs.js: rewrite skill-relative scripts/ and references/ links to absolute GitHub blob URLs since those files are not copied into the docusaurus site. - getting-started/azure-setup.md: replace relative ../../README.md and ../copilot-instructions.md links with GitHub blob URLs. Eliminates all broken-link warnings reported by 'docusaurus build'.
- installation.md: replace minimal install instructions with the three options from README (VS Code agent plugin / Copilot CLI / local dev), matching the README so the public site mirrors the canonical install guidance. - intro.md: apply themed mermaid styling (matching README and onboarding diagrams) to the Stage 1-4 deployment flow with class-based colouring for user / stage / gate / fix / deploy nodes.
Member
Author
|
Rebased on top of Merge conflict resolved — What changed in this push
|
sendtoshailesh
approved these changes
Apr 28, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request improves the
README.mdto provide clearer, more structured onboarding and usage instructions for Git-Ape. It reorganizes the introduction, expands the "Get Started" section with detailed installation options, clarifies the deployment flow, and enhances the included architecture and workflow diagrams with visual cues and updated descriptions.