DeployBrief DeployBrief
← Back to Documentation

Brief Templates

Create and customize deployment brief templates to match your team's workflow and documentation standards.

What are Brief Templates?

Brief templates define the structure and content of deployment briefs generated by DeployBrief. Templates consist of customizable sections with placeholders that are automatically filled with data from your Azure DevOps pipelines, work items, and repositories.

Templates support two formats: Markdown for documentation and HTML for rich formatting.

Creating a Template

  1. Navigate to Settings → Templates
  2. Click Create Template
  3. Enter template details:
    • Name: Descriptive name (e.g., "Standard Production Deploy")
    • Description: Optional description of template usage
    • Format: Choose Markdown or HTML
  4. Add sections to your template (see below)
  5. Click Save Template

Tip: Start with a default template and customize it to your needs. You can preview templates before saving.

Template Sections

Templates are composed of sections. Each section has:

  • Title: Section heading (e.g., "Deployment Summary")
  • Content: Text with placeholders for dynamic data
  • Order: Position in the final brief
  • Visibility: Optional conditions for showing/hiding sections

Common Sections

Deployment Summary

High-level overview: pipeline name, environment, deployment date, deployed by

Changes Included

List of work items, commits, pull requests included in the deployment

Test Results

Unit tests, integration tests, code coverage metrics

Rollback Plan

Steps to revert deployment, previous version information

Known Issues

Active bugs, limitations, monitoring alerts

Placeholders

Placeholders are variables that get replaced with actual data when generating a brief. Use double curly braces: {{placeholder}}

Available Placeholders

Pipeline Information

PlaceholderDescription
{{pipeline.name}}Pipeline name
{{pipeline.id}}Pipeline ID
{{pipeline.url}}Link to pipeline in Azure DevOps
{{build.number}}Build/run number
{{build.date}}Build completion date
{{build.status}}Build status (Succeeded, Failed, etc.)

Environment & Deployment

{{environment.name}}Target environment (Production, Staging, etc.)
{{deployment.date}}Deployment timestamp
{{deployment.by}}User who triggered deployment
{{deployment.reason}}Deployment trigger reason

Changes & Work Items

{{workitems.list}}List of work items with titles and links
{{workitems.count}}Number of work items
{{commits.list}}List of commits with messages
{{commits.count}}Number of commits
{{pullrequests.list}}List of merged pull requests

Test Results

{{tests.total}}Total test count
{{tests.passed}}Passed tests
{{tests.failed}}Failed tests
{{tests.coverage}}Code coverage percentage

Example Template (Markdown)

Here's a complete example of a deployment brief template:

# Deployment Brief: {{pipeline.name}}

## Deployment Summary

- **Pipeline:** {{pipeline.name}}
- **Build:** #{{build.number}}
- **Environment:** {{environment.name}}
- **Deployed By:** {{deployment.by}}
- **Deployment Date:** {{deployment.date}}
- **Status:** {{build.status}}

## Changes Included

### Work Items ({{workitems.count}})

{{workitems.list}}

### Commits ({{commits.count}})

{{commits.list}}

## Test Results

- **Total Tests:** {{tests.total}}
- **Passed:** {{tests.passed}} ✅
- **Failed:** {{tests.failed}} ❌
- **Code Coverage:** {{tests.coverage}}%

## Rollback Plan

If issues occur, revert to previous build:

1. Navigate to {{pipeline.url}}
2. Select previous successful build
3. Click "Redeploy"
4. Monitor application health

## Links

- [Pipeline]({{pipeline.url}}

HTML Templates

HTML templates provide rich formatting options with CSS styling:

<div class="deployment-brief">
  <h1>{{pipeline.name}}</h1>
  
  <div class="summary">
    <span class="badge">{{environment.name}}</span>
    <span class="build-number">#{{build.number}}</span>
  </div>

  <table class="info-table">
    <tr>
      <th>Deployed By</th>
      <td>{{deployment.by}}</td>
    </tr>
    <tr>
      <th>Date</th>
      <td>{{deployment.date}}</td>
    </tr>
  </table>
</div>

Best Practices

  • ✓ Keep it concise: Include only essential information
  • ✓ Use consistent formatting: Maintain standard structure across templates
  • ✓ Include links: Reference Azure DevOps items for details
  • ✓ Test placeholders: Preview templates before using in production
  • ✓ Version templates: Create dated versions (e.g., "Standard 2024-Q4")
  • ✓ Document custom templates: Add descriptions explaining usage
  • ✓ Share templates: Templates are workspace-wide; create reusable ones

Next Steps