From 469fb2e9e23d1654878866152bfe8341e674c6ba Mon Sep 17 00:00:00 2001 From: Adam Benhassen Date: Tue, 9 Dec 2025 23:30:38 +0100 Subject: [PATCH 1/3] docs: add retrieve app deployments based on last used data documentation and product update --- .../schema-registry/app-deployments.mdx | 82 +++++++++++++++++++ 1 file changed, 82 insertions(+) diff --git a/packages/web/docs/src/content/schema-registry/app-deployments.mdx b/packages/web/docs/src/content/schema-registry/app-deployments.mdx index 91f45a5b99..e76aea71ed 100644 --- a/packages/web/docs/src/content/schema-registry/app-deployments.mdx +++ b/packages/web/docs/src/content/schema-registry/app-deployments.mdx @@ -258,6 +258,88 @@ change to **retired**. - [`app:retire` API Reference](https://github.com/graphql-hive/console/tree/main/packages/libraries/cli#hive-appretire) +## Finding Stale App Deployments + +Hive tracks usage data for your app deployments. Each time a GraphQL request uses a persisted +document from an app deployment, Hive records when it was last used. This data helps you identify +app deployments that are candidates for retirement. + +### Usage Tracking + +When your GraphQL server or gateway reports usage to Hive, the `lastUsed` timestamp for the +corresponding app deployment is updated. You can see this information in the Hive dashboard or query +it via the GraphQL API. + +### Querying Stale Deployments via GraphQL API + +You can use the `activeAppDeployments` query to find app deployments that match specific criteria. +The date filters (`lastUsedBefore`, `neverUsedAndCreatedBefore`) use OR semantics. deployments +matching **either** date condition are returned. The `name` filter uses AND semantics to narrow down +results. + +```graphql +query FindStaleDeployments($target: TargetReferenceInput!) { + target(reference: $target) { + activeAppDeployments( + filter: { + # Optional: filter by app name (case-insensitive partial match) + name: "my-app" + # Deployments last used more than 30 days ago + lastUsedBefore: "2024-11-01T00:00:00Z" + # OR deployments that have never been used and are older than 30 days + neverUsedAndCreatedBefore: "2024-11-01T00:00:00Z" + } + ) { + edges { + node { + name + version + createdAt + lastUsed + } + } + } + } +} +``` + +| Filter Parameter | Description | +| --------------------------- | ------------------------------------------------------------------------------------------------ | +| `name` | Filter by app deployment name (case-insensitive partial match). Uses AND semantics. | +| `lastUsedBefore` | Return deployments that were last used before this timestamp. Uses OR with other date filter. | +| `neverUsedAndCreatedBefore` | Return deployments never used and created before this timestamp. Uses OR with other date filter. | + +### Retirement Workflow + +A typical workflow for retiring stale deployments: + +1. **Query stale deployments** using the `activeAppDeployments` query with appropriate filters +2. **Review the results** to ensure you're not retiring deployments still in use +3. **Retire deployments** using the `app:retire` CLI command or GraphQL mutation + +### Automated Cleanup + +For teams with many app deployments (e.g., one per PR or branch), you can automate cleanup by +combining the GraphQL API with the Hive CLI. + +Example script pattern: + +```bash +# Query stale deployments via GraphQL API +# Parse the response to get app names and versions +# Retire each deployment using the CLI: +hive app:retire \ + --registry.accessToken "" \ + --target "//" \ + --name "" \ + --version "" +``` + + + Always review deployments before retiring them programmatically. Consider protecting your latest + production deployment to avoid accidentally retiring active versions. + + ## Persisted Documents on GraphQL Server and Gateway Persisted documents can be used on your GraphQL server or Gateway to reduce the payload size of your From 0bef6db5224dd99a03e83ae9456236366d719bcc Mon Sep 17 00:00:00 2001 From: Adam Benhassen Date: Tue, 9 Dec 2025 23:36:22 +0100 Subject: [PATCH 2/3] add product update --- .../2025-12-09-stale-app-deployments/page.mdx | 65 +++++++++++++++++++ 1 file changed, 65 insertions(+) create mode 100644 packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx diff --git a/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx b/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx new file mode 100644 index 0000000000..6b0161ea1c --- /dev/null +++ b/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx @@ -0,0 +1,65 @@ +--- +title: Find and Clean Up Stale App Deployments +description: Query app deployments by last usage to identify candidates for retirement. +date: 2025-12-09 +authors: [adam] +--- + +Hive now tracks when each app deployment was last used, helping you identify stale deployments that +are candidates for retirement. + +## Query Stale Deployments + +Use the new `activeAppDeployments` query to find deployments based on usage: + +```graphql +query FindStaleDeployments($target: TargetReferenceInput!) { + target(reference: $target) { + activeAppDeployments( + filter: { + # Deployments last used more than 30 days ago + lastUsedBefore: "2024-11-01T00:00:00Z" + # OR deployments never used and older than 30 days + neverUsedAndCreatedBefore: "2024-11-01T00:00:00Z" + } + ) { + edges { + node { + name + version + createdAt + lastUsed + } + } + } + } +} +``` + +## Filter Options + +| Filter | Description | +| --------------------------- | ---------------------------------------------------------------- | +| `name` | Filter by deployment name (case-insensitive partial match) | +| `lastUsedBefore` | Deployments last used before this timestamp | +| `neverUsedAndCreatedBefore` | Deployments never used and created before this timestamp | + +The date filters use OR semantics—deployments matching either condition are returned. + +## Automated Cleanup + +For teams creating many deployments (e.g., one per PR), you can automate cleanup by combining the +GraphQL API with the Hive CLI: + +```bash +# Query stale deployments via GraphQL API, then retire each one: +hive app:retire \ + --registry.accessToken "" \ + --target "//" \ + --name "" \ + --version "" +``` + +--- + +- [Learn more about App Deployments](/docs/schema-registry/app-deployments) From eeed8597ea165446a8c5cf758ad2a3f8f7e4725f Mon Sep 17 00:00:00 2001 From: Adam Benhassen Date: Tue, 9 Dec 2025 23:39:55 +0100 Subject: [PATCH 3/3] prettier fix --- .../(posts)/2025-12-09-stale-app-deployments/page.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx b/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx index 6b0161ea1c..1ed02817d2 100644 --- a/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx +++ b/packages/web/docs/src/app/product-updates/(posts)/2025-12-09-stale-app-deployments/page.mdx @@ -38,11 +38,11 @@ query FindStaleDeployments($target: TargetReferenceInput!) { ## Filter Options -| Filter | Description | -| --------------------------- | ---------------------------------------------------------------- | -| `name` | Filter by deployment name (case-insensitive partial match) | -| `lastUsedBefore` | Deployments last used before this timestamp | -| `neverUsedAndCreatedBefore` | Deployments never used and created before this timestamp | +| Filter | Description | +| --------------------------- | ---------------------------------------------------------- | +| `name` | Filter by deployment name (case-insensitive partial match) | +| `lastUsedBefore` | Deployments last used before this timestamp | +| `neverUsedAndCreatedBefore` | Deployments never used and created before this timestamp | The date filters use OR semantics—deployments matching either condition are returned.