GitHub integration preview

src/content/docs/service-architecture-intelligence/github-integration.mdx

@@ -1,63 +1,227 @@
 ---
-title: Service Architecture Intelligence with GitHub Integration
+title: GitHub Integration for Service Architecture Intelligence
 tags:
     - New Relic integrations
     - GitHub integration
-metaDescription: Set up automatic ingestion of your GitHub Dependabot events by using webhook for ongoing ingestion.
+metaDescription: Learn how to integrate GitHub with New Relic to import repositories, teams, and user data for enhanced service architecture intelligence.
 freshnessValidatedDate: never
 ---
 
-<Callout title="PREVIEW">
 
-    We're still working on this feature, but we'd love for you to try it out!
+Are you looking to gain deeper insights into your service architecture by leveraging data from your GitHub account? The New Relic GitHub integration imports repositories, teams, and user data directly into the New Relic platform with selective data fetching capabilities.
 
-    This feature is currently provided as part of a preview program pursuant to our [pre-release policies](/docs/licenses/license-information/referenced-policies/new-relic-pre-release-policy).
-</Callout>
+This integration streamlines the onboarding process for users and teams while simplifying role management. It also clarifies entity ownership mapping, reducing setup time and effort. With the new selective data fetching feature, you can choose exactly which data types to import—whether it's teams and users, repositories and pull requests, or both. This integration aims to enhance the management and visibility of [Catalogs](/docs/service-architecture-intelligence/catalogs/catalogs) and [Scorecards](/docs/service-architecture-intelligence/scorecards/getting-started) within New Relic. For more information, refer to the [Service Architecture Intelligence capability](/docs/service-architecture-intelligence/getting-started).
 
 
-The New Relic GitHub integration imports users and teams from your GitHub account to enhance the visibility of your [Service Architecture Intelligence capability](/docs/service-architecture-intelligence/getting-started) in the New Relic platform. 
+* **Supported platforms:** 
+  - GitHub Cloud
+  - GitHub Enterprise (GHE) Cloud (without data residency)
+* **Supported regions:** US and EU regions
 
-This integration streamlines the onboarding process for users and teams, simplifies role management, and clarifies entity ownership mapping, reducing the setup configuration, time, and effort. This integration aims to enhance the management and visibility of [Catalogs](/docs/service-architecture-intelligence/catalogs/catalogs) and [Scorecards](/docs/service-architecture-intelligence/scorecards/getting-started) within New Relic. For more information, refer [Service Architecture Intelligence capability](/docs/service-architecture-intelligence/getting-started). 
+<Callout variant="important" title="important">
+* GHE on-premise, and GHE Cloud with data residency aren't supported.
+* Installing the integration in GitHub user accounts is not supported. Although GitHub allows installing the app in a user account, the sync mechanism will not work, and no data will be imported into New Relic.
+* Note that the GitHub integration isn't FedRAMP compliant.
+</Callout>
 
 
 **Prerequisites:**
 
-* Login to your GitHub account you plan to integrate with New Relic.
+* Log in to your GitHub account you plan to integrate with New Relic.
 * You must be the Organization Manager or Authentication Domain Manager.
 
+* Required entitlements:
+    * `teams_discount_usage`
+    * `integration_github_discount_usage`
+    * `integration_github_ccu`
 
-**To set up the GitHub integration:**
 
