Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

GitHub Deploy Keys Setup

Overview

Primary distribution method: EQ Synapse is distributed as Debian packages (.deb) via APT repository (see SEP-002).

When deploy keys are needed:

  • Development gateways - Testing unreleased code directly from repository
  • Early adopters/beta testers - Before package is available in APT repository
  • Custom builds - Sites requiring modifications not in standard packages
  • CI/CD systems - Automated builds and testing

Production deployments should use the APT repository for updates, not git clones.

What Are Deploy Keys?

Deploy keys provide repository-specific SSH access, allowing servers to pull (or push) to a single GitHub repository without using personal account credentials.

Benefits:

  • Repository-scoped access (not account-wide)
  • No password authentication (SSH key-based)
  • Can be revoked independently per device
  • Read-only or read-write permissions

Use case for EQ Synapse:

  • Clone syntropy repository on development gateways
  • Pull latest changes during development cycles
  • Build from source for testing or customization

Generate the Key Pair

On the gateway device (or development machine):

# Generate Ed25519 key pair (modern, secure algorithm)
ssh-keygen -t ed25519 -C "syntropy@$(hostname)" -f ~/.ssh/deploy_key_syntropy

Parameters:

  • -t ed25519 - Use Ed25519 algorithm (preferred over RSA for better security/performance)
  • -C "syntropy@$(hostname)" - Comment to identify the key (e.g., syntropy@EQG-0001)
  • -f ~/.ssh/deploy_key_syntropy - Output file path

Passphrase:

  • For automated deployments/CI: Press Enter for no passphrase
  • For manual development use: Set a passphrase for added security

Output:

Generating public/private ed25519 key pair.
Enter passphrase (empty for no passphrase): [press Enter]
Enter same passphrase again: [press Enter]
Your identification has been saved in /home/synapse/.ssh/deploy_key_syntropy
Your public key has been saved in /home/synapse/.ssh/deploy_key_syntropy.pub

Add the Public Key to GitHub

1. Copy the Public Key

cat ~/.ssh/deploy_key_syntropy.pub

Example output:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIAbCdEfGhIjKlMnOpQrStUvWxYz syntropy@EQG-0001

2. Add to GitHub Repository

  1. Navigate to: https://github.com/edge-energy/streem/settings/keys
  2. Click Add deploy key
  3. Fill in:
    • Title: Descriptive name (e.g., EQG-0001-dev or RPi-build-server)
    • Key: Paste the entire public key
    • Allow write access: Check only if push capability is needed (usually not for gateways)
  4. Click Add key

Security note: Each deploy key can only be associated with one repository (GitHub enforces this). If you need access to multiple repositories, create separate keys.

Configure SSH

Create or edit ~/.ssh/config to use the deploy key automatically:

# Create SSH config if it doesn't exist
mkdir -p ~/.ssh
chmod 700 ~/.ssh
touch ~/.ssh/config
chmod 600 ~/.ssh/config

Add this configuration:

Host github-syntropy
    HostName github.com
    User git
    IdentityFile ~/.ssh/deploy_key_syntropy
    IdentitiesOnly yes
    StrictHostKeyChecking accept-new

Configuration breakdown:

  • Host github-syntropy - Alias for this connection (used in git URLs)
  • HostName github.com - Actual GitHub server
  • User git - GitHub’s SSH user (always git)
  • IdentityFile - Path to your private key
  • IdentitiesOnly yes - Only use this key (don’t try other keys)
  • StrictHostKeyChecking accept-new - Auto-accept GitHub’s host key on first connection

Clone the Repository

For New Clones

# Clone using the SSH config alias
git clone git@github-syntropy:edge-energy/streem.git syntropy

# Navigate into the repository
cd syntropy

Important: Use the host alias (github-syntropy) from your SSH config, not github.com.

First Connection Prompt

On first connection, SSH will prompt you to verify GitHub’s host fingerprint:

The authenticity of host 'github.com (140.82.116.4)' can't be established.
ED25519 key fingerprint is SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

Verify the fingerprint against GitHub’s published SSH key fingerprints:

  • ED25519: SHA256:+DiY3wvvV6TuJJhbpZisF/zLDA0zPMSvHdkr4UvCOqU

Type yes to add GitHub to your known hosts and proceed.

Update an Existing Clone

If the repository is already cloned with HTTPS or a different SSH URL:

# Change remote URL to use deploy key
git remote set-url origin git@github-syntropy:edge-energy/streem.git

# Verify the change
git remote -v

Example output:

origin  git@github-syntropy:edge-energy/streem.git (fetch)
origin  git@github-syntropy:edge-energy/streem.git (push)

Testing the Connection

Verify SSH access to GitHub:

ssh -T git@github-syntropy

Expected output:

