Git Repositories

Overview

The Git Repositories panel enables teams to link external Git repositories to the Shakudo platform, allowing workloads (jobs, microservices, sessions) to access and sync code from version control systems. The panel supports both Primary Cluster and Satellite Cluster deployments, with automatic synchronization monitoring and SSH key management for secure repository access.

Access & Location

• Route: ?panel=git-repositories
• Navigation: Shakudo Objects → Git Repositories
• Access Requirements:
  • Create/Link Repository: Dashboard Admin or Dashboard Maintainer roles
  • Unlink Repository: Dashboard Admin role only
  • View SSH Keys: Dashboard Admin or Dashboard Maintainer roles
• Feature Flags: None

Key Capabilities

Link Git Repository to Primary Cluster

Connect external Git repositories to the Shakudo platform's primary cluster, enabling workloads to access code from your version control system. Each repository is assigned a unique SSH key pair for secure access.

When to use: Link repositories that will be used by jobs, microservices, or sessions running on the primary cluster.

Link Git Repository to Satellite Cluster

Connect external Git repositories to specific Satellite Clusters, allowing distributed deployments to access code independently. Each satellite cluster maintains its own set of repository connections.

When to use: Deploy code to remote Satellite Clusters that need independent Git repository access.

Monitor Repository Sync Status

Track real-time synchronization status of linked repositories, including commit information, sync health, and any errors. The system polls every 5 seconds to provide up-to-date status information.

When to use: Verify that repositories are in sync before running workloads, or troubleshoot synchronization issues.

Manage SSH Keys

View and copy SSH public keys for each repository to add as deploy keys in your Git provider (GitHub, GitLab, Bitbucket, etc.).

When to use: Configure repository access after linking, or retrieve keys when rotating access credentials.

User Interface

Main View

The panel features a tabbed interface with two main sections:

Primary Cluster Tab: Displays all Git repositories linked to the main Shakudo cluster

• Search and filter capabilities across all repository properties
• Real-time sync status updates every 5 seconds
• Quick access to tutorial videos for guidance

Satellite Clusters Tab: Shows Git repositories linked to specific Satellite Clusters

• Cluster selection dropdown to view repositories for a specific satellite
• Independent repository management per satellite cluster
• Same monitoring capabilities as primary cluster

Dialogs & Modals

1. Link Git Repository Dialog (Primary Cluster)

   • Purpose: Connect a new Git repository to the primary cluster
   • Fields:
     • Name: Unique identifier for the repository (alphanumeric, spaces, and special characters: / @ : . _ -)
     • Git Repository SSH URL: SSH URL in Git format (e.g., git@github.com:org/repo.git)
     • Default Branch: Branch name to sync (e.g., main, master, develop)
     • Use Default SSH Key: Optional legacy mode to use a shared SSH key across multiple repositories (not recommended)
   • Actions: Link or Cancel
   • Validation: Name uniqueness check, URL format validation

2. Unlink Git Repository Dialog

   • Purpose: Remove a Git repository connection from the platform
   • Warning: Permanently disconnects the repository; SSH keys should be manually removed from the Git provider
   • Actions: Unlink or Cancel
   • Access: Dashboard Admin only

3. SSH Key Dialog

   • Purpose: Display and copy SSH public key for repository configuration
   • Content: Shows either custom SSH key (recommended) or default SSH key (legacy)
   • Information tooltips explain the difference between custom and default SSH keys
   • Actions: Copy to clipboard, Close

4. Link Git Repository to Satellite Cluster Dialog

   • Purpose: Connect a Git repository to a specific Satellite Cluster
   • Fields: Same as primary cluster link dialog
   • Actions: Link or Cancel

5. Satellite Cluster SSH Key Dialog

   • Purpose: Display SSH public key for satellite cluster repository
   • Content: SSH public key specific to the satellite cluster
   • Actions: Copy to clipboard, Close

6. Tutorial Video Dialog

   • Purpose: Display instructional video for linking Git repositories
   • Content: Video with title and description
   • Actions: Close

Tables & Data Grids

1. Primary Cluster Git Repositories Table

   • Columns:
     • Actions: Unlink button, SSH Key button
     • Name: Repository identifier, with "default" badge if marked as default server
     • Status: Visual indicator (IN_SYNC, BEHIND, BRANCH_NOT_FOUND, REMOTE_NOT_FOUND) with tooltip showing commit details
     • Git Repository URL: Copyable SSH URL
     • Branch: Copyable branch name
     • Last Commit ID: Copyable commit hash
     • Last Commit Date: Formatted timestamp (YYYY-MM-DD HH:mm:ss)
     • ID: Hidden by default, copyable repository ID
   • Actions:
     • Unlink repository (admin only)
     • View/copy SSH key (admin/maintainer)
   • Filtering: Text-based search across all fields (name, URL, branch, commit info)
   • Refresh: Manual refresh button and automatic polling every 5 seconds
   • Pagination: 20 items per page

2. Satellite Cluster Git Repositories Table

   • Columns: Same as Primary Cluster table, plus:
     • Satellite Cluster Name: Displays the selected satellite cluster name
   • Actions: Same as Primary Cluster table
   • Filtering: No search (filtered by selected satellite cluster only)
   • Note: Table only displays when a satellite cluster is selected

Technical Details

GraphQL Operations

Queries:

• GetVcServersDocument - Retrieves all Git repositories for the primary cluster with optional search filtering. Excludes DELETED and DELETING statuses. Polls every 5 seconds.
• GetVcServersByNameDocument - Validates repository name uniqueness during creation
• GetSatelliteGitServersDocument - Retrieves Git repositories for a specific Satellite Cluster. Polls every 5 seconds.
• GetGitStatusDocument - Retrieves Git sync status for default repository monitoring

