@dash0/sdk-web 0.20.0 → 0.21.0

package/src/api/init_test.ts

@@ -1,7 +1,17 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import { InitOptions, InstrumentationName } from "../types/options";
 import { PropagatorConfig, Vars } from "../vars";
-import { SERVICE_NAME, SERVICE_NAMESPACE } from "../semantic-conventions";
+import {
+  SERVICE_NAME,
+  SERVICE_NAMESPACE,
+  VCS_CHANGE_ID,
+  VCS_OWNER_NAME,
+  VCS_PROVIDER_NAME,
+  VCS_REF_HEAD_NAME,
+  VCS_REF_HEAD_REVISION,
+  VCS_REPOSITORY_NAME,
+  VCS_REPOSITORY_URL_FULL,
+} from "../semantic-conventions";
 import { init as initFun } from "./init";
 
 // Mock all the instrumentation modules
@@ -397,4 +407,281 @@ describe("init", () => {
       expect(serviceNameAttr?.value.stringValue).toBe("unknown");
     });
   });
+
+  describe("vcs auto-detection", () => {
+    afterEach(() => {
+      vi.unstubAllEnvs();
+    });
+
+    const stringAttr = (key: string) => vars.resource.attributes.find((attr) => attr.key === key)?.value.stringValue;
+
+    it("derives full vcs resource attributes from Vercel env vars", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "dash0");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "main");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA", "abc123");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID", "42");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/dash0hq/dash0");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+      expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("abc123");
+      expect(stringAttr(VCS_CHANGE_ID)).toBe("42");
+    });
+
+    // The 9 framework prefixes Vercel auto-prefixes its VERCEL_GIT_* system
+    // vars under (per https://vercel.com/docs/environment-variables/framework-environment-variables).
+    // A passing test for each confirms the literal-accessor enumeration in
+    // detectVcsFromVercel is actually wired up.
+    const FRAMEWORK_PREFIX_SAMPLES: Array<[label: string, prefix: string]> = [
+      ["Next.js", "NEXT_PUBLIC_"],
+      ["Nuxt", "NUXT_ENV_"],
+      ["Create React App", "REACT_APP_"],
+      ["Gatsby", "GATSBY_"],
+      ["Vite", "VITE_"],
+      ["Astro / SvelteKit / Hydrogen", "PUBLIC_"],
+      ["Vue CLI", "VUE_APP_"],
+      ["RedwoodJS", "REDWOOD_ENV_"],
+      ["Sanity Studio", "SANITY_STUDIO_"],
+    ];
+
+    it.each(FRAMEWORK_PREFIX_SAMPLES)(
+      "derives Vercel vcs attributes from %s framework prefix (%s)",
+      (_label, prefix) => {
+        vi.stubEnv(`${prefix}VERCEL_GIT_PROVIDER`, "github");
+        vi.stubEnv(`${prefix}VERCEL_GIT_REPO_OWNER`, "dash0hq");
+        vi.stubEnv(`${prefix}VERCEL_GIT_REPO_SLUG`, "dash0");
+        vi.stubEnv(`${prefix}VERCEL_GIT_COMMIT_REF`, "main");
+        vi.stubEnv(`${prefix}VERCEL_GIT_COMMIT_SHA`, "abc123");
+        vi.stubEnv(`${prefix}VERCEL_GIT_PULL_REQUEST_ID`, "42");
+
+        init(baseOptions);
+
+        expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+        expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+        expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+        expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/dash0hq/dash0");
+        expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+        expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("abc123");
+        expect(stringAttr(VCS_CHANGE_ID)).toBe("42");
+      }
+    );
+
+    it.each(FRAMEWORK_PREFIX_SAMPLES)(
+      "derives Netlify vcs attributes from %s framework prefix (%s)",
+      (_label, prefix) => {
+        vi.stubEnv(`${prefix}REPOSITORY_URL`, "https://github.com/dash0hq/dash0");
+        vi.stubEnv(`${prefix}BRANCH`, "feature/x");
+        vi.stubEnv(`${prefix}COMMIT_REF`, "def456");
+        vi.stubEnv(`${prefix}REVIEW_ID`, "99");
+
+        init(baseOptions);
+
+        expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+        expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+        expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+        expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("feature/x");
+        expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("def456");
+        expect(stringAttr(VCS_CHANGE_ID)).toBe("99");
+      }
+    );
+
+    it("derives vcs resource attributes from Netlify env vars (parsed REPOSITORY_URL)", () => {
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://github.com/dash0hq/dash0.git");
+      vi.stubEnv("NEXT_PUBLIC_BRANCH", "feature/x");
+      vi.stubEnv("NEXT_PUBLIC_COMMIT_REF", "def456");
+      vi.stubEnv("NEXT_PUBLIC_REVIEW_ID", "99");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("dash0");
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/dash0hq/dash0.git");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("feature/x");
+      expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("def456");
+      expect(stringAttr(VCS_CHANGE_ID)).toBe("99");
+    });
+
+    it("prefers Vercel values over Netlify values when both are present", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "vercel-owner");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "vercel-repo");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "vercel-branch");
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://github.com/netlify-owner/netlify-repo");
+      vi.stubEnv("NEXT_PUBLIC_BRANCH", "netlify-branch");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("vercel-owner");
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("vercel-repo");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("vercel-branch");
+    });
+
+    it("opts.vcs overrides individual auto-detected fields", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "dash0");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "main");
+
+      init({
+        ...baseOptions,
+        vcs: {
+          refHeadName: "release/2026.06",
+          changeId: "1234",
+        },
+      });
+
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("dash0hq");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("release/2026.06");
+      expect(stringAttr(VCS_CHANGE_ID)).toBe("1234");
+    });
+
+    it("disableVcsDetection: true emits no vcs.* resource attributes even when env vars are set", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA", "abc123");
+
+      init({ ...baseOptions, disableVcsDetection: true });
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REF_HEAD_REVISION)).toBeUndefined();
+    });
+
+    it("disableVcsDetection: true still applies opts.vcs manual overrides", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "github");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "dash0hq");
+
+      init({
+        ...baseOptions,
+        disableVcsDetection: true,
+        vcs: { providerName: "gitlab", refHeadName: "release/1.0" },
+      });
+
+      // env-var values are suppressed
+      expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+      // manual overrides still win
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("gitlab");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("release/1.0");
+    });
+
+    it("applies opts.vcs fields as the sole source when no env vars are set", () => {
+      init({
+        ...baseOptions,
+        vcs: {
+          providerName: "github",
+          ownerName: "my-org",
+          repositoryName: "my-repo",
+          repositoryUrlFull: "https://github.com/my-org/my-repo",
+          refHeadName: "main",
+          refHeadRevision: "deadbeef",
+          changeId: "7",
+        },
+      });
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("my-org");
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("my-repo");
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://github.com/my-org/my-repo");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+      expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("deadbeef");
+      expect(stringAttr(VCS_CHANGE_ID)).toBe("7");
+    });
+
+    it("emits nothing when no env vars and no opts.vcs are provided", () => {
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBeUndefined();
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REF_HEAD_REVISION)).toBeUndefined();
+      expect(stringAttr(VCS_CHANGE_ID)).toBeUndefined();
+    });
+
+    it("emits only the partial attributes that are available", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA", "abc123");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF", "main");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+      expect(stringAttr(VCS_REF_HEAD_REVISION)).toBe("abc123");
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBeUndefined();
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+    });
+
+    it("does not derive repository URL when provider is unknown", () => {
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_PROVIDER", "someproprietary");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER", "owner");
+      vi.stubEnv("NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG", "repo");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("someproprietary");
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("owner");
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("repo");
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBeUndefined();
+    });
+
+    it("accepts gist.github.com as a github host alias", () => {
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://gist.github.com/owner/abc123");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("github");
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("owner");
+    });
+
+    it("rejects arbitrary github.com subdomains", () => {
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://evil.github.com/attacker/repo");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+    });
+
+    it("ignores a Netlify REPOSITORY_URL on an unknown host", () => {
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://internal-git.example.com/team/app");
+      vi.stubEnv("NEXT_PUBLIC_BRANCH", "main");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("https://internal-git.example.com/team/app");
+      expect(stringAttr(VCS_REF_HEAD_NAME)).toBe("main");
+    });
+
+    it("parses GitLab nested-group repository URLs to the last path segment", () => {
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "https://gitlab.com/group/subgroup/app.git");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBe("gitlab");
+      expect(stringAttr(VCS_OWNER_NAME)).toBe("group");
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBe("app");
+    });
+
+    it("ignores a malformed REPOSITORY_URL", () => {
+      vi.stubEnv("NEXT_PUBLIC_REPOSITORY_URL", "not-a-url");
+
+      init(baseOptions);
+
+      expect(stringAttr(VCS_REPOSITORY_URL_FULL)).toBe("not-a-url");
+      expect(stringAttr(VCS_PROVIDER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_OWNER_NAME)).toBeUndefined();
+      expect(stringAttr(VCS_REPOSITORY_NAME)).toBeUndefined();
+    });
+  });
 });

