template-usage

# Template Usage Skill Track template dependencies and usage across Harness via MCP v2 tools. ## MCP v2 Tools Used | Tool | Resource Type | Purpose | |------|--------------|---------| | `harness_search` | `template` | Find templates by keyword across orgs/projects | | `harness_list` | `template` | List templates, filter by scope | | `harness_get` | `template` | Get template details, versions, and usage references | | `harness_describe` | `template` | List supported operations and filters for templates | | `harness_schema` | `template` | Get the JSON Schema for template body fields (use for create/update) | Templates are managed via `harness_list` and `harness_get` only. For creating or updating templates, use the `/create-template` skill. ## Template Types | Type | Description | |------|-------------| | `Step` | Single step definition (build, test, deploy actions) | | `Stage` | Complete stage with steps (CI stage, CD stage, approval) | | `Pipeline` | Full pipeline definition | | `StepGroup` | Group of related steps bundled together | ## Template Scopes | Scope | Visibility | Query Parameters | |-------|-----------|-----------------| | Account | All orgs and projects | No org_id, no project_id | | Organization | All projects in the org | org_id only | | Project | Only within the project | org_id + project_id | ## Instructions ### Step 1: Find the Template Search by name or keyword: ``` harness_search( query="docker-build-push", resource_types=["template"], max_per_type=10, compact=true ) ``` Or list templates in a specific scope: ``` harness_list( resource_type="template", org_id="<org>", project_id="<project>", search_term="docker" ) ``` ### Step 2: Get Template Details ``` harness_get( resource_type="template", resource_id="<template_identifier>", org_id="<org>", project_id="<project>" ) ``` This returns the template definition, version history, and metadata. ### Step 3: Check Usage References ``` harness_get( resource_type="template", resource_id="<template_identifier>", org_id="<org>", project_id="<project>" ) ``` Parse the response for `referredEntities` or usage data. The response includes which pipelines and other templates reference this template. ### Step 4: Analyze and Present Organize findings into a report. For report templates (Usage Report, Impact Analysis, Unused Templates), consult references/report-templates.md. ## Examples ### Check who uses a template ``` /template-usage Which pipelines are using the docker-build-push template? ``` ### Impact analysis before update ``` /template-usage I want to make a breaking change to the k8s-deploy template. Show me what will be affected. ``` ### Find unused templates ``` /template-usage Which templates in our account have no references? I want to clean up. ``` ### Track version adoption ``` /template-usage Which version of the ci-stage template are different projects using? ``` ### Cross-project usage ``` /template-usage Show me all usages of account-level templates across all projects ``` ### Dependency chain ``` /template-usage Show me the full dependency chain for the release-pipeline template -- what does it reference and what references it? ``` ## Error Handling | Error | Cause | Solution | |-------|-------|----------| | Template not found | Wrong identifier or scope | Verify identifier and use correct org_id/project_id for the template's scope | | No usage data | Template genuinely unused or scope mismatch | Search at broader scope; account templates may be used in any project | | Empty search results | No templates match query | Try broader search terms or list all templates | ## Performance Notes - Paginate through all usage results before generating the impact report. Large templates may have many references. - Check usage across all scopes (account, org, project) for complete impact analysis. - Verify version information to distinguish between teams using current vs. outdated template versions. ## Troubleshooting ### No Usage Data Returned 1. Template may genuinely have no references 2. Query scope must match template scope -- an account-level template needs no org_id/project_id 3. Use `harness_search` with broader terms to find the template first ### Incomplete Usage List 1. Paginate through results -- increment `page` until all results are retrieved 2. Account-level templates can be referenced from any org/project -- check all scopes 3. Check for both pipeline and template references (templates can nest) ### Template Not Found 1. Verify the exact identifier (case-sensitive, underscores not hyphens) 2. Identifiers must match pattern: `^[a-zA-Z_][0-9a-zA-Z_]{0,127}$` 3. Check the correct scope -- project templates require org_id + project_id