Automate your builds and deployments on every Git push using scoped API keys and continuous integration services like GitHub Actions, GitLab CI, or Buildkite.

1. Create a deploy-scoped API key

Use leaf keys create to generate an API key dedicated to your CI pipeline:

leaf keys create --name "github-actions-ci" --can deploy --site "my-cool-project" --expires 90d

Output:

API key created. Copy this secret now; it will not be shown again:
leaf_pat_9a8f2c3e4d5a6b7c8d9e0f1a2b3c4d5e

Security best practices

• Scope keys by action: Use --can deploy for deployment pipelines and --can read for monitoring or auditing scripts.
• Restrict to a single site: Pass --site <name> so the key cannot deploy to or modify other sites in your account.
• Set an expiry: Pass --expires <duration> (e.g. 30d, 90d, 180d, or 365d). The default is 90d.
• Never commit secrets: Never hard-code the key into repository files or commits.

2. Configure the secret in your CI provider

In your repository settings, add a secret named LEAF_TOKEN:

• GitHub: Go to Settings → Secrets and variables → Actions → New repository secret.
• Name: LEAF_TOKEN
• Value: <your-api-key-secret>

3. GitHub Actions workflow example

Add a workflow file at .github/workflows/deploy.yml:

Before running the workflow, add leaf.toml to the repository with the target site:

site = "my-cool-project"

name: Deploy to LeafCloud

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Check out repository
        uses: actions/checkout@v4

      - name: Setup Bun
        uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest

      - name: Install dependencies
        run: bun install

      - name: Install LeafCloud CLI
        # <!-- distribution: assumed, verify before launch -->
        run: curl -fsSL https://leafcloud.in/install.sh | sh

      - name: Validate build with dry run
        run: leaf deploy --dry-run --json

      - name: Deploy site
        env:
          LEAF_TOKEN: ${{ secrets.LEAF_TOKEN }}
        run: leaf deploy --yes

Running headless with --yes and --json

When running leaf in scripts or automated pipelines:

• Pass --yes to prevent the CLI from prompting interactively for confirmations.
• Pass --json to receive structured newline-delimited JSON on standard output.
• leaf automatically detects CI environments (when the CI environment variable is present) and suppresses terminal color banners.