ELITEA Toolkit Guide: GitHub Integration

Introduction

Purpose of this Guide

This guide is your definitive resource for integrating and utilizing the GitHub toolkit within ELITEA. It provides a comprehensive, step-by-step walkthrough, from generating a GitHub Personal Access Token to configuring the toolkit in ELITEA and effectively using it within your Agents. By following this guide, you will unlock the power of automated code management, streamlined development workflows, and enhanced team collaboration, all directly within the ELITEA platform. This integration empowers you to leverage AI-driven automation to optimize your software development lifecycle using the combined strengths of ELITEA and GitHub.

Brief Overview of GitHub

GitHub is the world's leading web-based platform for version control, collaboration, and software development. It is built around Git and provides a rich ecosystem for developers to host, manage, and collaborate on code. GitHub is essential for modern software development, offering features for:

Integrating GitHub with ELITEA brings these powerful development capabilities directly into your AI-driven workflows. Your ELITEA Agents can then interact with your GitHub repositories to automate code-related tasks, enhance development processes, and improve team collaboration through intelligent automation, making your development workflows smarter and more efficient.

Toolkit's Account Setup and Configuration in GitHub

Account Setup

If you don't already have a GitHub account, follow these steps to create one:

  1. Visit GitHub Website: Open your web browser and go to github.com.
  2. Sign Up: Click on the "Sign up" button, located in the top right corner of the homepage.
  3. Enter Details: Follow the on-screen instructions to create your account. You will need to choose a username, provide your email address, and create a strong password.
  4. Verify Email: Check your inbox for a verification email from GitHub. Click the verification link in the email to activate your account.
  5. Log In: Once your email is verified, log in to GitHub using your newly created username and password.

Token/API Key Generation: Creating a Personal Access Token (Classic) in GitHub

For secure integration with ELITEA, it is essential to use a GitHub Personal Access Token (Classic). This method is significantly more secure than using your primary GitHub account password directly and allows you to precisely control the permissions granted to ELITEA.

Follow these steps to generate a Personal Access Token (Classic) in GitHub:

  1. Log in to GitHub: Access your GitHub account at github.com.
  2. Access Settings: Click on your profile avatar in the top right corner and then click on "Settings".
  3. Navigate to Developer Settings: In the left-hand sidebar, scroll down and click on "Developer settings".
  4. Access Personal Access Tokens (Classic): In the left-hand sidebar under "Personal access tokens," click on "Tokens (classic)".
  5. Generate New Token: Click the "Generate new token (classic)" button.
    • Note: If you have previously created tokens, you might see a "Generate new token" button instead.

  6. Provide Token Details:

    • Note (Description): In the "Note" field, enter a descriptive label for your token, such as "ELITEA Integration" or "ELITEA Agent Access." This will help you easily identify the purpose of this token in the future.
    • Expiration (Recommended): For enhanced security, it is highly recommended to set an Expiration date for your token. Choose a reasonable validity period to limit the token's lifespan. If compromised, a token with a shorter lifespan poses less risk.

    • Select Scopes - Grant Least Privilege (Crucial for Security): Carefully and deliberately select the scopes or permissions you grant to this token. It is paramount to grant only the absolute minimum necessary permissions required for your ELITEA Agent's intended interactions with GitHub. Overly permissive tokens pose a significant security risk. For typical ELITEA integration, consider these minimal scopes:

      • Minimal Scopes for Common Use Cases:

        • repo (For full access to private and public repositories. If possible, select more granular repo scopes instead of full repo):
          • repo:status (Access commit statuses)
          • public_repo (Access public repositories)
        • workflow (Access GitHub Actions workflows if your Agent needs to interact with workflows)
        • read:user (To read user profile information, often needed for basic interactions)

      • Additional Scopes for Specific Functionality (Grant only if needed):

        • issues (To access and manage issues)
        • pull_request (To access and manage pull requests)
        • gist (To access gists, if your Agent needs to work with gists)
        • read:org (To read organization membership and information, if your Agent needs organization-level access)

    Important Security Practices:

    • Principle of Least Privilege: Strictly adhere to the principle of least privilege. Grant only the scopes that are absolutely essential for your ELITEA Agent to perform its intended tasks.
    • Avoid "admin" or Broad Scopes: Never grant "admin" or overly broad permissions unless absolutely necessary and with a clear understanding of the security implications. Broad scopes significantly increase the potential security impact if the token is compromised.
    • Regular Token Review and Rotation: Regularly review the tokens you have generated and their associated scopes. Rotate tokens periodically (generate new ones and revoke old ones) as a security best practice, especially for sensitive integrations.

  7. Generate Token: Click the "Generate token" button at the bottom of the page.

  8. Securely Copy and Store the Personal Access Token: Immediately copy the generated token that is displayed on the next page. This is the only time you will be able to see and copy the full token value. Store it securely using a robust password manager or, preferably, ELITEA's built-in Secrets feature for enhanced security within the ELITEA platform. You will need this token to configure the GitHub toolkit in ELITEA.

