Templates - ShiftLabs

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

Template

A reusable pipeline configuration containing stages, scripts, and trigger rules.

Stage

A pipeline phase (build, test, deploy) with ordering and activation settings.

Script

Reusable code snippets injected into pipeline stages based on provider type.

Trigger Config

YAML-based webhook rules defining when pipelines should run.

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

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

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

Click Add Template

Click the Add Template button in the header.

Configure General Settings

Enter template name, description, select an icon, and choose deployment kind.

Set Requirements

Enable required features: Namespace, GitOps, Environments, Helm Chart.

Configure Helm Defaults (Optional)

If using Helm, set default repository, tag, and chart path.

Add Stages

Navigate to Stages tab and define pipeline stages with order and names.

Add Scripts

Navigate to Scripts tab and add reusable script snippets.

Configure Triggers

Navigate to Trigger tab and define webhook trigger rules in YAML.

Save

Click Save Changes to create the template.

How to View a Template

Find the Template

Locate the template in the list. Use filters to show System or Custom templates.

Click View

Click on the template row to open the detail page.

Browse Tabs

Navigate through General, Stages, Scripts, Trigger, and Preview tabs.

How to Edit a Template

Find the Template

Locate a custom template in the list.

Open Detail Page

Click on the template row.

Modify Settings

Update any configuration across the available tabs.

Save

Click Save Changes to apply updates.

System templates cannot be edited. Duplicate the template first to create an editable copy.

How to Duplicate a Template

Find the Template

Locate any template (system or custom) in the list.

Click Duplicate

Click the duplicate (copy) icon on the template row.

Review

A new custom template is created with all settings copied.

Rename

Edit the duplicated template to give it a unique name.

Duplicate system templates to create customized versions that you can modify.

How to Delete a Template

Find the Template

Locate a custom template to delete.

Click Delete

Click the delete (trash) icon on the template row.

Confirm

Confirm the deletion. This action cannot be undone.

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

Managing Stages

Adding a Stage

Open Stages Tab

Navigate to the Stages tab in the template detail page.

Click Add Stage

Click the Add Stage button.

Configure Stage

Enter display name, set order number, and toggle active status.

Save

Click Save Changes to persist the stage.

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

Open Scripts Tab

Navigate to the Scripts tab in the template detail page.

Click Add Script

Click the Add Script button.

Configure Script

Enter script key, select script type and provider type, then add the script content.

Save

Click Save Changes to persist the script.

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.

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.

Open Preview Tab

Navigate to the Preview tab in the template detail page.

Configure Parameters

Select Git provider, project name, and environments.

Generate Preview

Click Generate to create sample configuration files.

Review Output

Examine the generated YAML files to verify template behavior.

Use Preview to validate your template configuration before applying it to projects.

Troubleshooting

Cannot edit template

System templates cannot be edited; duplicate first
Verify you have write permission
Check if another user is editing the template

Cannot delete template

System templates cannot be deleted
Verify you have delete permission
Try refreshing the page

Stages not executing in order

Verify stage order numbers are correct
Lower numbers execute first
Check if stages are marked as active

Scripts not applying to pipeline

Verify script provider type matches project provider
Check script key is correctly referenced
Ensure script is saved

Trigger not firing

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

Preview not generating

All required parameters must be selected
Template must have at least one stage
Check for validation errors in other tabs

FAQ

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.

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.

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.

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.

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.

Can scripts reference template variables?

Yes. Scripts can use template variables and environment-specific values. Check the script documentation for available variables.

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.

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

​Key Concepts

Template

Stage

Script

Trigger Config

​Required Permissions

​Template Types

​Template Requirements

​Deployment Kinds

​How to Create a Template

​How to View a Template

​How to Edit a Template

​How to Duplicate a Template

​How to Delete a Template

​Managing Stages

​Adding a Stage

​Stage Properties

​Reordering Stages

​Managing Scripts

​Adding a Script

​Script Properties

​Configuring Trigger Rules

​Trigger Configuration Format

​Trigger Events

​Branch Patterns

​Using Preview

​Troubleshooting

​FAQ

​Best Practices

​Template Design

​Stages

​Scripts

​Trigger Configuration

​Organization

Key Concepts

Required Permissions

Template Types

Template Requirements

Deployment Kinds

How to Create a Template

How to View a Template

How to Edit a Template

How to Duplicate a Template

How to Delete a Template

Managing Stages

Adding a Stage

Stage Properties

Reordering Stages

Managing Scripts

Adding a Script

Script Properties

Configuring Trigger Rules

Trigger Configuration Format

Trigger Events

Branch Patterns

Using Preview

Troubleshooting

FAQ

Best Practices

Template Design

Stages

Scripts

Trigger Configuration

Organization