Publish bigquery-agent-analytics-tracing 0.1.0 to PyPI + Claude Code marketplace

[caohy1988]

Tracking the remaining publish work after the tracing-v0.1.0 GitHub release cut. Maps to the end of #234 step 4 (PyPI) and #234 step 5 (marketplace).

State

✅ Done:

• Release tag tracing-v0.1.0 cut; GitHub release has wheel, sdist, and Claude Code plugin tarball attached.
• release-tracing.yml workflow ran: verify / build / github-release all green.

❌ Pending:

• publish-testpypi and publish-pypi jobs failed on the first run because Trusted Publishers aren't configured yet (expected — see run #26481268141).
• No Claude Code marketplace catalog exists yet, so users have no /plugin install path.

Track 1 — PyPI Trusted Publishing (maintainer action)

Trusted Publisher values (from the OIDC claim set the failed run logged):

Field	Value
Project name	bigquery-agent-analytics-tracing
Owner	GoogleCloudPlatform
Repository	BigQuery-Agent-Analytics-SDK
Workflow filename	release-tracing.yml
Environment	testpypi (TestPyPI) / pypi (PyPI)

Docs: https://docs.pypi.org/trusted-publishers/adding-a-publisher/, https://docs.pypi.org/trusted-publishers/using-a-publisher/.

• A1. Create GitHub environment testpypi in repo Settings → Environments. No protection rules needed.
• A2. Create GitHub environment pypi with Required reviewers (at least one maintainer) so every PyPI publish needs a human OK. Recommended: also restrict to selected tags: tracing-v*.
• A3. Register pending publisher on TestPyPI at https://test.pypi.org/manage/account/publishing/ with the values above, environment = testpypi.
• A4. Register pending publisher on PyPI at https://pypi.org/manage/account/publishing/ with the values above, environment = pypi.
• A5. Re-run failed jobs on the existing release workflow — the wheel/sdist artifact is already built and uploaded, no new tag needed. Caveat: this only works while the release-tracing-dist workflow artifact is still retained (default 90 days, or whatever repo settings dictate). If retention has expired, run the full workflow against the existing tag — gh workflow run release-tracing.yml --ref tracing-v0.1.0 — to rebuild + re-upload the artifact before the publish jobs can pull it.
• A6. Verify TestPyPI install: pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ bigquery-agent-analytics-tracing==0.1.0.
• A7. Verify PyPI install (after the pypi environment approval is granted): pip install bigquery-agent-analytics-tracing==0.1.0. python -c \"from bigquery_agent_analytics_tracing import __version__; print(__version__)\" should print 0.1.0.

Track 2 — Claude Code marketplace

Correction from earlier guidance: The Claude Code marketplace docs at https://code.claude.com/docs/en/plugin-marketplaces list supported plugin source types as relative path, github, url, git-subdir, and npm. There is no github-release source type pointing at a release asset tarball. Do not point marketplace.json directly at the GitHub release tarball — that won't resolve.

