Confluent Schema Registry GitHub Action

This GitHub Action automates the process of managing schemas with Confluent-compatible schema registries. It performs the following tasks:

1. Takes a schema file as input
2. Retrieves the latest version from the Schema Registry
3. Compares the schemas for differences
4. Updates the schema if there are differences

This action uses the official @kafkajs/confluent-schema-registry package for reliable schema registry interactions.

Key Features

• Environment-based namespacing for subjects (e.g., dev-myschema, prod-myschema)
• Support for AVRO, JSON, and PROTOBUF schema types
• Automatically checks for differences between schema on registry and schema in VCS

Usage

name: Schema Registry Update

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  update-schema:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Update Schema Registry
        uses: boldtrail/confluent-schema-registry-action@v1
        with:
          schema-file: './schemas/my-schema.json'
          subject-name: 'my-topic-value'
          schema-compatibility: 'BACKWARD'
          registry-url: 'https://schema-registry.your-domain.com'
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}
          schema-type: 'AVRO'
          environment: ${{ github.ref == 'refs/heads/main' && 'prod' || 'dev' }}
          subject-pattern: '{env}_{name}'
          register-new: true
          check-compatibility: true

Inputs

Input	Description	Required	Default
schema-file	Path to the schema file	Yes	N/A
subject-name	Subject name in the schema registry	Yes (if namespace not provided)	N/A
subject-namespace	Subject namespace in the schema registry	Yes (if name not provided)	N/A
schema-compatibility	Compatibility of the schema registry	Yes	BACKWARD
registry-url	URL of the Schema Registry	Yes	N/A
username	Username for registry authentication	No	N/A
password	Password for registry authentication	No	N/A
schema-type	Schema type (AVRO, JSON, or PROTOBUF)	No	AVRO
environment	Environment name for namespacing (e.g., dev, staging, prod)	No	N/A
subject-pattern	Pattern for constructing namespaced subjects	No	{namespace}.{name}
register-new	Whether or not to register a new version of the schema	No	true
check-compatibility	Whether or not to check the compatibility of the schema changes	No	true

Outputs

Output	Description
updated	Whether the schema was updated in the registry (true/false)
compatible	Whether the schema is compatible with the registry (true/false)
schema_id	The global ID of the registered schema
namespaced_subject	The actual subject name used in the registry (with environment namespace if applicable)

Environment Namespacing

This action supports adding environment-based namespaces to your subject names. This is useful for:

1. Maintaining environment-specific schemas: Keep dev, staging, and production schemas separate
2. Multi-tenant deployments: Organize schemas by team, product, or application
3. Migration scenarios: Maintain both legacy and new schema versions

To use environment namespacing:

- name: Update Schema Registry
  uses: boldtrail/confluent-schema-registry-action@v1
  with:
    schema-file: './schemas/user.json'
    subject-name: 'user-value'
    environment: 'dev'  # Will create 'dev-user-value' in the registry

You can customize the namespace pattern:

- name: Update Schema Registry
  uses: boldtrail/confluent-schema-registry-action@v1
  with:
    schema-file: './schemas/user.json'
    subject-name: 'user-value'
    environment: 'prod'
    subject-pattern: '{name}_{env}'  # Will create 'user-value_prod' in the registry

Dynamic Environment Selection

You can dynamically select the environment based on the branch or other CI/CD conditions:

- name: Update Schema Registry
  uses: boldtrail/confluent-schema-registry-action@v1
  with:
    schema-file: './schemas/user.json'
    subject-name: 'user-value'
    # Use 'prod' for main branch, 'staging' for release branches, otherwise 'dev'
    environment: >-
      ${{ 
        github.ref == 'refs/heads/main' && 'prod' || 
        startsWith(github.ref, 'refs/heads/release/') && 'staging' || 
        'dev'
      }}

Example Workflow

Here's an example workflow that updates the schema registry on changes to schema files and fails if there are compatibility issues:

name: Schema Validation and Update

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  schema-update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      # Determine environment based on branch
      - name: Set environment
        id: env
        run: |
          if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
            echo "name=prod" >> $GITHUB_OUTPUT
          elif [[ "${{ github.ref }}" == "refs/heads/staging" ]]; then
            echo "name=staging" >> $GITHUB_OUTPUT
          else
            echo "name=dev" >> $GITHUB_OUTPUT
          fi
      
      - name: Process User Schema
        id: user-schema
        uses: boldtrail/confluent-schema-registry-action@v1
        with:
          schema-file: './schemas/user.json'
          subject-name: 'user-value'
          registry-url: ${{ secrets.SCHEMA_REGISTRY_URL }}
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}
          environment: ${{ steps.env.outputs.name }}
      
      - name: Schema Update Summary
        run: |
          echo "User schema updated: ${{ steps.user-schema.outputs.updated }}"
          echo "User schema ID: ${{ steps.user-schema.outputs.schema_id }}"
          echo "Actual subject name: ${{ steps.user-schema.outputs.namespaced_subject }}"

License

MIT

Notes on Schema Registry Compatibility

Confluent-compatible schema registries follow specific compatibility rules:

• BACKWARD: New schema can be used to read data written with the previous schema
• BACKWARD_TRANSITIVE: All new schema versions can be used to read data written with any previous schema version
• FORWARD: Previous schema can be used to read data written with the new schema
• FORWARD_TRANSITIVE: All previous schema versions can be used to read data written with any later schema version
• FULL: Both backward and forward compatibility
• FULL_TRANSITIVE Both backward and forward transitive compatibility
• NONE: No compatibility checking

You can configure compatibility levels in your Schema Registry. If schema is new, it will be created with the provided compatibility level.