> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shardcloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# How to Use GitHub Actions for CI/CD

> Deploy your application to Shard Cloud directly from your GitHub workflows.

## 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](https://shardcloud.app/dash) → **Config** → **Integrations**)

***

## Setup

### Step 1: Get Your ShardCloud API Key

<Steps>
  <Step title="Navigate to Integrations">
    Go to the [Shard Cloud Dashboard](https://shardcloud.app/dash) and navigate to
    **Config** → **Integrations**.
  </Step>

  <Step title="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>
</Steps>

### Step 2: Add Secret to GitHub

<Steps>
  <Step title="Open Repository Settings">
    Go to your GitHub repository and navigate to **Settings** → **Secrets and
    variables** → **Actions**.
  </Step>

  <Step title="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**.
  </Step>
</Steps>

<Warning>
  Always store your API key in GitHub Secrets. Never hardcode it in your
  workflow files or commit it to your repository.
</Warning>

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

```yaml .github/workflows/deploy.yml theme={null}
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>
```

<Note>
  Replace `<app_id>` with your actual Shard Cloud application ID. You can find
  this in your application's dashboard URL or settings.
</Note>

### Deploy and Restart

Commit your changes and restart the application in one workflow:

```yaml .github/workflows/deploy.yml theme={null}
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:

```yaml .github/workflows/deploy.yml theme={null}
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):

```yaml .github/workflows/deploy.yml theme={null}
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:

```yaml .github/workflows/deploy.yml theme={null}
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:

| 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 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](/cli/cli) for a complete list

***

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Secrets" icon="lock">
    Always store your API key in GitHub Secrets. Never hardcode credentials.
  </Card>

  <Card title="Create Backups" icon="database">
    Create backups before major deployments to ensure you can rollback if needed.
  </Card>

  <Card title="Use Specific Branches" icon="code-branch">
    Use specific branches for production deployments to prevent accidental deployments.
  </Card>

  <Card title="Combine Commands" icon="code">
    Combine multiple commands to create complex deployment workflows.
  </Card>
</CardGroup>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Deployment fails">
    Check the action logs for specific error messages. Verify your `.shardcloud`
    configuration is valid. Ensure all required files are in your repository.
  </Accordion>

  <Accordion title="Working directory not found">
    Verify that the `workdir` path is correct relative to your repository root.
    Ensure the directory exists in your repository.
  </Accordion>
</AccordionGroup>

***

## Additional Resources

* [ShardCloud GitHub Action Repository](https://github.com/shard-cloud/action)
* [ShardCloud CLI Documentation](/cli/cli)
* [GitHub Actions Documentation](https://docs.github.com/en/actions)