PORTN-3058 Add new guide for mapping Git users to Port accounts

[kodjomiles]

Description

Added new guide to automatically map git users to Port account users

Added docs pages

Please also include the path for the added docs

-Map Git users to Port user accounts (/guides/all/map-git-users-to-port-accounts)

[notion-workspace]

Create a guide for mapping GitHub, GitLab and ADO user to a Port User

[aws-amplify-eu-west-1]

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-2579.d2ngvl90zqbob8.amplifyapp.com

[claude]

Claude finished @kodjomiles's task —— View job

---

PR Review Complete ✅

I've reviewed this PR against the CONTRIBUTING.md guidelines. Here's my detailed feedback:

Todo List:

• Read CONTRIBUTING.md and CLAUDE.md for review criteria
• Review new guide file: docs/guides/all/map-git-users-to-port-accounts.md
• Review constants file changes: src/components/guides-section/consts.js
• Analyze content quality, technical accuracy, and formatting
• Provide comprehensive review feedback

---

📋 Review Summary

Overall Assessment: The PR successfully adds a comprehensive guide for mapping Git users to Port accounts with mostly excellent quality and adherence to documentation standards.

✅ Strengths

Content Quality

• Comprehensive coverage of GitHub, GitLab, and Azure DevOps integrations
• Clear step-by-step instructions with proper action verbs ("Go to", "Click on", "Add")
• Well-structured sections with logical flow from prerequisites through implementation
• Good use of tabs to organize platform-specific content with proper queryString attribute
• Practical examples with code snippets and configuration details

Technical Accuracy

• Correct integration mappings for all three Git platforms
• Proper blueprint relations setup between Git users and Port users
• Valid automation configuration with appropriate webhook calls
• Accurate API endpoints and payload structure

Formatting & Standards Compliance

• ✅ Headers follow lowercase convention (e.g., "Map Git users to Port user accounts")
• ✅ Code blocks include showLineNumbers for multi-line examples
• ✅ Proper use of admonitions with descriptive titles
• ✅ Consistent use of details/summary with bold formatting and "Click to expand"
• ✅ Full path links used throughout (not relative)
• ✅ Active voice and "We" language in guide content

⚠️ Issues Found

1. Typo in Prerequisites (Line 22)

Issue: "Port's GitHub Integrtion" should be "Port's GitHub Integration"

