TriLuna Try it free

github_tool_client_setup

GitHub Tool Configuration Guide for SAS Clients

This guide explains how to configure your tri-LUNA agent to use GitHub integration with your own GitHub access token.

Table of Contents

  1. Overview
  2. Prerequisites
  3. Step 1: Create a GitHub Personal Access Token
  4. Step 2: Configure Your Agent
  5. Step 3: Test the Integration
  6. Available GitHub Actions
  7. Troubleshooting
  8. Security Best Practices

Overview

The GitHub tool allows your tri-LUNA agent to interact with your GitHub repositories, enabling:

  • Issue management (create, update, list, assign)
  • Comment on issues and pull requests
  • Review recent commits
  • Track project progress
  • Manage sprints and milestones

Your agent uses a webhook-based integration that connects to GitHub’s API using a personal access token you provide.

Prerequisites

Before you begin, ensure you have:

  • A GitHub account with access to the repository you want to integrate
  • Admin access to your tri-LUNA dashboard
  • Permission to create personal access tokens in your GitHub organization (if using an organization repository)

Step 1: Create a GitHub Personal Access Token

1.1 Access GitHub Token Settings

  1. Log in to GitHub
  2. Click your profile picture in the top-right corner
  3. Select Settings
  4. Scroll down in the left sidebar and click Developer settings
  5. Click Personal access tokens → Tokens (classic)
  6. Click Generate new token → Generate new token (classic)

Note: If your organization uses fine-grained tokens, you can use those instead. The classic token instructions are provided for broader compatibility.

1.2 Configure Token Permissions

Give your token a descriptive name, such as:

tri-LUNA Agent - [Agent Name] - GitHub Integration

Required Scopes (check these boxes):

For Public and Private Repositories:

  • repo (Full control of private repositories)
    • This includes: repo:status, repo_deployment, public_repo, repo:invite, security_events
  • read:org (Read org and team membership) - if using organization repositories
  • read:user (Read user profile data) - for accurate attribution

Expiration: Choose an expiration period based on your security policy:

  • 30 days: Most secure, requires regular renewal
  • 60 days: Balanced security and convenience
  • 90 days: Less frequent renewal
  • No expiration: Not recommended for production use

1.3 Generate and Save the Token

  1. Click Generate token at the bottom of the page
  2. IMPORTANT: Copy your token immediately - GitHub will only show it once
  3. Save it securely in your password manager or secure notes

Your token will look like:

ghp_AbCdEfGhIjKlMnOpQrStUvWxYz1234567890

Step 2: Configure Your Agent

You have two options to configure your agent with the GitHub token:

  1. Log in to your tri-LUNA dashboard at https://triluna.app
  2. Navigate to Agents
  3. Select the agent you want to configure
  4. Go to the Integrations tab
  5. Find GitHub Tool and click Configure
  6. Enter the following information:
    • GitHub Token: Paste your personal access token
    • Repository: Enter your repository in the format owner/repo (e.g., mycompany/myproject)
    • Default Branch: Usually main or master
  7. Click Save Configuration
  8. The system will validate your token and repository access

Option B: Contact Support

