GitHub Integration for Vantage

Overview

The GitHub Integration for Vantage provides capabilities to connect and interact with GitHub repositories and their workflows. This integration allows users to fetch repository details, manage issues, and monitor workflow runs. Its primary purpose is to simplify the access and manipulation of GitHub data from within the Vantage platform, enabling data analytics and performance tracking.

Settings

The GitHub Integration provides a number of settings that control its behavior and interactions with GitHub's API. Each setting is detailed below:

Authentication Token

1. Name: token
2. Input Type: String
3. Description: This setting is used to authenticate requests to the GitHub API. Changing this value affects access to GitHub resources based on the permissions associated with the new token.
4. Default Value: No default value; the token must be set during integration setup.

Pagination Limits

1. Name: perPage
2. Input Type: Numeric
3. Description: This setting specifies the number of records to be returned per page in API calls for listing repositories, issues, or workflow runs. Adjusting this value can improve performance or allow more results to be returned in a single request.
4. Default Value: 30

Page Number

1. Name: page
2. Input Type: Numeric
3. Description: This setting controls the specific page of results to retrieve from the GitHub API. Changing this value will retrieve different slices of results based on pagination.
4. Default Value: 1

Repository Visibility

1. Name: visibility
2. Input Type: Dropdown
3. Description: Controls whether to retrieve all repositories or filter them by public or private visibility. Modifying this setting determines what kinds of repositories can be accessed.
4. Default Value: RepoVisibility.ALL

Workflow Event Type

1. Name: event
2. Input Type: Dropdown
3. Description: Specifies the type of event that triggers the workflow runs to be fetched (e.g., push, pull_request). Changing this value influences which workflows are returned.
4. Default Value: None (this must be set for calls to getWorkflowRuns)

Workflow Run Status

1. Name: status
2. Input Type: Dropdown
3. Description: Defines the status of the workflow runs to retrieve (e.g., queued, in_progress, completed). Changes here determine which runs are filtered and returned.
4. Default Value: None (this must be set for calls to getWorkflowRuns)

Workflow Run Conclusion

1. Name: conclusion
2. Input Type: Dropdown
3. Description: Indicates the conclusion status of the workflow runs to filter (e.g., success, failure). Adjusting this setting will refine the data returned based on the final state of execution.
4. Default Value: None (this must be set for calls to getWorkflowRuns)

How It Works

The GitHub Integration interacts with the GitHub API using the provided authentication token to make authorized requests. It has methods for fetching user repositories, organization repositories, issues, and workflow runs. The integration validates required scopes based on the actions being performed, ensuring permissions are correctly handled.

1. Authorization: The authorization token is embedded in API requests, allowing access based on the defined scopes.
2. Data Fetching: Users can query repositories, issues, and workflow statuses based on customizable parameters such as visibility, pagination, and states.
3. Error Handling: The integration includes mechanisms to check for missing parameters and scope validation, providing informative error messages.

Data Expectations

The GitHub Integration expects data inputs to be correctly formatted based on the API specifications:

• Authorization Token: Must be a valid GitHub personal access token with appropriate scopes.
• Pagination Parameters: Numeric values for perPage and page, with perPage being capped by GitHub's API limits.
• Event and Status Strings: Must match the defined enumeration values as per GitHub's API standards.

Use Cases & Examples

Use Cases

1. Monitoring Repository Issues: A development team can use the integration to automatically fetch and analyze open issues across multiple repositories, facilitating issue tracking and resolution prioritization.
2. Workflow Automation: DevOps teams can track workflow runs across various repositories to ensure that build and deployment processes are functioning as expected, allowing for quick identification of failures or delays.
3. Custom Reporting: Teams can extract repository metrics like the number of commits or the state of pull requests for reporting and analytics, supporting strategic business decisions.

Example Configuration

Use Case: Monitor Repository Issues for a Development Team

Configuration Data

{
    "token": "ghp_YOUR_ACCESS_TOKEN_HERE",
    "perPage": 50,
    "page": 1,
    "visibility": "private"
}

Explanation: The configuration allows the integration to authenticate with a personal access token, fetch up to 50 issues from private repositories, starting from the first page of results. This enables the team to efficiently analyze a large volume of issues and take actions accordingly.

Conclusion

The GitHub Integration for Vantage is a powerful tool that enables users to interact with their GitHub repositories comprehensively. With robust settings, configurable options, and a clear methodology for retrieving data, organizations can leverage their GitHub data directly within the Vantage platform for enhanced analytics and performance tracking capabilities.