- [Port's GitHub Integrtion](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/).

2. Admonition Placement Issue (Lines 306-308)

Issue: The tip admonition is placed inside the details block but should be outside for better visibility:

    :::tip Select the relevant Git integration
    In this automation example, we show how to map Port users to all supported Git platforms (GitHub, GitLab, and Azure DevOps) at once...
    :::

    </details>

3. Missing Alt Text for Images

Issue: While no images are used in this guide, the screenshots mentioned in the contributing guidelines for guides aren't present. Consider adding screenshots for key steps.

4. Blueprint Naming Inconsistency

Issue: The guide uses "_user" (with underscore) in mappings but refers to User blueprint in text. Should clarify this is the same blueprint.

🔧 Constants File Review (src/components/guides-section/consts.js)

✅ Correct Implementation

• Proper placement in availableGuides array at the end
• Appropriate tags including SDLC, Git platforms, and Automations
• Correct logos using generic "Git" logo
• Accurate description and title
• Valid link path matching the actual file location

Suggestions for Improvement

• Consider adding "RBAC" tag since the guide deals with user account mapping
• The guide could benefit from "Getting started" category assignment

📝 Minor Recommendations

1. Add troubleshooting section for common issues users might encounter
2. Include expected outcomes after key steps (as mentioned in contributing guidelines)
3. Consider adding a diagram showing the relationship between Git users and Port users
4. Add validation steps to verify the mapping is working correctly

🎯 Final Verdict

This is a high-quality PR that adds significant value to the documentation. The guide is comprehensive, technically accurate, and follows most documentation standards. The issues identified are minor and easily addressable.

Recommendation: ✅ Approve with minor fixes

The PR successfully addresses the requirement to create a guide for mapping Git users to Port accounts and provides clear, actionable instructions for all major Git platforms.

---

[claude]

Claude finished @kodjomiles's task —— View job

---

PR Review Complete ✅

I've reviewed this PR against the CONTRIBUTING.md guidelines. Here's my detailed feedback:

Todo List:

• Read CONTRIBUTING.md and CLAUDE.md for review criteria
• Review new guide file: docs/guides/all/map-git-users-to-port-accounts.md
• Review constants file changes: src/components/guides-section/consts.js
• Analyze content quality, technical accuracy, and formatting
• Provide comprehensive review feedback

---

📋 Review Summary

Overall Assessment: The PR successfully adds a comprehensive guide for mapping Git users to Port accounts with mostly excellent quality and adherence to documentation standards.

✅ Strengths

Content Quality

• Comprehensive coverage of GitHub, GitLab, and Azure DevOps integrations
• Clear step-by-step instructions with proper action verbs ("Go to", "Click on", "Add")
• Well-structured sections with logical flow from prerequisites through implementation
• Good use of tabs to organize platform-specific content with proper queryString attribute
• Practical examples with code snippets and configuration details

Technical Accuracy

• Correct integration mappings for all three Git platforms
• Proper blueprint relations setup between Git users and Port users
• Valid automation configuration with appropriate webhook calls
• Accurate API endpoints and payload structure

Formatting & Standards Compliance

• ✅ Headers follow lowercase convention (e.g., "Map Git users to Port user accounts")
• ✅ Code blocks include showLineNumbers for multi-line examples
• ✅ Proper use of admonitions with descriptive titles
• ✅ Consistent use of details/summary with bold formatting and "Click to expand"
• ✅ Full path links used throughout (not relative)
• ✅ Active voice and "We" language in guide content

⚠️ Issues Found

1. Typo in Prerequisites (Line 22)

Issue: "Port's GitHub Integrtion" should be "Port's GitHub Integration"

- [Port's GitHub Integrtion](https://docs.port.io/build-your-software-catalog/sync-data-to-catalog/git/github/).

2. Admonition Placement Issue (Lines 306-308)

Issue: The tip admonition is placed inside the details block but should be outside for better visibility:

    :::tip Select the relevant Git integration
    In this automation example, we show how to map Port users to all supported Git platforms (GitHub, GitLab, and Azure DevOps) at once...
    :::

    </details>

3. Missing Alt Text for Images

Issue: While no images are used in this guide, the screenshots mentioned in the contributing guidelines for guides aren't present. Consider adding screenshots for key steps.

4. Blueprint Naming Inconsistency

Issue: The guide uses "_user" (with underscore) in mappings but refers to User blueprint in text. Should clarify this is the same blueprint.

🔧 Constants File Review (src/components/guides-section/consts.js)

✅ Correct Implementation

• Proper placement in availableGuides array at the end
• Appropriate tags including SDLC, Git platforms, and Automations
• Correct logos using generic "Git" logo
• Accurate description and title
• Valid link path matching the actual file location

Suggestions for Improvement

• Consider adding "RBAC" tag since the guide deals with user account mapping
• The guide could benefit from "Getting started" category assignment

📝 Minor Recommendations

1. Add troubleshooting section for common issues users might encounter
2. Include expected outcomes after key steps (as mentioned in contributing guidelines)
3. Consider adding a diagram showing the relationship between Git users and Port users
4. Add validation steps to verify the mapping is working correctly

🎯 Final Verdict

This is a high-quality PR that adds significant value to the documentation. The guide is comprehensive, technically accurate, and follows most documentation standards. The issues identified are minor and easily addressable.

Recommendation: ✅ Approve with minor fixes

The PR successfully addresses the requirement to create a guide for mapping Git users to Port accounts and provides clear, actionable instructions for all major Git platforms.

---