Skip to content

Git Connections Guide

Connect GitHub repositories to your SkillMeat projects to automatically scan for Claude artifacts. A single git connection can be linked to multiple projects, and you manage all connections from a central location.

Overview

Git connections are the bridge between your GitHub repositories and SkillMeat projects. Each connection represents a specific GitHub repository and branch that you want to scan. Connections are:

  • Persistent: Exist independently of projects and persist across your workspace
  • Reusable: A single connection can be linked to multiple projects
  • Scannable: Each connection can be triggered to scan for Claude artifacts (skills, commands, agents, MCP servers, hooks)
  • Flexible: Configured with branch selection and token authentication

Why Use Git Connections?

Git connections enable you to:

  • Automatically discover Claude artifacts in your GitHub repositories
  • Keep projects synchronized with upstream sources
  • Manage multiple repositories from a single interface
  • Control token authentication at the connection level for enterprise scenarios

Managing Git Connections

Viewing All Connections

Navigate to the Git Connections page (usually available in the navigation menu or Settings) to see all connections in your workspace.

The Git Connections page displays:

  • Repository URL - The GitHub repository address
  • Branch - The currently configured branch for scanning
  • Linked Projects - Count of projects using this connection
  • Last Scanned - When the artifact scan was last run
  • Actions - Buttons to edit, unlink, or delete the connection

Filtering Connections

Use the filter controls at the top of the page to narrow your view:

Filter Purpose Details
By Project Show connections linked to a specific project Useful when managing connections for one project at a time
By Team (Enterprise) Show connections scoped to a specific team Available in multi-tenant deployments
Unlinked Show connections not yet linked to any project Helps identify unused connections

