CI/CD Integration

Use the Shoehorn CLI in your CI/CD pipelines to validate catalog manifests on every pull request. This catches errors before they reach your Shoehorn instance.

What it validates

The CLI checks .shoehorn/*.yaml and catalog-info.yaml files against the manifest schema:

• Required fields are present
• Field types are correct
• Entity references are valid
• Backstage compatibility (if using catalog-info.yaml)

GitHub Actions

Create .github/workflows/validate-manifests.yml:

name: Validate Manifests

on:
  pull_request:
    paths:
      - '**/*.yaml'
      - '**/*.yml'

jobs:
  validate:
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd

      - name: Install Shoehorn CLI
        run: |
          curl -sL https://github.com/shoehorn-dev/cli/releases/latest/download/shoehorn-linux-amd64 -o shoehorn
          chmod +x shoehorn
          sudo mv shoehorn /usr/local/bin/

      - name: Validate manifests
        run: |
          find . -path '*/.shoehorn/*.yaml' -o -name 'catalog-info.yaml' | \
          while read file; do
            echo "Validating $file"
            shoehorn validate "$file" || exit 1
          done

To validate only changed files:

      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
        with:
          fetch-depth: 0

      - name: Validate changed manifests
        run: |
          git diff --name-only origin/main...HEAD | \
          grep -E '\.yaml$' | \
          xargs -r shoehorn validate

GitLab CI

Add to .gitlab-ci.yml:

validate_manifests:
  stage: validate
  image: alpine:latest
  before_script:
    - wget -q https://github.com/shoehorn-dev/cli/releases/latest/download/shoehorn-linux-amd64 -O /usr/local/bin/shoehorn
    - chmod +x /usr/local/bin/shoehorn
  script:
    - |
      find . -path '*/.shoehorn/*.yaml' -o -name 'catalog-info.yaml' | \
      while read file; do
        echo "Validating $file"
        shoehorn validate "$file" || exit 1
      done
  only:
    changes:
      - "**/*.yaml"

Jenkins

Add to your Jenkinsfile:

stage('Validate Manifests') {
    steps {
        sh '''
            curl -sL https://github.com/shoehorn-dev/cli/releases/latest/download/shoehorn-linux-amd64 -o shoehorn
            chmod +x shoehorn
            find . -path '*/.shoehorn/*.yaml' -o -name 'catalog-info.yaml' | \
            while read file; do
                echo "Validating $file"
                ./shoehorn validate "$file" || exit 1
            done
        '''
    }
}

Converting Backstage manifests

If you are migrating from Backstage, validate that your catalog-info.yaml files convert cleanly:

shoehorn convert catalog-info.yaml --validate

This parses the Backstage format and checks that it maps to valid Shoehorn entities.

Registering entities from CI

You can also create or update entities from CI using the REST API with an API key:

curl -X POST https://shoehorn.example.com/api/v1/manifests/entities \
  -H "Authorization: Bearer $SHOEHORN_API_KEY" \
  -H "Content-Type: application/x-yaml" \
  --data-binary @.shoehorn/catalog.yaml

Generate an API key with catalog:write scope in Admin > Security > API Keys.

Tips

• Run validation on pull requests so broken manifests never merge.
• Use xargs -P 4 for parallel validation in repos with many manifests.
• Pin the CLI version in CI to avoid unexpected changes: download a specific release tag instead of latest.
• Keep manifests in .shoehorn/ directories — the crawler discovers them automatically, and CI validates them in the same location.