Skip to main content

signaloid-cli github connect

Create or update GitHub integration.

Synopsis​

signaloid-cli github connect --username <ghUser> --token <pat> [options]

Description​

Creates or updates the GitHub integration for your Signaloid account. This connects your GitHub account to Signaloid, enabling repository access and automated builds.

Options​

OptionDescription
--username <ghUser>GitHub username (required)
--token <pat>GitHub Personal Access Token (required)
--user-id <id>User ID (defaults to current user, requires admin for others)

Personal Access Token Requirements​

Your GitHub PAT must have the following scopes:

  • repo - Full control of private repositories
  • read:org - Read org membership (if using organization repos)

Output​

Returns the integration details:

{
  "UserID": "user-abc123",
  "GithubUsername": "myusername",
  "Connected": true,
  "ConnectedAt": "2025-01-20T10:30:00Z",
  "Message": "GitHub connected/updated"
}

Examples​

Connect GitHub Account​

signaloid-cli github connect \
  --username myusername \
  --token ghp_abc123xyz789...

Update Existing Integration​

# Update with new token (e.g., after rotation)
signaloid-cli github connect \
  --username myusername \
  --token ghp_newtoken123...

Connect with Validation​

#!/bin/bash

GH_USER="$1"
GH_TOKEN="$2"

if [ -z "$GH_USER" ] || [ -z "$GH_TOKEN" ]; then
  echo "Usage: $0 <github-username> <github-token>"
  exit 1
fi

# Connect
echo "Connecting GitHub account: $GH_USER"
if ! signaloid-cli github connect \
  --username "$GH_USER" \
  --token "$GH_TOKEN"; then
  echo "Failed to connect GitHub"
  exit 1
fi

# Validate by listing repos
echo "Validating connection..."
REPOS=$(signaloid-cli github repos 2>&1)

if [ $? -eq 0 ]; then
  REPO_COUNT=$(echo $REPOS | jq '. | length')
  echo "Success! Found $REPO_COUNT accessible repositories"
else
  echo "Warning: Connected but unable to list repositories"
  echo "Check token permissions"
  exit 1
fi

Exit Codes​

CodeDescription
0Success
1Failed to connect/update GitHub (invalid credentials, API error)

Security Best Practices​

Never Hardcode Tokens​

# ❌ Bad - token in script
signaloid-cli github connect --username user --token ghp_abc123...

# ✅ Good - token from environment
signaloid-cli github connect --username user --token "$GITHUB_TOKEN"

# ✅ Good - token from secure file
TOKEN=$(cat ~/.secrets/github-token)
signaloid-cli github connect --username user --token "$TOKEN"

Token Validation​

Before connecting, validate the token has required scopes:

# Check token scopes using GitHub API
curl -H "Authorization: token $GITHUB_TOKEN" \
  https://api.github.com/user | jq '.login, .scopes'

Troubleshooting​

Invalid Token​

Error: Failed to connect GitHub - invalid credentials

Solution: Verify the token is correct and has not expired. Generate a new token if needed.

Insufficient Permissions​

Warning: Connected but unable to access repositories

Solution: Ensure the token has repo and read:org scopes.

See Also​

Last updated on