› System › System settings › GitHub › GitHub integration

GitHub integration

To configure the GitHub integration, do the following:

  1. Sign up for GitHub.

  2. Create GitHub App

    OAuth only Apps and personal access token does not work as they do not support refresh tokens.

  3. 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.

  4. Configure GitHub integration for the current user in TotalAgility.

Create GitHub App

Create 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 only App as you cannot generate the refresh tokens in OAuth App for authenticating as a user which is TotalAgility mandatory when configuring OAuth server in TotalAgility.
  1. Sign up for GitHub.
  2. In the GitHub page, click Create Repository.

    The Repository holds all the project files including the version history.

  3. Enter the Repository name and Description for the repository.
  4. To restrict who can access the repository and commit changes to this repository, select Public or Private.
  5. Click Create repository.

    The code page appears with Username and repository name.

  6. Copy the GitHub URL displayed in the box: https://github.com/<GitHubusername>/<Repositoryname>.

    Use this URL when configuring OAuth server in TotalAgility.

  7. To create GitHub Apps, in the top-right hand corner of the page, click the user account settings and then click Settings.
  8. Under Account settings, click Developer settings.
  9. In the Developer settings page, click New GitHub App.

    The Register new GitHub App page opens.

  10. Enter a name for the App in the GitHub App name box.
  11. Enter the Homepage URL as https://www.red-gate.com/simple-talk/.
  12. Set the Callback URL to http://localhost.
  13. To get a refresh token which can be used to request an updated token when the current token expires, keep the check box selected for Expire user authorization tokens.
  14. To identify and authorize the installing user for GitHub Apps, select the check box for Request user authorization (OAuth) during installation.
  15. You can set the Webhook URL to your company name or a random URL such as https://www.google.com.
  16. By default, GitHub Apps do not have any permissions. When you create a GitHub App, you can select the permissions it needs to access end user data. Permissions can also be added and removed. Grant the read-only, no access or read and write permissions for each permission type under the following groups, as needed: Repository permissions, Organization permissions and User permissions.
  17. Select where the GitHub App be installed:

    • Only this account (default): Allows GitHub app installation on the current user account.

    • Any account: Allows GitHub app installation by any user or organization.

  18. Click Create GitHub App.

    The GitHub App is created. The following details are displayed on the General tab.

    • Owned by: <GitHubusername>

    • App ID: For example, 143993.

    • Client ID: For example, Iv1.ff4abd15364d7d07

      This Client ID is used in configuring the OAuth server in TotalAgility.

  19. Copy the Public link URL from the box and save the URL.
  20. To generate a client secret to authenticate as the application to the API, click Generate a new client secret.

    The client secret key is generated. For example, 1ecd8837dc9dc3927321c8058f60bc3ab6c65f47

    Make sure to copy the client secret and save it as you cannot view it again. You can generate a new one if needed. This client secret is used in configuring the OAuth server in TotalAgility.
  21. Click Save changes.
  22. Navigate to Settings > Developer settings > GitHub Apps.

    The <GitHubusername> page opens.

  23. Click Install App.

    The GitHub App is installed for your repository.

Configure GitHub integration for the current user in TotalAgility

You can configure your machine to connect to the GitHub server which is holding or will hold the TotalAgility solution.

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

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

      You are prompted to sign in to GitHub.

    10. Sign in to GitHub using the username or email address, and password.

      You are redirected to the authorized application.

    11. Copy the URL from the browser tab and paste in the Authorization code box in the New OAuth 2.0 server configuration dialog box and click Authorize.
    12. By default, the check box for Supports refresh token is selected and read-only which means you need OAuth refresh token each time to communicate with GitHub.
    13. Click Save.

      The OAuth server is configured.

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

    The GitHub repository dialog box is displayed.

  3. Enter the GitHub repository URL.
  4. 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 path more than 260 characters long.

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

    You need 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.

  6. To test the GitHub connection, in the GitHub card, click Repository.

    The GitHub repository dialog box is displayed.

  7. Click Test connection.

    The Authorize dialog box is displayed. When you logon to the TotalAgility Designer as the resource who 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.

  8. In the Authorize dialog box, do either of the following:

    • Click the Get authorization code link.

      The authorization server redirects to the custom redirect URI which the authorization server is configured with. Copy the entire URL the authorization server has redirected to and paste in the Authorization code field. Click the Authorize to authorize the resource to GitHub access. Ensure a valid refresh token is acquired from the authorization server to establish connectivity and click Save.

      The connection details are saved.

    • Click Cancel to proceed without GitHub functionality.

    When additional users launch TotalAgility Designer, they will be asked to authorize themselves for GitHub access on logon.

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

    On confirmation, the connection is deleted.