Manifest File

The manifest file is a JSON document that contains all the metadata for a Record. It’s always named phaset.manifest.json and lives in your repository alongside your code.

When you update the manifest file and push to Git, your CI/CD pipeline automatically updates the Record in Phaset (given correct integration). This keeps documentation in sync with your actual software—no manual updates, no stale information.

Why Manifest Files Matter

Documentation as code. Your Record metadata lives in Git, versioned alongside your software. Review it in pull requests. Track changes over time. Treat documentation like code. Update the manifest, push to Git, and the Record updates automatically. No logging into Phaset. No manual data entry. No forgetting to update documentation. The manifest file is authoritative. When someone asks “what’s the SLA for this service?” the answer is in Git, not someone’s head or a forgotten wiki.

Because manifests are handled like code, changes to Record metadata can go through code review. Want to change ownership? That’s a pull request. Want to mark something deprecated? That’s a pull request with a paper trail.

Manifest File Structure

Here’s a complete example showing all available fields:

{
  "spec": {
    "name": "Test Component",
    "repo": "org/repo",
    "description": "A test component",
    "lifecycleStage": "development",
    "version": "1.0.0",
    "kind": "service",
    "group": "<random_id>",
    "system": "<random_id>",
    "domain": "<random_id>",
    "dataSensitivity": "internal",
    "businessCriticality": "high",
    "deploymentModel": "public_cloud",
    "sourcingModel": "custom"
  },
  "baseline": {
    "id": "abcd1234"
  },
  "contacts": [
    {
      "email": "[email protected]",
      "relation": "owner"
    }
  ],
  "tags": [
    "test",
    "example"
  ],
  "slo": [
    {
      "title": "Availability",
      "description": "Service availability",
      "type": "availability",
      "target": "99.9%",
      "period": 30
    }
  ],
  "links": [
    {
      "url": "https://example.com",
      "title": "Example",
      "icon": "web"
    }
  ],
  "api": [
    {
      "name": "TestAPI",
      "schemaPath": "/schema/test.json"
    }
  ],
  "dependencies": [
    {
      "target": "abcde12345",
      "description": "A description here",
      "criticality": "medium"
    }
  ],
  "metadata": {
    "createdBy": "test-user"
  }
}

Key Sections

Section	Required	Description
spec	✓	Core Record information: identity (name, repo, description, version), organization (domain, system, group), and classification (kind, lifecycle stage, criticality); only name is required
baseline	-	Which Baseline ID to use for Standards checks
contacts	-	Who owns and maintains this software (up to 3 contacts)
tags	-	Searchable labels for filtering and organization (up to 5 tags)
slo	-	Service Level Objectives defining reliability targets (up to 20 SLOs)
links	-	Related resources like dashboards, documentation, and runbooks (up to 20 links)
api	-	API schemas and specifications (up to 20 APIs)
dependencies	-	Other Records this software depends on
metadata	-	Custom key-value pairs for additional context

How It Works

1. Create phaset.manifest.json in your repository root
2. Add Record metadata as JSON
3. Commit and push to your main branch
4. CI/CD pipeline runs, sends manifest to Phaset via Integration API
5. Record updates automatically in Phaset

From that point forward, any changes to the manifest automatically update the Record. Documentation stays in sync with zero manual effort.

All Records Must Be Created in the UI First!

Please note that because of the requirement for webhook tokens to be used in CI/CD or other automation contexts, currently all Records must be created initially in the Phaset UI (web application) first. Doing so generates the webhook token that you will need to use. No need for extensive filling-in of information if you don’t want to, though.

See the next tip for a productivity hack!

Manual vs Automated Records

Records can be managed two ways:

Manual management: Create and update Records directly in the UI. Good for:

• Getting started quickly
• Managing external/third-party software
• Small teams or simple setups

Automated management: Records update via CI/CD. Good for:

• Keeping documentation in sync with code
• Scaling across many services
• Ensuring consistency through automation

Start in the UI and Copy The Data to JSON

Under the hood, there’s no big difference if you fill out a Record in the UI and copy/download the data into a manifest, or if you start from an empty manifest.

Consider taking a few minutes to conveniently and comprehensively fill out the Record in the UI, the first time around.

Most organizations will use both: automation for their own services, manual entry for third-party tools and external dependencies.

Getting Started

1. Create a manifest file in one of your repositories
2. Add basic metadata (name, description, repo at minimum)
3. Set up CI/CD integration following the Integration Guide
4. Push the manifest and verify the Record updates
5. Expand gradually to more repositories

Start simple. A manifest with just name, description, and repo is enough to get started. Add more fields as you need them.

Integration Guide

See the Integration Guide for complete setup instructions, including CI/CD configuration and the Integration API details.

Validation and Schema

The manifest file follows a specific schema. If you provide invalid data, the Integration API will reject it with an error message indicating what’s wrong.

See the Integration API documentation for complete schema details.