# LocalCloud in GitHub Actions

> Run LocalCloud in a GitHub Actions workflow with readiness checks, pinned image identity, and localhost SDK endpoints.
>
> Source: https://local.cloud/workflows/github-actions-gcp-emulator/

GitHub Actions

The Public Preview License permits individuals and organizations, including for-profit companies, to run ongoing internal CI without payment or a license key.

[Read docs](https://local.cloud/docs/) [Check compatibility](https://local.cloud/compatibility/) [SDK examples](https://local.cloud/docs/sdk-examples/)

Fact

No GCP secrets are required for the local job.

Fact

Readiness gate: http://localhost:5380/readiness.

Fact

Keep the workflow non-production and review the proprietary Public Preview License.

Eligible automation shape

## Health before tests

The workflow should fail fast if LocalCloud is not healthy. Do not let tests silently fall back to production SDK endpoints.

Secrets boundary

## Keep local jobs credentialless

A LocalCloud PR job should not need service-account JSON, workload identity, or a billing project. If a later deployment job needs them, keep it separate and guarded.

Copy-ready setup

## Commands and prompts

### Copy a prompt for your coding agent

#### Configure internal CI

Have an agent add a permitted non-production LocalCloud CI workflow.

```
Read https://local.cloud/docs/licensing/ before changing this automation. Keep the workflow within the Public Preview License's non-production boundary. Propose the smallest change that starts LocalCloud, waits for readiness, exports emulator env vars, runs integration tests locally, and avoids real GCP secrets.
```

#### Start LocalCloud

Give an agent one URL and have it start the local GCP sandbox.

```
Fetch https://local.cloud/ai/agents.md and follow the instructions to start LocalCloud on my machine. Install the LocalCloud CLI if it is missing, verify Docker, start or reuse LocalCloud, export emulator environment variables, and run one local GCP SDK/API smoke check. Do not ask for or use real GCP credentials.
```

GitHub Actions YAML

```
name: localcloud-integration-tests
on: [pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Start LocalCloud
        run: |
          # Public preview permits non-production internal organization and team CI.
          # Pin an image digest when the workflow must be repeatable.
          docker volume create localcloud-data

          docker run -d --name localcloud \
            -p 127.0.0.1:5380-5405:5380-5405 \
            -m 4g \
            -v localcloud-data:/var/lib/localcloud \
            agentcloud/localcloud:latest
          for i in $(seq 1 60); do curl -fsS http://localhost:5380/readiness && exit 0; sleep 2; done
          docker logs localcloud
          exit 1
      - name: Export emulator env and test
        run: |
          eval "$(curl -fsS 'http://localhost:5380/env?format=shell')"
          ./scripts/integration-test.sh
```

Production boundary

## Before production

Use LocalCloud for non-production development, testing, and CI under the [Public Preview License](https://local.cloud/license/), check [each service's local boundaries](https://local.cloud/compatibility/), and validate against real Google Cloud before you deploy.

Related

## Next steps

- [Complete GitHub Actions guide](https://local.cloud/docs/github-actions/) — Setup action, direct Docker, service IDs, SDK settings, and AI-agent jobs.
- [Terraform docs](https://local.cloud/docs/terraform/) — Endpoint override patterns for IaC.
- [GCP integration testing in CI](https://local.cloud/gcp-integration-testing/) — GitLab CI and Jenkins templates, test design, and a prompt for the first CI change.