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

# CI/CD with GitHub Actions

> Ready-to-use workflows for linting, testing, building, and deploying your app

Shipnative includes GitHub Actions workflows for continuous integration and deployment.

## Included Workflows

| Workflow | File          | Trigger               | Purpose                               |
| -------- | ------------- | --------------------- | ------------------------------------- |
| CI       | `ci.yml`      | Push, PR              | Lint, typecheck, test, build analysis |
| Deploy   | `deploy.yml`  | Push to main, Release | Production deployments                |
| Preview  | `preview.yml` | Pull Request          | Preview deployments for PRs           |

***

## CI Workflow

Runs on every push and pull request to ensure code quality.

### Jobs

1. **Lint** - ESLint checks
2. **Typecheck** - TypeScript compilation
3. **Test** - Jest test suite
4. **Build Web App** - Expo web build with bundle size analysis
5. **Bundle Analysis** - Tree-shaking and dependency checks
6. **Build Marketing** - Marketing site build

```yaml theme={null}
# Triggered automatically on:
on:
  pull_request:
  push:
    branches: [main]
```

***

## Deploy Workflow

Handles production deployments for web and mobile.

### Triggers

* **Push to main** → Auto-deploy web + marketing
* **GitHub Release** → Build + submit mobile apps to stores
* **Manual dispatch** → Select what to deploy

### Required Secrets

Add these in **GitHub Settings → Secrets**:

| Secret                        | Description                          |
| ----------------------------- | ------------------------------------ |
| `EXPO_TOKEN`                  | Expo access token from expo.dev      |
| `VERCEL_TOKEN`                | Vercel deployment token              |
| `VERCEL_ORG_ID`               | Vercel organization ID               |
| `VERCEL_PROJECT_ID`           | Vercel project ID for web app        |
| `VERCEL_MARKETING_PROJECT_ID` | Vercel project ID for marketing site |

### Environment Secrets

| Secret                                 | Description          |
| -------------------------------------- | -------------------- |
| `EXPO_PUBLIC_SUPABASE_URL`             | Supabase project URL |
| `EXPO_PUBLIC_SUPABASE_PUBLISHABLE_KEY` | Supabase anon key    |
| `EXPO_PUBLIC_POSTHOG_KEY`              | PostHog API key      |
| `EXPO_PUBLIC_SENTRY_DSN`               | Sentry DSN           |

### Manual Deployment

1. Go to **Actions** → **Deploy**
2. Click **Run workflow**
3. Select what to deploy:
   * Deploy web app
   * Deploy marketing site
   * Build & submit iOS
   * Build & submit Android
4. Choose EAS profile (production/preview)

***

## Preview Workflow

Creates preview deployments for pull requests.

### Features

* **Web preview URL** - Vercel preview deployment
* **Mobile preview** - EAS Update with QR code
* **Marketing preview** - Separate preview for marketing site
* **Auto-comments** - PR comments with preview URLs

### How It Works

1. Open a PR with changes to the app
2. GitHub Actions builds a preview
3. Bot comments on PR with preview URLs
4. Scan QR code to test on mobile device

<Tip>
  **Testing Mobile Previews:** Install a development build with the preview channel configured, then scan the QR code from the PR comment.
</Tip>

***

## Setup Guide

### 1. Get Expo Token

```bash theme={null}
# Login to Expo
npx expo login

# Get your token from expo.dev
# Settings → Access Tokens → Create
```

### 2. Configure EAS

```bash theme={null}
cd apps/app
eas build:configure
eas credentials  # Set up iOS/Android certs
```

### 3. Set Up Vercel (Optional)

```bash theme={null}
# Install Vercel CLI
npm i -g vercel

# Link project
cd apps/app
vercel link

# Get IDs from .vercel/project.json
cat .vercel/project.json
```

### 4. Add GitHub Secrets

Go to your repo → **Settings** → **Secrets and variables** → **Actions** → **New repository secret**

Add all required secrets listed above.

***

## Customization

### Changing Deploy Triggers

Edit `.github/workflows/deploy.yml`:

```yaml theme={null}
on:
  push:
    branches:
      - main
      - production  # Add more branches
    paths:
      - "apps/app/**"  # Only deploy when app changes
```

### Adding Custom Jobs

```yaml theme={null}
jobs:
  my-custom-job:
    name: Custom Job
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run custom script
        run: ./scripts/my-script.sh
```

### Environment-Specific Deploys

```yaml theme={null}
jobs:
  deploy-staging:
    environment:
      name: staging
      url: https://staging.yourapp.com
    # Uses secrets from staging environment
```

***

## Troubleshooting

### Build Failing

1. Check that all secrets are set correctly
2. Verify EAS is configured: `eas build:configure`
3. Check build logs in EAS dashboard

### Preview Not Working

1. Ensure `VERCEL_TOKEN` is valid
2. Check Vercel project is linked
3. Verify paths-filter is detecting changes

### Mobile Submit Failing

1. Verify App Store / Play Store credentials in EAS
2. Check app version is incremented
3. Review EAS submit logs

<Warning>
  **Don't commit secrets!** Always use GitHub Secrets for sensitive values. Never put API keys in workflow files.
</Warning>