GitHub-Generate_Token GitHub-Generate_Token2 GitHub-Generate_Token3 GitHub-Generate_Token4

GitHub Integration with ELITEA

Agent Creation/Configuration

To integrate GitHub, you'll need to configure it within an ELITEA Agent. You can integrate GitHub with a new Agent or modify an existing one.

  1. Navigate to Agents Menu: In ELITEA, go to the Agents menu.
  2. Create or Edit Agent:
    • New Agent: Click "+ Agent" to create a new Agent. Follow the steps to define Agent details such as name, description, type, and instructions.
    • Existing Agent: Select the Agent you wish to integrate with GitHub and click on its name to edit its configuration.
  3. Access Toolkits Section: Within the Agent configuration, scroll down to the "Tools" section.

Toolkit Configuration

This section details how to configure the GitHub toolkit within your ELITEA Agent.

  1. Add Toolkit: In the "Tools" section, click the "+" icon.
  2. Select GitHub Toolkit: From the dropdown list of available toolkits, choose "GitHub". This will open the "New GitHub tool" configuration section.

  3. Configure GitHub Toolkit Settings: Fill in the following configuration fields in the "New GitHub tool" section:

    • Name: Enter a descriptive Name for your GitHub toolkit instance. This name will be used to reference the toolkit within your Agent's instructions (e.g., "MyGitHubRepo", "CodeRepoAccess"). Choose a name that clearly indicates its purpose.
    • Description: Provide a concise Description of the toolkit's purpose or the specific GitHub repository it will access (e.g., "Access to the main development code repository").
    • URL: This field is pre-filled with the standard GitHub API URL: https://api.github.com. In the vast majority of cases, you should not modify this URL. Only change it if you are connecting to a self-hosted GitHub Enterprise Server instance, in which case you should enter the specific API URL for your Enterprise Server.
    • Repository: Enter the Repository name that you want to access with this toolkit. Use the format: repository_owner/repository_name (e.g., MyOrganization/my-project-repo). Ensure you use the correct owner/organization and repository name.
    • Main branch: Specify the Main branch of your repository. This is typically main or master.
    • Authentication Options - Token: Select the "Token" authentication option.
      • Password/Secret: Choose "Password" and then paste the Personal Access Token (Classic) you generated in GitHub (during the "Software-Specific Setup" section of this guide) into the "Password" field.
      • Enhanced Security with Secrets (Recommended): For significantly enhanced security, it is strongly recommended to use the "Secret" option. Select "Secret" and then choose a pre-configured secret from the dropdown list. You must first securely store your Personal Access Token as a Secret within ELITEA's Secrets Management feature. Using Secrets is a critical security best practice that prevents hardcoding sensitive credentials directly in the toolkit configuration, reducing the risk of exposure.

    GitHub-Toolkit_Configuration.png

  4. Enable Desired Tools: In the "Tools" section within the GitHub toolkit configuration, carefully select the checkboxes next to only the specific GitHub tools that your Agent will actually need to use. Enable only the tools that are absolutely necessary to adhere to the principle of least privilege and minimize potential security risks. Available tools include:

    • Get issues - Retrieves a list of issues.
    • Get issue - Retrieves details of a specific issue.
    • Search issues - Searches for issues based on provided criteria.
    • Create issue - Creates a new issue.
    • Update issue - Updates an existing issue.
    • Comment on issue - Adds a comment to an issue.
    • List open pull requests (PRs) - Lists open pull requests.
    • Get pull request - Retrieves details of a specific pull request.
    • List pull request files - Lists files changed in a pull request.
    • Create pull request - Creates a new pull request.
    • Create file - Creates a new file.
    • Read file - Reads the content of a file.
    • Update file - Updates the content of an existing file.
    • Delete file - Deletes a file.
    • List files in branch - Lists files in a branch.
    • List branches in repo - Lists branches in the repository.
    • Set active branch - Sets the active branch.
    • Create branch - Creates a new branch.
    • Get files from directory - Retrieves files from a directory.

  5. Complete Setup: Click the arrow icon (usually located at the top right of the toolkit configuration section) to finalize the GitHub toolkit setup and return to the main Agent configuration menu.

  6. Click Save in the Agent configuration to save all changes.

