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

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

Add to Repository

1. Copy public key:

   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

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

# .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:

# 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

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

Delete Key

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

Aspect	Deploy Keys	User SSH Keys
Scope	Single repository	All accessible repos
Account	No user account	Requires user account
Permissions	Read-only or RW	User's permissions
Use Case	CI/CD, automation	Daily 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

# 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.