> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Create and manage reusable pipeline configurations for CI/CD workflows

Pipeline Templates define reusable CI/CD configurations including stages, scripts, and trigger rules. Use templates to standardize pipeline behavior across projects and teams.

## Key Concepts

<CardGroup cols={2}>
  <Card title="Template" icon="file-code">
    A reusable pipeline configuration containing stages, scripts, and trigger rules.
  </Card>

  <Card title="Stage" icon="layer-group">
    A pipeline phase (build, test, deploy) with ordering and activation settings.
  </Card>

  <Card title="Script" icon="code">
    Reusable code snippets injected into pipeline stages based on provider type.
  </Card>

  <Card title="Trigger Config" icon="bolt">
    YAML-based webhook rules defining when pipelines should run.
  </Card>
</CardGroup>

## Required Permissions

| Action           | Permission                          |
| ---------------- | ----------------------------------- |
| View templates   | `iam:project:cicd:templates:read`   |
| Create templates | `iam:project:cicd:templates:write`  |
| Edit templates   | `iam:project:cicd:templates:write`  |
| Delete templates | `iam:project:cicd:templates:delete` |

## Template Types

| Type       | Description                                  | Actions                       |
| ---------- | -------------------------------------------- | ----------------------------- |
| **System** | Pre-built templates provided by the platform | View, Duplicate               |
| **Custom** | User-created templates                       | View, Edit, Duplicate, Delete |

<Info>
  System templates cannot be modified or deleted. Duplicate a system template to create a customizable copy.
</Info>

## Template Requirements

Templates can specify which features a project must have configured:

| Requirement      | Description                                       |
| ---------------- | ------------------------------------------------- |
| **Namespace**    | Project must belong to a namespace                |
| **GitOps**       | Project must have GitOps configuration            |
| **Environments** | Project must have deployment environments defined |
| **Helm Chart**   | Project must use Helm for deployments             |

## Deployment Kinds

Templates support different deployment strategies:

| Kind           | Description                    |
| -------------- | ------------------------------ |
| **kubernetes** | Standard Kubernetes deployment |
| **helm**       | Helm chart-based deployment    |
| **docker**     | Docker container deployment    |
| **serverless** | Serverless function deployment |

## How to Create a Template

<Steps>
  <Step title="Click Add Template">
    Click the **Add Template** button in the header.
  </Step>

  <Step title="Configure General Settings">
    Enter template name, description, select an icon, and choose deployment kind.
  </Step>

  <Step title="Set Requirements">
    Enable required features: Namespace, GitOps, Environments, Helm Chart.
  </Step>

  <Step title="Configure Helm Defaults (Optional)">
    If using Helm, set default repository, tag, and chart path.
  </Step>

  <Step title="Add Stages">
    Navigate to Stages tab and define pipeline stages with order and names.
  </Step>

  <Step title="Add Scripts">
    Navigate to Scripts tab and add reusable script snippets.
  </Step>

  <Step title="Configure Triggers">
    Navigate to Trigger tab and define webhook trigger rules in YAML.
  </Step>

  <Step title="Save">
    Click **Save Changes** to create the template.
  </Step>
</Steps>

## How to View a Template

<Steps>
  <Step title="Find the Template">
    Locate the template in the list. Use filters to show System or Custom templates.
  </Step>

  <Step title="Click View">
    Click on the template row to open the detail page.
  </Step>

  <Step title="Browse Tabs">
    Navigate through General, Stages, Scripts, Trigger, and Preview tabs.
  </Step>
</Steps>

## How to Edit a Template

<Steps>
  <Step title="Find the Template">
    Locate a custom template in the list.
  </Step>

  <Step title="Open Detail Page">
    Click on the template row.
  </Step>

  <Step title="Modify Settings">
    Update any configuration across the available tabs.
  </Step>

  <Step title="Save">
    Click **Save Changes** to apply updates.
  </Step>
</Steps>

<Warning>
  System templates cannot be edited. Duplicate the template first to create an editable copy.
</Warning>

## How to Duplicate a Template

<Steps>
  <Step title="Find the Template">
    Locate any template (system or custom) in the list.
  </Step>

  <Step title="Click Duplicate">
    Click the duplicate (copy) icon on the template row.
  </Step>

  <Step title="Review">
    A new custom template is created with all settings copied.
  </Step>

  <Step title="Rename">
    Edit the duplicated template to give it a unique name.
  </Step>
</Steps>

<Tip>
  Duplicate system templates to create customized versions that you can modify.
</Tip>

## How to Delete a Template

<Steps>
  <Step title="Find the Template">
    Locate a custom template to delete.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon on the template row.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting a template does not affect existing projects using it, but new projects cannot use the deleted template.
</Warning>

## Managing Stages

### Adding a Stage

<Steps>
  <Step title="Open Stages Tab">
    Navigate to the Stages tab in the template detail page.
  </Step>

  <Step title="Click Add Stage">
    Click the **Add Stage** button.
  </Step>

  <Step title="Configure Stage">
    Enter display name, set order number, and toggle active status.
  </Step>

  <Step title="Save">
    Click **Save Changes** to persist the stage.
  </Step>
</Steps>

### Stage Properties

| Property         | Description                                  |
| ---------------- | -------------------------------------------- |
| **Display Name** | Human-readable stage name shown in pipelines |
| **Order**        | Execution sequence (lower numbers run first) |
| **Active**       | Whether the stage is enabled in pipelines    |

### Reordering Stages

Change the order value for each stage to control execution sequence. Stages execute in ascending order (1, 2, 3...).

## Managing Scripts

### Adding a Script

