Skip to content

Deploy keys provide repository-specific SSH access. Use them for CI/CD, automated deployments, and agent authentication.

What are Deploy Keys? ​

Deploy keys are SSH keys that:

  • Grant access to a single repository
  • Can be read-only or read-write
  • Don't require a user account
  • Are perfect for automation

Creating Deploy Keys ​

Generate Key ​

bash
ssh-keygen -t ed25519 -C "deploy@ci" -f deploy_key
# No passphrase (for automation)

Add to Repository ​

  1. Copy public key:

    bash
    cat deploy_key.pub
  2. Go to Settings → Deploy Keys

  3. Click New Deploy Key

  4. Paste public key

  5. Add title (e.g., "Production Server")

  6. Select permissions:

    • ☑️ Read access (pull/clone)
    • ☐ Write access (push)
  7. Click Add

Via API ​

bash
curl -X POST /api/v1/repos/org/repo/keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "CI Server",
    "key": "ssh-ed25519 AAAAC3NzaC... deploy@ci",
    "read_only": true
  }'

Using Deploy Keys ​

In CI/CD ​

yaml
# .kizuna/workflows/deploy.yml
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Setup SSH
        run: |
          mkdir -p ~/.ssh
          echo "$DEPLOY_KEY" > ~/.ssh/deploy_key
          chmod 600 ~/.ssh/deploy_key
          echo "Host deploy\n  HostName kizuna.example.com\n  User git\n  IdentityFile ~/.ssh/deploy_key" > ~/.ssh/config
      
      - name: Deploy
        run: |
          git clone deploy:org/repo.git
          # ... deployment steps

For Agents ​

Agents can use deploy keys:

  1. Generate key pair for agent
  2. Add public key as deploy key
  3. Provide private key to agent securely
  4. Agent uses key for Git operations

On Servers ​

For production deployments:

bash
# On server
mkdir -p ~/.ssh
chmod 700 ~/.ssh

# Add deploy key
cat > ~/.ssh/id_ed25519 <> EOF
-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----
EOF
chmod 600 ~/.ssh/id_ed25519

# Add to known hosts
ssh-keyscan kizuna.example.com >> ~/.ssh/known_hosts

# Clone
git clone git@kizuna.example.com:org/repo.git

Read-Only vs Read-Write ​

Read-Only ​

  • Clone/pull only
  • Safe for CI that only needs to build
  • Can be used by multiple systems

Read-Write ​

  • Can push
  • Use for deployment systems
  • More powerful, use sparingly

Managing Deploy Keys ​

List Keys ​

bash
curl /api/v1/repos/org/repo/keys

Delete Key ​

bash
curl -X DELETE /api/v1/repos/org/repo/keys/123

Rotate Keys ​

  1. Generate new key pair
  2. Add new public key to repository
  3. Update systems to use new private key
  4. Remove old key

Best Practices ​

  1. Use read-only when possible — Safer default
  2. One key per purpose — Don't reuse keys
  3. Rotate regularly — Change every 6 months
  4. No passphrases — For automation keys
  5. Secure storage — Protect private keys
  6. Audit usage — Review which keys are active

Comparison: Deploy Keys vs SSH Keys ​

AspectDeploy KeysUser SSH Keys
ScopeSingle repositoryAll accessible repos
AccountNo user accountRequires user account
PermissionsRead-only or RWUser's permissions
Use CaseCI/CD, automationDaily development

Troubleshooting ​

Key Not Working ​

Check:

  1. Key added to correct repository
  2. Correct permissions (read vs write)
  3. Private key format correct
  4. Known hosts configured

Permission Denied ​

bash
# Verify key
cat ~/.ssh/deploy_key.pub
# Should match what's in repository settings

# Test connection
ssh -i ~/.ssh/deploy_key -T git@kizuna.example.com

Summary ​

Deploy keys provide:

  • Repository-specific access — Limited scope
  • Automation-friendly — No user account needed
  • Permission control — Read-only or read-write
  • Security — Keys are isolated per repo

They're the secure way to give automated systems access to your code.