Integrate with GitHub Enterprise Server

  • Release version: Xanadu
  • Updated August 1, 2024
  • 5 minutes to read

    • Integrating your Software Asset Management application with the GitHub Enterprise Server application help you track your software subscriptions and reclaim unused licenses.

    Important:
    Minimize security risks and protect information by granting access only to the necessary user or API permissions.
    Table 1. Minimal user permissions
    Process Required user role in the GitHub Enterprise Server application Authentication scopes
    Download subscriptions site admininistrator site_admin
    Reclaim subscription site admininistrator site_admin

    Generate an API access token for GitHub Enterprise Server

    Generate a token that you can use to access the GitHub Enterprise Server API.

    Before you begin

    GitHub Role required: site administrator

    About this task

    The GitHub repository hosting service uses personal access tokens to grant users access to the GitHub API. Personal access tokens function similarly to OAuth access tokens by authorizing API requests. By generating a personal access token to authorize your GitHub Enterprise Server API requests, you can gain access to the GitHub Enterprise Server API.

    Procedure

    1. From a web browser, open your GitHub Enterprise Server instance.
    2. Sign in to your GitHub account.
    3. On the GitHub page header, select your profile photo and then select Settings.
      Your profile settings open.
    4. From the left navigation pane, select Developer Settings.
      Your developer settings open.
    5. From the left navigation pane, select Personal access tokens.
    6. On the Personal access tokens page, select Generate new token.
    7. If you’re prompted to confirm your password before proceeding, enter your GitHub password and then select Confirm password.
    8. On the New personal access token form, describe the purpose of the token in the Note field.
    9. In the Select scopes form section, enable the site_admin OAuth scope by selecting the site_admin check box.
      OAuth scopes limit the level of access that the application has to your protected resources. The site_admin OAuth scope enables you to manage your enterprise users, organizations, and repositories.
    10. Select Generate token.
      Your personal access token generates.
    11. Copy the access token and save it in a secure location for later use.

    Create a GitHub Enterprise Server connection

    Create a connection between your GitHub Enterprise Server applications and your ServiceNow instance.

    Before you begin

    If you want to use a MID Server for communication between your ServiceNow instance and your GitHub Enterprise Server applications, you must first set up a MID Server on your instance. See MID Server for detailed instructions.

    ServiceNow Role required: admin

    Procedure

    1. From your ServiceNow instance, navigate to Process Automation > Flow Designer.
      The Flow Designer launches in a new tab.
    2. Select the Connections tab.
    3. Select View Details for your GitHub Server connection.
    4. From the list of available connections, locate GitHub Server and then select Configure.
    5. In the Configure Connection dialog box, fill in the fields.
      Table 2. Configure Connection dialog box
      Field Description
      Connection Name Name of the GitHub Server connection.
      Connection URL URL of your GitHub instance.
      Use MID Server Option that enables your ServiceNow instance to use a MID Server for communication with your GitHub Enterprise Server applications.
      • If your instance requires a MID Server, set this field to true.
      • If your instance doesn’t require a MID Server, leave this field empty.
      Important:
      To enable this option, you must already have a MID Server set up on your instance. See MID Server for detailed instructions.
      API Key Personal access token that enables you to access the GitHub Enterprise Server API. Enter <api-key>, where <api-key> is the personal access token that you generated in Generate an API access token for GitHub Enterprise Server.
    6. Select Configure Connection.

    Create a GitHub Enterprise Server integration profile

    Create a GitHub Enterprise Server integration profile to track software subscriptions and optimize licensing for your GitHub Enterprise Server applications.

    Before you begin

    To create a GitHub Enterprise Server integration profile, request the Software Asset Management - SaaS License Management plugin (sn_sam_saas_int) from the ServiceNow Store.

    ServiceNow Role required: sam_integrator or admin

    About this task

    If you’re using Software Asset Workspace, the option to create the GitHub Server integration profile in Core UI is inactive.

    Procedure

    1. Navigate to the integration profile.
      InterfaceAction
      Core UI
      1. Navigate to All > Software Asset > SaaS License > Direct Integration Profiles.
      2. Select New.
      3. Select GitHub Server Subscription Profile.
      Software Asset Workspace
      1. Navigate to License operations > User Subscriptions > Direct integration profiles.
      2. Select New.
      3. Select GitHub Server from the drop-down list.
      4. Select Continue.
    2. On the form, fill in the fields.
      Table 3. Integration Profile form
      Field Description
      Display Name Name of the integration profile. For example, GitHub Server Integration.
      Connection & Credential Connection and credential alias for the GitHub spoke. This field is automatically set to sn_github_spoke.GitHub_Server.
      Status Status of the integration profile.
      • If you have not published the integration profile, this field is automatically set to Draft.
      • If you have already published the integration profile, this field is automatically set to Published.
      Profile type Type of integration profile. This field is automatically set to github_server_subscription.
    3. On the Download Subscription Subflow tab, verify that the Subflow field is set to GitHub Server Download Subscriptions.
      You can view events performed by individual users up to one year prior to the current date. For more information, see Review a software reclamation rule.
      Note:
      Software Asset Management pulls the events from the time that you start downloading user subscriptions irrespective of the profile creation date.
    4. On the Reclaim Subscription Subflow tab, verify that the Subflow field is set to GitHub Server Reclaim Subscription.
    5. Select Save.
      Your ServiceNow instance creates a draft integration profile. The integration profile uses the GitHub Server Download Subscriptions and GitHub Server Reclaim Subscription subflows to retrieve data from your GitHub Enterprise Server applications.
    6. After the form reloads, select Publish.
    7. In the Publish Confirmation dialog box, select OK.

    What to do next

    After the integration connects, your ServiceNow instance automatically creates software models, reclamation rules, and software subscriptions that are refreshed daily.

    If you want to set up multiple integration profiles with unique connections, create child aliases to manage different configurations and settings for each integration profile. For more information, see Create a child alias to set up multiple integration profiles.

    Review all automatically generated reclamation rules to reclaim user subscriptions. For more information, see Review a software reclamation rule.

    Create software entitlements for the automatically generated software models to track used software against owned software.
    Reconciliation also runs on your subscriptions as a scheduled job or on-demand. You can view your reconciliation results in the License Workbench (Software Asset Management classic application) or the License usage view (Software Asset Workspace). Use these results to determine your license compliance position and to remediate any non-compliance.