Skip to content

Support git-native transport for install sources (any Git host, not just GitHub) #1241

@wfscot

Description

@wfscot

Problem

The install command currently requires the GitHub API to resolve refs and fetch skill files from remote sources. This means it only works with GitHub-hosted repositories (GitLab is recognized by the source parser but throws at runtime).

For teams using Azure DevOps, Bitbucket, self-hosted Gitea, or any other Git host, install simply doesn't work. This is unfortunate because the declarative source + lockfile model is well designed and would be valuable regardless of where the repo is hosted.

Proposal

Add a git-native transport option that uses standard git CLI operations instead of the GitHub API. All the needed operations have git-native equivalents:

Current (GitHub API) Git-native equivalent
Resolve ref to SHA git ls-remote <url> <ref>
List files in directory git clone --depth 1 --sparse or git archive --remote
Fetch file contents Read from shallow clone

This would work with any Git remote as long as the user has git auth configured (SSH keys, credential helpers, etc.), which they almost certainly do if they're already working with the repo.

Suggested configuration

Add an optional transport field to SourceEntry:

{
  "sources": [
    // Default: uses GitHub API (current behavior, unchanged)
    { "source": "owner/repo" },

    // Git-native: works with any git remote
    { "source": "https://dev.azure.com/org/project/_git/repo", "transport": "git" },

    // Also works with SSH URLs
    { "source": "git@ssh.dev.azure.com:v3/org/project/repo", "transport": "git" }
  ]
}

The transport field would accept:

  • "github" (default for github.com URLs, current behavior)
  • "git" (git-native, works with any host)

When transport is omitted, the current behavior is preserved -- GitHub URLs use the GitHub API, just as they do today.

Implementation sketch

The git-native transport would:

  1. Resolve refs: git ls-remote <url> <ref> to get the commit SHA (same data as the current GitHub API call)
  2. Fetch skills: Shallow clone into a temp directory with git clone --depth 1 --branch <ref> --sparse <url> <tmpdir>, then sparse-checkout the skills path
  3. Read files: Copy skill directories from the temp clone into .rulesync/skills/.curated/
  4. Compute integrity: Same SHA-256 hashing as today
  5. Clean up: Remove the temp directory

The lockfile format wouldn't need to change -- it already stores commit SHAs and integrity hashes, which are transport-agnostic.

Benefits

  • Works with any Git host (Azure DevOps, Bitbucket, GitLab, self-hosted, etc.)
  • Uses existing git authentication -- no separate token configuration
  • No platform-specific API dependencies
  • Lockfile format is unchanged
  • Fully backward-compatible (existing GitHub sources continue to work as-is)

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions