GitHub integration

To configure the GitHub integration, do the following:

Sign up for GitHub.
Create GitHub App

OAuth only Apps and personal access token does not work as they do not support refresh tokens.
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 GitHub integration for the current user in TotalAgility.

Create 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 only App as you cannot generate the refresh tokens in OAuth App for authenticating as a user which is mandatory when configuring OAuth server in TotalAgility.

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

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

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.

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

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 into GitHub.
10. Sign into 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 it into 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 an OAuth refresh token each time to communicate with GitHub.
13. Click Save.
  
  The OAuth server is configured.
Navigate to System > System settings > GitHub and click Repository.

The GitHub repository dialog box is displayed.
Enter the GitHub repository URL.
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.
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.
To test the GitHub connection, in the GitHub card, click Repository.

The GitHub repository dialog box is displayed.
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.
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 it into 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 login.
To delete the connection to the GitHub source control, click Delete in the Authorize dialog box.

On confirmation, the connection is deleted.