-1. Go to **[one.newrelic.com > + Integration & Agents > GitHub integration](https://one.newrelic.com/marketplace/install-data-source?state=9306060d-b674-b245-083e-ff8d42765e0d)**.
-2. On the **Select an account** screen, keep the default account selection and click **Continue**.
-3. On the **Integration setup** screen:
+## What data can be synced
 
-    1. To connect with your GitHub account, click **Install**. The New Relic Observability opens in the GitHub Marketplace. 
-    2. Complete the app installation within your GitHub organization to retrieve data related to users, teams, and repositories.
-        After the installation is complete, you will be redirected to the New Relic platform.
-    3. Click **First time sync**.
-    4. *(Optional)* Click **On-demand sync** to manually sync the data.
+The GitHub integration allows you to selectively choose which data types to import into New Relic, giving you control over what information is synchronized:
 
-        <Callout variant="tip" title="tip">
+### Available data types
 
-            You can manually synchronize the data once every 4 hours. The **On-demand sync** button remains disabled if sync has occurred within the previous 4 hours.
+* **Teams and Users**: Import GitHub team structures and user information to enhance team management and ownership mapping
+
+  <Callout variant="important">
+  **User email visibility requirement**: The integration only imports GitHub users who have configured their email addresses as public in their GitHub profile settings. Team members with private email configurations will be excluded from the user data synchronization process.
+  </Callout>
 
-        </Callout>
+* **Repositories and Pull Requests**: Import repository data and pull request information for better code visibility and deployment tracking
+* **Both**: Import all available data types for comprehensive GitHub integration
 
-    5. After you view the Sync started message, click **Continue**. The **GitHub Integration** screen will then display the count of teams and repositories, refreshing every 5 seconds. Allow a few minutes for the complete import of all data.
+### Data selection considerations
+
+<Callout variant="important">
+**Team integration conflicts**: If teams have already been integrated into New Relic from another source (such as Service teams), GitHub teams will not be allowed to be fetched and stored to prevent data conflicts. In this case, you can only select repositories and pull request data.
+</Callout>
+
+You'll be able to configure your data selection preferences during the initial setup process.
+
+
+## Set up the GitHub integration
+
+1. Go to **[one.newrelic.com > + Integration & Agents > GitHub integration](https://one.newrelic.com/marketplace/install-data-source?state=9306060d-b674-b245-083e-ff8d42765e0d)**.
+2. On the **Select an action** step, select **Set up a new integration**, and click **Continue**.
+3. On the **Begin integration** screen:
+
+    a. To connect with your GitHub account, click **Get started in GitHub**. The New Relic Observability opens in the GitHub Marketplace.
+    b. Complete the app installation within your GitHub organization to retrieve data related to your selected data types.
+    After the installation is complete, you will be redirected to the **Select an action** step one more time.
+    c. Select **Begin integration**, and click **Continue**.
+
+    d. **Select your data preferences**: Choose which data types you want to sync:
+       - **Teams + Users**: Import GitHub team structures and user information
+       - **Repositories + Pull Requests**: Import repository and pull request data
+       - **Both**: Import all available data types
+
+       <Callout variant="tip">
+       If teams are already integrated from another source (like Service teams), the **Teams + Users** option will be disabled to prevent conflicts.
+       </Callout>
+
+    e. Click **Start first sync** to begin importing your selected data types.
+
+    g. After you view the **Sync started** message, click **Continue**. The **Integration status** screen will display the count of your selected data types (teams, repositories, etc.), refreshing every 5 seconds. Allow a few minutes for the complete import of all data.
 
         <img
             title="GitHub integration"
             alt="GitHub integration"
             src="/images/github-integration-progress.webp"
         /> 
 
-4. On the **GitHub integration** screen:
+4. *(Optional)* On the **GitHub integration** screen, access your imported data:
 
-    - Click **Go to Teams** to view the imported teams information on [Teams](/docs/service-architecture-intelligence/teams/teams).
+    - Click **Go to Teams** to view the imported teams information on [Teams](/docs/service-architecture-intelligence/teams/teams) (if teams were selected during setup)
+    - Click **Go to Repositories** to view the imported repositories information on [Repositories](/docs/service-architecture-intelligence/repositories/repositories) (if repositories were selected during setup)
 
     <Callout variant="tip" title="tip">
+        **Auto-assign repositories to teams**: You can automatically assign GitHub repositories to their teams by creating a `teamOwningRepo` custom property in GitHub. Create the custom property at the organization level and assign a value for the custom property at the repository level. Additionally, you can set up a custom property for multiple repositories at the organization level simultaneously. The integration will automatically assign the repositories to the respective teams based on the custom property. For more information on creating custom properties, refer to the [GitHub documentation](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).
+    </Callout>
 
-        You can auto-assign GitHub repositories to their teams by creating a `teamOwningRepo` custom property in GitHub. Create the custom property at the organization level and assign a value for the custom property at the repository level. Additionally, you can set up a custom property for multiple repositories at the organization level simultaneously. The integration will automatically assign the repositories to the respective teams based on the custom property. For more information on creating custom properties, refer to the [GitHub documentation](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization).
 
-    </Callout>
+
+
+## Enable team ownership discovery
+
+The GitHub integration includes a discovery service that can automatically establish team ownership of repositories based on GitHub's organizational structure and custom properties.
+
+### How team ownership works
+
+The discovery service uses multiple methods to establish repository ownership:
+
+1. **GitHub custom properties**: Uses the `teamOwningRepo` custom property to directly assign repositories to teams
+2. **Team membership analysis**: Analyzes commit patterns and team member contributions to infer ownership
+3. **Repository organization**: Uses GitHub's organizational structure and team permissions to determine ownership
+
+### Setting up automatic team ownership
+
+To enable automatic team ownership discovery:
+
+1. **Create custom properties in GitHub** (recommended):
+   - Navigate to your GitHub organization settings
+   - Create a `teamOwningRepo` custom property at the organization level
+   - Assign team values to repositories at the repository level
+   - The integration will automatically map these relationships during sync
+
+2. **Configure team permissions**:
+   - Ensure teams have appropriate repository access in GitHub
+   - The discovery service will use these permissions to infer ownership relationships
+
+3. **Enable automatic team ownership discovery**:
+   - After sync completion, enable automatic team ownership discovery in New Relic. For more information, refer to the [Automating Teams ownership documentation](https://docs.newrelic.com/docs/service-architecture-intelligence/teams/manage-teams/#assign-ownership).
+   - Verify that ownership relationships are correctly established
+
+
+<Callout variant="tip">
+**Best practices for team ownership**:
+- Use consistent naming conventions for teams across GitHub and New Relic
+- Regularly update custom properties when repository ownership changes
+- Review and validate ownership mappings after each sync to ensure accuracy
+</Callout>
+
+
+## Manage your GitHub integration
+
+After setting up your GitHub integration, you can manage it through the New Relic interface. This includes refreshing data, editing configuration, and uninstalling when needed.
+
+### Access integration management
+
+1. Go to **[one.newrelic.com > + Integration & Agents > GitHub integration](https://one.newrelic.com/marketplace/install-data-source?state=9306060d-b674-b245-083e-ff8d42765e0d)**.
+
+2. On the **Select an action** step, select **Manage your organization**, and click **Continue**.
+
+    <img
+        title="GitHub integration manage organization option"
+        alt="Screenshot showing the manage organization option in GitHub integration"
+        src="/images/github-integration-manage-org-option.webp"
+    />
+
+The **Manage GitHub integration** screen displays your connected organizations with their current sync status and data types.
+
+
+### Refresh data
+
+When you click the **Refresh data** option, it provides a streamlined way to update your GitHub data in New Relic.
+
+**To refresh data:**
+
+1. From the **Manage GitHub integration** screen, locate your organization.
+
+2. Click **Refresh data** next to the organization that you want to update and then click **Continue**.
+
+3. On the **Refresh Data** step, click **Sync on demand**.
+
+The system will then validate your GitHub permissions and organization access, fetch only new or changed data since the last sync, process and map the updated data according to your selected data types, and update the integration status to reflect the latest sync timestamp and data counts.
+
+**What gets refreshed:**
+- New team members added to GitHub teams
+- Repository changes (new repos, archived repos, permission changes)
+- Updated team ownership through custom properties
+- Changes to user profiles and team structures
+
+<Callout variant="tip">
+**Refresh frequency**: You can refresh data as often as needed. The process typically takes a few minutes depending on the size of your organization and selected data types.
+</Callout>
+
+### Edit integration settings
+
+Use the **Edit** option to modify your integration configuration after initial setup. You can adjust which data types are synchronized between GitHub and New Relic, choosing from Teams + Users, Repositories + Pull Requests, or Both data types based on your current needs.
+
+**To edit the GitHub integration:**
+
+1. From the **Manage GitHub integration** screen, locate your organization.
+
+2. Click **Edit** next to the organization that you want to update and then click **Continue**.
+
+3. On the **Edit Integration Settings** step, adjust your data type selections as needed.
+
+4. Click **Save changes** to apply your updates.
+
+**What happens during edit:**
+- Current data remains intact during configuration changes
+- New settings apply to subsequent syncs
+- You can preview changes before applying them
+- The integration continues running with previous settings until you save changes 
+
+
+### Uninstall the GitHub integration
+
+Uninstalling the GitHub integration stops data synchronization from the selected organization but preserves all previously imported data in New Relic.
+
+**To uninstall:**
+
+1. From the **Manage GitHub integration** screen, locate the organization you want to uninstall and click **Uninstall**.
+
+2. In the confirmation dialog, review the organization details and click **Uninstall organization** to confirm.
+
+3. You'll see a success message confirming the uninstallation.
+
+
+<Callout variant="important">
+**Data retention after uninstall**: All previously synced data (teams, users, repositories, pull requests) will remain in New Relic after uninstalling the integration. If you need to remove this data, contact New Relic support.
+</Callout>
+
+
+
+