<Steps>
  <Step title="Open Scripts Tab">
    Navigate to the Scripts tab in the template detail page.
  </Step>

  <Step title="Click Add Script">
    Click the **Add Script** button.
  </Step>

  <Step title="Configure Script">
    Enter script key, select script type and provider type, then add the script content.
  </Step>

  <Step title="Save">
    Click **Save Changes** to persist the script.
  </Step>
</Steps>

### Script Properties

| Property          | Description                                                            |
| ----------------- | ---------------------------------------------------------------------- |
| **Script Key**    | Unique identifier for referencing the script                           |
| **Script Type**   | Category of script (build, test, deploy, etc.)                         |
| **Provider Type** | Git provider the script is compatible with (GitHub, GitLab, Bitbucket) |
| **Content**       | The actual script code                                                 |

## Configuring Trigger Rules

### Trigger Configuration Format

Trigger rules are defined in YAML format and control when pipelines are triggered by webhooks.

```yaml theme={null}
on:
  push:
    branches:
      - main
      - develop
      - feature/*

  pull_request:
    branches:
      - main
    types:
      - opened
      - synchronize

  tag:
    patterns:
      - v*
      - release-*

environment_mapping:
  main: prod
  develop: staging
  feature/*: dev
```

### Trigger Events

| Event             | Description                                          |
| ----------------- | ---------------------------------------------------- |
| **push**          | Triggered on commits pushed to matching branches     |
| **pull\_request** | Triggered on PR events (opened, synchronize, merged) |
| **tag**           | Triggered when tags matching patterns are created    |

### Branch Patterns

Use glob patterns for flexible branch matching:

| Pattern     | Matches                             |
| ----------- | ----------------------------------- |
| `main`      | Exact match for "main" branch       |
| `feature/*` | Any branch starting with "feature/" |
| `release/*` | Any branch starting with "release/" |
| `*`         | All branches                        |

## Using Preview

The Preview tab generates sample `.kodeshift` configuration files based on the template settings.

<Steps>
  <Step title="Open Preview Tab">
    Navigate to the Preview tab in the template detail page.
  </Step>

  <Step title="Configure Parameters">
    Select Git provider, project name, and environments.
  </Step>

  <Step title="Generate Preview">
    Click **Generate** to create sample configuration files.
  </Step>

  <Step title="Review Output">
    Examine the generated YAML files to verify template behavior.
  </Step>
</Steps>

<Tip>
  Use Preview to validate your template configuration before applying it to projects.
</Tip>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Cannot edit template" icon="circle-question">
    * System templates cannot be edited; duplicate first
    * Verify you have write permission
    * Check if another user is editing the template
  </Accordion>

  <Accordion title="Cannot delete template" icon="circle-question">
    * System templates cannot be deleted
    * Verify you have delete permission
    * Try refreshing the page
  </Accordion>

  <Accordion title="Stages not executing in order" icon="circle-question">
    * Verify stage order numbers are correct
    * Lower numbers execute first
    * Check if stages are marked as active
  </Accordion>

  <Accordion title="Scripts not applying to pipeline" icon="circle-question">
    * Verify script provider type matches project provider
    * Check script key is correctly referenced
    * Ensure script is saved
  </Accordion>

  <Accordion title="Trigger not firing" icon="circle-question">
    * Verify YAML syntax is valid
    * Check branch patterns match your branches
    * Ensure webhook is configured for the repository
    * Verify event type is included in trigger config
  </Accordion>

  <Accordion title="Preview not generating" icon="circle-question">
    * All required parameters must be selected
    * Template must have at least one stage
    * Check for validation errors in other tabs
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="What's the difference between system and custom templates?">
    System templates are provided by the platform and cannot be modified. Custom templates are user-created and fully editable. Duplicate a system template to create a customizable version.
  </Accordion>

  <Accordion title="Can I share templates between projects?">
    Yes. Templates are available to all projects within your organization. Any project can use any template they have read access to.
  </Accordion>

  <Accordion title="How do I create a template from an existing project?">
    Currently, templates must be created manually. Export your project's pipeline configuration and use it as a reference when creating a new template.
  </Accordion>

  <Accordion title="Can I have multiple trigger configs in one template?">
    Yes. The trigger YAML can define multiple events (push, pull\_request, tag) with different branch patterns and settings.
  </Accordion>

  <Accordion title="What happens if I update a template used by existing projects?">
    Existing pipelines continue using their current configuration. Template changes only affect new projects or when a project explicitly re-applies the template.
  </Accordion>

  <Accordion title="How do I test a template before using it?">
    Use the Preview tab to generate sample configuration files. Review the output to verify the template produces the expected pipeline configuration.
  </Accordion>

  <Accordion title="Can scripts reference template variables?">
    Yes. Scripts can use template variables and environment-specific values. Check the script documentation for available variables.
  </Accordion>

  <Accordion title="What's the maximum number of stages in a template?">
    There is no hard limit on stages. However, keep pipelines focused and consider splitting complex workflows into multiple pipelines.
  </Accordion>
</AccordionGroup>

## Best Practices

### Template Design

* Create templates for common workflow patterns
* Keep templates focused on specific use cases
* Use descriptive names and descriptions
* Document template requirements clearly

### Stages

* Order stages logically (build → test → deploy)
* Use consistent naming across templates
* Keep stage count manageable (3-5 stages typical)
* Disable stages instead of deleting when debugging

### Scripts

* Write provider-agnostic scripts when possible
* Use script keys that describe the action
* Keep scripts modular and reusable
* Test scripts independently before adding to templates

### Trigger Configuration

* Use specific branch patterns over wildcards
* Map environments appropriately for each branch
* Include only necessary event types
* Document trigger behavior in template description

### Organization

* Prefix template names with team or purpose
* Use icons to visually categorize templates
* Review and update templates periodically
* Remove unused custom templates