{"id":51508564,"url":"https://github.com/blackwell-systems/gcp-emulator","last_synced_at":"2026-07-08T03:30:43.051Z","repository":{"id":348882713,"uuid":"1200172378","full_name":"blackwell-systems/gcp-emulator","owner":"blackwell-systems","description":"Local GCP runtime for development and testing: unified Secret Manager, KMS, Eventarc, and IAM with full API compatibility. No credentials, no network, single process.","archived":false,"fork":false,"pushed_at":"2026-04-03T08:21:20.000Z","size":65,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-03T14:05:50.487Z","etag":null,"topics":["cloud-emulator","docker","emulator","eventarc","gcp","gcp-emulator","golang","google-cloud","grpc","grpc-gateway","hermetic-testing","iam","kms","local-development","mock","rest-api","secret-manager","testing"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/blackwell-systems.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T05:39:42.000Z","updated_at":"2026-04-03T08:21:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/blackwell-systems/gcp-emulator","commit_stats":null,"previous_names":["blackwell-systems/gcp-emulator"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/blackwell-systems/gcp-emulator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcp-emulator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcp-emulator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcp-emulator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcp-emulator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/blackwell-systems","download_url":"https://codeload.github.com/blackwell-systems/gcp-emulator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/blackwell-systems%2Fgcp-emulator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35251015,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-08T02:00:06.796Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-emulator","docker","emulator","eventarc","gcp","gcp-emulator","golang","google-cloud","grpc","grpc-gateway","hermetic-testing","iam","kms","local-development","mock","rest-api","secret-manager","testing"],"created_at":"2026-07-08T03:30:42.586Z","updated_at":"2026-07-08T03:30:43.044Z","avatar_url":"https://github.com/blackwell-systems.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GCP Emulator\n\n[![Blackwell Systems](https://raw.githubusercontent.com/blackwell-systems/blackwell-docs-theme/main/badge-trademark.svg)](https://github.com/blackwell-systems)\n[![Go Reference](https://pkg.go.dev/badge/github.com/blackwell-systems/gcp-emulator.svg)](https://pkg.go.dev/github.com/blackwell-systems/gcp-emulator)\n[![Go Version](https://img.shields.io/badge/go-1.24+-blue.svg)](https://go.dev/)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n\n\u003e **Unified local emulator for Google Cloud Platform** — Secret Manager, KMS, Eventarc, and IAM enforcement in a single process.\n\nRun your entire GCP stack locally with one command. No credentials, no network, no docker-compose juggling.\n\n## Quick Start\n\n```bash\n# Install\ngo install github.com/blackwell-systems/gcp-emulator/cmd/gcp-emulator@latest\n\n# Run (IAM off — all requests allowed)\ngcp-emulator\n\n# Run with IAM enforcement\ngcp-emulator --policy policy.yaml --iam-mode strict\n```\n\n## Docker\n\n```bash\ndocker run -p 9090:9090 -p 8090:8090 \\\n  ghcr.io/blackwell-systems/gcp-emulator:latest\n```\n\nWith a policy file:\n\n```bash\ndocker run -p 9090:9090 -p 8090:8090 \\\n  -v $(pwd)/policy.yaml:/policy.yaml \\\n  -e GCP_EMULATOR_POLICY_FILE=/policy.yaml \\\n  -e IAM_MODE=strict \\\n  ghcr.io/blackwell-systems/gcp-emulator:latest\n```\n\n## Services\n\nAll services share a single gRPC port. A unified REST gateway handles HTTP transcoding.\n\n| Service | gRPC (`:9090`) | REST (`:8090`) |\n|---|---|---|\n| Secret Manager | `google.cloud.secretmanager.v1.SecretManagerService` | `/v1/projects/{p}/secrets/...` |\n| KMS | `google.cloud.kms.v1.KeyManagementService` | `/v1/projects/{p}/locations/.../keyRings/...` |\n| Eventarc | `google.cloud.eventarc.v1.Eventarc` | `/v1/projects/{p}/locations/...` |\n| Eventarc Publisher | `google.cloud.eventarc.publishing.v1.Publisher` | `/v1/projects/{p}/locations/...` |\n| Long-running Ops | `google.longrunning.Operations` | — |\n| IAM | `google.iam.v1.IAMPolicy` | — |\n\nHealth endpoints: `GET /healthz`, `GET /readyz`\n\n## Use with GCP Go SDK\n\n```go\nimport (\n    \"google.golang.org/grpc\"\n    \"google.golang.org/grpc/credentials/insecure\"\n    secretmanager \"cloud.google.com/go/secretmanager/apiv1\"\n    eventarc \"cloud.google.com/go/eventarc/apiv1\"\n)\n\nconn, _ := grpc.NewClient(\"localhost:9090\",\n    grpc.WithTransportCredentials(insecure.NewCredentials()))\n\nsmClient, _ := secretmanager.NewClient(ctx,\n    option.WithGRPCConn(conn))\n\neaClient, _ := eventarc.NewClient(ctx,\n    option.WithGRPCConn(conn))\n```\n\nOr via environment variable:\n\n```bash\nexport SECRETMANAGER_EMULATOR_HOST=localhost:9090\nexport EVENTARC_EMULATOR_HOST=localhost:9090\n```\n\n## IAM Enforcement\n\nCopy `policy.yaml.example` to `policy.yaml` and customize:\n\n```yaml\nroles:\n  roles/secretmanager.admin:\n    permissions:\n      - secretmanager.secrets.create\n      - secretmanager.secrets.get\n\nprojects:\n  my-project:\n    bindings:\n      - role: roles/secretmanager.admin\n        members:\n          - serviceAccount:app@my-project.iam.gserviceaccount.com\n```\n\nInject the caller identity via gRPC metadata:\n\n```\nx-emulator-principal: serviceAccount:app@my-project.iam.gserviceaccount.com\n```\n\n| `--iam-mode` | Behavior |\n|---|---|\n| `off` (default) | All requests allowed, no policy required |\n| `permissive` | Logs denials, does not block |\n| `strict` | Blocks unauthorized requests with `PERMISSION_DENIED` |\n\n## Environment Variables\n\n| Variable | Default | Description |\n|---|---|---|\n| `GCP_EMULATOR_GRPC_PORT` | `9090` | gRPC port for all services |\n| `GCP_EMULATOR_HTTP_PORT` | `8090` | REST gateway port |\n| `GCP_EMULATOR_POLICY_FILE` | — | Path to IAM policy YAML |\n| `IAM_MODE` | `off` | IAM enforcement mode |\n| `IAM_TRACE` | `false` | Log every IAM decision |\n\n## Individual Service Emulators\n\nNeed just one service? Use the standalone emulators:\n\n| Service | Repository |\n|---|---|\n| Secret Manager | [`gcp-secret-manager-emulator`](https://github.com/blackwell-systems/gcp-secret-manager-emulator) |\n| KMS | [`gcp-kms-emulator`](https://github.com/blackwell-systems/gcp-kms-emulator) |\n| Eventarc | [`gcp-eventarc-emulator`](https://github.com/blackwell-systems/gcp-eventarc-emulator) |\n| IAM | [`gcp-iam-emulator`](https://github.com/blackwell-systems/gcp-iam-emulator) |\n\n## Architecture\n\n```\ngcp-emulator (single process)\n│\n├── gRPC :9090\n│   ├── SecretManagerService      ← gcp-secret-manager-emulator\n│   ├── KeyManagementService      ← gcp-kms-emulator\n│   ├── Eventarc                  ← gcp-eventarc-emulator\n│   ├── Publisher                 ← gcp-eventarc-emulator\n│   ├── Operations                ← gcp-eventarc-emulator\n│   └── IAMPolicy                 ← gcp-iam-emulator\n│\n└── REST :8090\n    ├── /v1/projects/*/secrets/*          → Secret Manager\n    ├── /v1/projects/*/locations/*/keyRings/* → KMS\n    ├── /v1/projects/*/locations/*         → Eventarc\n    └── /healthz, /readyz\n```\n\n## Migrating from gcp-iam-control-plane\n\nIf you were using the now-archived [`gcp-iam-control-plane`](https://github.com/blackwell-systems/gcp-iam-control-plane) CLI, this repo is its replacement. The old CLI orchestrated separate emulators via docker-compose; this one runs everything in a single process.\n\n```bash\n# Old\ngo install github.com/blackwell-systems/gcp-iam-control-plane/cmd/gcp-emulator@latest\n\n# New\ngo install github.com/blackwell-systems/gcp-emulator/cmd/gcp-emulator@latest\n```\n\nThe `--policy`, `--iam-mode`, `--trace`, and `--watch` flags are all preserved. No changes to `policy.yaml` format required.\n\n## License\n\nApache 2.0 — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fgcp-emulator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fblackwell-systems%2Fgcp-emulator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fblackwell-systems%2Fgcp-emulator/lists"}