From cbe11093fa72b2a22fc12b449a62dfc3e91a7017 Mon Sep 17 00:00:00 2001 From: Vigneshraj Sekar Babu Date: Fri, 23 Jan 2026 14:03:07 -0800 Subject: [PATCH] docs: add ttl, configurable labels doc --- src/pages/docs/features/_meta.ts | 9 ++ .../docs/features/configurable-labels.mdx | 84 +++++++++++++++++ src/pages/docs/features/environment-ttl.mdx | 92 +++++++++++++++++++ 3 files changed, 185 insertions(+) create mode 100644 src/pages/docs/features/configurable-labels.mdx create mode 100644 src/pages/docs/features/environment-ttl.mdx diff --git a/src/pages/docs/features/_meta.ts b/src/pages/docs/features/_meta.ts index 8de6f0f..0609fb1 100644 --- a/src/pages/docs/features/_meta.ts +++ b/src/pages/docs/features/_meta.ts @@ -18,6 +18,9 @@ export default { "auto-deployment": { "title": "Auto Deploy & Labels" }, + "configurable-labels": { + "title": "Configurable Labels" + }, "template-variables": { "title": "Template Variables" }, @@ -29,5 +32,11 @@ export default { }, "native-helm-deployment": { "title": "Native Helm Deployment" + }, + "secrets": { + "title": "Cloud Secrets" + }, + "environment-ttl": { + "title": "Environment TTL" } }; \ No newline at end of file diff --git a/src/pages/docs/features/configurable-labels.mdx b/src/pages/docs/features/configurable-labels.mdx new file mode 100644 index 0000000..28a875a --- /dev/null +++ b/src/pages/docs/features/configurable-labels.mdx @@ -0,0 +1,84 @@ +--- +title: Configurable Labels +tags: + - labels + - configuration + - deploy + - disabled + - keep + - status-comments + - global-config +--- + +import { Callout } from "nextra/components"; + +Lifecycle allows you to customize the GitHub labels that control environment deployments, TTL behavior, and status comments through the `global_config.labels` configuration. + +## Configuration + +The labels configuration is stored in the `global_config` table with the key `labels`: + +```json +{ + "deploy": ["lifecycle-deploy!", "lfc-deploy"], + "disabled": ["lifecycle-disabled!", "lfc-skip"], + "keep": ["lifecycle-keep!", "lfc-keep"], + "statusComments": ["lifecycle-status-comments!"], + "defaultStatusComments": true, + "defaultControlComments": true +} +``` + +### `deploy` + +Labels that trigger environment deployment. When any deploy label is added to a PR, Lifecycle creates an ephemeral environment. The first label in the array is used when adding labels programmatically. Supports multiple labels for different teams or naming conventions. + +**Default:** `["lifecycle-deploy!"]` + +### `disabled` + +Labels that prevent or teardown deployments. When any disabled label is added or deploy label is removed, the active environment will be torn down. + +**Default:** `["lifecycle-disabled!"]` + +### `keep` + +Labels that disable TTL cleanup for an environment. When present on a PR, prevents automatic teardown due to inactivity and sets `lfc/ttl-enable: false` on the Kubernetes namespace. + +**Default:** `["lifecycle-keep!"]` + +### `statusComments` + +Labels that control status comment visibility on a per-PR basis. Behavior depends on the `defaultStatusComments` setting. + +**Default:** `["lifecycle-status-comments!"]` + +### `defaultStatusComments` + +Controls whether status comments are enabled by default across all PRs. When `true`, status comments show for all PRs. When `false`, status comments only show when the status comment label is present. + +**Default:** `true` + +### `defaultControlComments` + +Enables or disables control-related comments system-wide. + +**Default:** `true` + + + Changes to label configuration require refreshing the global config cache or + waiting for the automatic refresh cycle. + + +--- + +## Summary + +| Property | Type | Purpose | +| ------------------------ | -------- | ----------------------------------- | +| `deploy` | string[] | Trigger environment deployment | +| `disabled` | string[] | Prevent or teardown deployments | +| `keep` | string[] | Disable TTL cleanup | +| `statusComments` | string[] | Control status comment visibility | +| `defaultStatusComments` | boolean | Enable status comments by default | +| `defaultControlComments` | boolean | Enable control comments system-wide | diff --git a/src/pages/docs/features/environment-ttl.mdx b/src/pages/docs/features/environment-ttl.mdx new file mode 100644 index 0000000..6648f48 --- /dev/null +++ b/src/pages/docs/features/environment-ttl.mdx @@ -0,0 +1,92 @@ +--- +title: Environment TTL +tags: + - ttl + - cleanup + - lifecycle-keep + - inactivity + - global-config +--- + +import { Callout } from "nextra/components"; + +Lifecycle automatically cleans up inactive ephemeral environments based on configurable TTL (Time To Live) settings. This helps reduce resource usage while allowing teams to keep environments alive when needed. + +## Configuration + +The TTL cleanup configuration is stored in the `global_config` table with the key `ttl_cleanup`: + +```json +{ + "enabled": true, + "dryRun": false, + "inactivityDays": 14, + "checkIntervalMinutes": 240, + "commentTemplate": "This environment has been inactive for {inactivityDays} days and will be automatically cleaned up.", + "excludedRepositories": [] +} +``` + +### `enabled` + +Enables or disables automatic cleanup of inactive environments. + +**Default:** `false` + +### `dryRun` + +Runs cleanup process without actually tearing down environments. Useful for testing. + +**Default:** `true` + +### `inactivityDays` + +Number of days of inactivity before an environment is eligible for cleanup. + +**Default:** `14` + +### `checkIntervalMinutes` + +How frequently the cleanup job runs to check for stale environments. + +**Default:** `240` (4 hours) + +### `commentTemplate` + +Custom message posted to the PR when cleaning up. Supports `{inactivityDays}` placeholder and dynamic label replacements. + +**Default:** `"Tearing down lifecycle env since no activity in the past {inactivityDays} days."` + +### `excludedRepositories` + +Repository names (format: `owner/repo`) to exclude from automatic cleanup. + +**Default:** `[]` + + + Changes to TTL configuration require refreshing the global config cache or + waiting for the automatic refresh cycle. + + +--- + +## How It Works + +Lifecycle tracks environment expiration using `lfc/ttl-expireAtUnix` labels on Kubernetes namespaces. The cleanup service runs periodically to scan for expired environments, validates eligibility (PR is open, not static, not excluded), and tears down environments by removing the deploy label and adding the disabled label. + +### Preventing Cleanup + +Add the `keep` label to a PR to prevent automatic cleanup. This disables TTL on the namespace and keeps the environment alive indefinitely. See [Configurable Labels](/docs/features/configurable-labels) to customize the keep label. + +--- + +## Summary + +| Property | Type | Purpose | +| ---------------------- | -------- | ---------------------------------- | +| `enabled` | boolean | Enable/disable automatic cleanup | +| `dryRun` | boolean | Test mode without actual cleanup | +| `inactivityDays` | number | Days of inactivity before cleanup | +| `checkIntervalMinutes` | number | Cleanup job frequency in minutes | +| `commentTemplate` | string | Custom cleanup message for PRs | +| `excludedRepositories` | string[] | Repositories excluded from cleanup |