Documentation for getOneRepo

Overview

The node is a component of the Vantage analytics and data platform designed to interface with a GitHub repository. Its purpose is to retrieve details about a specific repository owned by a specified GitHub account. It handles incoming parameters to ensure all necessary data is provided, manages the connection to GitHub's API, and returns repository data in a structured format. Additionally, it incorporates error handling to manage potential integration issues, ensuring robustness in the application.

Inputs

The function accepts three main parameters through the inputs, config, and context objects.

Expected Input Data

• inputs

  • repo (string): The name of the repository to fetch.
  • owner (string): The GitHub account owner of the repository.

• config

  • repo (string, default: 'Hello-World'): The default repository name to use if not provided in inputs.
  • owner (string, default: 'octocat'): The default owner name to use if not provided in inputs.

• context

  • This provides the necessary context for building a connection instance to GitHub, primarily containing authentication tokens or session details.

Settings

1. Repo (Input Setting)

• Name: repo
• Input Type: String
• Description: This setting determines the name of the repository to retrieve. If not specified in the inputs object, it defaults to 'Hello-World'.
• Default Value: 'Hello-World'
• Behavior: Changing this value allows you to pull information for a different repository in GitHub. If the repository does not exist or the name is incorrect, an error will occur.

2. Owner (Input Setting)

• Name: owner
• Input Type: String
• Description: Specifies the GitHub account owner of the repository. This is a required field; if not provided, it will default to 'octocat'.
• Default Value: 'octocat'
• Behavior: Altering this setting changes the user context under which to query the repository. An incorrect owner will lead to a failure to retrieve the desired repository.

How It Works

1. Initialization: The function first extracts the repo and owner values from either the inputs or config objects, employing default values if neither is provided.

2. Integration Establishment: Utilizing the the integration connection function, it establishes a connection with GitHub's API, passing the string 'github' as the identifier and the current context to manage authentication.

3. Validation: It checks whether both inputs.owner and inputs.repo are provided; if either is missing, an error is thrown.

4. API Call: The function subsequently invokes the getRepo method on the integration object to fetch details about the specified repository.

5. Error Handling: If an error occurs during the API call or connection establishment, it captures the error and returns a structured error message.

6. Output Data: On successful retrieval, it returns the repository data encapsulated in an object under the key output1.

Use Cases & Examples

Use Case 1: Project Management

A project management team uses the node to fetch repository details regularly to analyze pull requests and issue tracking related to active development projects. The default values ensure that they can run standard reports without needing to change configurations constantly.

Use Case 2: DevOps Monitoring

An organization wants to monitor specific repositories for changes over time. By integrating getOneRepo into their data monitoring application, they can pull details about the repository (like commit history and contributors) and visualize these changes over time.

Example Configuration

Use Case Integration for Project Management:

Assuming a scenario where the project management team wants to analyze the "backend" repository owned by "my_org", the configuration would be as follows:

{
  "inputs": {
    "repo": "backend",
    "owner": "my_org"
  },
  "config": {
    "repo": "Hello-World",
    "owner": "octocat"
  },
  "context": {
    "authToken": "your_github_token"
  }
}

In this example:

• The repository "backend" under "my_org" will be queried.
• If the owner or repository is incorrect, it will throw an error indicating the requirements are not met, while fallback values for the default will not be invoked since the necessary fields are provided in inputs.