customize dependency graph submission

.github/workflows/dependency-submission.yml

@@ -0,0 +1,47 @@
+name: Shipped dependency submission
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [ main ]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: shipped-dependency-submission
+  cancel-in-progress: false
+
+jobs:
+  dependency-submission:
+    # Never replace the default-branch inventory with a manually selected branch.
+    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+
+    - name: Set up JDK 17
+      uses: actions/setup-java@c1e323688fd81a25caa38c78aa6df2d33d3e20d9 # v4.8.0
+      with:
+        java-version: 17
+        distribution: 'temurin'
+
+    - name: Submit shipped dependencies
+      uses: gradle/actions/dependency-submission@9c971963bec38e04b3d30dcc455b5382be2fdbfb # v6.3.0
+      env:
+        # All selected library configurations describe shipped runtime dependencies.
+        DEPENDENCY_GRAPH_RUNTIME_INCLUDE_CONFIGURATIONS: '.*'
+      with:
+        cache-provider: basic
+        additional-arguments: --no-configuration-cache
+        # Include the shaded agent's source runtime graph: the agent's `internal`
+        # configuration sees the shadow JAR, not the libraries already bundled in it.
+        dependency-graph-include-projects: '^:(braintrust-sdk|braintrust-otel-extension|braintrust-java-agent(:internal)?)$'
+        # SDK: runtimeClasspath + non-transitive embed inputs.
+        # Extension / agent internals: runtimeClasspath.
+        # Agent: bootstrap + bootstrapLibs + internal packaging inputs.
+        # Do not include compile/test classpaths, examples, or compatibility tooling.
+        dependency-graph-include-configurations: '^(runtimeClasspath|embed|bootstrap|bootstrapLibs|internal)$'

CONTRIBUTING.md

@@ -20,3 +20,38 @@ Because the SDK is new and under active development, third-party contribution be
 ## Development
 
 See [AGENTS.md](./AGENTS.md) for best practices developing, testing, and releasing the SDK.
+
+## Dependency security alerts
+
+`.github/workflows/dependency-submission.yml` submits the shipped dependency graph
+on pushes to `main`, or through a manual run on the default branch. It does not
+enable Dependabot update PRs.
+
+The inventory includes the SDK's runtime and embedded inputs, the OTel extension's
+runtime dependencies, and the Java agent's bootstrap and internal packaging inputs.
+The agent's internal module is also scanned directly because its shaded JAR hides
+its bundled dependencies from the outer agent's dependency graph.
+
+Only these packaging projects and configurations contribute to the inventory.
+Dependencies used solely by tests, examples, build tooling, or compile-only
+instrumentation targets are excluded. Transitive dependencies that ship are still
+included, and submitted dependencies are marked as runtime. This is a shipped-product
+inventory, not a security inventory of everything executed during development or CI.
+
+When changing JAR assembly or adding a published artifact, update the workflow's
+project/configuration filters to cover its dependency inputs.
+
+### Switching from automatic dependency submission
+
+1. Merge the workflow to `main` and confirm **Shipped dependency submission** succeeds.
+2. Check **Insights → Dependency graph** for the filtered inventory. It should retain
+   Jackson, Byte Buddy, and the agent's OTel dependencies, without test-only frameworks.
+3. Under **Settings → Advanced Security → Dependency graph**, disable **Automatic
+   dependency submission** to stop the redundant, unfiltered submission job. Leave
+   the dependency graph and Dependabot alerts enabled. Security-update PRs can remain
+   disabled.
+
+The workflow saves its generated JSON snapshot as an Actions artifact for inspection.
+GitHub gives explicit workflow submissions precedence over automatic submissions for
+the same manifest, so the filtered inventory can be verified before disabling the
+automatic job.