> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/3.0/harness-platform-resources/templates/v1-stage-template.md).

# Create a V1 stage template

A stage template defines an entire stage, including its steps and any inputs the stage needs at runtime. Use it to standardize a complete unit of pipeline execution, such as a release stage, a scanning stage, or an AI-driven failure analysis stage.

***

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* **V1 pipeline access:** A project with V1 pipelines enabled. Go to the [V1 pipelines overview](https://github.com/iKettles/harness-gitbook/tree/main/3k-docs/platform/getting-started/pipeline/README.md) to enable V1 in your project.
* **Secrets and connectors:** Any secrets the template references (for example, API keys) and a connector for each container image used by its steps. Go to the [secrets reference](/harness-platform/3.0/in-harness-3.0/secrets.md) and the [connectors reference](/harness-platform/3.0/in-harness-3.0/connectors.md) to configure them.
* **Permissions:** Create and Edit on Templates. Go to the [RBAC in Harness](/harness-ai/use-harness-platform/platform-access-control.md) to configure roles.

***

### Author the stage template <a href="#author-the-stage-template" id="author-the-stage-template"></a>

Define the template under the top-level `template` key with a `stage` block. Declare runtime inputs under `template.inputs`. The body of `stage` matches a stage you would write inline in a pipeline.

```yaml
template:
  inputs:
    executionUrl:
      required: true
      type: string
  stage:
    steps:
      - id: analyze_execution_failure
        name: Analyze Execution Failure
        run:
          container:
            image: pkg.harness.io/vrvdt5ius7uwygso8s0bia/harness-agents/claude-code-plugin:main
          env:
            ANTHROPIC_API_KEY: <+secrets.getValue("rohan_llm_key")>
          with:
            allowed_tools: mcp__harness__*
            log_file: .agent/output/harness-error-analyzer-v3-log.jsonl
            max_turns: "100"
            mcp_servers: '{"harness":{"allowed":["harness_diagnose","harness_get"],"headers":{"X-Api-Key":"<+secrets.getValue(\"rohan_pat\")>"},"type":"http","url":"https://unifiedpipeline.harness.io/mcp-server-external/mcp"}}'
            task: |
              You are a Pipeline Failure Analyzer. Your job is to analyze a failed Harness pipeline execution and provide a clear, actionable summary.

              Input: Harness Execution URL: <+inputs.executionUrl>

              Workflow:
              1. Parse the execution URL to extract identifiers: account, org, project, pipeline, and execution ID.
              2. Use the Harness MCP tools to fetch execution details.
              3. Identify the specific step or steps that failed.
              4. Extract the relevant error messages and short log snippets.
              5. Analyze the root cause of the failure.
              6. Output a clean text summary with these fields:
                 - Pipeline, Failed Stage, Failed Step, Error, Root Cause, Suggested Fix.
version: 1
```

Inputs declared under `template.inputs` are referenced inside the stage with `<+inputs.<name>>` (or `${{ inputs.<name> }}` in expression-style fields). Mark inputs as `required: true` when the stage cannot run without them.

***

### Store the template <a href="#store-the-template" id="store-the-template"></a>

Choose where the template is versioned.

* **Harness-managed:** Save the template in the Harness platform. Versions are created and promoted in Harness.
* **Git-stored:** Commit the template to a Git repository. The Git tag, branch, or commit determines the resolved version.

Go to the [V1 Template Library overview](/harness-platform/3.0/harness-platform-resources/templates/template.md) to compare storage modes.

***

### Reference the template from a pipeline <a href="#reference-the-template-from-a-pipeline" id="reference-the-template-from-a-pipeline"></a>

Reference a stage template from inside the `stages` list with the `template` block. Set `uses` to `<scope>.<name>@<version>` and supply input values under `with`.

```yaml
pipeline:
  stages:
    - template:
        uses: account.analyze-failure@1.0.0
        with:
          executionUrl: <+pipeline.triggeredExecutionUrl>
```

If you omit the version suffix, the pipeline resolves to the latest stable version at execution time.

```yaml
pipeline:
  stages:
    - template:
        uses: account.golang
        with:
          version: "1.19"
          goos: linux
          goarch: amd64
          cgo-enabled: true
```

A stage template can be combined with other inline stages. Each `template` entry in `stages` expands into one stage at runtime.

***

### Next steps <a href="#next-steps" id="next-steps"></a>

A stage template standardizes a complete stage, including its inputs. When you only need to share a smaller unit, use a step or step group template instead. Go to the [step template guide](/harness-platform/3.0/harness-platform-resources/templates/v1-step-template.md) to share a single step. Go to the [step group template guide](/harness-platform/3.0/harness-platform-resources/templates/v1-step-group-template.md) to share an ordered set of steps.