AgentSkillsCN

deployment-management

通过列出、筛选和清理操作管理LangGraph Cloud部署。当管理测试部署、清理孤立资源、按名称模式筛选，或处理批量删除时使用。自动从devcontainer环境获取凭据。

SKILL.md
--- frontmatter
name: deployment-management
description: Managing LangGraph Cloud deployments through listing, filtering, and cleanup operations. Use when managing test deployments, cleaning up orphaned resources, filtering by name patterns, or handling bulk deletion. Automatically sources credentials from devcontainer environment.
scope: project

Deployment Management

Manage LangGraph Cloud deployments using the Langstar CLI with focus on test deployment cleanup, filtering, and environment handling.

Core Capabilities

  • •List deployments with filtering by name, status, or type
  • •Filter test deployments by pattern (test-, langstar-test-)
  • •Delete deployments individually or in batch
  • •Handle environment variables automatically (check first, source if needed)
  • •Interactive confirmation for destructive operations

Table of Contents

Prerequisites

Required Credentials

LangSmith API:

  • •LANGSMITH_API_KEY - API key for Control Plane authentication
  • •LANGSMITH_WORKSPACE_ID - Workspace ID (optional if using organization)

Location: /workspace/.devcontainer/.env (gitignored)

CLI Tool

All operations use langstar graph commands:

  • •langstar graph list - List with filtering
  • •langstar graph get <id> - Get details
  • •langstar graph delete <id> - Delete deployment

Environment Handling

Critical Pattern: Check Before Sourcing

Always check if credentials exist BEFORE sourcing:

bash
# ✅ CORRECT: Check first
if [ -z "$LANGSMITH_API_KEY" ] || [ -z "$LANGSMITH_WORKSPACE_ID" ]; then
    echo "📋 Sourcing credentials..."
    source /workspace/.devcontainer/.env
fi

# Verify (never expose actual values)
[ -n "$LANGSMITH_API_KEY" ] && echo "✓ LANGSMITH_API_KEY set" || echo "❌ Not set"

Security Rule: Never expose credential values:

bash
# ❌ WRONG: Exposes sensitive data
echo "Key: $LANGSMITH_API_KEY"

# ✅ CORRECT: Only check presence
[ -n "$LANGSMITH_API_KEY" ] && echo "Set" || echo "Not set"

Core Workflows

Workflow 1: List All Deployments

bash
# Source credentials if needed
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# List deployments
langstar graph list --limit 20

Output:

code
┌────────────────────────────────┬──────────────────────┬────────┐
│ Name                           │ ID                   │ Status │
├────────────────────────────────┼──────────────────────┼────────┤
│ langstar-test-1763668434       │ 97dff6a5-f844-472... │ Ready  │
│ test-deployment-1763666536     │ 8665a96b-4620-407... │ Ready  │
└────────────────────────────────┴──────────────────────┴────────┘

Workflow 2: Filter by Name Pattern

bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# Filter by substring
langstar graph list --name-contains "test"
langstar graph list --name-contains "langstar-test"

# Combine filters
langstar graph list --name-contains "test" --status READY --limit 100

Workflow 3: Delete Single Deployment

bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# Interactive deletion (prompts for confirmation)
langstar graph delete <deployment-id>

# Skip confirmation
langstar graph delete <deployment-id> --yes

Workflow 4: Batch Cleanup of Test Deployments

Recommended: Interactive review before each deletion

bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# List test deployments to review
langstar graph list --name-contains "test" --limit 100

# Get deployment IDs
deployment_ids=$(langstar graph list --name-contains "test" --limit 100 --format json | jq -r '.resources[].id')

# Delete with confirmation for each
for id in $deployment_ids; do
    echo "Deployment: $id"
    langstar graph get "$id" | jq '{name, status, created_at}'
    read -p "Delete? (y/n): " confirm
    [ "$confirm" = "y" ] && langstar graph delete "$id" --yes && echo "✓ Deleted"
done

Alternative: Bulk deletion (use with caution)

See examples/batch-cleanup.md for non-interactive scripts.

Workflow 5: Filter by Status or Type

Available filters:

  • •Status: READY, AWAITING_DATABASE, UNUSED, AWAITING_DELETE
  • •Type: dev_free, dev, prod
bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

# Filter by status
langstar graph list --status READY
langstar graph list --status UNUSED

# Filter by type
langstar graph list --deployment-type dev_free

# Combine filters
langstar graph list --name-contains "test" --status READY

CLI Reference

list - List deployments

bash
langstar graph list [OPTIONS]

Options:
  -l, --limit <N>              Max to return [default: 20]
      --offset <N>             Pagination offset [default: 0]
      --name-contains <STR>    Filter by name substring
      --status <STATUS>        Filter: READY, AWAITING_DATABASE, UNUSED, etc.
      --deployment-type <TYPE> Filter: dev_free, dev, prod
  -f, --format <FORMAT>        Output: text, json [default: text]

