analytics_ops 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3bf17db3adc805f77cf7d22e2ea2840a3eaf44a007be8036a48bf58a4d2d3a36
+  data.tar.gz: 1642e17fb59a976a471636a92f8da2f1290c3e13eb7bee515722efd8315a2e4a
+SHA512:
+  metadata.gz: c934c5e8856505c2ec5d8e4311ac9f9e3d23ba47078fc478170dcda4d08e5d5be990402fa2795d56138ba30d2c8e92dbe368fdb1fb3da254bead9ba429338f09
+  data.tar.gz: b96a8112f501416f763d3528419435e2364526f66cd43266ec3880825f61c964550eca739ece89607d7d89a583051b44d35d1f3f62a018260dab625d13a871ef

data/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+Analytics Ops follows Semantic Versioning for its public Ruby, CLI,
+configuration, and plan contracts.
+
+## [0.1.0] - 2026-07-22
+
+### Added
+
+- Strict version-1 YAML configuration with safe Psych parsing, no ERB or
+  aliases, a 1 MiB limit, allowlisted environment interpolation, fail-closed
+  keys, quoted numeric identifiers, and committed JSON Schema.
+- Immutable desired state, normalized Admin resources, canonical JSON,
+  snapshot fingerprints, and deterministic planning.
+- Version-1 saved plans with strict scalar/payload/identity validation,
+  duplicate-key and secret-field rejection, cross-property protection,
+  atomic mode-0600 writes, and committed JSON Schema.
+- Create/update-only planning for web stream default URI, retention, key
+  events, custom dimensions, and custom metrics. Unmanaged resources are never
+  deleted or archived.
+- Explicit guarded apply with saved-plan-only execution, fresh snapshot
+  validation, stale-plan rejection, stop-on-first-failure behavior, and
+  structured partial reconciliation.
+- Lazy official Google Admin and Data adapters, typed/redacted errors,
+  deterministic protobuf contract tests, and no generated types in public
+  results.
+- `doctor`, `discover`, `snapshot`, `audit`, `plan`, `apply`,
+  `verify`, `report`, `realtime`, and `schema` CLI commands.
+- Human, automation-safe JSON, and report-only CSV output with stable exit
+  statuses.
+- Immutable standard/realtime report definitions, normalized result metadata
+  and quota information, and seven built-in commercial recipes.
+- Optional Rails 7.2–8.1 Railtie, install generator, binstub, and read-only
+  operator Rake tasks.
+- Public RBS signatures, security/redaction checks, Ruby 3.2–4.0 CI, Rails
+  compatibility jobs, package inspection, dependency audit, and OIDC Trusted
+  Publishing workflow.
+- Complete operator, safety, report, Rails, architecture, compatibility, and
+  troubleshooting documentation.
+
+### Security
+
+- Requiring the gem, loading configuration, and booting Rails perform no
+  network I/O.
+- Credentials and report rows are excluded from configuration and plan
+  contracts; common credential patterns are redacted from errors.
+- Ordinary plans cannot delete or archive resources.

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"analytics_ops" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["nelsonchavespro@gmail.com"](mailto:"nelsonchavespro@gmail.com").

data/CONTRIBUTING.md

