Git Deploy

Deploy and update instance files directly from Git repositories. Great for modders, server admins, and teams using CI/CD pipelines.

Overview

Git Deploy enables:

Automatic Updates: Push to GitHub/GitLab and your workload files update automatically
Version Control: Track all changes to configs, mods, and plugins
CI/CD Integration: Use GitHub Actions or GitLab CI to deploy
Rollback Support: Revert to previous versions if needed

Quick Start

1. Configure Git for an Instance

bash

curl -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository": "https://github.com/user/my-minecraft-server",
    "branch": "main",
    "target_path": "/data",
    "webhook_enabled": true
  }' \
  "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git"

2. Trigger a Sync

bash

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git/sync"

3. Check Status

bash

curl -H "Authorization: Bearer $TOKEN" \
  "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git/status"

Configuration Options

Field	Type	Default	Description
`repository`	string	required	Git repository URL
`branch`	string	`main`	Branch to sync
`target_path`	string	`/data`	Path inside container
`auth_type`	string	`none`	`none`, `token`, or `ssh`
`credential_id`	uuid	-	ID of stored credential
`auto_sync`	bool	`false`	Sync on instance start
`webhook_enabled`	bool	`false`	Accept webhook triggers
`post_sync_action`	string	`none`	`none`, `restart`, or `custom`
`post_sync_command`	string	-	Custom command after sync

Authentication

Public Repositories

No authentication needed:

json

{
  "repository": "https://github.com/user/public-repo",
  "auth_type": "none"
}

Private Repositories (Token)

Create a Personal Access Token (PAT) on GitHub/GitLab
Store it as a credential in Shardlyn
Reference the credential:

json

{
  "repository": "https://github.com/user/private-repo",
  "auth_type": "token",
  "credential_id": "uuid-of-stored-credential"
}

Private Repositories (SSH)

For SSH authentication, use the SSH URL format:

json

{
  "repository": "[email protected]:user/private-repo.git",
  "auth_type": "ssh",
  "credential_id": "uuid-of-ssh-key-credential"
}

Webhooks

GitHub Setup

Go to your repo → Settings → Webhooks → Add webhook
Set Payload URL to: https://your-shardlyn-domain/v1/webhooks/github
Set Content type to: application/json
Copy the webhook secret from your Shardlyn config
Select "Just the push event"
Save

GitLab Setup

Go to your repo → Settings → Webhooks
Set URL to: https://your-shardlyn-domain/v1/webhooks/gitlab
Set Secret token from your Shardlyn config
Check "Push events"
Save

Webhook Security

Webhooks are verified using:

GitHub: HMAC-SHA256 signature in X-Hub-Signature-256 header
GitLab: Token comparison in X-Gitlab-Token header

CI/CD Integration

GitHub Actions

yaml

name: Deploy Instance Files

on:
  push:
    branches: [main]
    paths:
      - 'server/**'
      - 'mods/**'
      - 'config/**'

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Shardlyn Sync
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.SHARDLYN_TOKEN }}" \
            "${{ secrets.SHARDLYN_URL }}/v1/instances/${{ secrets.INSTANCE_ID }}/git/sync"

      - name: Wait for sync completion
        run: |
          for i in {1..30}; do
            STATUS=$(curl -s \
              -H "Authorization: Bearer ${{ secrets.SHARDLYN_TOKEN }}" \
              "${{ secrets.SHARDLYN_URL }}/v1/instances/${{ secrets.INSTANCE_ID }}/git/status" \
              | jq -r '.status')

            echo "Sync status: $STATUS"

            if [ "$STATUS" = "synced" ]; then
              echo "Sync completed successfully!"
              exit 0
            fi

            if [ "$STATUS" = "error" ]; then
              echo "Sync failed!"
              exit 1
            fi

            sleep 10
          done

          echo "Timeout waiting for sync"
          exit 1

      - name: Restart server (optional)
        run: |
          curl -X POST \
            -H "Authorization: Bearer ${{ secrets.SHARDLYN_TOKEN }}" \
            "${{ secrets.SHARDLYN_URL }}/v1/instances/${{ secrets.INSTANCE_ID }}/restart"

GitLab CI

yaml

stages:
  - deploy

deploy_server:
  stage: deploy
  only:
    - main
  script:
    - |
      curl -X POST \
        -H "Authorization: Bearer $SHARDLYN_TOKEN" \
        "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git/sync"
    - |
      for i in $(seq 1 30); do
        STATUS=$(curl -s \
          -H "Authorization: Bearer $SHARDLYN_TOKEN" \
          "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git/status" \
          | jq -r '.status')

        if [ "$STATUS" = "synced" ]; then
          echo "Deploy successful!"
          exit 0
        fi

        if [ "$STATUS" = "error" ]; then
          echo "Deploy failed!"
          exit 1
        fi

        sleep 10
      done

Webhook Tokens

For CI/CD pipelines, create dedicated webhook tokens:

Create Token

bash

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "github-actions",
    "instance_id": "optional-instance-uuid",
    "permissions": ["sync", "restart"],
    "expires_in": 31536000
  }' \
  "$SHARDLYN_URL/v1/webhook-tokens"

Response:

json

{
  "id": "uuid",
  "name": "github-actions",
  "token": "whk_abc123...",  // Only shown once!
  "permissions": ["sync", "restart"],
  "expires_at": "2027-01-22T00:00:00Z"
}

List Tokens

bash

curl -H "Authorization: Bearer $TOKEN" \
  "$SHARDLYN_URL/v1/webhook-tokens"

Delete Token

bash

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$SHARDLYN_URL/v1/webhook-tokens/$TOKEN_ID"

Sync History

View deployment history:

bash

curl -H "Authorization: Bearer $TOKEN" \
  "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git/history"

Response:

json

[
  {
    "id": "uuid",
    "commit_hash": "abc123f",
    "commit_message": "Update server config",
    "branch": "main",
    "status": "synced",
    "files_changed": 5,
    "additions": 42,
    "deletions": 10,
    "triggered_by": "webhook",
    "trigger_source": "github",
    "started_at": "2024-01-22T10:00:00Z",
    "completed_at": "2024-01-22T10:00:15Z"
  }
]

Post-Sync Actions

Auto-Restart

Automatically restart the server after sync:

json

{
  "repository": "https://github.com/user/repo",
  "post_sync_action": "restart"
}

Custom Command

Run a custom command after sync:

json

{
  "repository": "https://github.com/user/repo",
  "post_sync_action": "custom",
  "post_sync_command": "/data/scripts/post-deploy.sh"
}

Best Practices

Repository Structure

my-game-server/
├── config/
│   ├── server.properties
│   └── permissions.yml
├── mods/
│   ├── mod1.jar
│   └── mod2.jar
├── plugins/
│   └── plugin1.jar
├── scripts/
│   └── post-deploy.sh
└── README.md

.gitignore

text

# Ignore runtime files
*.log
logs/
crash-reports/
world/
*.dat
*.dat_old

# Ignore large binary files (use Git LFS or external storage)
*.zip
*.tar.gz

Git LFS for Large Files

For mods and large assets, consider Git LFS:

bash

git lfs install
git lfs track "*.jar"
git lfs track "mods/*.jar"

Troubleshooting

Sync Failed

Check the error message in status:

bash

curl -H "Authorization: Bearer $TOKEN" \
  "$SHARDLYN_URL/v1/instances/$INSTANCE_ID/git/status"

Common issues:

Authentication failed: Check credentials
Repository not found: Verify URL and access
Branch not found: Check branch name exists
Disk full: Clear old files or increase storage

Webhook Not Triggering

Verify webhook URL is correct
Check webhook secret matches
Look for delivery errors in GitHub/GitLab webhook settings
Ensure instance has webhook_enabled: true

Permission Denied

Ensure the target path is within allowed volumes:

/data
/config
/server
/home
/app
/opt

API Reference

See the API Documentation for complete endpoint details.

Endpoint	Method	Description
`/v1/instances/{id}/git`	GET	Get git config
`/v1/instances/{id}/git`	PUT	Create/update config
`/v1/instances/{id}/git`	DELETE	Remove config
`/v1/instances/{id}/git/sync`	POST	Trigger sync
`/v1/instances/{id}/git/status`	GET	Get sync status
`/v1/instances/{id}/git/history`	GET	List sync history
`/v1/webhook-tokens`	GET/POST	Manage tokens
`/v1/webhooks/github`	POST	GitHub webhook
`/v1/webhooks/gitlab`	POST	GitLab webhook

Next Steps

Instances — Manage the running containers that Git Deploy syncs to
File Management — Browse and edit synced files inside instances
Workloads — Define container templates for your deployments
Security — Manage API tokens and webhook credentials

Git Deploy ​

Overview ​

Quick Start ​

1. Configure Git for an Instance ​

2. Trigger a Sync ​

3. Check Status ​

Configuration Options ​

Authentication ​

Public Repositories ​

Private Repositories (Token) ​

Private Repositories (SSH) ​

Webhooks ​

GitHub Setup ​

GitLab Setup ​

Webhook Security ​

CI/CD Integration ​

GitHub Actions ​

GitLab CI ​

Webhook Tokens ​

Create Token ​

List Tokens ​

Delete Token ​

Sync History ​

Post-Sync Actions ​

Auto-Restart ​

Custom Command ​

Best Practices ​

Repository Structure ​

.gitignore ​

Git LFS for Large Files ​

Troubleshooting ​

Sync Failed ​

Webhook Not Triggering ​

Permission Denied ​

API Reference ​

Next Steps ​

Git Deploy

Overview

Quick Start

1. Configure Git for an Instance

2. Trigger a Sync

3. Check Status

Configuration Options

Authentication

Public Repositories

Private Repositories (Token)

Private Repositories (SSH)

Webhooks

GitHub Setup

GitLab Setup

Webhook Security

CI/CD Integration

GitHub Actions

GitLab CI

Webhook Tokens

Create Token

List Tokens

Delete Token

Sync History

Post-Sync Actions

Auto-Restart

Custom Command

Best Practices

Repository Structure

.gitignore

Git LFS for Large Files

Troubleshooting

Sync Failed

Webhook Not Triggering

Permission Denied

API Reference

Next Steps