Tool Overview

Once the GitHub toolkit is configured and added to your Agent, you can utilize the following tools within your Agent's instructions to enable interaction with your GitHub repositories:

Instructions and Prompts for Using the GitHub Toolkit

To effectively instruct your ELITEA Agent to use the GitHub toolkit, you need to provide clear and precise instructions within the Agent's "Instructions" field. These instructions are crucial for guiding the Agent on when and how to utilize the available GitHub tools to achieve your desired automation goals.

Instruction Creation for OpenAI Agents

When crafting instructions for the GitHub toolkit, especially for OpenAI-based Agents, clarity and precision are paramount. Break down complex tasks into a sequence of simple, actionable steps. Explicitly define all parameters required for each tool and guide the Agent on how to obtain or determine the values for these parameters. OpenAI Agents respond best to instructions that are:

When instructing your Agent to use a GitHub toolkit tool, adhere to this structured pattern:

1. **State the Goal:** Begin by clearly stating the objective you want to achieve with this step. For example, "Goal: To retrieve the content of the 'README.md' file."
2. **Specify the Tool:** Clearly indicate the specific GitHub tool to be used for this step. For example, "Tool: Use the 'read_file' tool."
3. **Define Parameters:** Provide a detailed list of all parameters required by the selected tool. For each parameter:
    - Parameter Name: `<Parameter Name as defined in tool documentation>`
    - Value or Source: `<Specify the value or how to obtain the value. Examples: "user input", "from previous step", "hardcoded value 'main'", "value of variable X">`
4. **Describe Expected Outcome (Optional but Recommended):** Briefly describe the expected result or outcome after the tool is successfully executed. For example, "Outcome: The Agent will provide the content of the 'README.md' file."

Example Agent Instructions for GitHub Toolkit Tools (Optimized for OpenAI Agents):

1. Goal: Update the 'config.json' file in the 'settings' branch with new configuration values provided by the user.
2. Tool: Use the "update_file" tool.
3. Parameters:
    - Repository Name: "Specify the repository name in 'owner/repo' format. Use the repository configured in the GitHub toolkit."
    - File Path: "config.json"
    - Branch Name: "settings"
    - New Content: "Ask the user for the new JSON configuration content. Ensure it is valid JSON format. Example: {\"setting\": \"new_value\"}"
4. Outcome: The 'config.json' file in the 'settings' branch will be updated with the user-provided JSON configuration. Confirm the update to the user.

1. Goal: Create a new feature branch for implementing user authentication, named 'feature-user-auth', branching from the 'develop' branch.
2. Tool: Use the "create_branch" tool.
3. Parameters:
    - Repository Name: "Specify the repository name in 'owner/repo' format. Use the repository configured in the GitHub toolkit."
    - New Branch Name: "feature-user-auth"
    - Base Branch: "develop"
4. Outcome: A new branch named 'feature-user-auth' will be created in the repository, based on the 'develop' branch. Inform the user that the branch has been created.

1. Goal: Provide the user with a list of all branches in the repository to help them understand the project's branch structure.
2. Tool: Use the "list_branches_in_repo" tool.
3. Parameters:
    - Repository Name: "Specify the repository name in 'owner/repo' format. Use the repository configured in the GitHub toolkit."
4. Outcome: Present the list of branches to the user in a clear and readable format.

1. Goal: Retrieve the content of the 'README.md' file from the 'main' branch to provide the user with a project overview.
2. Tool: Use the "read_file" tool.
3. Parameters:
    - Repository Name: "Specify the repository name in 'owner/repo' format. Use the repository configured in the GitHub toolkit."
    - File Path: "README.md"
    - Branch Name: "main"
4. Outcome: Display the content of the 'README.md' file to the user.

Conversation Starters

Utilize these conversation starters to initiate interactions with your GitHub-integrated Agent. These are useful for both testing the integration and for common usage scenarios.

1. For Testing and Troubleshooting Connection & Configuration:

These conversation starters are specifically designed to verify if the GitHub toolkit is correctly configured, authenticated, and successfully connected to your GitHub repository. They test basic functionalities to ensure the integration is working as expected.

