diff --git a/docs/user/reference/config/component-groups.md b/docs/user/reference/config/component-groups.md
index 6651a570..0bdd58ec 100644
--- a/docs/user/reference/config/component-groups.md
+++ b/docs/user/reference/config/component-groups.md
@@ -15,14 +15,14 @@ Component groups organize related components together and let you apply shared d
 
 ## Metadata
 
-The optional `[component-groups.<name>.metadata]` table documents the group's intent and provenance. It shares exactly the same fields and validation rules as [overlay metadata](overlays.md): a required `category`, plus optional commit/bug links and an upstreamable assessment. It is documentation only — it does not affect how members are resolved or built.
+The optional `[component-groups.<name>.metadata]` table documents the group's intent and provenance. It shares exactly the same fields and validation rules as [overlay metadata](overlays.md): a required `category`, a required `upstream-status`, and optional commit/bug links. It is documentation only — it does not affect how members are resolved or built.
 
 | Field | TOML Key | Type | Required | Description |
 |-------|----------|------|----------|-------------|
-| Category | `category` | enum | **Yes** | Classification of the group's intent (e.g. `backport-dist-git`, `azl-disable-flaky-tests`) |
-| Commits | `commits` | string array (URLs) | No | Upstream commit URLs this group references; required when `category = "backport-dist-git"` |
-| Bugs | `bugs` | array of `{ url = "..." }` tables | No | References to related issue-tracker entries; see [Bug references](overlays.md#bug-references) |
-| Upstreamable | `upstreamable` | boolean | No | Whether the group's change can be upstreamed (`true`/`false`); omit when not yet assessed |
+| Category | `category` | enum | **Yes** | Classification of the group's intent (e.g. `upstream-backport`, `azl-disable-flaky-tests`); see [Categories](overlays.md#categories) for the full list |
+| Upstream status | `upstream-status` | enum | **Yes** | Relationship to upstream (`upstreamed`, `upstreamable`, `needs-upstream-hook`, `inapplicable`, `unknown`); see [Upstream status](overlays.md#upstream-status). Must be `upstreamed` or `upstreamable` when `category = "upstream-backport"` |
+| Commits | `commits` | array of `{ url = "..." }` tables | Sometimes | Upstream commit references this group backports; required when `category = "upstream-backport"`. See [URL references](overlays.md#url-references) |
+| Bugs | `bugs` | array of `{ url = "..." }` tables | No | References to related issue-tracker entries; see [URL references](overlays.md#url-references) |
 
 ```toml
 [component-groups.check-skip-initial-failures]
@@ -31,7 +31,7 @@ components = ["bats", "dnf", "git"]
 
 [component-groups.check-skip-initial-failures.metadata]
 category = "azl-disable-flaky-tests"
-# upstreamable omitted: upstreamability for this group has not been assessed yet.
+upstream-status = "upstreamable"
 ```
 
 ## Component Membership
diff --git a/internal/projectconfig/loader_test.go b/internal/projectconfig/loader_test.go
index 71dd5d0f..67d781ce 100644
--- a/internal/projectconfig/loader_test.go
+++ b/internal/projectconfig/loader_test.go
@@ -491,10 +491,10 @@ func TestLoadAndResolveProjectConfig_ComponentGroupWithMetadata(t *testing.T) {
 specs = ["SPECS/**/*.spec"]
 
 [component-groups.core.metadata]
-category = "backport-dist-git"
-commits = ["https://example.com/commit/abc"]
+category = "upstream-backport"
+commits = [{ url = "https://example.com/commit/abc" }]
 bugs = [{ url = "https://example.com/bug/1" }]
-upstreamable = true
+upstream-status = "upstreamable"
 `
 
 	ctx := testctx.NewCtx()
@@ -506,11 +506,10 @@ upstreamable = true
 	if assert.Contains(t, config.ComponentGroups, "core") {
 		group := config.ComponentGroups["core"]
 		require.NotNil(t, group.Metadata)
-		assert.Equal(t, OverlayCategoryBackportDistGit, group.Metadata.Category)
-		assert.Equal(t, []string{"https://example.com/commit/abc"}, group.Metadata.Commits)
-		assert.Equal(t, []BugRef{{URL: "https://example.com/bug/1"}}, group.Metadata.Bugs)
-		require.NotNil(t, group.Metadata.Upstreamable)
-		assert.True(t, *group.Metadata.Upstreamable)
+		assert.Equal(t, OverlayCategoryUpstreamBackport, group.Metadata.Category)
+		assert.Equal(t, []URLRef{{URL: "https://example.com/commit/abc"}}, group.Metadata.Commits)
+		assert.Equal(t, []URLRef{{URL: "https://example.com/bug/1"}}, group.Metadata.Bugs)
+		assert.Equal(t, OverlayUpstreamStatusUpstreamable, group.Metadata.UpstreamStatus)
 	}
 }