firebase / firebase/firebase-tools

docs: Service Usage generateServiceIdentity authorization and versioning are undocumented

Open
#11,070 0 comments 0 reactions 0 assignees View on GitHub
api: functions docs
Dominant language
TypeScript
Stars
4.5k
Forks
1.3k
Avg merge
1d 12h
Merged PRs (30d)
84

Description

Tracking issue for the documentation gaps found while answering #11005. These are Google Cloud documentation pages rather than anything in this repo, so this issue exists to record what needs updating and route it, not to change files here.

The CLI calls Service Usage v1beta1 `services.generateServiceIdentity` during gen 2 functions preparation (`src/gcp/serviceusage.ts`, called from `src/deploy/functions/prepare.ts`). Anyone building a least-privilege CI role currently has no documented way to tell what to grant for it.

| Page | Gap | Could state |
|---|---|---|
| [Service Usage access control](https://cloud.google.com/service-usage/docs/access-control) | Method table omits `services.generateServiceIdentity`, while listing enable, use, get, list, disable and the quota methods | That the method checks no consumer project IAM permission |
| [`services.generateServiceIdentity` reference](https://cloud.google.com/service-usage/docs/reference/rest/v1beta1/services/generateServiceIdentity) | OAuth scopes only, no IAM permission, no behaviour when the identity already exists | The permission position, and that repeat calls return the existing identity unchanged |
| [Create and grant roles to service agents](https://cloud.google.com/iam/docs/create-service-agents) | Documents only Workload Identity `GenerateServiceAgents` with `workloadidentity.serviceAgents.create`, no cross reference in either direction | Whether it supersedes the Service Usage RPC |

Also worth stating on those pages: the method exists only in v1beta1. The v1 discovery document has no equivalent, so there is no GA endpoint to move to.

The testing behind this is in #11005: a service account with no role bindings received HTTP 200, including for services whose identity did not yet exist, while the same token was denied on `services.get` and `services.list`.

Routing for the fix: Documentation component 187166, and IAM component 187161 for the third page.

Contributor guide

Open the contributing guide

Research direction

Start with src/gcp/serviceusage.ts and src/deploy/functions/prepare.ts, then read the testing and findings in #11005. Review the three linked Google Cloud pages and route the documentation and IAM updates to their listed components. Done means the pages cover authorization, existing-identity behavior, v1beta1-only versioning, and the relationship to Workload Identity.

Written by the indexing model from the issue text.

Assessment

Tech stack
google-cloud, typescript
Domain
cli, cloud, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.