If you don’t have direct access to the integrations panel:

  1. Email your administrator at support@triluna.app
  2. Include:
    • Your agent name or agent ID
    • Your GitHub repository (format: owner/repo)
    • Your encrypted token (use the encryption tool at https://triluna.app/tools/encrypt)
  3. Support will configure your agent within 1 business day

Step 3: Test the Integration

3.1 Test via Agent Conversation

  1. Start a conversation with your agent (via phone, widget, or dashboard)
  2. Ask: “What GitHub issues are currently open?”
  3. Your agent should respond with a list of issues from your repository

3.2 Expected Response

Your agent will say something like:

I found 5 open issues in your repository:
1. Issue #42: Fix login authentication bug
2. Issue #38: Add dark mode support
3. Issue #35: Update documentation
...

3.3 If Something Goes Wrong

If your agent responds with an error message like:

  • “MCP Access to GitHub is offline at this time” - Your token may not be configured correctly
  • “Authentication failed” - Your token may be invalid or expired
  • “Repository not found” - Check the repository name format

See Troubleshooting below for detailed solutions.

Available GitHub Actions

Once configured, your agent can perform these actions:

1. List Issues

Ask: “Show me all open issues” or “List closed issues”

  • Lists all issues with their status, labels, and creation date
  • Can filter by open or closed state

2. Get Issue Details

Ask: “What’s the status of issue #25?”

  • Provides full details of a specific issue
  • Shows description, comments, assignees, and labels

3. Create New Issues

Ask: “Create a new issue for implementing user authentication”

  • Creates an issue with your description
  • Returns the new issue number and URL

4. Update Issues

Ask: “Close issue #30” or “Update the title of issue #25 to ‘Fix critical bug’”

  • Can update issue state (open/closed)
  • Can modify title and description

5. Assign Issues

Ask: “Assign issue #25 to edmiidz”

  • Assigns issues to team members
  • Supports multiple assignees

6. Add Comments

Ask: “Add a comment to issue #30 saying ‘Implementation completed’”

  • Adds comments to issues
  • Useful for status updates

7. List Recent Commits

Ask: “What commits were made today?” or “Show me recent changes”

  • Lists commits from the last 24 hours
  • Shows commit message, author, and timestamp

8. Pull Request Operations

Ask: “What comments are on PR #15?” or “Show me reviews for PR #12”

  • List PR comments and review feedback
  • Get PR details including merge status

Troubleshooting

Problem: “MCP Access to GitHub is offline”

Cause: Your agent doesn’t have a GitHub token configured.

Solution:

  1. Verify your token was saved correctly in the dashboard
  2. Check that the repository format is owner/repo (not a URL)
  3. Contact support if the configuration panel shows the token as saved

Problem: “Authentication failed” or “Bad credentials”

Cause: Your GitHub token is invalid, expired, or doesn’t have the required permissions.

Solution:

  1. Generate a new token following Step 1
  2. Ensure you selected the repo scope
  3. Update your agent configuration with the new token

Problem: “Repository not found” or “404 Not Found”

Cause: The repository name is incorrect or your token doesn’t have access.

Solution:

  1. Verify the repository exists and you have access
  2. Check the format is owner/repo (e.g., microsoft/vscode, not https://github.com/microsoft/vscode)
  3. For private repositories, ensure your token has the repo scope
  4. For organization repositories, verify your token has access to that org

Problem: Rate Limiting

Cause: GitHub API has usage limits (5,000 requests per hour for authenticated users).

Solution:

  • Wait for the rate limit to reset (shown in error message)
  • Contact support if you consistently hit rate limits
  • Consider upgrading to GitHub Enterprise for higher limits

Problem: Agent doesn’t recognize GitHub commands

Cause: The GitHub tool may not be enabled on your agent.

Solution:

  1. Verify the tool is configured in the dashboard under Integrations
  2. Try rephrasing your request: “Use GitHub to list all issues”
  3. Contact support to verify the tool is properly installed

Security Best Practices

Token Management

  1. Use Fine-Grained Tokens (if available)

    • Provide repository-specific access
    • Can be scoped to specific permissions
    • More secure than classic tokens

  2. Set Token Expiration

    • Use 30-60 day expiration for production
    • Set calendar reminders to renew before expiration
    • Automate renewal notifications

  3. Rotate Tokens Regularly

    • Generate new tokens quarterly or when team members leave
    • Revoke old tokens immediately after replacing

  4. Use Separate Tokens per Agent

    • Don’t share tokens across multiple agents
    • Makes it easier to track usage and revoke access
    • Provides better audit trails

Access Control

  1. Minimum Required Permissions

    • Only grant repo scope if the agent needs full repository access
    • Use public_repo for public repositories only
    • Avoid granting admin scopes unless absolutely necessary

  2. Repository Restrictions

    • Use fine-grained tokens to restrict access to specific repositories
    • Don’t grant organization-wide access if only one repo is needed

  3. Monitor Token Usage

    • Regularly review GitHub’s token usage logs
    • Watch for unexpected API calls
    • Set up alerts for suspicious activity

Compliance

  1. Document Token Creation

    • Maintain a record of which tokens are assigned to which agents
    • Document the purpose and scope of each token
    • Keep track of expiration dates

  2. Audit Trail

    • GitHub logs all API activity by token
    • Review audit logs regularly
    • Your tri-LUNA platform also logs all GitHub operations

  3. Secure Storage

    • Never commit tokens to version control
    • Don’t share tokens via email or chat
    • Use your organization’s secret management system if available

Advanced Configuration

Using GitHub Enterprise

If your organization uses GitHub Enterprise:

  1. Contact tri-LUNA support with your GitHub Enterprise API URL
  2. Provide your enterprise-issued personal access token
  3. Support will configure the custom API endpoint for your agent

Multi-Repository Access

To give your agent access to multiple repositories:

  1. Configure a primary repository in the agent settings
  2. When asking the agent to perform actions, specify the repository:
    • “List issues in mycompany/project-a”
    • “Create an issue in mycompany/project-b”

Custom Workflows

You can train your agent to handle custom GitHub workflows:

  1. Contact support to discuss your specific workflow needs
  2. Provide examples of the types of interactions you want
  3. Support can add custom system prompts to guide the agent’s behavior

FAQ

Q: Can I use the same token for multiple agents? A: While technically possible, we recommend using separate tokens for better security and audit trails.

Q: What happens if my token expires? A: Your agent will return an authentication error. Generate a new token and update the configuration.

Q: Can my agent create pull requests? A: Currently, the tool focuses on issue management. PR creation is on the roadmap. Contact support for updates.

Q: Is my GitHub token stored securely? A: Yes, tokens are encrypted at rest and in transit. Only your agent can use the token for GitHub API calls.

Q: Can I revoke access at any time? A: Yes, revoke the token in GitHub settings, and your agent will immediately lose access.

Q: Does this work with GitHub Projects? A: Basic project integration is supported. Advanced project features are in development.

Support

Need help? Contact us:

When contacting support, include:

  • Your agent ID or name
  • The error message you’re seeing
  • Steps you’ve already tried

Changelog

Version 1.0 (October 2025)

  • Initial release
  • Support for basic issue management
  • PR comment and review listing
  • Commit history tracking

Last Updated: October 11, 2025 Document Version: 1.0 Maintained by: TriLuna Development Team