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

# Automate Builds

> Automate Capwrapper builds and app store deployments in GitHub Actions, GitLab CI, and other pipelines using capwrap-cli and environment secrets.

Integrating `capwrap-cli` into your CI/CD pipeline lets you trigger builds and deploy to the App Store or Google Play automatically on every push, without any manual steps in the dashboard. This is useful for teams that want to ship mobile app updates as part of their standard release workflow.

<Warning>
  Never commit your Capwrapper API key to version control. Store it as an encrypted secret in your CI/CD platform and reference it via an environment variable. Anyone with access to your API key can trigger builds and deployments on your account.
</Warning>

## Install as a dev dependency

For CI/CD use, install `capwrap-cli` as a dev dependency rather than globally. This pins the CLI version to your project, ensures every pipeline run uses the same version, and avoids global install permission issues in CI environments.

```bash theme={null}
npm install --save-dev capwrap-cli
```

<Tip>
  When `capwrap-cli` is installed as a dev dependency, run every command with `npx capwrap` instead of `capwrap`. The `npx` prefix resolves the binary from your local `node_modules`, so no global install is needed.
</Tip>

## Store your API key as a secret

Add your Capwrapper API key as a secret named `CAPWRAP_API_KEY` in your CI/CD platform. The examples below reference it as `${{ secrets.CAPWRAP_API_KEY }}` (GitHub Actions) and `$CAPWRAP_API_KEY` (GitLab CI).

## GitHub Actions example

The workflow below triggers on every push to `main`, installs `capwrap-cli`, authenticates, and creates an Android build.

```yaml theme={null}
name: Build Android App

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install capwrap-cli
        run: npm install -g capwrap-cli

      - name: Authenticate
        run: capwrap auth login --key ${{ secrets.CAPWRAP_API_KEY }}

      - name: Create build
        run: |
          capwrap build create \
            --url https://myapp.example.com \
            --name "My App" \
            --bundle-id com.example.myapp \
            --platform android
```

## GitLab CI example

The equivalent pipeline for GitLab CI. Set `CAPWRAP_API_KEY` as a masked CI/CD variable in your project's **Settings > CI/CD > Variables**.

```yaml theme={null}
build-android:
  image: node:18
  script:
    - npm install -g capwrap-cli
    - capwrap auth login --key $CAPWRAP_API_KEY
    - capwrap build create --url $APP_URL --name "$APP_NAME" --bundle-id $BUNDLE_ID
```

Use GitLab CI/CD variables (`$APP_URL`, `$APP_NAME`, `$BUNDLE_ID`) to keep your pipeline configuration reusable across environments.

## Best practices

* **Always store API keys as secrets.** Never hardcode them in your pipeline configuration or commit them to your repository.
* **Pin the CLI version** using `npm install --save-dev capwrap-cli`. This prevents unexpected behavior if a new CLI version introduces breaking changes.
* **Validate your config before building.** Add a `capwrap validate` step before `capwrap build create` to catch configuration errors early and avoid burning build minutes on a job that will fail.
* **Check build status before deploying.** Use `capwrap build status <build-id>` to confirm a build completed successfully before triggering a deployment step.
* **Use environment-specific variables** for `--url`, `--name`, and `--bundle-id` so the same pipeline works across staging and production environments without modification.