> For the complete documentation index, see [llms.txt](https://whitepaper.litho.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://whitepaper.litho.ai/.github/secrets.md).

# GitHub Actions Secrets Configuration

This document describes the required GitHub Secrets for automated deployment.

## Required Secrets

Navigate to: **Settings** → **Secrets and variables** → **Actions** → **New repository secret**

### 1. SSH Connection Secrets

| Secret Name       | Description                       | Example                                                                                                                               |
| ----------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `SSH_PRIVATE_KEY` | SSH private key for server access | <p><code>-----BEGIN OPENSSH PRIVATE KEY-----</code><br>Your private key content<br><code>-----END OPENSSH PRIVATE KEY-----</code></p> |
| `SERVER_IP`       | VPS/Server IP address             | `72.60.177.106`                                                                                                                       |
| `SERVER_USER`     | SSH username                      | `root`                                                                                                                                |

### 2. Application Configuration Secrets (Optional)

These can be added to the `.env` file on the server manually, or configured as secrets for automatic injection:

| Secret Name      | Description                  | Example                                            |
| ---------------- | ---------------------------- | -------------------------------------------------- |
| `DATABASE_URL`   | PostgreSQL connection string | `postgresql://user:pass@postgres:5432/lithosphere` |
| `LITHO_RPC_URL`  | Blockchain RPC endpoint      | `https://testnet-rpc.lithosphere.network`          |
| `LITHO_CHAIN_ID` | Chain ID                     | `61`                                               |

## Generating SSH Key Pair

If you don't have an SSH key pair, generate one:

```bash
# On your local machine
ssh-keygen -t ed25519 -C "github-actions-deploy" -f ~/.ssh/lithosphere_deploy

# Copy public key to server
ssh-copy-id -i ~/.ssh/lithosphere_deploy.pub root@72.60.177.106

# Copy private key content for GitHub Secret
cat ~/.ssh/lithosphere_deploy
# Copy the entire output including BEGIN and END lines
```

## Adding Secrets to GitHub

1. Go to your repository: <https://github.com/KaJLabs/lithosphere>
2. Click **Settings** → **Secrets and variables** → **Actions**
3. Click **New repository secret**
4. Add each secret:
   * **Name**: `SSH_PRIVATE_KEY`
   * **Value**: Paste your private key (entire content)
   * Click **Add secret**
5. Repeat for `SERVER_IP` and `SERVER_USER`

## Verifying Secrets

After adding secrets, you can trigger a deployment:

1. Go to **Actions** tab
2. Select **Deploy to VPS** workflow
3. Click **Run workflow**
4. Select environment (testnet/staging/mainnet)
5. Click **Run workflow**

The workflow will:

* Connect to your server via SSH
* Pull latest code from GitHub
* Build Docker images
* Deploy services
* Run health checks

## Deployment Workflow

The deployment happens automatically on:

* Push to `main` branch (changes in `Makalu/**`)
* Manual trigger via GitHub Actions UI

### Workflow Steps:

1. ✅ Checkout code
2. ✅ Setup SSH connection
3. ✅ Pull latest code on server
4. ✅ Build Docker images
5. ✅ Deploy services
6. ✅ Health checks
7. ✅ Rollback on failure

## Security Best Practices

* ✅ Never commit private keys to the repository
* ✅ Use SSH keys instead of passwords
* ✅ Rotate SSH keys periodically
* ✅ Use environment-specific secrets for staging/production
* ✅ Limit SSH key permissions to deployment user only
* ✅ Use read-only database credentials where possible

## Troubleshooting

### SSH Connection Failed

```
Permission denied (publickey)
```

**Solution**: Verify `SSH_PRIVATE_KEY` is correctly formatted with BEGIN/END lines

### Health Check Failed

```
API health check failed after 5 attempts
```

**Solution**: Check server logs: `ssh root@SERVER_IP "cd /opt/lithosphere/Makalu && docker compose logs api"`

### Build Failed

```
docker compose build failed
```

**Solution**: Check for syntax errors in Dockerfile or dependencies issues

## Manual Deployment

If automated deployment fails, deploy manually:

```bash
ssh root@72.60.177.106

cd /opt/lithosphere
git clone https://github.com/KaJLabs/lithosphere.git temp
cp -r temp/Makalu/* Makalu/
rm -rf temp

cd Makalu
docker compose build
docker compose up -d
docker compose ps
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://whitepaper.litho.ai/.github/secrets.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.