@@ -0,0 +1,67 @@
+# Contributing
+
+Thank you for helping make Analytics Ops safer and easier to operate.
+
+## Setup
+
+```bash
+git clone https://github.com/nelsonchaves/analytics_ops.git
+cd analytics_ops
+bin/setup
+bin/check
+```
+
+Useful focused commands:
+
+```bash
+bundle exec rspec spec/analytics_ops/clients/data_spec.rb
+bundle exec rubocop
+bundle exec rbs -I sig validate
+bundle exec rake build
+```
+
+Use `RSPEC_STATUS_FILE=/tmp/analytics_ops-rspec-status` when the repository is
+mounted read-only except for source edits.
+
+## Design rules
+
+- Keep the core plain Ruby and independent of Rails and Active Support.
+- Use Google's official Ruby clients; do not add another HTTP or OAuth stack.
+- Keep generated Google objects behind adapters.
+- Do not introduce telemetry, a database, browser analytics, or boot-time
+  network access.
+- Preserve the read-only default and saved-plan confirmation boundary.
+- Do not add ordinary delete/archive operations.
+- Use immutable gem-owned public values and typed errors.
+
+## Tests
+
+Use RSpec. Run focused specs while changing a subsystem, then run the complete
+suite before the milestone commit. Ordinary tests must use injected fakes and
+must never contact a real property.
+
+An opt-in live check may use only a dedicated disposable GA4 property. It must
+use uniquely prefixed resources and clean up only resources it created. Never
+run a live test against production.
+
+Changes to a Google adapter need request/response coercion tests against the
+supported official generated classes. Changes to planning need deterministic
+output, stale-state, cross-property, and idempotency coverage.
+
+## Pull requests
+
+Keep commits focused and explain:
+
+- the user-visible problem and public contract
+- read/write behavior and rollback implications
+- tests and compatibility checks performed
+- documentation or schema changes
+
+Update `CHANGELOG.md` and the relevant support matrix when behavior changes.
+Configuration and plan incompatibilities require an explicit schema version;
+they never migrate silently.
+
+Never commit credentials, real property exports, visitor data, production
+plans, or production identifiers. Follow [SECURITY.md](SECURITY.md) for private
+vulnerability reports and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for project
+conduct.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Nelson Chaves
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,188 @@
+# Analytics Ops
+
+**Google Analytics 4 configuration as code and reporting for Ruby and Rails.**
+
+Analytics Ops gives you a review-first way to inspect GA4, detect drift, run
+useful reports, and apply a small set of safe configuration changes. The core
+is plain Ruby; Rails support is optional.
+
+## Five-minute read-only start
+
+You need Ruby 3.2 or newer, a GA4 property you can read, and the
+[Google Cloud CLI](https://cloud.google.com/sdk/docs/install).
+
+1. Add Analytics Ops to your bundle:
+
+   ```ruby
+   # Gemfile
+   gem "analytics_ops", "~> 0.1", group: :development
+   ```
+
+   ```bash
+   bundle install
+   ```
+
+2. Enable the Google Analytics Admin API and Data API in your own Google Cloud
+   project, then create local Application Default Credentials:
+
+   ```bash
+   gcloud auth application-default login \
+     --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"
+   ```
+
+3. Create `config/analytics_ops.yml`:
+
+   ```yaml
+   version: 1
+
+   profiles:
+     production:
+       property_id: "123456789"
+   ```
+
+4. Check access without changing anything:
+
+   ```bash
+   bundle exec analytics-ops doctor
+   bundle exec analytics-ops discover
+   bundle exec analytics-ops audit
+   bundle exec analytics-ops report traffic_acquisition
+   ```
+
+Every command above is read-only. `audit` exits with status 2 when it finds
+drift, which makes it useful in CI.
+
+## The safe change workflow
+
+```text
+configuration → audit → saved plan → review → apply → verify
+```
+
+```bash
+# Read-only: save a deterministic plan with mode 0600
+bundle exec analytics-ops plan --output tmp/ga4-plan.json
+
+# Review the JSON before doing anything
+less tmp/ga4-plan.json
+
+# Mutating: prints the exact saved operations and asks you to type yes
+bundle exec analytics-ops apply tmp/ga4-plan.json
+
+# Read-only: confirm managed settings now match
+bundle exec analytics-ops verify
+```
+
+`apply` refreshes the remote snapshot, rejects stale plans, and executes only
+the operations in the saved file. Ordinary plans never delete or archive
+anything. If one operation fails, execution stops and reports what succeeded,
+what failed, and what remains.
+
+## Common commands
+
+| Command | Purpose | Remote writes? |
+| --- | --- | --- |
+| `analytics-ops doctor` | Check configuration, credentials, APIs, property access, clients, and clock | No |
+| `analytics-ops discover` | List accessible accounts, properties, and streams | No |
+| `analytics-ops snapshot` | Print normalized managed remote state | No |
+| `analytics-ops audit` | Show drift without writing a plan file | No |
+| `analytics-ops plan --output FILE` | Review and save deterministic changes | No |
+| `analytics-ops apply FILE` | Apply one reviewed, non-stale plan | **Yes** |
+| `analytics-ops verify` | Check convergence | No |
+| `analytics-ops report NAME` | Run a built-in standard report | No |
+| `analytics-ops realtime` | Run the realtime-events report | No |
+| `analytics-ops schema --format json` | Print the configuration schema | No |
+
+Use `--format json` for automation. CSV is available only for reports:
+
+```bash
+bundle exec analytics-ops report landing_pages --format csv
+```
+
+See [Commands](docs/commands.md) for every option and exit status.
+
+## IDs: the quick distinction
+
+Use fake values like these in examples and tests:
+
+| Value | Example | Where it belongs |
+| --- | --- | --- |
+| Account ID | `100000001` | Discovery output only |
+| Property ID | `123456789` | `property_id` in configuration and API requests |
+| Stream ID | `987654321` | `stream_id` in configuration |
+| Measurement ID | `G-EXAMPLE1` | Browser tagging; never use it as a stream ID |
+| OAuth client | A Cloud project client ID/secret | Owned by your application, never this YAML |
+| Service-account identity | `ga-reader@example-project.iam.gserviceaccount.com` | Granted GA access; its key is never this YAML |
+
+## Ruby API
+
+```ruby
+workspace = AnalyticsOps::Workspace.load(
+  "config/analytics_ops.yml",
+  profile: "production"
+)
+
+plan = workspace.plan
+plan.write("tmp/ga4-plan.json")
+
+report = workspace.report("calculator_completions")
+report.rows.each { |row| puts row.fetch("eventCount") }
+```
+
+Loading the gem, loading YAML, and booting Rails do not contact Google.
+Network calls happen only when a workspace operation is invoked.
+
+## Rails
+
+```ruby
+# Gemfile
+gem "analytics_ops", require: "analytics_ops/rails", group: :development
+```
+
+```bash
+bin/rails generate analytics_ops:install
+bin/rake analytics:doctor
+bin/rake 'analytics:report[traffic_acquisition]'
+```
+
+The integration is a Railtie, not an Engine. It adds a generator and operator
+Rake tasks—no models, migrations, routes, controllers, views, JavaScript, or
+boot-time network calls. See [Rails integration](docs/rails.md).
+
+## What Analytics Ops does not do
+
+- It does not inject browser analytics or manage consent banners.
+- It does not store credentials, tokens, report rows, or local state.
+- It does not delete accounts, properties, streams, or unmanaged resources.
+- It does not claim to manage settings that Google exposes only in the UI.
+- Experimental declarations are findings only in version 0.1.0; they are not
+  silently applied through Alpha APIs.
+
+## Documentation
+
+| Guide | Topic |
+| --- | --- |
+| [Authentication](docs/authentication.md) | ADC, scopes, service accounts, and safe automation |
+| [Configuration](docs/configuration.md) | Complete strict YAML contract |
+| [Commands](docs/commands.md) | CLI syntax, formats, and exit statuses |
+| [Reports](docs/reports.md) | Built-in recipes and GA reporting limitations |
+| [Rails](docs/rails.md) | Generator and Rake tasks |
+| [Safety](docs/safety.md) | Plans, stale-state protection, rollback, and credentials |
+| [Plan format](docs/plan-format.md) | Version-1 JSON contract |
+| [API support](docs/api-support-matrix.md) | Exactly what is managed, manual, or unsupported |
+| [Client compatibility](docs/google-client-compatibility.md) | Tested official Google gem versions |
+| [Troubleshooting](docs/troubleshooting.md) | Common failures and fixes |
+| [Architecture](docs/architecture.md) | Boundaries and data flow |
+
+For development, run:
+
+```bash
+bin/setup
+bin/check
+```
+
+Security issues belong in private vulnerability reporting; see
+[SECURITY.md](SECURITY.md). Contributions follow [CONTRIBUTING.md](CONTRIBUTING.md).
+
+Analytics Ops is MIT licensed and is not affiliated with, sponsored by, or
+endorsed by Google LLC. Google Analytics is a trademark of Google LLC and is
+named only to describe API compatibility.

data/SECURITY.md

@@ -0,0 +1,56 @@
+# Security policy
+
+## Supported versions
+
+Analytics Ops is pre-release. Security fixes currently target the latest
+commit on `master`. A published support table will replace this section before
+1.0.
+
+## Report privately
+
+Do not open a public issue for a vulnerability or exposed credential. Use
+GitHub's private vulnerability reporting for this repository.
+
+Include:
+
+- affected version or commit
+- smallest safe reproduction
+- expected and observed behavior
+- potential impact
+- whether a disposable or production property was involved
+
+Do not include credentials, access or refresh tokens, authorization headers,
+private keys, visitor data, report exports, or production plan files.
+
+If credentials may be exposed, revoke or rotate them with Google immediately;
+do not wait for a project response.
+
+## Security guarantees
+
+Analytics Ops:
+
+- uses Application Default Credentials or an explicitly injected Google
+  credential object
+- refuses credential-shaped configuration and plan fields
+- redacts common authorization material from translated errors
+- performs no network I/O while requiring the gem, loading YAML, or booting
+  Rails
+- defaults to read-only commands
+- requires a strictly validated saved plan and explicit confirmation to mutate
+- rejects stale and cross-property plans
+- excludes delete/archive operations from ordinary plans
+- never logs report results automatically
+- has no telemetry, credential store, database, or browser injection
+- publishes through RubyGems Trusted Publishing without a stored API key
+
+Plan files still describe operational configuration and are created with mode
+0600. Report output may contain sensitive aggregate data and should be handled
+under the operator's data policy.
+
+## Operator responsibilities
+
+Analytics Ops cannot secure an overprivileged Cloud project, service account,
+GitHub organization, CI runner, GA property, or exported report. Use
+least-privilege read credentials for routine work, isolate mutation
+credentials, protect release environments, and keep production mutation
+credentials out of Rails web containers.

data/docs/api-support-matrix.md

@@ -0,0 +1,50 @@
+# API support matrix
+
+This matrix describes Analytics Ops 0.1.0—not every method Google exposes.
+
+| State | Meaning |
+| --- | --- |
+| Managed | Read and safely create/update within the stated limit |
+| Audited | Read-only |
+| Experimental | Explicitly declared, but Alpha behavior is isolated and may change |
+| Manual | Reported as an operator checklist |
+| Unsupported | Deliberately outside the public contract |
+
+| Capability | State | Exact 0.1.0 behavior |
+| --- | --- | --- |
+| Account/property discovery | Audited | Lists accessible summaries |
+| Data-stream discovery | Audited | Lists web, Android, and iOS streams |
+| Web stream default URI | Managed | Updates an existing web stream |
+| Stream create/delete | Unsupported | Missing streams become findings |
+| Data retention | Managed | Reads and updates supported periods/reset behavior |
+| Key events | Managed | Reads and creates missing events; no delete |
+| Custom dimensions | Managed | Reads, creates, and updates display name/description; user ads flag where supported |
+| Custom metrics | Managed | Reads, creates, and updates display name/description |
+| Standard Data API reports | Audited | Immutable definitions and normalized results |
+| Realtime Data API reports | Audited | Immutable definitions and normalized results |
+| Batch reports | Unsupported | Use individual definitions |
+| Enhanced Measurement | Experimental | Validated declaration and finding only; no mutation |
+| Google Signals | Experimental | Validated declaration and finding only; no mutation |
+| Consent coverage | Manual | Must be verified in tagging/consent systems |
+| Ads-personalization regions | Manual | Not inferred from similarly named API fields |
+| Stream data redaction | Manual | UI/API policy must be verified separately |
+| User-provided data setting | Unsupported | Not read or changed |
+| Event create/edit rules | Unsupported | Alpha, outside 0.1.0 |
+| Audiences and expanded datasets | Unsupported | Alpha, outside 0.1.0 |
+| Google Ads, AdSense, DV360, SA360 links | Unsupported | Not read or changed |
+| BigQuery links | Unsupported | Not read or changed |
+| Access bindings | Unsupported | Not read or changed |
+| Measurement Protocol secrets/events | Unsupported | Never managed |
+| Account/property/stream deletion | Unsupported | No destructive path |
+
+Google marks some Admin API capabilities as Alpha and warns that Alpha
+contracts may break. Analytics Ops never labels a capability managed merely
+because a generated class exists. The supported operations above have
+executable protobuf-coercion contract specs against the pinned official Ruby
+clients.
+
+References:
+
+- [Google Analytics Admin API overview](https://developers.google.com/analytics/devguides/config/admin/v1)
+- [Google Analytics Data API](https://developers.google.com/analytics/devguides/reporting/data/v1)
+- [Google Analytics Admin API changelog](https://developers.google.com/analytics/devguides/config/admin/v1/changelog)

data/docs/architecture.md

@@ -0,0 +1,89 @@
+# Architecture
+
+Analytics Ops is a plain-Ruby library and CLI with optional Rails hooks. It has
+no database and keeps Google's generated classes behind two narrow adapters.
+
+```text
+strict YAML
+  → immutable desired state
+  → Admin API snapshot
+  → deterministic planner
+  → versioned saved plan
+  → explicit guarded apply
+  → convergence verification
+
+immutable report definition
+  → Data API adapter
+  → immutable normalized result
+```
+
+## Core objects
+
+| Object | Responsibility |
+| --- | --- |
+| `Configuration` | Bounded safe YAML, environment interpolation, schema validation |
+| `DesiredState` | Immutable configuration for one profile |
+| `Resources` | Gem-owned account/property/stream/settings values |
+| `Snapshot` | Canonical managed remote state and SHA-256 fingerprint |
+| `Planner` | Pure desired-versus-snapshot comparison; no client access |
+| `Plan` | Strict deterministic JSON mutation contract |
+| `Applier` | Confirmation, fresh-snapshot check, sequential saved operations |
+| `Clients::Admin` | Official Admin request translation and response normalization |
+| `Reports::Definition` | Strict immutable Data API query |
+| `Clients::Data` | Standard/realtime request translation and result normalization |
+| `Workspace` | Public orchestration API with independently injectable clients |
+| `CLI` | Option validation, formats, stable statuses, and explicit confirmation |
+| `Railtie` | Optional generator and operator Rake tasks |
+
+## Dependency direction
+
+Domain and planning code know nothing about protobufs, gRPC, Rails, Active
+Support, OAuth flows, or HTTP transports. Admin and Data adapters translate
+official generated values immediately into immutable Analytics Ops values.
+The adapters can be injected independently, so tests use deterministic fakes.
+
+The core requires Google's wrapper gems lazily. Requiring `analytics_ops`
+defines classes only; it does not instantiate a client or discover ADC.
+
+## State model
+
+Google Analytics is the remote source of truth. There is no local state
+database. The configuration declares desired state and a snapshot captures the
+relevant remote state. Canonical key ordering and normalized arrays make
+snapshot fingerprints and plan bytes deterministic.
+
+Apply accepts an already validated plan, refreshes the snapshot, compares its
+fingerprint, then sends only the saved operations. A partial response is
+explicit reconciliation data, not a hidden retry or rollback.
+
+## Error boundary
+
+Expected failures become typed Analytics Ops errors:
+
+- configuration and invalid plan
+- authentication and authorization
+- unsupported capability and identity conflict
+- stale plan and confirmation required
+- quota, timeout, invalid request, and remote failure
+- partial apply with a structured result
+
+Messages are redacted before user-visible output. Callers do not need to parse
+Google exception text.
+
+An injected logger receives small JSON request events containing only the
+service method and target resource. Request bodies, authorization data, and
+report results are never logged automatically. CLI logging defaults to
+`warn`.
+
+## Rails boundary
+
+`require "analytics_ops/rails"` adds a Railtie only. It does not add an
+Engine, model, migration, route, controller, view, asset, or boot-time network
+call. Browser analytics and consent remain application concerns.
+
+## Experimental boundary
+
+Google identifies certain Admin capabilities as Alpha. Version 0.1.0 accepts
+explicit Enhanced Measurement and Google Signals declarations only so they can
+appear as experimental findings. It does not apply them. Stable/beta
+operations do not depend on an experimental public Analytics Ops contract.

data/docs/authentication.md

@@ -0,0 +1,86 @@
+# Authentication
+
+Analytics Ops uses [Google Application Default Credentials (ADC)](https://cloud.google.com/docs/authentication/application-default-credentials)
+through Google's official Ruby clients. It does not implement OAuth, store
+tokens, or accept credential fields in configuration.
+
+## Local read-only use
+
+Use an identity that has read access to the target GA4 property:
+
+```bash
+gcloud auth application-default login \
+  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"
+```
+
+Enable both APIs in the Google Cloud project used for authentication:
+
+- Google Analytics Admin API
+- Google Analytics Data API
+
+Then run:
+
+```bash
+analytics-ops doctor
+```
+
+`doctor` makes small read-only calls to both APIs. It confirms that Google
+accepts the credentials and that the property can be read. The installed
+clients do not expose a reliable contract for inspecting the scopes inside an
+already-issued token, so `doctor` reports scope inspection as `unknown`
+instead of guessing.
+
+## Applying changes
+
+Read-only credentials cannot apply a plan. Use a separately protected identity
+with the `analytics.edit` scope and sufficient access to the GA4 property:
+
+```bash
+gcloud auth application-default login \
+  --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly,https://www.googleapis.com/auth/analytics.edit"
+```
+
+Keep mutation credentials out of a deployed Rails web container. Apply plans
+from an administrator workstation or a protected release job.
+
+## Automation
+
+Prefer one of these:
+
+- A dedicated service account with only the GA properties and roles it needs.
+- Workload Identity Federation, which avoids a long-lived JSON key.
+- An explicitly injected Google credentials object when using the Ruby API.
+
+Cloud IAM permission alone does not grant access to a GA4 property. Add the
+service-account identity—such as
+`ga-reader@example-project.iam.gserviceaccount.com`—to the property with the
+appropriate Google Analytics role.
+
+## Values that are easy to confuse
+
+| Value | Example | Meaning |
+| --- | --- | --- |
+| Property ID | `123456789` | Numeric GA4 property identifier used by Admin and Data APIs |
+| Stream ID | `987654321` | Numeric data-stream resource identifier |
+| Measurement ID | `G-EXAMPLE1` | Web tagging identifier; not accepted as `property_id` or `stream_id` |
+| Account ID | `100000001` | Numeric Analytics account identifier shown by discovery |
+| OAuth client | Client ID and secret in your Cloud project | Starts a user OAuth flow; never put it in Analytics Ops YAML |
+| Service account | An IAM email identity | Receives GA property access; a JSON private key is credential material |
+
+## Credential rules
+
+- Never put credentials, paths to credentials, access tokens, refresh tokens,
+  private keys, API keys, or OAuth secrets in `analytics_ops.yml`.
+- Never put credentials in a saved plan.
+- Never commit service-account JSON.
+- Never paste credentials into an issue, fixture, log, or report.
+- Revoke or rotate credentials immediately after suspected exposure.
+- Do not create a shared public OAuth client for this gem.
+
+Analytics Ops redacts common credential patterns from translated errors, but
+redaction is a final safety net—not a safe way to handle secrets.
+
+Official Google setup references:
+
+- [Admin API quickstart](https://developers.google.com/analytics/devguides/config/admin/v1/quickstart)
+- [Data API quickstart](https://developers.google.com/analytics/devguides/reporting/data/v1/quickstart-client-libraries)