Hi edge-energy/streem! You've successfully authenticated, but GitHub does not provide shell access.

If you see this message, the deploy key is working correctly.

Common Operations

Pull Latest Changes

cd /path/to/syntropy
git pull origin main  # or your branch name

Switch Branches

# List available branches
git branch -a

# Switch to a branch
git checkout dev-pipeline-transport-v3.3.0

# Pull latest for current branch
git pull

Build from Source

After cloning/pulling, build the project:

# Build Rust components
cd server
cargo build --release

# Build Python package
cd ../synapse
uv build

# Build Sight frontend
cd ../sight
npm install
npm run build

For detailed build instructions, see BUILDING.md.

Security Best Practices

Key Management

  1. Unique keys per device - Don’t reuse deploy keys across multiple gateways
  2. Descriptive titles - Use device hostname in GitHub deploy key title
  3. Rotate keys periodically - Regenerate keys annually or when devices are decommissioned
  4. Revoke unused keys - Remove deploy keys from GitHub when device is retired

File Permissions

Ensure correct permissions on SSH files:

chmod 700 ~/.ssh                          # Directory: read/write/execute for owner only
chmod 600 ~/.ssh/config                   # Config: read/write for owner only
chmod 600 ~/.ssh/deploy_key_syntropy      # Private key: read/write for owner only
chmod 644 ~/.ssh/deploy_key_syntropy.pub  # Public key: readable by all (not sensitive)

Critical: Never share or commit private keys. Only the .pub (public) key should be uploaded to GitHub.

Read-Only vs. Write Access

  • Development gateways: Read-only is sufficient (no push capability needed)
  • CI/CD systems: May need write access for automated commits (tags, version bumps)
  • Production gateways: Should never have deploy keys (use APT packages instead)

Troubleshooting

Permission Denied (publickey)

Error:

git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.

Solutions:

  1. Verify SSH config alias is correct: cat ~/.ssh/config
  2. Test SSH connection: ssh -T git@github-syntropy
  3. Check key is loaded: ssh-add -l
  4. Verify public key is added to GitHub deploy keys
  5. Ensure private key has correct permissions: chmod 600 ~/.ssh/deploy_key_syntropy

Wrong Repository or Host

Error:

ERROR: Repository not found.
fatal: Could not read from remote repository.

Solutions:

  1. Verify repository name: edge-energy/streem (not Energy-Quotient/syntropy)
  2. Check remote URL: git remote -v
  3. Ensure deploy key is added to the correct repository
  4. Confirm SSH config HostName is github.com

SSH Agent Not Finding Key

If using an SSH agent and key isn’t auto-loading:

# Add key to agent
ssh-add ~/.ssh/deploy_key_syntropy

# Verify it's loaded
ssh-add -l

To load automatically on login, add to ~/.bashrc or ~/.profile:

# Auto-start SSH agent and load deploy key
if [ -z "$SSH_AUTH_SOCK" ]; then
  eval $(ssh-agent -s)
  ssh-add ~/.ssh/deploy_key_syntropy 2>/dev/null
fi

Host Key Verification Failed

Error:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@    WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED!     @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@

Cause: GitHub’s host key changed (rare, but verify on GitHub’s security page) or man-in-the-middle attack.

Solution (if legitimate change):

# Remove old host key
ssh-keygen -R github.com

# Reconnect and verify new fingerprint
ssh -T git@github-syntropy

Migration to APT Repository

Long-term recommendation: Migrate development gateways to use APT repository once packages are available.

Migration steps:

  1. Add EQ APT repository (see SEP-002)
  2. Install eq-gateway package via apt
  3. Remove git clone and build infrastructure
  4. Keep deploy key only for custom/experimental builds

When to keep deploy keys:

  • Active development on unreleased features
  • Testing experimental branches
  • Custom patches not yet upstreamed

Multiple Repositories

If you need access to multiple Edge Energy repositories, create separate keys:

# Syntropy repository
ssh-keygen -t ed25519 -C "syntropy@$(hostname)" -f ~/.ssh/deploy_key_syntropy

# Another repository (example)
ssh-keygen -t ed25519 -C "other-repo@$(hostname)" -f ~/.ssh/deploy_key_other

Add separate SSH config entries:

Host github-syntropy
    HostName github.com
    User git
    IdentityFile ~/.ssh/deploy_key_syntropy
    IdentitiesOnly yes

Host github-other
    HostName github.com
    User git
    IdentityFile ~/.ssh/deploy_key_other
    IdentitiesOnly yes

Clone using the appropriate alias:

git clone git@github-syntropy:edge-energy/streem.git
git clone git@github-other:edge-energy/other-repo.git

References

Internal Documentation

External Resources

For questions or issues with deploy key setup:

  • Kevin Davies - kdavies@eq.systems

© 2026 EQ Systems Inc.