get - Get deployment details

bash
langstar graph get <DEPLOYMENT_ID>

Returns full deployment JSON including source config, status, timestamps, and revisions.

delete - Delete deployment

bash
langstar graph delete <DEPLOYMENT_ID> [OPTIONS]

Options:
  -y, --yes    Skip confirmation prompt

Best Practices

Environment Variables

✅ Check before sourcing

bash
if [ -z "$LANGSMITH_API_KEY" ]; then
    source /workspace/.devcontainer/.env
fi

✅ Never expose values

bash
[ -n "$LANGSMITH_API_KEY" ] && echo "✓ Set" || echo "✗ Not set"

Deployment Deletion

✅ Review before deleting

bash
# List first, verify, then delete
langstar graph list --name-contains "test"
langstar graph delete <id> --yes

✅ Interactive confirmation for batch

bash
# Confirm each deletion
for id in $ids; do
    read -p "Delete $id? (y/n): " confirm
    [ "$confirm" = "y" ] && langstar graph delete "$id" --yes
done

Filtering

✅ Use specific patterns

bash
# Specific reduces false matches
langstar graph list --name-contains "langstar-test-"

✅ Combine filters for precision

bash
langstar graph list --name-contains "test" --status READY --deployment-type dev_free

Common Use Cases

Clean Up After Integration Tests

bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi

# List test deployments
langstar graph list --name-contains "langstar-test"
langstar graph list --name-contains "test-deployment"

# Delete each
langstar graph delete <id-1> --yes
langstar graph delete <id-2> --yes

Find Unused Deployments

bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi

# List unused
langstar graph list --status UNUSED --limit 100

# Review and delete manually
langstar graph list --limit 100 --format json | \
    jq '.resources[] | select(.status == "UNUSED") | {name, id, created_at, status}'

Filter by User/CI Pattern

bash
# Source credentials
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi

# Filter by username/CI prefix
langstar graph list --name-contains "alice-"
langstar graph list --name-contains "ci-build-"
langstar graph list --name-contains "pr-"

Troubleshooting

"Authentication failed"

Diagnosis:

bash
[ -n "$LANGSMITH_API_KEY" ] && echo "Set" || echo "Not set"
[ -n "$LANGSMITH_WORKSPACE_ID" ] && echo "Set" || echo "Not set"

Solution:

bash
source /workspace/.devcontainer/.env
# Verify
[ -n "$LANGSMITH_API_KEY" ] && echo "Set" || echo "Not set"

"Deployment not found"

Cause: Deployment deleted or incorrect ID.

Solution:

bash
# Verify ID from list
langstar graph list --limit 100
langstar graph list --name-contains "<name-fragment>"

No Deployments Returned

Solution:

bash
# Try without filters
langstar graph list --limit 100

# Try broader patterns
langstar graph list --name-contains "test"

Additional Resources

  • •Batch Cleanup Examples - Non-interactive deletion scripts
  • •CLI Command Reference - Detailed command documentation
  • •Issue #188 - Original feature request
  • •Issue #186 - Context for orphaned deployments
  • •SDK - sdk/src/deployments.rs - Full API client
  • •CLI - cli/src/commands/graph.rs - Implementation

Integration

With test-runner-worktree Skill

Clean up after test runs:

bash
# After integration tests
cd /workspace/wip/<worktree-name>
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
langstar graph list --name-contains "langstar-test"

With git-worktrees Skill

Works in any location - credentials source the same:

bash
# Works in main or worktree
cd /workspace
# or
cd /workspace/wip/claude-188-deployment-management

# Source once
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
langstar graph list

Quick Reference Templates

Environment Check

bash
if [ -z "$LANGSMITH_API_KEY" ] || [ -z "$LANGSMITH_WORKSPACE_ID" ]; then
    source /workspace/.devcontainer/.env
fi
[ -n "$LANGSMITH_API_KEY" ] && echo "✓" || echo "✗"

List Test Deployments

bash
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
langstar graph list --name-contains "test" --limit 100

Interactive Batch Delete

bash
if [ -z "$LANGSMITH_API_KEY" ]; then source /workspace/.devcontainer/.env; fi
for id in $(langstar graph list --name-contains "test" --format json | jq -r '.resources[].id'); do
    langstar graph get "$id" | jq '{name, status, created_at}'
    read -p "Delete? (y/n): " confirm
    [ "$confirm" = "y" ] && langstar graph delete "$id" --yes
done

Key Takeaways

  1. •Check environment variables before sourcing
  2. •Never expose credential values
  3. •Review deployments before batch deletion
  4. •Use specific name patterns
  5. •Combine filters for precision
  6. •Interactive confirmation prevents accidents
  7. •CLI handles all operations - no direct API calls needed