mtcvctm GitHub Action

Overview

View on GitHub Report Issues

The mtcvctm GitHub Action automates the process of:

• Converting Markdown credential documentation to credential metadata JSON
• Generating multiple output formats: SD-JWT VC (VCTM), mso_mdoc (ISO 18013-5), and W3C VCDM 2.0
• Maintaining a dedicated vctm branch with generated files
• Creating the registry manifest for discovery
• Keeping credential metadata synchronized with your documentation

Quick Start

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

name: Generate Credential Metadata

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 Credential Metadata
        uses: sirosfoundation/mtcvctm-action@v1
        with:
          input-dir: credentials
          output-branch: vctm
          base-url: https://example.com/credentials

Action Inputs

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.vctm.json   # SD-JWT VC Type Metadata
│   ├── IdentityCredential.mdoc.json   # mso_mdoc (ISO 18013-5)
│   ├── IdentityCredential.vc.json     # W3C VCDM 2.0 Schema
│   ├── MembershipCredential.vctm.json
│   ├── MembershipCredential.mdoc.json
│   └── MembershipCredential.vc.json
└── README.md                  # Auto-generated documentation

Multi-Format Output

mtcvctm automatically generates three credential format specifications from each Markdown source file:

All three formats are derived from the same Markdown source, ensuring consistency across credential implementations. Format-specific options can be configured via front matter (see Markdown Format).

Example Workflow: Multi-Environment

For organizations with staging and production environments:

name: Generate Credential Metadata

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 Credential Metadata
        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 credential metadata
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

Credential metadata not updating

Check that your paths filter includes all relevant files:

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

Invalid credential metadata 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 credential metadata:

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

Resources

• mtcvctm on GitHub - CLI tool and GitHub Action
• Docker Image - Container image on GitHub Container Registry
• SD-JWT VC Specification - SD-JWT VC type metadata reference
• Registry Documentation - How to register your credential types
• Support & Contributing - Report issues and contribute

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 credential metadata JSON, bridging the gap between documentation and specification.