> ## 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 Set Up Git Integration

> Configure automatic deployments from GitHub to Shard Cloud.

## Introduction

Git integration allows you to automatically deploy your application whenever you push changes to your GitHub repository. Shard Cloud offers two methods to set this up.

***

## Method 1: GitHub Integration (Recommended)

This is the easiest and preferred method. Connect your GitHub account once and select repositories for each app.

<Steps>
  <Step title="Connect GitHub Account">
    Go to [Shard Cloud Dashboard](https://shardcloud.app/dash) and navigate to
    **Config** → **Integrations**. Click **"Connect with GitHub"** and authorize
    Shard Cloud to access your repositories.
  </Step>

  <Step title="Link Repository to Your App">
    Go to your application in the dashboard and navigate to the **Deploys**
    section. Select the repository you want to connect and choose the branch to
    deploy from.
  </Step>

  <Step title="Done!">
    Everything else is handled automatically by our backend. Push to your
    connected branch and your app will redeploy.
  </Step>
</Steps>

<Note>
  This method is simpler because you don't need to manage tokens or webhooks
  manually. Shard Cloud handles everything for you.
</Note>

***

## Method 2: Manual Webhook Setup

If you prefer more control or need to use a personal access token, you can set up webhooks manually.

<Steps>
  <Step title="Generate GitHub Access Token">
    Go to [GitHub Personal Access Tokens](https://github.com/settings/tokens)
    and click **"Generate new token (classic)"**. Configure the following: -
    **Note**: Give it a descriptive name (e.g., "Shard Cloud Deploy") -
    **Expiration**: Set to "No expiration" to avoid interruptions - **Scopes**:
    Select only **"repo"** (full control of private repositories) Click
    **"Generate token"** and **copy it immediately** (you won't see it again).
  </Step>

  <Step title="Configure Token in Shard Cloud">
    Go to [Shard Cloud Dashboard](https://shardcloud.app/dash/applications) and
    select your application. Navigate to the **Deploy** section, paste your
    GitHub token, and click **Save**. A **webhook URL** will be generated.
    **Copy this URL** for the next step.
  </Step>

  <Step title="Configure GitHub Webhook">
    Go to your repository on GitHub and navigate to **Settings** → **Webhooks**.
    Click **"Add webhook"** and configure: - **Payload URL**: Paste the webhook
    URL from Shard Cloud - **Content type**: `application/json` - **Events**:
    Select "Just the push event" Click **"Add webhook"**.
  </Step>

  <Step title="Test the Integration">
    Make a change to your code, commit, and push to the `main` or `master`
    branch. Your application should automatically redeploy.
  </Step>
</Steps>

<Note>
  Automatic deployments only trigger on pushes to the `main` or `master` branch.
</Note>

***

## Monitoring Deployments

After each push:

1. Go to your application in the Shard Cloud dashboard
2. Check the **Deployments** or **Logs** section
3. Verify the deployment completed successfully

## Best Practices

<CardGroup cols={2}>
  <Card title="Use a Production Branch" icon="code-branch">
    Deploy from a stable branch like `main` or `master`.
  </Card>

  <Card title="Test Locally First" icon="flask">
    Always test changes locally before pushing.
  </Card>

  <Card title="Don't Commit Secrets" icon="lock">
    Use environment variables for sensitive data.
  </Card>

  <Card title="Monitor Deployments" icon="eye">
    Check deployment logs after each push.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="GitHub integration not showing repositories">
    Ensure you've authorized Shard Cloud to access your repositories. Try
    disconnecting and reconnecting your GitHub account. Check that the
    repository is not private without proper permissions.
  </Accordion>

  <Accordion title="Webhook not triggering">
    Check that the webhook URL is correct. Verify the GitHub token has the
    correct permissions. Look at webhook delivery logs in GitHub (Settings →
    Webhooks → Recent Deliveries).
  </Accordion>

  <Accordion title="Deployment fails">
    Check the deployment logs in Shard Cloud. Ensure your `.shardcloud` config
    is valid. Verify all required files are in the repository.
  </Accordion>

  <Accordion title="Token expired">
    Generate a new token and update it in Shard Cloud. Consider using tokens
    without expiration.
  </Accordion>
</AccordionGroup>