mtcvctm GitHub Action

Automatically generate and publish VCTM definitions from Markdown documentation using the mtcvctm GitHub Action.

Overview

View on GitHub

The mtcvctm GitHub Action automates the process of:

  • Converting Markdown credential documentation to VCTM JSON
  • Maintaining a dedicated vctm branch with generated files
  • Creating the registry manifest for discovery
  • Keeping VCTMs synchronized with your documentation

Quick Start

Create .github/workflows/vctm.yml in your repository: 

name: Generate VCTMs

on:
  push:
    branches: [main]
    paths:
      - 'credentials/**/*.md'
  workflow_dispatch:

permissions:
  contents: write

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Generate VCTMs
        uses: sirosfoundation/mtcvctm-action@v1
        with:
          input-dir: credentials
          output-branch: vctm
          base-url: https://example.com/credentials

Action Inputs

Input Required Default Description
input-dir Yes — Directory containing Markdown credential definitions
output-branch No vctm Branch to publish generated VCTMs to
base-url Yes — Base URL for VCT URIs (e.g., https://example.com/credentials)
config-file No mtcvctm.yaml Path to configuration file

Markdown Format

Create Markdown files with YAML front matter to define your credentials: 

---
vct: https://example.com/credentials/IdentityCredential
name: Identity Credential
description: A credential attesting to a person's identity
schema: https://example.com/schemas/identity.json
extends: https://example.com/credentials/BaseCredential
display:
  background_color: "#1a73e8"
  text_color: "#ffffff"
  logo:
    uri: https://example.com/logo.png
    alt_text: Example Organization
---

# Identity Credential

This credential represents a verified identity...

## Claims

| Claim | Description |
|-------|-------------|
| given_name | The person's given name |
| family_name | The person's family name |
| birthdate | Date of birth in ISO 8601 format |

## Usage

This credential can be used to...

Configuration File

Optionally create mtcvctm.yaml for advanced configuration: 

# mtcvctm.yaml
input: credentials
output: dist/vctm
base_url: https://example.com/credentials

# Default display properties applied to all credentials
defaults:
  display:
    locale: en-US
    background_color: "#ffffff"
    text_color: "#000000"

# Organization metadata
organization:
  name: Example Organization
  url: https://example.com
  logo: https://example.com/logo.png

Generated Output

The action creates the following structure in the vctm branch: 

vctm/
├── .well-known/
│   └── vctm-registry.json    # Registry manifest
├── credentials/
│   ├── IdentityCredential.json
│   └── MembershipCredential.json
└── README.md                  # Auto-generated documentation

Example Workflow: Multi-Environment

For organizations with staging and production environments: 

name: Generate VCTMs

on:
  push:
    branches: [main, develop]
    paths:
      - 'credentials/**/*.md'

jobs:
  generate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Set environment
        id: env
        run: |
          if [ "$" = "refs/heads/main" ]; then
            echo "base_url=https://credentials.example.com" >> $GITHUB_OUTPUT
            echo "branch=vctm" >> $GITHUB_OUTPUT
          else
            echo "base_url=https://staging.credentials.example.com" >> $GITHUB_OUTPUT
            echo "branch=vctm-staging" >> $GITHUB_OUTPUT
          fi
      
      - name: Generate VCTMs
        uses: sirosfoundation/mtcvctm-action@v1
        with:
          input-dir: credentials
          output-branch: $
          base-url: $

Manual Setup (Without Action)

If you prefer not to use the GitHub Action, you can use the mtcvctm CLI directly: 

# Install mtcvctm
go install github.com/sirosfoundation/mtcvctm@latest

# Generate VCTMs
mtcvctm generate -i credentials -o dist/vctm -b https://example.com/credentials

# Generate registry manifest
mtcvctm registry -i dist/vctm -o dist/vctm/.well-known/vctm-registry.json

Then manually create and push to the vctm branch.

Troubleshooting

Action fails with "permission denied"

Ensure the workflow has write permissions: 

permissions:
  contents: write

VCTMs not updating

Check that your paths filter includes all relevant files: 

on:
  push:
    paths:
      - 'credentials/**/*.md'
      - 'mtcvctm.yaml'

Invalid VCTM generated

Validate your Markdown front matter matches the expected schema. Run locally to debug: 

mtcvctm generate -i credentials -o /tmp/vctm --verbose

Next Steps

Once your GitHub Action is set up and generating VCTMs:

  1. Verify the vctm branch exists and contains valid VCTM files
  2. Check that .well-known/vctm-registry.json lists all your VCTMs
  3. Register your repository with the SIROS Registry

Resources

About the Name

Wondering about the unusual name? mtcvctm is an anagram of its purpose:

MarkDown To Create Verifiable Credential Type Metadata

The tool transforms human-readable Markdown documentation into machine-readable VCTM JSON, bridging the gap between documentation and specification.