Creating a New Connection

  1. Click the Add Connection or Plus button at the top of the Git Connections page
  2. In the dialog, enter:
  3. Repository URL - Full GitHub URL (e.g., https://github.com/username/repo)
  4. Branch - The branch to scan (defaults to main or master)
  5. Click Create

The connection is now available and can be linked to projects.

Editing a Connection

  1. Click the connection row or the edit button
  2. Update the repository URL or branch as needed
  3. Click Save

Deleting a Connection

  1. Click the delete button on the connection row
  2. Confirm the deletion

Important: Deleting a connection removes it from all linked projects. Projects that depend on the connection will no longer be able to scan that repository.

Linking Connections to Projects

Git connections are useful only when linked to projects. The Git Sources tab on your project detail page shows all connections linked to that project.

Viewing Linked Connections

  1. Open a project in SkillMeat
  2. Navigate to the Git Sources tab
  3. You'll see all connections currently linked to the project in either:
  4. Card view - Visual cards showing repository, branch, and scan status
  5. Table view - A table with all connection details

Linking an Existing Connection

  1. Open a project and go to the Git Sources tab
  2. Click Link Connection or the Plus button
  3. A dialog appears with available git connections
  4. Select the connection you want to link
  5. Click Link

The connection is now linked to the project and can be scanned.

Creating and Linking a Connection Inline

If you want to create a new connection directly from the Git Sources tab:

  1. Click Create New Connection button in the Git Sources tab
  2. Enter the repository URL and branch
  3. Click Create and Link

The connection is created and automatically linked to the current project in one step.

Unlinking a Connection

  1. Open a project and go to the Git Sources tab
  2. Find the connection you want to unlink
  3. Click the unlink button or three-dot menu and select Unlink

Important: Unlinking removes the connection from the project but does NOT delete the connection. It remains available to link to other projects.

Git Connections in Project Workflows

Adding Connections During Project Creation

When creating a new project, you have the option to add git connections at setup time:

  1. In the project creation form, look for a Git Sources section (usually an expandable accordion)
  2. Click Add Git Connection
  3. Either:
  4. Select an existing connection from the list, or
  5. Create a new connection inline
  6. Complete the project creation

The project is created with the selected git connections already linked.

Managing Connections in Project Settings

Some projects allow you to manage linked connections in the project settings:

  1. Open the project settings
  2. Navigate to the Git Sources or Connections section
  3. View, link, or unlink connections as needed
  4. Save any changes

Scanning for Artifacts

Once a git connection is linked to a project, you can trigger a scan to discover Claude artifacts in the repository.

Triggering a Scan

  1. Open a project and navigate to the Git Sources tab
  2. Find the connection you want to scan
  3. Click the Scan button or refresh icon
  4. The scan begins (this may take a few moments depending on repository size)

Scan Results

After the scan completes, SkillMeat displays:

  • Scan Status - Success, in progress, or error status
  • Artifacts Found - Count of discovered artifacts
  • Last Scanned - Timestamp of the most recent scan
  • Artifact List - Discovered skills, commands, agents, MCP servers, and hooks

You can then import these artifacts into your collection if desired.

Scan Configuration

Advanced scan options may include:

Option Purpose
Branch Override Temporarily scan a different branch than the connection's default
Artifact Type Filters Scan for specific artifact types (e.g., only skills, only commands)
Depth Limit Limit how deep the scanner searches in the repository structure

Token Management

SkillMeat uses a layered token fallback chain to authenticate with GitHub. This allows flexible credential management across single and multi-team deployments.

Token Fallback Chain

When scanning a git connection, SkillMeat tries tokens in this order:

  1. Per-Connection Token - A token specific to this git connection (if configured)
  2. Personal Developer Token - Your personal GitHub PAT saved in your account
  3. Organization/Team Token - A shared token for your org or team (enterprise only)
  4. Global GitHub Token - The default token configured in Settings → GitHub Authentication
  5. Unauthenticated Fallback - Public GitHub API (60 requests per hour)

The first available token in this chain is used for authentication.

Setting a Per-Connection Token (Enterprise)

In enterprise deployments, you can set a token specific to a git connection:

  1. Click the connection to edit it
  2. Look for Token Settings or Authentication
  3. Enter your GitHub PAT (Personal Access Token)
  4. Click Save

This token will be used whenever this connection is scanned, overriding tokens further down the fallback chain.

Security: Tokens are encrypted at rest and never displayed in plain text after being saved.

Personal Developer Token

Users can store their own GitHub PAT in their account for private repository access:

  1. Navigate to Settings → GitHub Authentication
  2. Enter your GitHub Personal Access Token
  3. Click Save or Set Token

Your token is now available for all scans in your projects.

Global GitHub Token

The global token in Settings → GitHub Authentication applies to all users and connections when no more specific token is available:

  1. Navigate to Settings → GitHub Authentication
  2. Enter a GitHub PAT with appropriate permissions
  3. Click Save or Set Token

This token is used as the fallback when personal or connection-specific tokens are not configured.

Why Multiple Token Levels?

Different token levels serve different use cases:

Level Best For
Per-Connection Restricted access to specific repositories (GitHub App tokens)
Personal Developer User's private repositories and organizations
Organization/Team Shared, read-only access for team members (enterprise)
Global Default fallback for all users

Local vs Enterprise Differences

SkillMeat provides different capabilities depending on your edition.

Local Edition

The local edition is designed for single-user development:

  • Single Global Token: One GitHub token shared across all connections (from Settings)
  • Default Project: One implicit project context
  • No Team Filtering: Connections are not scoped to teams
  • No Per-Connection Tokens: All connections use the global token

Setup: Configure your GitHub token in Settings → GitHub Authentication, and it applies to all git connections in your workspace.

Enterprise Edition

The enterprise edition supports multi-tenant deployments with advanced token management:

  • Layered Token Fallback: Full token hierarchy (per-connection → personal → team → global → public)
  • Token Management Panel: Dedicated UI for managing credentials at different scopes
  • Team-Based Filtering: Filter connections by team and organization
  • Per-Connection Tokens: Set unique tokens for each connection
  • Personal Developer Tokens: Each user can store their own PAT
  • Team/Org Tokens: Shared tokens managed at the organization level

Token Management (Enterprise Only):

  1. Navigate to Settings → Token Management
  2. View your current tokens at different scopes:
  3. Your personal tokens
  4. Organization/team tokens
  5. Connection-specific tokens
  6. Add, update, or revoke tokens as needed

Enterprise Workflow:

If you're in an enterprise deployment:

  1. An administrator may set an organization token (one token for everyone)
  2. You can add a personal token for your private repositories
  3. For sensitive repositories, your team lead can set a per-connection token

The most specific token (connection-specific) takes precedence when available.

Best Practices

Organizing Connections

  • One connection per repository: Create separate connections for each repository you want to scan
  • Use meaningful branch names: Always specify the correct branch (usually main or master)
  • Link strategically: Link connections only to projects that use them to keep the interface clean

Token Security

  • Limit PAT scopes: When creating a GitHub PAT, request only the minimum scopes needed (usually just repo read access)
  • Rotate tokens regularly: Change your tokens periodically for better security
  • Use team tokens for shared access: In enterprise, prefer organization/team tokens over personal tokens for shared repositories
  • Per-connection tokens for restricted access: Use GitHub App installation tokens or restricted PATs for sensitive repositories

Artifact Discovery

  • Scan periodically: Set a schedule to scan connections regularly to stay current with upstream changes
  • Review scan results: Check that discovered artifacts are expected before importing them
  • Use filters during scanning: If scanning large repositories, use artifact type filters to focus on what you need

Project Management

  • Consolidate related connections: Group related git connections in a single project
  • Archive unused connections: Delete connections no longer in use to keep your workspace clean
  • Document connection purposes: Add notes to project settings explaining why each git connection is linked

Troubleshooting

"Authentication failed" Error

Problem: Scans are failing with authentication errors.

Solutions: 1. Verify your GitHub token has the repo scope for private repositories 2. Check that your token hasn't expired (personal PATs have optional expiration dates) 3. Try a higher-priority token: - Add a personal token in Settings → GitHub Authentication - Or contact your team lead for an organization token (enterprise) 4. Ensure the repository is accessible with your token by testing on GitHub directly

"Repository not found" Error

Problem: The scanner can't find the repository.

Solutions: 1. Verify the repository URL is correct (including the GitHub domain) 2. If it's a private repository, confirm you have access and a valid token is configured 3. Check that the branch name matches (e.g., main vs master) 4. Ensure the repository still exists and hasn't been deleted

Scan Hangs or Times Out

Problem: Scans are slow or timing out.

Solutions: 1. Large repositories: Use artifact type filters to scan only specific types 2. Network issues: Check your internet connection 3. GitHub rate limiting: If scanning many times in quick succession, you may hit rate limits. Wait a few minutes before retrying. 4. Too many artifacts: If scanning discovers thousands of artifacts, the import process may be slow. Consider scanning only the specific parts of the repository you need.

Problem: A git connection won't link to a project.

Solutions: 1. Verify the connection exists (it should appear in the Git Connections list) 2. Confirm you have permission to modify the project 3. Check that the project hasn't reached a connection limit (if applicable) 4. Try refreshing the page and attempting again

Token Issues in Enterprise

Problem: "Per-connection token not available" or similar message.

Solutions: 1. Verify the git_credentials_enabled feature flag is enabled (check with your administrator) 2. Confirm your role allows token management (may be restricted to admins) 3. Contact your enterprise administrator to set organization or team tokens if personal tokens aren't sufficient