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..1ed02817d2 --- /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) 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