› System › Additional settings › GitHub › Repository › Configure GitHub integration

Configure GitHub integration

You can configure your machine to connect to GitHub.

GitHub integration is not supported within TotalAgility Apps.

Prerequisites

The following are the prerequisites for configuring GitHub integration.

  1. Sign up for GitHub.

  2. Create a GitHub App

Create a GitHub App

Create a GitHub App to generate and use the OAuth tokens to identify the users. An OAuth access token can authenticate as a user of your GitHub App (also called user-to-server requests). For example, you can use an OAuth access token to authenticate as a user when a GitHub App needs to verify a user’s identity or act on a user’s behalf.

TotalAgility does not support GitHub’s OAuth App, as you cannot generate the refresh tokens in the OAuth App for authenticating as a user which is mandatory when configuring the OAuth server in TotalAgility.

The same applies to personal access tokens; they also do not support refresh tokens.

By default, GitHub Apps do not have any permissions to access end-user data. When you create a GitHub App, you must add the required permissions. You can grant read and write permissions for each type under the following groups: Repository permissions, Organization permissions, and User permissions.

The following are the minimum repository permissions required for the GitHub integration to access the repository.

Permission

Access type

Contents: Repository content, commits, branches, downloads, releases, and merges.

Read and write

Pull requests: Pull requests and related comments, assignees, labels, milestones, and merges.

Read and write

Commit statuses: Commit statuses

Read and write

Configure GitHub integration for the current user in TotalAgility

Once the GitHub app is created, you can configure your machine to connect to the GitHub server which is holding or will hold the TotalAgility solution.

Use the GitHub App's client ID and client secret to configure the OAuth server in TotalAgility and then authorize yourself for GitHub access by getting the authorization code.

Configure the OAuth server for TotalAgility

Configure the OAuth server using the GitHub URL, access token URL, client ID, and client secret generated when creating the GitHub App.

Use the GitHub App's client ID and client secret to configure the OAuth server in TotalAgility and then authorize yourself for GitHub access by getting the authorization code.

  1. Navigate to Integration > OAuth 2.0 servers and click New.
  2. Enter a unique Name for the OAuth 2.0 server.
  3. By default, the system automatically saves a new OAuth server in your working category. To store it in a different category, select a category.
  4. Select the Grant type as Authorization code.
  5. Select the Authentication method.
  6. Enter the Client ID and the Client secret.
  7. To get an access token, enter the Access token URL as https://github.com/login/oauth/access_token.
  8. Enter the Authorization code URL as https://github.com/login/oauth/authorize.
  9. Select Use custom redirect URI and enter the redirect URI in the box as http://<KTAServer>/TotalAgility/Designer/OAuth2_Authorization.html.

    The custom redirect URI in TotalAgility should match the callback URL configured in GitHub. For more information on "Redirect URI" and "Use custom redirect URI", see Configure OAuth 2.0 server using Authorization code grant type.

  10. By default, the check box for Supports refresh token is selected and read-only which means you need an OAuth refresh token each time to communicate with GitHub.
  11. Click Authorize.

    You are prompted to sign into GitHub.

  12. Sign into GitHub using the username or email address, and password.

    You are redirected to the authorized application.

  13. Copy the URL from the browser tab, paste it into the Authorization code box in the New OAuth 2.0 server configuration dialog box, and click Authorize.
  14. Click Save.

    The OAuth server is configured.

Specify the GitHub repository and authorize access

  1. Navigate to System > System settings > GitHub and click Repository.

    The GitHub repository dialog box is displayed.

  2. Enter the GitHub repository URL.
  3. Optional. Specify the Branch of the GitHub repository. If the branch is not specified, the default branch gets cloned.

    The GitHub repository is cloned on the app server. Currently, Windows does not allow paths more than 260 characters long.

  4. On the OAuth server list, select the preconfigured OAuth server that is configured for the GitHub server and click Save.

    You need an OAuth token to communicate with GitHub for the current user. When you modify the OAuth server details, access tokens are cleared. You must re-authorize the access tokens.

  5. To test the GiHub connection, click Test connection.

    The Authorize dialog box is displayed. When you log on to the TotalAgility Designer as the resource configured for the GitHub access, and if the "Custom redirect URI" is specified when configuring the OAuth server, you are prompted to authorize yourself for GitHub access or to proceed without GitHub functionality.

    To authorize yourself for GitHub access, do the following:

    1. Click the Get authorization code link. The authorization server redirects to the custom redirect URI with which the authorization server is configured.

    2. Copy the entire URL the authorization server has redirected to and paste it into the Authorization code field.

    3. Click Authorize.

    4. Ensure a valid refresh token is acquired from the authorization server to establish connectivity and click Save.

    To proceed without GitHub functionality, click Cancel.

    When additional users launch TotalAgility Designer, they are asked to authorize themselves for GitHub access on login.

  6. To delete the connection to the GitHub source control, click Delete in the Authorize dialog box.

    On confirmation, the connection is deleted.