Mutations:

• CreateVcServerDocument - Creates a new Git repository connection for the primary cluster
  • Parameters: name, url, defaultBranch, useDefaultSSHKey
  • Returns: repository ID, name, URL, branch, SSH key setting, status
• DeleteVcServerDocument - Marks a Git repository for deletion by setting status to DELETING
  • Parameters: repository ID
  • Returns: repository ID
• CreateSatelliteGitServerDocument - Creates a Git repository connection for a Satellite Cluster
  • Parameters: satelliteClusterName, name, url, defaultBranch, useDefaultSSHKey
  • Returns: satellite repository details

Subscriptions:

• None (uses polling for real-time updates)

Component Structure

• Main Component: components/GitRepositories/GitRepositoriesPanel.tsx
• Dialogs:
  • components/GitRepositories/Dialogs/GitRepositoriesLinkDialog.tsx
  • components/GitRepositories/Dialogs/GitRepositoriesUnlinkDialog.tsx
  • components/GitRepositories/Dialogs/GitRepositorySSHKeyDialog.tsx
  • components/GitRepositories/Dialogs/SatelliteCluster/SatelliteGitRepositoriesLinkDialog.tsx
  • components/GitRepositories/Dialogs/SatelliteCluster/SatelliteGitRepositoriesUnlinkDialog.tsx
  • components/GitRepositories/Dialogs/SatelliteCluster/SatelliteGitRepositorySSHKeyDialog.tsx
• Supporting Components:
  • components/GitRepositories/GitRepositoriesStatus.tsx - Git status monitoring
  • components/GitRepositories/GitRepositoriesStatusIcon.tsx - Status visualization
  • components/GitRepositories/GitRepositoriesAutocomplete.tsx - Repository selection

Repository Status States

• IN_SYNC: Repository is synchronized with the remote branch (green check icon)
• BEHIND: Local repository is behind the remote branch (orange warning icon)
• BRANCH_NOT_FOUND: Specified branch doesn't exist in the repository (red error icon)
• REMOTE_NOT_FOUND: Cannot connect to remote repository; SSH key may be missing or invalid (red error icon)
• FAILING/FAILED: Kubernetes resources failed to create (gray disabled icon)

Common Workflows

Link a New Git Repository to Primary Cluster

1. Click "Link Git Repository" button in the top-right corner
2. Enter a unique name for the repository
3. Provide the Git repository SSH URL (format: git@provider.com:org/repo.git)
4. Specify the default branch to sync (e.g., main)
5. Optionally enable "Use default SSH key" (not recommended for security)
6. Click "Link" to create the connection
7. Click the SSH Key icon in the Actions column
8. Copy the SSH public key
9. Add the key as a deploy key in your Git provider's repository settings
10. Wait for the status to change to "IN_SYNC"

Link a Repository to a Satellite Cluster

1. Switch to the "Satellite Clusters" tab
2. Select a Satellite Cluster from the dropdown
3. Click "Link Git Repository To Satellite Cluster" button
4. Follow the same steps as linking to primary cluster (steps 2-10 above)

Troubleshoot Repository Sync Issues

1. Check the Status column for error indicators
2. Hover over the status icon to view detailed error information
3. For "REMOTE_NOT_FOUND" errors:
   • Click the SSH Key icon to view the public key
   • Verify the key is added to your Git provider's repository settings
   • Ensure the repository URL is correct
4. For "BRANCH_NOT_FOUND" errors:
   • Verify the branch name exists in the repository
   • Check for typos in the branch name
5. Use the Refresh button to force an immediate sync check
6. Monitor the Last Commit Date to verify ongoing synchronization

Remove a Git Repository

1. Locate the repository in the table
2. Click the unlink icon (✖) in the Actions column
3. Review the warning message about SSH key cleanup
4. Click "Unlink" to confirm
5. Manually remove the SSH key from your Git provider's repository settings

Related Features

• Immediate Jobs - Jobs can reference Git repositories for code execution
• Scheduled Jobs - Scheduled workloads can sync code from linked repositories
• Microservices - Services can deploy code from linked Git repositories
• Sessions - Development sessions can clone and work with linked repositories
• Satellite Clusters - Remote cluster deployments can link their own repositories
• Environment Configs - Environments specify which repository to use for workload execution

Notes & Tips

SSH Key Management

• Custom SSH Keys (Recommended): Each repository gets a unique SSH key pair, following security best practices. Most Git providers support multiple deploy keys per repository.
• Default SSH Key (Legacy): A single shared SSH key across multiple repositories. Not recommended as GitHub and GitLab restrict this for security reasons. Only use if adding the SSH key to a bot user account with repository read access.

Repository Naming

• Names must be unique across all repositories in the cluster
• Valid characters: letters, numbers, spaces, and special characters (/ @ : . _ -)
• Choose descriptive names that indicate the repository's purpose

Sync Monitoring

• The panel automatically polls for updates every 5 seconds
• Manual refresh is available if immediate status check is needed
• Status tooltips provide detailed commit information and error messages

Performance Considerations

• Large repositories may take longer to perform initial sync
• Network issues between Shakudo and the Git provider can cause REMOTE_NOT_FOUND errors
• Satellite clusters sync independently and may have different sync states than primary cluster

Security Best Practices

• Always use custom SSH keys for each repository
• Remove SSH keys from Git providers when unlinking repositories
• Restrict repository access to read-only (deploy keys) when possible
• Use dedicated service/bot accounts for repository access rather than personal accounts

Default Repository

• A repository marked with the "default" badge is used as the primary code source for the platform
• The default repository's sync status is monitored separately and shown in the platform status interface
• Only one repository can be marked as default at a time