Skip to main content

​
Introduction

The ShardCloud GitHub Action allows you to deploy your application to Shard Cloud directly from your GitHub workflows. Automate deployments, backups, restarts, and more with simple workflow configurations. This action installs the ShardCloud CLI and allows you to execute ShardCloud commands as part of your CI/CD pipeline.

​
Prerequisites

Before setting up GitHub Actions, you’ll need:
  • A ShardCloud account
  • A GitHub repository
  • A ShardCloud API key (get it from Dashboard → Config → Integrations)

​
Setup

​
Step 1: Get Your ShardCloud API Key

1

Navigate to Integrations

Go to the Shard Cloud Dashboard and navigate to Config → Integrations.
2

Generate API Key

Generate or copy your API key. This key will be used to authenticate with the ShardCloud CLI in your GitHub workflows.

​
Step 2: Add Secret to GitHub

1

Open Repository Settings

Go to your GitHub repository and navigate to Settings → Secrets and variables → Actions.
2

Create New Secret

Click New repository secret and create a secret with: - Name: SHARD_CLOUD_API_KEY - Value: Your ShardCloud API key Click Add secret.
Always store your API key in GitHub Secrets. Never hardcode it in your workflow files or commit it to your repository.

​
Step 3: Create Workflow File

Create a .github/workflows/deploy.yml file in your repository. You can use any of the examples below based on your needs.

​
Usage Examples

​
Basic Deployment

Deploy your application to Shard Cloud on every push to the main branch:
.github/workflows/deploy.yml
name: Deploy to Shard Cloud
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Deploy to Shard Cloud
        uses: shard-cloud/action@main
        with:
          token: ${{ secrets.SHARD_CLOUD_API_KEY }}
          commands: commit <app_id>
Replace <app_id> with your actual Shard Cloud application ID. You can find this in your application’s dashboard URL or settings.

​
Deploy and Restart

Commit your changes and restart the application in one workflow:
.github/workflows/deploy.yml
name: Deploy and Restart
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Deploy and Restart Application
        uses: shard-cloud/action@main
        with:
          token: ${{ secrets.SHARD_CLOUD_API_KEY }}
          commands: |
            commit <app_id>
            restart <app_id>

​
Backup Before Deploy

Create a backup before deploying new changes to ensure you can rollback if needed:
.github/workflows/deploy.yml
name: Backup and Deploy
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Backup and Deploy
        uses: shard-cloud/action@main
        with:
          token: ${{ secrets.SHARD_CLOUD_API_KEY }}
          commands: |
            backup <app_id>
            commit <app_id>

​
Custom Working Directory

Execute commands from a specific directory (useful for monorepos):
.github/workflows/deploy.yml
name: Deploy from Subdirectory
on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Deploy Application
        uses: shard-cloud/action@main
        with:
          token: ${{ secrets.SHARD_CLOUD_API_KEY }}
          workdir: ./my-app
          commands: commit <app_id>

​
Multi-Environment Deployment

Deploy to different environments based on the branch:
.github/workflows/deploy.yml
name: Multi-Environment Deploy
on:
  push:
    branches:
      - main
      - staging

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Deploy to Production
        if: github.ref == 'refs/heads/main'
        uses: shard-cloud/action@main
        with:
          token: ${{ secrets.SHARD_CLOUD_API_KEY }}
          commands: |
            backup <prod_app_id>
            commit <prod_app_id>
            restart <prod_app_id>
      
      - name: Deploy to Staging
        if: github.ref == 'refs/heads/staging'
        uses: shard-cloud/action@main
        with:
          token: ${{ secrets.SHARD_CLOUD_API_KEY }}
          commands: commit <staging_app_id>

​
Action Inputs

The ShardCloud GitHub Action supports the following inputs:
InputRequiredDefaultDescription
tokenYes-ShardCloud API Key (store in secrets)
commandsNo-ShardCloud CLI commands to execute
workdirNo.Working directory for command execution

​
Available Commands

The action supports all ShardCloud CLI commands. Common commands include:
  • commit <app_id> - Deploy changes to your application
  • restart <app_id> - Restart your application
  • backup <app_id> - Create a backup of your application
  • logs <app_id> - View application logs
  • And more - refer to the ShardCloud CLI documentation for a complete list

​
Best Practices

Use Secrets

Always store your API key in GitHub Secrets. Never hardcode credentials.

Create Backups

Create backups before major deployments to ensure you can rollback if needed.

Use Specific Branches

Use specific branches for production deployments to prevent accidental deployments.

Combine Commands

Combine multiple commands to create complex deployment workflows.

​
Troubleshooting

Verify that your SHARD_CLOUD_API_KEY secret is correctly set in your repository settings. Ensure the API key is valid and hasn’t expired. Check the action logs for specific error messages.
Verify that your commands input is correctly formatted. For multiple commands, use a multi-line string with |. Check that your app_id is correct.
Check the action logs for specific error messages. Verify your .shardcloud configuration is valid. Ensure all required files are in your repository.
Verify that the workdir path is correct relative to your repository root. Ensure the directory exists in your repository.

​
Additional Resources