2. For General Agent Usage Scenarios & Workflow Initiation:

These conversation starters demonstrate how to initiate agent execution for common, practical GitHub-related tasks and workflows. They represent typical user requests and showcase the agent's ability to perform useful actions within GitHub.

These conversation starters offer a solid foundation for interacting with your GitHub-integrated ELITEA Agent. They can be further customized and expanded upon to precisely match your specific use cases, workflows, and the unique automation needs of your software development projects.

Use Cases

The GitHub toolkit unlocks numerous automation possibilities for software development workflows within ELITEA. Here are key use cases, demonstrating how each tool can be applied, formatted to match the Bitbucket guide style:

Troubleshooting and Support

Troubleshooting

FAQ

  1. Q: Can I use my regular GitHub password directly for the ELITEA integration instead of a Personal Access Token?

    • A: No, using a GitHub Personal Access Token (Classic) is mandatory and strongly recommended for security. Direct password authentication is not supported for ELITEA's GitHub toolkit integration. Personal Access Tokens provide a significantly more secure and controlled method for granting access to external applications like ELITEA, without exposing your primary account credentials.

  2. Q: What scopes/permissions are absolutely necessary and minimally sufficient for the GitHub Personal Access Token to work with ELITEA?

    • A: The minimum required scopes depend on the specific GitHub tools your ELITEA Agent will be using. For basic read-only access to repositories (e.g., using read_file, list_files_in_branch), the repo:status and public_repo scopes might suffice. However, for most common integration scenarios involving modifications (e.g., create_file, update_file, create_pull_request), you will need the broader repo scope or more granular repo write scopes. For issue and pull request management, include issues and pull_request scopes respectively. Always adhere to the principle of least privilege and grant only the scopes that are strictly necessary for your Agent's intended functionalities. Refer to the GitHub documentation for detailed scope descriptions.

  3. Q: What is the correct format for specifying the GitHub Repository name in the ELITEA toolkit configuration?

    • A: The GitHub Repository name must be entered in the format repository_owner/repository_name (e.g., MyOrganization/my-project-repo). Ensure you include both the repository owner's username or organization name and the repository name, separated by a forward slash /. This format is crucial for ELITEA to correctly identify and access your repository on GitHub.

  4. Q: Why am I consistently encountering "Permission Denied" errors, even though I believe I have configured everything correctly and granted the necessary permissions?

    • A: If you are still facing "Permission Denied" errors despite careful configuration, systematically re-examine the following:
      • Token Scope Accuracy: Double and triple-check the scopes/permissions granted to your GitHub Personal Access Token in your GitHub Developer Settings. Ensure that the token possesses the exact scopes required for each GitHub tool your Agent is attempting to use. Pay close attention to write vs. read permissions.
      • Repository Access Verification: Explicitly verify that the GitHub account associated with the Personal Access Token has the necessary access rights to the specific target repository within GitHub itself. Confirm repository membership, collaborator status, and assigned roles/permissions within the GitHub repository settings.
      • Token Validity and Revocation: Double-check that the Personal Access Token is still valid, has not expired, and has not been accidentally revoked in your GitHub settings. Generate a new token as a test if unsure.
      • Typographical Errors: Carefully review all configuration fields in ELITEA, especially the Repository name, Username (though less relevant for token auth), and the Token itself for any hidden typographical errors or accidental whitespace.

If, after meticulously checking all of these points, you still encounter "Permission Denied" errors, please reach out to ELITEA Support with detailed information for further assistance.

Support and Contact Information

If you encounter any persistent issues, have further questions, or require additional assistance beyond the scope of this guide regarding the GitHub integration or ELITEA Agents in general, please do not hesitate to contact our dedicated ELITEA Support Team. We are committed to providing timely and effective support to ensure you have a seamless and productive experience with ELITEA.

How to Reach ELITEA Support:

Best Practices for Submitting Effective Support Requests:

To enable our support team to understand and resolve your issue as efficiently as possible, please include the following critical information in your support email:

Pre-Support Request Actions (Self-Help):

Before contacting support, we strongly encourage you to first thoroughly explore the resources available within this comprehensive guide and the broader ELITEA documentation. You may find readily available answers to common questions, solutions to known issues, or configuration guidance within these resources, potentially resolving your issue more quickly.

To further enhance your understanding and skills in integrating GitHub with ELITEA, here are some helpful resources: