Skip to content
Phaset Docs

Your First Record

This tutorial walks you through creating your first Record in Phaset. You’ll learn both manual and automated approaches, so you can choose what works best for your workflow.

What you’ll accomplish

Section titled “What you’ll accomplish”

By the end of this tutorial, you’ll have:

  • Created a Record representing a piece of software
  • Understood the difference between manual and automated lifecycle management
  • (Optional) Set up automated updates via CI/CD

Time required: 10-15 minutes (manual) or 20-30 minutes (with automation)

Prerequisites

Section titled “Prerequisites”
  • Phaset installed and running
  • Access to your Phaset organization
  • (For automation) A Git repository with CI/CD capabilities

Step 1: Choose your lifecycle approach

Section titled “Step 1: Choose your lifecycle approach”

Records in Phaset can be managed in two ways:

Manual lifecycle — You update Record information directly through the Phaset web interface. Best for getting started, external tools, or SaaS products you don’t control.

Automated lifecycle — Record information lives in a phaset.manifest.json file in your Git repository and updates automatically via CI/CD. Best for custom-developed software where you want automation.

Step 2: Create your first Record

Section titled “Step 2: Create your first Record”

  1. Log into Phaset and navigate to the Catalog view.

  2. Click Create Record.

  3. Click Edit Record.

  4. Fill in the basic information:

    • Name: e.g., “Payment API”
    • Description: Brief description of what this software does
    • Kind: Select the type (service, library, website, etc.)
    • Lifecycle stage: Current stage (production, development, etc.)

  5. Add ownership information:

    • Owner email: The primary person or team responsible
    • Relation: Set to “owner”

  6. (Optional) Add additional context:

    • Tags: Keywords for easy searching
    • Links: Documentation, dashboards, or related URLs
    • System/Domain/Group: Organizational structure

  7. Click Save or Create.

You’re done! Your first Record is now visible in the Catalog. You can update it anytime by clicking into the Record and editing fields directly.

Step 3 (Optional): Automate updates via CI/CD

Section titled “Step 3 (Optional): Automate updates via CI/CD”

Once you have a Record in automated lifecycle, set up CI/CD to push updates automatically.

  1. In your GitHub repository, go to Settings > Secrets and variables > Actions.

  2. Add these secrets:

    • PHASET_API_KEY: Your API key from Step 2
    • PHASET_ENDPOINT: Your Phaset URL (e.g., https://phaset.example.com/integration)
    • PHASET_ORG_ID: Your Organization ID
    • PHASET_RECORD_ID: Your Record ID

  3. Create .github/workflows/phaset.yml in your repository:

name: Update Phaset


on:
  push:
    branches: [main]


jobs:
  phaset:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4


      - name: Update Phaset Record
        uses: phasetdev/phaset-action@v0
        with:
          endpoint: ${{ secrets.PHASET_ENDPOINT }}
          api-key: ${{ secrets.PHASET_API_KEY }}
          org-id: ${{ secrets.PHASET_ORG_ID }}
          record-id: ${{ secrets.PHASET_RECORD_ID }}

  1. Commit and push this workflow file.

  2. The workflow will run automatically on the next push to main, updating your Record in Phaset.

Step 4: Verify your Record

Section titled “Step 4: Verify your Record”

  1. Navigate to the Catalog in Phaset.

  2. Find your newly updated Record (use search or filters if needed).

  3. Click on the Record to view its details.

  4. Verify that all information appears correctly.

For automated Records, make a small change to phaset.manifest.json, commit it, and verify that Phaset updates automatically after your CI/CD runs.

What’s next?

Section titled “What’s next?”

Now that you have your first Record, consider:

Add Standards tracking — Define quality standards and automatically track compliance. See the Standards guide. TODO

Set up Metrics — Configure webhooks to track DORA metrics and engineering productivity. See the Integration guide. TODO

Create more Records — Document your entire software landscape for complete visibility.

Define Baselines — Set organizational standards that Records should meet. See the Baselines guide. TODO

Troubleshooting

Section titled “Troubleshooting”

Record not appearing in Catalog?

  • Verify your Organization ID is correct
  • Check that you saved/created the Record
  • For automated Records, ensure the CI/CD job ran successfully

CI/CD integration failing?

  • Double-check all secrets/variables are set correctly
  • Verify the phaset.manifest.json file is valid JSON
  • Check your CI/CD logs for specific error messages
  • Ensure Node.js is available in your CI environment

Need help?

Section titled “Need help?”