package/src/api/vcs.ts

@@ -0,0 +1,359 @@
+import { vars } from "../vars";
+import {
+  VCS_CHANGE_ID,
+  VCS_OWNER_NAME,
+  VCS_PROVIDER_NAME,
+  VCS_REF_HEAD_NAME,
+  VCS_REF_HEAD_REVISION,
+  VCS_REPOSITORY_NAME,
+  VCS_REPOSITORY_URL_FULL,
+} from "../semantic-conventions";
+import { InitOptions, VcsAttributes } from "../types/options";
+import { addAttribute } from "../utils/otel";
+
+// Module-local typing for the `process` global. The SDK does not depend on
+// @types/node, and bundler substitution requires literal `process.env.NAME`
+// accessors (dot notation, not bracket lookup). We enumerate the exact set of
+// env var names the readers below access via template-literal types — typos
+// are caught at compile time, and `noPropertyAccessFromIndexSignature` does
+// not fire because each key is a known union member, not an index signature.
+//
+// Adding a new framework prefix here automatically permits every combination
+// with every known suffix. Adding a vendor suffix permits every combination
+// with every known prefix.
+type FrameworkPrefix =
+  | "NEXT_PUBLIC_"
+  | "NUXT_ENV_"
+  | "REACT_APP_"
+  | "GATSBY_"
+  | "VITE_"
+  | "PUBLIC_"
+  | "VUE_APP_"
+  | "REDWOOD_ENV_"
+  | "SANITY_STUDIO_";
+
+type VercelGitSuffix =
+  | "VERCEL_GIT_PROVIDER"
+  | "VERCEL_GIT_REPO_OWNER"
+  | "VERCEL_GIT_REPO_SLUG"
+  | "VERCEL_GIT_COMMIT_REF"
+  | "VERCEL_GIT_COMMIT_SHA"
+  | "VERCEL_GIT_PULL_REQUEST_ID";
+
+type NetlifyGitSuffix = "REPOSITORY_URL" | "BRANCH" | "COMMIT_REF" | "REVIEW_ID";
+
+type BrowserBuildEnvKey = `${FrameworkPrefix}${VercelGitSuffix | NetlifyGitSuffix}`;
+
+type BrowserBuildEnv = { readonly [K in BrowserBuildEnvKey]?: string };
+
+declare const process: { env?: BrowserBuildEnv } | undefined;
+
+// Single source of truth mapping each VcsAttributes field to its OTel
+// resource attribute name. Typed as `Record<keyof VcsAttributes, string>` so
+// adding a field to VcsAttributes without adding an entry here is a compile
+// error — no silent "I forgot to apply that field" bugs.
+const VCS_FIELD_TO_ATTRIBUTE: Record<keyof VcsAttributes, string> = {
+  providerName: VCS_PROVIDER_NAME,
+  ownerName: VCS_OWNER_NAME,
+  repositoryName: VCS_REPOSITORY_NAME,
+  repositoryUrlFull: VCS_REPOSITORY_URL_FULL,
+  refHeadName: VCS_REF_HEAD_NAME,
+  refHeadRevision: VCS_REF_HEAD_REVISION,
+  changeId: VCS_CHANGE_ID,
+};
+
+/**
+ * Derive VCS (version control) context from the build environment and apply
+ * the resulting `vcs.*` resource attributes to `vars.resource.attributes`.
+ *
+ * Detection precedence per attribute: `opts.vcs` → Vercel env vars → Netlify
+ * env vars. Manual overrides via `opts.vcs` always win, even when
+ * `opts.disableVcsDetection` is set.
+ */
+export function applyVcsResourceAttributes(opts: InitOptions) {
+  const vcs = detectVcs(opts);
+  for (const field of Object.keys(VCS_FIELD_TO_ATTRIBUTE) as (keyof VcsAttributes)[]) {
+    const value = vcs[field];
+    if (value) {
+      addAttribute(vars.resource.attributes, VCS_FIELD_TO_ATTRIBUTE[field], value);
+    }
+  }
+}
+
+function detectVcs(opts: InitOptions): VcsAttributes {
+  // opts.vcs manual overrides always win, even when auto-detection is disabled.
+  // This lets callers on non-Vercel/Netlify platforms supply context explicitly
+  // while still opting out of any env-var reading.
+  const override = opts.vcs ?? {};
+
+  if (opts.disableVcsDetection) {
+    return override;
+  }
+
+  const vercel = detectVcsFromVercel();
+  const netlify = detectVcsFromNetlify();
+
+  return {
+    providerName: override.providerName ?? vercel.providerName ?? netlify.providerName,
+    ownerName: override.ownerName ?? vercel.ownerName ?? netlify.ownerName,
+    repositoryName: override.repositoryName ?? vercel.repositoryName ?? netlify.repositoryName,
+    repositoryUrlFull: override.repositoryUrlFull ?? vercel.repositoryUrlFull ?? netlify.repositoryUrlFull,
+    refHeadName: override.refHeadName ?? vercel.refHeadName ?? netlify.refHeadName,
+    refHeadRevision: override.refHeadRevision ?? vercel.refHeadRevision ?? netlify.refHeadRevision,
+    changeId: override.changeId ?? vercel.changeId ?? netlify.changeId,
+  };
+}
+
+// Frameworks expose env vars to the browser bundle using a per-framework
+// prefix (Next.js `NEXT_PUBLIC_*`, Vite `VITE_*`, etc.). For each known
+// vendor suffix (e.g. Vercel's `VERCEL_GIT_PROVIDER`, Netlify's
+// `REPOSITORY_URL`) we enumerate the prefixed variants below.
+//
+// IMPORTANT: each `process.env.NAME` MUST be a LITERAL accessor. Webpack
+// DefinePlugin, Next.js, Gatsby, and equivalents substitute env vars at
+// build time only when they see the literal form. Dynamic lookups like
+// `process.env[name]` or iterating a string array are NOT substituted —
+// they would resolve to `undefined` in the browser bundle.
+//
+// The 9 prefixes below are the framework presets Vercel auto-prefixes
+// `VERCEL_*` system vars under (https://vercel.com/docs/environment-variables/framework-environment-variables).
+// Users on platforms without auto-prefixing (Netlify, Cloudflare Pages, custom
+// CI) can manually expose any env var under any of these prefixes and get
+// the same auto-detection.
+//
+// Adding a new framework prefix = one new literal accessor per attribute in
+// each `detectVcsFrom*` function below.
+
+function detectVcsFromVercel(): VcsAttributes {
+  let provider: string | undefined;
+  let owner: string | undefined;
+  let repo: string | undefined;
+  let ref: string | undefined;
+  let revision: string | undefined;
+  let changeId: string | undefined;
+  try {
+    provider = pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_GIT_PROVIDER,
+      process?.env?.NUXT_ENV_VERCEL_GIT_PROVIDER,
+      process?.env?.REACT_APP_VERCEL_GIT_PROVIDER,
+      process?.env?.GATSBY_VERCEL_GIT_PROVIDER,
+      process?.env?.VITE_VERCEL_GIT_PROVIDER,
+      process?.env?.PUBLIC_VERCEL_GIT_PROVIDER,
+      process?.env?.VUE_APP_VERCEL_GIT_PROVIDER,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_PROVIDER,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_PROVIDER
+    );
+    owner = pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_GIT_REPO_OWNER,
+      process?.env?.NUXT_ENV_VERCEL_GIT_REPO_OWNER,
+      process?.env?.REACT_APP_VERCEL_GIT_REPO_OWNER,
+      process?.env?.GATSBY_VERCEL_GIT_REPO_OWNER,
+      process?.env?.VITE_VERCEL_GIT_REPO_OWNER,
+      process?.env?.PUBLIC_VERCEL_GIT_REPO_OWNER,
+      process?.env?.VUE_APP_VERCEL_GIT_REPO_OWNER,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_REPO_OWNER,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_REPO_OWNER
+    );
+    repo = pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_GIT_REPO_SLUG,
+      process?.env?.NUXT_ENV_VERCEL_GIT_REPO_SLUG,
+      process?.env?.REACT_APP_VERCEL_GIT_REPO_SLUG,
+      process?.env?.GATSBY_VERCEL_GIT_REPO_SLUG,
+      process?.env?.VITE_VERCEL_GIT_REPO_SLUG,
+      process?.env?.PUBLIC_VERCEL_GIT_REPO_SLUG,
+      process?.env?.VUE_APP_VERCEL_GIT_REPO_SLUG,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_REPO_SLUG,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_REPO_SLUG
+    );
+    ref = pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_GIT_COMMIT_REF,
+      process?.env?.NUXT_ENV_VERCEL_GIT_COMMIT_REF,
+      process?.env?.REACT_APP_VERCEL_GIT_COMMIT_REF,
+      process?.env?.GATSBY_VERCEL_GIT_COMMIT_REF,
+      process?.env?.VITE_VERCEL_GIT_COMMIT_REF,
+      process?.env?.PUBLIC_VERCEL_GIT_COMMIT_REF,
+      process?.env?.VUE_APP_VERCEL_GIT_COMMIT_REF,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_COMMIT_REF,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_COMMIT_REF
+    );
+    revision = pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.NUXT_ENV_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.REACT_APP_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.GATSBY_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.VITE_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.PUBLIC_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.VUE_APP_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_COMMIT_SHA,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_COMMIT_SHA
+    );
+    changeId = pickFirstString(
+      process?.env?.NEXT_PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.NUXT_ENV_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.REACT_APP_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.GATSBY_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.VITE_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.PUBLIC_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.VUE_APP_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.REDWOOD_ENV_VERCEL_GIT_PULL_REQUEST_ID,
+      process?.env?.SANITY_STUDIO_VERCEL_GIT_PULL_REQUEST_ID
+    );
+  } catch (_ignored) {
+    // process is not defined (or a bundler shimmed it strangely) — skip.
+  }
+
+  return {
+    providerName: provider,
+    ownerName: owner,
+    repositoryName: repo,
+    repositoryUrlFull: buildRepositoryUrlFromVercel(provider, owner, repo),
+    refHeadName: ref,
+    refHeadRevision: revision,
+    changeId,
+  };
+}
+
+function detectVcsFromNetlify(): VcsAttributes {
+  // Netlify exposes read-only build env vars (REPOSITORY_URL, BRANCH,
+  // COMMIT_REF, REVIEW_ID) but does not auto-prefix them for browser
+  // exposure. Users must surface them via their framework's prefix
+  // convention themselves (e.g. `NEXT_PUBLIC_REPOSITORY_URL = $REPOSITORY_URL`
+  // for Next.js, `VITE_REPOSITORY_URL = $REPOSITORY_URL` for Vite, etc.).
+  // We enumerate the same 9 framework prefixes as the Vercel path above.
+  let repositoryUrl: string | undefined;
+  let branch: string | undefined;
+  let commit: string | undefined;
+  let reviewId: string | undefined;
+  try {
+    repositoryUrl = pickFirstString(
+      process?.env?.NEXT_PUBLIC_REPOSITORY_URL,
+      process?.env?.NUXT_ENV_REPOSITORY_URL,
+      process?.env?.REACT_APP_REPOSITORY_URL,
+      process?.env?.GATSBY_REPOSITORY_URL,
+      process?.env?.VITE_REPOSITORY_URL,
+      process?.env?.PUBLIC_REPOSITORY_URL,
+      process?.env?.VUE_APP_REPOSITORY_URL,
+      process?.env?.REDWOOD_ENV_REPOSITORY_URL,
+      process?.env?.SANITY_STUDIO_REPOSITORY_URL
+    );
+    branch = pickFirstString(
+      process?.env?.NEXT_PUBLIC_BRANCH,
+      process?.env?.NUXT_ENV_BRANCH,
+      process?.env?.REACT_APP_BRANCH,
+      process?.env?.GATSBY_BRANCH,
+      process?.env?.VITE_BRANCH,
+      process?.env?.PUBLIC_BRANCH,
+      process?.env?.VUE_APP_BRANCH,
+      process?.env?.REDWOOD_ENV_BRANCH,
+      process?.env?.SANITY_STUDIO_BRANCH
+    );
+    commit = pickFirstString(
+      process?.env?.NEXT_PUBLIC_COMMIT_REF,
+      process?.env?.NUXT_ENV_COMMIT_REF,
+      process?.env?.REACT_APP_COMMIT_REF,
+      process?.env?.GATSBY_COMMIT_REF,
+      process?.env?.VITE_COMMIT_REF,
+      process?.env?.PUBLIC_COMMIT_REF,
+      process?.env?.VUE_APP_COMMIT_REF,
+      process?.env?.REDWOOD_ENV_COMMIT_REF,
+      process?.env?.SANITY_STUDIO_COMMIT_REF
+    );
+    reviewId = pickFirstString(
+      process?.env?.NEXT_PUBLIC_REVIEW_ID,
+      process?.env?.NUXT_ENV_REVIEW_ID,
+      process?.env?.REACT_APP_REVIEW_ID,
+      process?.env?.GATSBY_REVIEW_ID,
+      process?.env?.VITE_REVIEW_ID,
+      process?.env?.PUBLIC_REVIEW_ID,
+      process?.env?.VUE_APP_REVIEW_ID,
+      process?.env?.REDWOOD_ENV_REVIEW_ID,
+      process?.env?.SANITY_STUDIO_REVIEW_ID
+    );
+  } catch (_ignored) {
+    // process is not defined — skip.
+  }
+
+  const parsed = parseRepositoryUrl(repositoryUrl);
+  return {
+    providerName: parsed?.providerName,
+    ownerName: parsed?.ownerName,
+    repositoryName: parsed?.repositoryName,
+    repositoryUrlFull: repositoryUrl,
+    refHeadName: branch,
+    refHeadRevision: commit,
+    changeId: reviewId,
+  };
+}
+
+function pickFirstString(...values: (string | undefined)[]): string | undefined {
+  for (const value of values) {
+    if (value) return value;
+  }
+  return undefined;
+}
+
+function buildRepositoryUrlFromVercel(
+  provider: string | undefined,
+  owner: string | undefined,
+  repo: string | undefined
+): string | undefined {
+  if (!provider || !owner || !repo) return undefined;
+  const host = vcsHostForProvider(provider);
+  if (!host) return undefined;
+  return `https://${host}/${owner}/${repo}`;
+}
+
+// Single source of truth for provider↔host mapping. Both `vcsHostForProvider`
+// (Vercel path: provider name is known, derive the canonical host) and
+// `vcsProviderForHost` (Netlify path: only the URL is known, derive the
+// provider) consult this map so adding a provider is one edit. Each entry is
+// a list of accepted hostnames; the FIRST entry is the canonical host used
+// when building URLs from a provider name. Subsequent entries are exact
+// aliases — we do not match arbitrary subdomains.
+const VCS_PROVIDER_HOSTS: Record<string, readonly string[]> = {
+  github: ["github.com", "gist.github.com"],
+  gitlab: ["gitlab.com"],
+  bitbucket: ["bitbucket.org"],
+};
+
+function vcsHostForProvider(provider: string): string | undefined {
+  return VCS_PROVIDER_HOSTS[provider]?.[0];
+}
+
+function parseRepositoryUrl(
+  url: string | undefined
+): { providerName: string; ownerName: string; repositoryName: string } | undefined {
+  if (!url) return undefined;
+
+  let host: string;
+  let pathname: string;
+  try {
+    const parsed = new URL(url);
+    host = parsed.host;
+    pathname = parsed.pathname;
+  } catch (_ignored) {
+    return undefined;
+  }
+
+  const provider = vcsProviderForHost(host);
+  if (!provider) return undefined;
+
+  const trimmed = pathname.replace(/^\/+/, "").replace(/\.git$/, "");
+  const segments = trimmed.split("/");
+  if (segments.length < 2) return undefined;
+
+  const ownerName = segments[0];
+  // Bitbucket and GitLab can have nested groups; the repository slug is the
+  // last path segment. GitHub paths are always two segments.
+  const repositoryName = segments[segments.length - 1];
+  if (!ownerName || !repositoryName) return undefined;
+
+  return { providerName: provider, ownerName, repositoryName };
+}
+
+function vcsProviderForHost(host: string): string | undefined {
+  for (const [provider, hosts] of Object.entries(VCS_PROVIDER_HOSTS)) {
+    if (hosts.includes(host)) return provider;
+  }
+  return undefined;
+}

package/src/semantic-conventions.ts

@@ -6,6 +6,15 @@ export const DEPLOYMENT_ENVIRONMENT_NAME = "deployment.environment.name";
 export const DEPLOYMENT_NAME = "deployment.name";
 export const DEPLOYMENT_ID = "deployment.id";
 
+// VCS Resource Attribute Keys
+export const VCS_PROVIDER_NAME = "vcs.provider.name";
+export const VCS_OWNER_NAME = "vcs.owner.name";
+export const VCS_REPOSITORY_NAME = "vcs.repository.name";
+export const VCS_REPOSITORY_URL_FULL = "vcs.repository.url.full";
+export const VCS_REF_HEAD_NAME = "vcs.ref.head.name";
+export const VCS_REF_HEAD_REVISION = "vcs.ref.head.revision";
+export const VCS_CHANGE_ID = "vcs.change.id";
+
 // Misc Signal Attribute Keys
 export const EVENT_NAME = "event.name";
 export const WEB_EVENT_TITLE = "dash0.web.event.title";