How to Use GitHub Actions for CI/CD

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

Navigate to Integrations

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

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

Open Repository Settings

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

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: app 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: |
            app commit <app_id>
            app 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 create <app_id>
            app 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: app 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 create <prod_app_id>
            app commit <prod_app_id>
            app 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: app commit <staging_app_id>

Action Inputs

The ShardCloud GitHub Action supports the following inputs:

Input	Required	Default	Description
`token`	Yes	-	ShardCloud API Key (store in secrets)
`commands`	No	-	ShardCloud CLI commands to execute
`workdir`	No	`.`	Working directory for command execution

Available Commands

The action supports every ShardCloud CLI v2 command, which are grouped by resource: shardcloud <resource> <verb> (app, db, vm, backup, lb, image). Common commands include:

app commit <app_id> - Deploy changes to your application
app restart <app_id> - Restart your application
backup create <app_id> - Create a backup — this now works identically for apps, databases, and VMs, not just apps
app 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

Action fails with authentication error

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.

Commands not executing

Verify that your commands input is correctly formatted. For multiple commands, use a multi-line string with |. Check that your app_id is correct.

Deployment fails

Check the action logs for specific error messages. Verify your .shardcloud configuration is valid. Ensure all required files are in your repository.

Working directory not found

Verify that the workdir path is correct relative to your repository root. Ensure the directory exists in your repository.

Introduction

Platform Features

Bot Platforms

API Frameworks

Website Frameworks

How to Use GitHub Actions for CI/CD

Introduction

Prerequisites

Setup

Step 1: Get Your ShardCloud API Key

Step 2: Add Secret to GitHub

Step 3: Create Workflow File

Usage Examples

Basic Deployment

Deploy and Restart

Backup Before Deploy

Custom Working Directory

Multi-Environment Deployment

Action Inputs

Available Commands

Best Practices

Use Secrets

Create Backups

Use Specific Branches

Combine Commands

Troubleshooting

Additional Resources

​Introduction

​Prerequisites

​Setup

​Step 1: Get Your ShardCloud API Key

​Step 2: Add Secret to GitHub

​Step 3: Create Workflow File

​Usage Examples

​Basic Deployment

​Deploy and Restart

​Backup Before Deploy

​Custom Working Directory

​Multi-Environment Deployment

​Action Inputs

​Available Commands

​Best Practices

Use Secrets

Create Backups

Use Specific Branches

Combine Commands

​Troubleshooting

​Additional Resources

Introduction

Prerequisites

Setup

Step 1: Get Your ShardCloud API Key

Step 2: Add Secret to GitHub

Step 3: Create Workflow File

Usage Examples

Basic Deployment

Deploy and Restart

Backup Before Deploy

Custom Working Directory

Multi-Environment Deployment

Action Inputs

Available Commands

Best Practices

Troubleshooting

Additional Resources