Two shapes work. Recommended order: ship B0 (the in-repo fallback) now to unblock the install path, then move to B1–B4 (separate distribution repo) once someone with GoogleCloudPlatform/* repo-creation rights can set them up.

B0 — In-repo marketplace catalog (immediate, no new repos needed) — IMPLEMENTED IN #252

Adds the catalog + an expanded dist folder to this repo:

.claude-plugin/
└── marketplace.json
plugins/
└── claude_code_dist/
    └── bigquery-agent-analytics-tracing/
        ├── .claude-plugin/plugin.json   # stamped 0.1.0
        ├── hooks/
        ├── commands/
        ├── scripts/
        ├── vendor/
        ├── MARKETPLACE.md
        └── README.md

marketplace.json uses a relative plugin source:

{
  "name": "bqaa-tracing",
  "owner": { "name": "Google LLC" },
  "plugins": [
    {
      "name": "bigquery-agent-analytics-tracing",
      "source": "./plugins/claude_code_dist/bigquery-agent-analytics-tracing",
      "description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
      "version": "0.1.0",
      "author": { "name": "Google LLC" },
      "license": "Apache-2.0"
    }
  ]
}

Users install with a Git-source add, optionally sparse to skip the rest of the SDK repo:

/plugin marketplace add GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK --sparse .claude-plugin plugins/claude_code_dist
/plugin install bigquery-agent-analytics-tracing@bqaa-tracing

Critical constraint: the marketplace MUST be added via the Git source form (<owner>/<repo>), not by passing a direct URL to marketplace.json. Relative source paths only resolve when Claude Code has a local checkout of the surrounding repo to walk into. A direct-URL add fetches only the catalog JSON; the install would then fail to resolve ./plugins/claude_code_dist/....

Status:

• B0.1. PR #252 opened with the catalog + dist folder + README install-path swap.
• B0.2. Merge plugins: add Claude Code marketplace catalog + 0.1.0 dist folder #252.
• B0.3. claude plugin validate . against the merged catalog (validates the manifest shape against the current Claude CLI schema).
• B0.4. Fresh-session install smoke against a scratch BQ dataset; assert attributes.writer.version = '0.1.0' on the resulting rows.

B1 — Plugin distribution repo (the resolved plugin artifact, committed and tagged)

• B1.1. Create repo GoogleCloudPlatform/bqaa-tracing-claude-code-plugin.
• B1.2. Populate it with the built plugin tarball contents (not source — vendor/ is generated and gitignored in source, and the source plugin.json has the 0.0.0+local placeholder):

  bqaa-tracing-claude-code-plugin/
  ├── .claude-plugin/plugin.json    # stamped 0.1.0
  ├── hooks/
  ├── commands/
  ├── scripts/
  ├── vendor/                       # includes .dist-info/METADATA so writer.version resolves
  ├── MARKETPLACE.md
  └── README.md
  

  Source: extract bigquery-agent-analytics-tracing-claude-code-0.1.0.tar.gz from the GitHub release.
• B1.3. Tag the repo:

  git tag -a v0.1.0 -m "bqaa tracing claude code plugin 0.1.0"
  git push origin v0.1.0

• B1.4. Add release automation to this repo so future tracing-vX.Y.Z cuts on the SDK repo automatically PR the new tarball contents over and tag here. Can be a separate follow-up — manual sync is fine for v0.1.0.

B2 — Marketplace catalog repo

• B2.1. Create repo GoogleCloudPlatform/bqaa-tracing-marketplace.
• B2.2. Add .claude-plugin/marketplace.json with a github source pointing at the distribution repo's tag:

  {
    "name": "bqaa-tracing",
    "owner": {
      "name": "Google LLC",
      "url": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK"
    },
    "plugins": [
      {
        "name": "bigquery-agent-analytics-tracing",
        "description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
        "version": "0.1.0",
        "author": { "name": "Google LLC" },
        "source": {
          "source": "github",
          "repo": "GoogleCloudPlatform/bqaa-tracing-claude-code-plugin",
          "ref": "v0.1.0"
        },
        "homepage": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK/tree/main/plugins/claude_code",
        "repository": "https://github.com/GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK",
        "license": "Apache-2.0",
        "keywords": ["bigquery", "agent-analytics", "observability", "tracing", "claude-code"]
      }
    ]
  }

  Verify the exact field naming (source.type vs source.source, ref vs tag) against the current Claude Code docs and the version of claude CLI you're running. Some doc versions use \"source\": \"github\" shorthand for simple entries.

B3 — Validate locally before going public

• B3.1. From a clone of bqaa-tracing-marketplace:

  claude plugin validate .

  Resolve any schema errors. Iterate on the manifest shape until validation passes.
• B3.2. Load the local marketplace in a fresh Claude Code session:

  /plugin marketplace add /path/to/local/bqaa-tracing-marketplace
  /plugin install bigquery-agent-analytics-tracing@bqaa-tracing
  /bqaa-setup
  

  Send one real prompt, then query BigQuery:

  SELECT event_type, JSON_VALUE(attributes, '$.writer.version') AS writer_version,
         agent, timestamp
  FROM `your-project.your_dataset.agent_events`
  WHERE agent = 'claude-code'
  ORDER BY timestamp DESC LIMIT 5

  Expected: writer_version = '0.1.0'.

B4 — Publish + announce

• B4.1. Push the marketplace repo public.
• B4.2. Update plugins/claude_code/README.md in this repo to replace the curl-and-extract recipe with the marketplace install:

  /plugin marketplace add GoogleCloudPlatform/bqaa-tracing-marketplace
  /plugin install bigquery-agent-analytics-tracing@bqaa-tracing
  

• B4.3. Open a PR on this repo that updates the install docs + adds a pointer to the marketplace repo from MARKETPLACE.md.

B5 — Submit to Anthropic's official marketplace (after B1–B4 settle)

• B5.1. Once the self-hosted catalog has been validated by users for at least one release cycle, package the submission to Anthropic:
  • Plugin distribution repo URL + tag
  • Marketplace catalog repo URL
  • MARKETPLACE.md verification checklist (already in this repo)
  • Live BigQuery dry-run evidence (#242 comment)
  • Plugin metadata from .claude-plugin/plugin.json
• B5.2. Submit via the process documented at https://code.claude.com/docs/en/plugin-marketplaces#official-marketplace.

Ongoing release routine (after both tracks are live)

Once Trusted Publishing + marketplace catalog are wired up, the steady-state release process is:

1. Bump producers/pyproject.toml version → PR → merge.
2. git tag -a tracing-vX.Y.Z → git push origin tracing-vX.Y.Z on this repo.
3. release-tracing.yml does the rest (verify → build → github-release → publish-testpypi → publish-pypi).
4. Download bigquery-agent-analytics-tracing-claude-code-X.Y.Z.tar.gz from the new GitHub release. Extract into bqaa-tracing-claude-code-plugin repo, commit, tag vX.Y.Z, push.
5. Open PR on bqaa-tracing-marketplace bumping marketplace.json's version and source.ref. Merge.
6. Smoke test: fresh Claude Code session → /plugin install → confirm BigQuery rows tag with the new version.

Step 4 can be automated as a follow-up (cross-repo workflow trigger from this repo on tracing-v* tags).

References

• Move tracing producers (OpenAI Agents SDK, Codex CLI, Claude Code plugin) into this repo and publish PyPI + plugin artifacts #229 — umbrella issue (move tracing producers to this repo)
• Distribute tracing package and Claude Code plugin #234 — publish + plugin milestone
• producers: marketplace polish — /bqaa-setup slash command + IAM docs #242 — marketplace polish (just merged)
• producers: bump tracing 0.1.0.dev0 → 0.1.0 for first release #249 — version bump 0.1.0.dev0 → 0.1.0 (just merged)
• Trusted Publishing setup
• Claude Code marketplace docs
• Existing release workflow
• RELEASING.md runbook

[caohy1988]

Review suggestions after checking the current Claude Code marketplace docs:

1. Add an immediate fallback path that does not require creating new GoogleCloudPlatform/* repos. Since repo creation under the org is blocked for non-org members, Track 2 should include a B0 / B1-alt: in-repo marketplace catalog:

.claude-plugin/
└── marketplace.json
plugins/
└── claude_code_dist/
    └── bigquery-agent-analytics-tracing/
        ├── .claude-plugin/plugin.json   # stamped 0.1.0
        ├── hooks/
        ├── commands/
        ├── scripts/
        ├── vendor/
        ├── MARKETPLACE.md
        └── README.md

marketplace.json can then use a relative plugin source:

{
  "name": "bqaa-tracing",
  "owner": { "name": "Google LLC" },
  "plugins": [
    {
      "name": "bigquery-agent-analytics-tracing",
      "source": "./plugins/claude_code_dist/bigquery-agent-analytics-tracing",
      "description": "Stream Claude Code hook traces to Google BigQuery Agent Analytics agent_events.",
      "version": "0.1.0",
      "author": { "name": "Google LLC" },
      "license": "Apache-2.0"
    }
  ]
}

Users can add the marketplace from this repo, ideally with sparse checkout to avoid cloning the full SDK history/content:

/plugin marketplace add GoogleCloudPlatform/BigQuery-Agent-Analytics-SDK --sparse .claude-plugin plugins/claude_code_dist
/plugin install bigquery-agent-analytics-tracing@bqaa-tracing

This lets us ship the marketplace path immediately. The separate bqaa-tracing-claude-code-plugin + bqaa-tracing-marketplace repos can remain the cleaner long-term shape once someone with org permissions creates them.

2. Fix the sample external-repo github source object. The docs examples use "source": "github", not "type": "github":

"source": {
  "source": "github",
  "repo": "GoogleCloudPlatform/bqaa-tracing-claude-code-plugin",
  "ref": "v0.1.0"
}

The issue already says to verify source.type vs source.source; I would make this prescriptive now so nobody copies the likely-invalid shape.

3. Add one warning under the in-repo fallback: do not add the marketplace by direct URL to .claude-plugin/marketplace.json if using a relative plugin source. Relative sources only work when the marketplace is added via a Git source, because Claude Code needs the surrounding repo checkout to resolve ./plugins/....

4. Add an artifact-retention note to Track 1 A5. Re-running failed publish jobs from run #26481268141 works while the release-tracing-dist artifact is still retained. If artifact retention expires, maintainers may need to re-run the full release workflow/job set for the tracing-v0.1.0 tag rather than only the failed publish jobs.

Docs basis: Claude Code marketplace docs list relative path sources and github object sources, and explicitly note relative paths resolve from the marketplace root only for Git-hosted marketplaces: https://code.claude.com/docs/en/plugin-marketplaces

[caohy1988]

Applied the four review suggestions:

1. B0 (in-repo fallback) added at the top of Track 2 and marked IMPLEMENTED IN plugins: add Claude Code marketplace catalog + 0.1.0 dist folder #252. Promotes the in-repo path from "future contingency" to the recommended-first step, since GoogleCloudPlatform/* repo creation is blocked for non-org-members. B1–B4 stay as the long-term cleaner shape once someone with org rights can stand up the separate repos.
2. Fixed "type": "github" → "source": "github" in the B2.2 example so nobody copies the likely-invalid shape.
3. Git-source-vs-URL warning added in B0 (the constraint that relative source paths only resolve when the marketplace is added via /plugin marketplace add <owner>/<repo>, not via a direct URL to marketplace.json). Same warning landed in plugins/claude_code/README.md, plugins/claude_code_dist/README.md, and producers/README.md via plugins: add Claude Code marketplace catalog + 0.1.0 dist folder #252 → e7525e4.
4. Artifact-retention caveat added to A5 — gh workflow run release-tracing.yml --ref tracing-v0.1.0 is the recovery command if the release-tracing-dist workflow artifact has expired before the publish jobs get re-run.