SRE Agent - Mattermost Integration API

A FastAPI-based ChatOps integration for Site Reliability Engineering operations through Mattermost

📋 Table of Contents

• Overview
• Features
• Prerequisites
• Installation
• Configuration
• Running the Application
• File Structure
• Core Components
• API Endpoints
• Database Migrations

Overview

This FastAPI integration focuses on Site Reliability Engineering (SRE) operations using ChatOps principles. Built primarily for Mattermost, it enables teams to receive alerts, collaborate during incidents, and follow playbooks for efficient incident resolution.

Features

• ✅ Alert Management: Receive alerts from Elastic and forward them to Mattermost channels
• 🚨 Incident Response: Acknowledge alerts and automatically create dedicated incident channels/playbooks
• 🎫 Jira Integration: Create and update Jira issues directly from Mattermost
• 📝 Post-Mortem Reports: Generate comprehensive post-mortem documentation
• 🔄 Database Persistence: SQLite database with Alembic migrations for data management
• 🤖 Interactive Dialogs: Custom Mattermost dialogs for streamlined workflows

Prerequisites

Before setting up the project, ensure you have:

• Python 3.10+ installed
• Mattermost Server with bot account credentials
• Jira account with API token (optional, for Jira integration)
• Elasticsearch instance (optional, for alert ingestion)
• Git for version control

Installation

1. Clone the Repository

git clone <repository-url>
cd SRE-Agent

2. Create Virtual Environment

Windows:

python -m venv .venv
.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

Configuration

1. Environment Variables

Copy the example environment file and configure your settings:

cp env.example .env

Edit .env with your credentials:

# API Configuration
API_SERVER = # Server URL e.g., http://localhost:8000

# Database Configuration
DATABASE_NAME = # Database name e.g., mydatabase

# Jira Configuration
JIRA_SERVER = # Jira server URL        
JIRA_EMAIL = # Jira email e.g., user@example.com
JIRA_API_TOKEN = # Jira API token
JIRA_PROJECT_KEY = # Jira project key

# Mattermost Configuration
MATTERMOST_SERVER = # Mattermost server URL
MATTERMOST_WEBHOOK_URL = # Mattermost webhook URL
MATTERMOST_API_TOKEN = # Mattermost API token

# LLM Configuration
ANTHROPIC_API_KEY = # Anthropic API key
ANTHROPIC_MODEL = # Anthropic model e.g., claude-sonnet-4-5-20250929

2. Database Initialization

Initialize the database with Alembic migrations:

alembic upgrade head

Running the Application

Option 1: VS Code Debugger (Recommended for Development)

1. Open the project in VS Code
2. Go to Debug and Run panel (Ctrl+Shift+D)
3. Select Python Debugger: FastAPI
4. Click Run or press F5

Option 2: Command Line

uvicorn main:app --reload

The application will be available at:

• API: http://localhost:8000
• Swagger Docs: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

Option 3: Production

uvicorn main:app --host 0.0.0.0 --port 8000 --workers 4

File Structure

SRE-Agent/
├── alembic/                  # Database migration management
│   ├── env.py
│   ├── script.py.mako
│   └── versions/             # Migration scripts
├── builders/
│   ├── attachment_builder.py # Attachment builder classes
│   ├── dialog_builder.py     # Dialog builder classes
│   └── post_mortem_builder.py # Post-mortem builder
├── clients/
│   └── mattermost_client.py  # MattermostClient OOP class
├── config/
│   └── settings.py           # Pydantic-based configuration
├── database/
│   ├── database.py           # Database connection and session
│   └── models.py             # SQLAlchemy database models
├── models/
│   ├── mattermost.py         # Mattermost data models
│   ├── requests.py           # API request models
│   └── responses.py          # API response models
├── prompts/
│   ├── summary_prompt.txt    # Summary generation prompt
│   └── timeline_prompt.txt   # Timeline generation prompt
├── routers/
│   ├── jira.py               # JIRA integration endpoints
│   └── mattermost.py         # Mattermost HTTP endpoints
├── services/
│   ├── api_response.py       # API response utilities
│   ├── jira_service.py       # JIRA business logic
│   └── mattermost_service.py # Mattermost business logic
├── env.example              # Environment variables template
├── .gitignore                # Git ignore rules
├── alembic.ini               # Alembic configuration
├── main.py                   # FastAPI application entry
├── migrate.py                # Database migration utilities
├── PostMortemPrompt.txt      # Post-mortem generation prompt
├── requirements.txt          # Dependencies
└── sre_agent.db              # SQLite database

Core Components

🚀 main.py

Entry point for the FastAPI application. Initializes the app, configures middleware, and registers all routers.

📡 ./routers

Contains all API endpoints that accept requests from Mattermost and Jira operations.

Files:

• mattermost.py - Handles Mattermost webhooks, slash commands, and interactive actions
• jira.py - Manages Jira integration endpoints for issue creation and updates

🔧 ./services

Business logic layer that processes requests and orchestrates operations between clients and data models.

Files:

• mattermost_service.py - Core Mattermost business logic
• jira_service.py - Jira integration business logic
• api_response.py - Standardized API response utilities

🤖 ./clients/mattermost_client.py

Custom Mattermost client for API interactions. Since Mattermost doesn't provide an official Python SDK, this client implements the necessary HTTP requests to interact with the Mattermost API.

Key Methods:

• post_message() - Send messages to channels
• create_channel() - Create new channels
• post_ephemeral() - Send private messages
• open_dialog() - Display interactive dialogs

🏗️ ./builders

Builder pattern implementations for constructing complex Mattermost objects.

Files:

• attachment_builder.py - Build message attachments with fields and actions
• dialog_builder.py - Create interactive dialog forms
• post_mortem_builder.py - Generate post-mortem report structures

🗃️ ./database

Database models and connection management using SQLAlchemy.

Files:

• database.py - Database session and connection configuration
• models.py - SQLAlchemy ORM models for persistent data

📊 ./models

Pydantic models for request/response validation and data serialization.

Files:

• mattermost.py - Mattermost-specific data models
• requests.py - API request schemas
• responses.py - API response schemas

🗄️ ./alembic

Database migration management using Alembic.

Key Files:

• versions/ - Migration scripts
• env.py - Alembic environment configuration

📝 ./prompts

Text prompts for AI-assisted features like post-mortem generation.

⚙️ env.example

Template for required environment variables. Must be copied to .env and configured for the application to run properly.

API Endpoints

Mattermost Integration

Endpoint	Method	Description
/api/alert	POST	Receive and forward alerts to Mattermost
/api/acknowledge	POST	Acknowledge an alert and start playbook
/api/create-channel	POST	Create a new incident channel
/api/open-playbook-dialog	POST	Display playbook selection dialog
/api/start-playbook	POST	Initialize a playbook run
/api/post-message	POST	Send a message to a channel
/api/post-ephemeral	POST	Send a private ephemeral message

Jira Integration

Endpoint	Method	Description
/api/jira/create-issue	POST	Create a new Jira issue
/api/jira/update-issue	POST	Update an existing Jira issue

Health & Status

Endpoint	Method	Description
/health	GET	Health check endpoint
/docs	GET	Interactive API documentation (Swagger UI)

Database Migrations

This project uses Alembic for database schema management.

Create a New Migration

alembic revision -m "description of changes"

Apply Migrations

alembic upgrade head

Rollback Migration

alembic downgrade -1

View Migration History

alembic history

Logging

Enable debug logging by setting environment variable:

LOG_LEVEL=DEBUG uvicorn main:app --reload