{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":32197,"path":"it-service-management/devops-change-velocity/playbook-enter-github-instance-details.md","title":"Onboard GitHub to DevOps Change Velocity — Workspace","bundle":null,"doc_type":null,"release":"australia","body":"\n# Onboard GitHub to DevOps Change Velocity — Workspace\n\nConnect to your GitHub instance using the DevOps Change Workspace playbook to discover, configure, and import repositories, plans, and pipelines.\n\n## Before you begin\n\nComplete the tasks specified in the [Getting started with DevOps Change Velocity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/setting-up-devops-change-velocity.md) topic.\n\nRole required: sn\\_devops.admin or sn\\_devops.tool\\_owner\n\n## About this task\n\nServiceNow DevOps Change Velocity supports three GitHub offerings. Use the following table to determine which tool Integration type and URL apply to your GitHub setup:\n\n\n
\n\nGitHub offering\n\n\n\nTool name\n\n\n\nURL of the tool instance\n\n
\n\nGitHub \\(Standard\\)\n\n\n\nGitHub\n\n\n\n`https://api.github.com`\n\n
\n\nGitHub Enterprise Cloud\n\n\n\nGitHub\n\n\n\n`https://api.github.com`\n\n
\n\nGitHub Enterprise Server\n\n\n\nGitHub Enterprise\n\n\n\n`https://` **Note:** Self-hosted instance must be your own server.\n\n
**Note:**\n\nDon't use your GitHub Enterprise Cloud account's web address as the tool URL. For example, using `https://github.com/enterprises/` as the tool URL fails because this is a browser-only page, not an API endpoint. This error appears as \"Tool cannot be created because the tool URL is invalid.\"\n\nIf you use GitHub Enterprise Cloud, follow these rules:\n\n- Select **GitHub** as the tool.\n- Enter `https://api.github.com` as the URL of the tool instance.\n\nOnly enter a different hostname if you run a self-hosted GitHub Enterprise Server instance on your own server.\n\n## Procedure\n\n1. Navigate to **Workspaces** > **DevOps Change Workspace** and use one of the following options to open the Playbook to onboard GitHub.\n\n\n
\n\nOption\n\n\n\nSteps\n\n
\n\n**Homepage**\n\n\n\n1. Select **Connect a tool**.\n2. From the Connect to a tool modal, select the tool from the appropriate category \\(Orchestration, Code, Plan, or Software quality\\). For example, if you want to connect to GitHub as coding tool, you'd select the **Coding tools** category.\n\n\n
\n\n**Applications module**\n\n\n\n1. Select **Applications** \\(\\[Omitted image \"applications-icon.png\"\\] Alt text: Applications icon.\\) from the primary navigation.\n2. Select an existing application, or create one. To create an application, see [Create an application - Workspace](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/app-create-workspace.md).\n3. From the  Recommended actions  pane, select the  **Connect a tool ** card.\n4. From the Connect to a tool modal, select the tool from the appropriate category. For example, if you want to connect to GitHub as coding tool, select GitHub under the **Code** category.\n\n\n
\n\n**Tools module**\n\n\n\n1. Select **Tools** \\(\\[Omitted image \"tools-icon-wkspc.png\"\\] Alt text: Tools icon.\\) from the primary navigation.\n2. From the Capability list, select the appropriate category. For example, if you want to connect to GitHub as coding tool, you'd select the **Coding** category.\n3. Select **Connect a tool**.\n4. On the  Connect to a tool  modal, select GitHub.\n\n\n
**Important:** If you want to discover and track tool objects like pipelines, plans, or repositories while connecting to the tool, you must connect your tool from the Application module.\n\n2. In the **Tool name** field, enter a name for the tool.\n\n \\[Omitted image \"github-plybk-04.png\"\\] Alt text: Connect to GitHub\n\n3. Select **Next**.\n\n The DevOps playbook opens to help you complete the onboarding tasks.\n\n4. Complete the connection and configuration using the playbook.\n\n 1. In the **Credential type** field, select one of the following credential type.\n\n - Basic Auth\n - OAuth 2.0 with Authorization Code\n - OAuth 2.0 with JSON Web Token \\(JWT\\)\n 2. Enter the credentials.\n\n\n
\n\nBasic Auth\n\n\n\nEnter the username and password/access token of your GitHub instance.\n\n \\[Omitted image \"github-basic-auth.png\"\\] Alt text: GitHub basic auth credential type.\n\n
\n\nOAuth 2.0 with Authorization Code\n\n\n\nSelect an existing OAuth 2.0 with Authorization Code credential record or create an OAuth 2.0 with Authorization Code credential record. For more information, see [Create a credential record for GitHub App provider \\(Authorization Code\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/dev-ops-github-apps-oauth-auth.md).\n\n \\[Omitted image \"github-oauth-auth.png\"\\] Alt text: GitHub Oauth 2.0 with Authorization Code credential type\n\n
\n\nOAuth 2.0 with JSON Web Token \\(JWT\\)\n\n\n\nTo connect using OAuth 2.0 with a JWT, you must first perform the following:\n\n- [Create and configure a GitHub App](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/dev-ops-github-apps-oath-jwt.md)\n- [Generate the Java KeyStore certificate for GitHub](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/dev-ops-github-apps-oath-jwt.md)\n- [Attach the GitHub Java KeyStore certificate to your instance](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/dev-ops-github-apps-oath-jwt.md)\n After completing the prerequisites, you can continue with the DevOps Change Velocity Connect playbook activity:\n\n1. Select the **Use an existing JWT credential record** option if you want to use an already existing JWT credential record. If this option is not selected, the fields to create a new JWT credential record are displayed. Proceed to the next step.\n2. In the **JKS certificate** field, select an existing JKS certificate. This is the name you entered to uniquely identify the JWT provider. JKS certificates are created using shell commands to create a sys\\_certificate record.\n\nFor more information, see [Create a JWT signing key for the GitHub JKS certificate](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/dev-ops-github-apps-oath-jwt.md).\n\n3. In the **Signing key** field, enter the signing key to be assigned to your JKS certificate. This is the export password entered while [generating the JKS certificate](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/dev-ops-github-apps-oath-jwt.md).\n4. In the **GitHub App ID** field, select the app ID of your GitHub App \\(available in the About section of your GitHub App configuration in GitHub\\). The following image displays an example of the About section of a GitHub App configuration from where you can access the GitHub App ID, Client ID, and Client secret.\n\n\\[Omitted image \"github-jwt-about-screen.png\"\\] Alt text: About page of GitHub App.\n\n5. In the **Client ID** field, select the client ID of your GitHub App \\(available in the About section of your GitHub App configuration in GitHub\\).\n6. In the **Client secret** field, select the client secret of your GitHub App \\(available in the About section of your GitHub App configuration in GitHub\\).\n7. In the **Token URL** field, select the location of the token endpoint that the instance uses to retrieve and refresh tokens.\n\nFor cloud version, enter: `https://api.github.com/app/installations//access_tokens`.\n\nFor enterprise version, enter: `https:///api/v3/app/installations//access_tokens`.\n\nFor the installation id, go to Install App section in your GitHub App configuration in GitHub and select the gear icon to configure your app. The installation id will be in the webpage URL. For example, https://github.com/settings/installations/<installation\\_id>.\n\n\\[Omitted image \"github-oauth-jwt.png\"\\] Alt text: GitHub Oauth 2.0 with JWT credential type.\n\n If the OAuth credential is created using GitHub Apps - JWT, the **Configure with GitHub App** option will be available on the tool record page.\n\n
For more information on OAuth2.0 credentials, see [Setting up GitHub OAuth 2.0 credentials for DevOps Change Velocity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/setting-up-github-oauth-dev-ops.md).\n\n 3. Enter a value in the **GitHub app slug name** field to check the permission requirements of the tool before connecting if you have created your Oauth 2.0 credentials using GitHub Apps.\n\n **Note:** If you are connecting to GitHub Enterprise Server with data residency controls, select your **username + app slug name** in the **GitHub app slug name** field.\n\n You can find the app slug name on the settings page of your app.\n\n 4. If your GitHub instance is attached to a MID Server, select the **MID Server** option and enter its details.\n\n For more information about MID server, see [MID Server selection](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/c_MIDServerSelector.md).\n\n **Note:** The OAuth Authorization Code & JWT grant types are supported for GitHub & GitHub Enterprise with MID server.\n\n 5. Select **Connect**.\n\n \\[Omitted image \"github-plybk-01.png\"\\] Alt text: Connect GitHub to DevOps Change Velocity.\n\n 6. Permission checks are run on the credentials that you entered.\n\n Permissions required and permissions that are available are displayed. If you want to enter credentials with better permissions, select **Re-enter credentials**. For detailed information on all the required permissions, see GitHub permissions in [Permissions required for DevOps tools](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/tool-req-permission.md).\n\n For OAuth 2.0, if you haven’t entered the GitHub app slug name, the tool is connected without checking permission requirements.\n\n 7. Select **Next**.\n\n \\[Omitted image \"github-plybk-05.png\"\\] Alt text: Permission checks\n\n5. Specify the access for the tool.\n\n 1. If you want to control access to the tool, add the groups that must be given access to the tool in the **Maintained by** field.\n\n The tasks these users in the groups can perform depends on the role assigned to them.\n\n - DevOps Tool Owner role: Can view and edit the tool.\n - DevOps App Owner role: Can view the tool and can associate, discover, import historical data, and modify pipeline steps \\(if applicable\\) of the tool's objects \\(such as plans, repositories, and pipelines\\).\n - DevOps Administrator role: Can edit all tools.\n - Other DevOps roles: Can view the tool.\n **Note:** If you don't select a group and skip this step, all users with the DevOps Tool Owner role will be able to edit the tool.\n\n 2. If you choose to control access to the tool, the **All App Owners can view and associate tool objects to applications** option becomes available for selection.\n\n This option enables all users having the DevOps App Owner role to access the tool. If selected, they’ll be able to view, associate, discover, import historical data, and modify pipeline steps \\(if applicable\\) of the tool's objects.\n\n 3. Select **Assign**.\n \\[Omitted image \"github-plybk-06.png\"\\] Alt text: Specify tool access\n\n6. Configure webhooks automatically in your GitHub instance to send data to DevOps Change Velocity.\n\n This action configures the following webhooks:\n\n - **push**: To gather repository commits, branches, and tags\n - **workflow\\_job**: To gather pipeline data\n - **issues**: To gather issues \\(work item\\) data\n **Note:** Completing the configuration as part of this task is recommended as real-time notifications are ideal to maintain current information, particularly for automating change requests. Otherwise, you can set up the webhook by configuring it manually later by enabling nightly polling to fetch data system for any tracked repositories or pipelines by setting the **Enable Polling** property to **Yes**.\n\n Select the repositories for which you want to configure webhooks and select **Configure**.\n\n \\[Omitted image \"github-plybk-02.png\"\\] Alt text: Select repositories to configure from GitHub.\n\n To configure manually, select **Configure manually**. See [Configure webhooks in GitHub manually](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/config-webhooks-github-manually.md) for more information.\n\n **Important:**\n\n - If you're connecting from the Home page or Tools module, the connection is complete and you're taken to the Summary page.\n - If you're connecting from the Applications module, then repositories and pipelines available are discovered. You can track and import historical data from them.\n7. Select the plans to track.\n\n 1. Select the plans for which you want to track updates and associate with the application.\n\n After the tool onboarding is complete, the work items only for these selected plans are automatically imported.\n\n 2. Select **Next**.\n\n \\[Omitted image \"github-issues-plan-playbook.png\"\\] Alt text: Track plans playbook step\n\n8. Select the repositories to track.\n\n 1. Select the repositories for which you want to track updates and associate with the application.\n 2. Select **Next**.\n\n \\[Omitted image \"github-plybk-08.png\"\\] Alt text: Select repositories for tracking.\n\n **Note:** If you want the automatic pipeline discovery \\(scheduled job\\) to process untracked repositories as well, set the **sn\\_devops.discover.tracked\\_repos\\_only** system property to false.\n\n 3. If you want to import repository data, select the date range and select **Submit**.\n\n You can import up to 90 days of data. Workflows associated with the repositories will also be imported.\n\n **Note:** You can't import commits from forked repositories. This limitation exists because the GitHub REST API does not return commit data for forked repositories.\n\n9. Select the pipelines to track.\n\n 1. Select the pipelines for which you want to track updates and associate to the application.\n\n 2. Select **Next**.\n\n 3. For each selected pipeline, all steps or stages are imported for the last successful execution. In the Assign services to pipeline steps activity, you can select the following for each pipeline step:\n 1. **Pipeline step type**: Select a step type for which you want to assign a service.\n\n **Tip:** Specify at least the **Prod deploy** step type for steps that represents the production deployment to enable DevOps to identify successful pipeline executions as production deployments.\n\n 2. **Service**: Select the CMDB application service that the pipeline step maps to.\n\n Application service maps approximately to the environment. If you use the same pipeline step to deploy to different environments, leave the field empty. Service information enables DevOps to identify and report on operational metrics such as incidents, outages, and so on.\n\n 4. Select **Next**.\n\n \\[Omitted image \"github-plybk-03.png\"\\] Alt text: Assign services to pipelines from GitHub.\n\n10. From the **Summary** page, select **View tool record** to review the details of the connected GitHub tool.\n\n \\[Omitted image \"github-plybk-07.png\"\\] Alt text: Connection summary\n\n For GitHub Actions pipelines, you must perform some additional steps like creating secrets, defining the workflow configuration in GitHub, and so on. For more information, see [GitHub Actions configurations](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/github-actions-integration-with-devops.md).\n\n\n## Result\n\nYou’ve successfully onboarded your GitHub tool to DevOps Change Velocity.\n\n## What to do next\n\nYou can manually discover plans after your GitHub tool is onboarded as well. As there is no plan entity in GitHub, the repositories will be considered to discover corresponding plan records in ServiceNow.\n\n1. From the tool record page, select **Discover** to discover plans.\n2. Select **Configure**. Plans are tracked and a webhook called **issues** is created to send real-time notifications for work items.\n\nThe following information is updated for a work item in ServiceNow when the corresponding issue is updated in GitHub.\n\n- Change in issue title\n- Assignees update\n- Transfer issue\n\n **Note:** When an issue is transferred, the same will be marked as transferred in the repository from which it is being transferred and opened in the repository to which it is being transferred.\n\n- Delete issue\n\n **Note:** When an issue is deleted in GitHub, the corresponding work item is not deleted in ServiceNow but the state of the work item will be marked as deleted.\n\n\nIf you are an upgrading customer, plans will be discovered for your repositories through the scheduled job to discover periodically or through manual discovery. After your plans are discovered, you can enable the **sn\\_devops.track.github.issues** property to re-configure all the previously configured repositories at once so that all plans are tracked and the issues webhook is created for work items.\n\n**Note:** Historical import of plans is not supported.\n\n**Parent Topic:**[GitHub integration with DevOps Change Velocity](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/github-integration-dev-ops.md)\n\n**Related topics** \n\n\n[Configure webhooks from the tool record](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/it-service-management/devops-change-velocity/configure-webhooks-from-the-tool-record.md)\n\n"}}