docs: add v2.6.0 features - GitHub App auth, OIDC algorithms, and UserInfo claims

[markphelps]

Summary

• Document new GitHub App credential type for Git storage authentication (feat: add GitHub App authentication support flipt#5327)
• Document new OIDC algorithms provider config for customizing accepted ID token signing algorithms (feat(oidc): support configurable token signing algorithms flipt#5362)
• Document new OIDC fetch_extra_user_info provider config for merging UserInfo endpoint claims into auth sessions (feat(oidc): optionally merge userinfo claims into auth session flipt#5364)
• Update configuration overview reference tables with all new properties (since v2.6.0)
• Break up monolithic credentials reference table into per-type subsections for readability
• Add visual verification instructions to AGENTS.md for browser-based QA using Playwright MCP tools

[claude]

Pull Request Review

I've reviewed PR #386 and found the documentation changes to be well-structured and comprehensive. Here's my detailed feedback:

✅ Strengths

1. Excellent Documentation Structure: The changes follow a clear, consistent pattern across all three configuration files (authentication, storage, and overview).

2. Comprehensive Coverage: All three new v2.6.0 features are thoroughly documented:

   • GitHub App authentication for Git storage
   • OIDC algorithms configuration
   • OIDC fetch_extra_user_info configuration

3. Good Examples: Each new feature includes clear YAML configuration examples with realistic placeholder values.

4. Proper Cross-References: The overview.mdx reference tables are correctly updated with all new properties and proper version tags (v2.6.0).

5. Improved Readability: Breaking up the monolithic credentials table into per-type subsections significantly improves readability and makes it easier to find specific credential configurations.

6. Follows Style Guidelines: The content adheres to the Microsoft Writing Style Guide requirements (second-person voice, clear explanations, proper formatting).

7. Link Formatting: All external links use proper markdown syntax with descriptive text (e.g., [create a GitHub App](https://...)).

8. Helpful Notes: Appropriate use of <Note> callout components to highlight important information (e.g., mutual exclusivity of private_key_path and private_key_bytes).

9. AGENTS.md Enhancement: The addition of visual verification instructions using Playwright MCP tools is a valuable improvement for QA processes.

💡 Suggestions for Improvement

1. Minor Consistency Issue in Default Values

In authentication.mdx line 316:

If not specified, the default is ["RS256"].

In overview.mdx line 353, the default is shown as:

["RS256"]

Consider using consistent formatting - either both should use code formatting or both should be plain text. I recommend code formatting for both: ["RS256"]

2. GitHub App Security Benefits

The GitHub App section in storage.mdx (line 224-226) mentions security benefits:

"GitHub App tokens are short-lived, offer higher rate limits, and provide more granular permissions."

Consider adding a similar note in the credentials section of overview.mdx to help users understand why they might choose GitHub App over access tokens.

3. Algorithm List Formatting

The list of supported algorithms (line 298 in authentication.mdx) could be more readable as a bulleted list:

Current:

Supported algorithms: RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512.

Suggested:

Supported algorithms:
- RS256, RS384, RS512 (RSA)
- ES256, ES384, ES512 (ECDSA)
- PS256, PS384, PS512 (RSA-PSS)

This groups them by algorithm family, making it clearer for users who may not be familiar with JWT signing algorithms.

4. UserInfo Endpoint Use Case

The fetch_extra_user_info section (line 318-339 in authentication.mdx) is well-written. Consider adding a concrete example of which providers commonly require this:

<Tip>
  This is especially useful with Azure AD, which often omits group claims from
  ID tokens and requires calling the UserInfo endpoint to retrieve them.
</Tip>

🔍 Quality Checks

• ✅ Frontmatter: All modified MDX files have proper title and description
• ✅ Code Blocks: All YAML examples have proper language tags
• ✅ Link Syntax: All external links use markdown format with descriptive text
• ✅ Version Tags: All new properties correctly labeled with "v2.6.0"
• ✅ Table Formatting: All reference tables maintain consistent column alignment
• ✅ No Security Issues: No credentials or sensitive information exposed in examples

📝 Summary

This is a high-quality documentation PR that accurately reflects the new features in v2.6.0. The changes are well-organized, clearly written, and follow the project's documentation standards. The suggestions above are minor enhancements that would further improve clarity, but they are not blockers for merging.

Recommendation: ✅ Approve with minor suggestions

The PR is ready to merge as-is, though incorporating the suggestions would provide additional value to users.

---

Review conducted using Claude Code with analysis of documentation structure, style guidelines compliance, and technical accuracy.