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	Discover template resource schema and fields

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