semaphore-config-schema

Semaphore — Config Schema Generator

This skill produces and maintains config.schema.yaml — a JSON Schema draft 2020-12 document (written in YAML) describing every valid key in a Semaphore config.json / config.yaml. The schema is the source of truth for IDE autocomplete (via yaml-language-server) and for any future server-side config validation.

The schema is derived from Go code, never hand-edited speculatively. If ConfigType doesn't have a field, the schema must not have it. If a field has a default: or rule: tag, the schema must reflect it.

Inputs (source of truth)

All Go types live in the util package. Read these files in full before writing anything:

If a struct moves or a new file appears, find it with:

grep -rn "^type .* struct" util/ | grep -v _test

Output

A single file: config.schema.yaml in the repository root.

Header (top of file) — keep exactly this shape:

$schema: "https://json-schema.org/draft/2020-12/schema"
$id: "https://semaphoreui.com/schemas/config.schema.json"
title: Semaphore configuration
description: Schema for Semaphore UI config.json / config.yaml. Generated from util.ConfigType.
type: object

Field-mapping rules

These are non-negotiable — apply them mechanically.

Property name

Use the json: tag's first segment (before any comma):

Port string `json:"port,omitempty" ...`   // → property name "port"

Skip fields where the json: tag is "-" (e.g. RunnerConfig.RegistrationToken, SubscriptionConfig.Key — those are env-only, not file-configurable). Document this in the schema's description for the containing struct if a sensitive token is reachable only via env.

Skip unexported fields (lowercase first letter) — but include their referenced types if they appear via exported fields. Example: oidcEndpoint is unexported but referenced from OidcProvider.Endpoint, so define it under $defs as OidcEndpoint.

JSON Schema type

Constraints from tags

• default:"X" → emit default: X (cast to the right type — default:"10" on int becomes default: 10).
• rule:"^...
  quot; → emit pattern: "^...
  quot;. Don't also add a format: — the regex is more authoritative.
• env:"NAME,sensitive" → append (sensitive). to the description. The schema doesn't have a native "sensitive" flag, so this is documentation-only.
• env:"NAME" without sensitive → no change to schema.
• URL-looking string fields (web hooks, redirect URLs) → add format: uri unless a pattern is already set from a rule: tag.

enum discovery

enum is not always in tags — sometimes it's in code:

1. Check for a rule:"^a|b|c
   quot; regex — convert that to enum: [a, b, c] instead of a pattern (more useful in IDE).
2. Check for typed constants near the struct (e.g. SyslogFormat has SyslogDefault = "" and SyslogRFC5424 = "rfc5424" → enum: ["", rfc5424]).
3. TeamInviteType constants (TeamInviteEmail, TeamInviteUsername, TeamInviteBoth) → enum.

Reusable types → $defs

Every named struct that appears as a field type gets a $defs/<TypeName> entry. Reference via $ref: "#/$defs/<TypeName>". Top-level properties should reference, not inline.

Exception: lumberjack.Logger is external — define a minimal stub $defs/LumberjackLogger with the common fields (filename, maxsize, maxage, maxbackups, localtime, compress). Do not try to fully model it.

additionalProperties

Leave it unset (defaults to true). The schema is informational, not strict — making it strict would break existing configs that have stray keys (legacy fields, typos used as comments, etc.).

Workflow

1. Read all four Go files

Use Read on each file. Do not skim. Note every exported field on every struct.

2. Build a mental map: struct → properties

For ConfigType (the root), list every exported field with its json: name, Go type, and any default: / rule: / env: tags. Then for each referenced struct, do the same. Stop when no new structs appear.

3. Diff against existing config.schema.yaml

Before writing, compare what Go has vs. what the schema has:

# List all json tag names in Go
grep -hoE 'json:"[^,"]+' util/*.go | sed 's/json:"//' | sort -u > /tmp/go-keys.txt

# List all property keys in the schema
yq '.properties | keys | .[]' config.schema.yaml | sort -u > /tmp/schema-keys.txt

diff /tmp/go-keys.txt /tmp/schema-keys.txt

Identify three categories:

• In Go, missing from schema → add.
• In schema, missing from Go → remove (the Go struct is the source of truth).
• In both → check that type / default / pattern still match.

Show the user the diff before applying changes if it's larger than ~5 lines.

4. Write config.schema.yaml

Use the YAML formatting conventions already established in the file:

• Section comments split top-level properties into visual groups: # === Database ===, # === HTTP server ===, # === Authentication ===, etc.
• Inline-object syntax { type: string, default: foo } for one-property entries.
• Multi-line block form when there are 3+ properties or a description.
• Quote string values that contain :, /, +, =, or start with a digit. Don't quote bare identifiers like string, boolean, integer.
• $ref values are quoted: { $ref: "#/$defs/DbConfig" }.

5. Validate

After writing, run two checks:

python3 - <<'PY'
import yaml, jsonschema
with open("config.schema.yaml") as f:
    schema = yaml.safe_load(f)
jsonschema.Draft202012Validator.check_schema(schema)  # meta-validation
print("schema is valid")

# Confirm an existing config.yaml still passes
try:
    with open("config.yaml") as f:
        cfg = yaml.safe_load(f)
    errors = list(jsonschema.Draft202012Validator(schema).iter_errors(cfg))
    print(f"config.yaml: {len(errors)} error(s)")
    for e in errors:
        print(f"  {list(e.path)}: {e.message}")
except FileNotFoundError:
    pass
PY

Both must pass. If config.yaml doesn't exist locally, skip the second check — the meta-validation alone is sufficient.

6. Don't touch config.yaml

The user's config.yaml may contain stray legacy keys or comments. Do not "clean it up" as part of this skill — the schema generation is a one-way operation Go → schema. If the user wants a cleaner config, that's a separate task.

Common pitfalls

• json:"-" fields: easy to accidentally include. Always check the tag, not the field name.
• Pointer vs. value: *int is nullable, plain int is not. Reflect that in type.
• Typo'd filenames: util/OdbcProvider.go (should be Oidc) — preserve it; renaming files is out of scope.
• Tag inheritance illusion: nested structs don't inherit tags from their parent field. The default: on ConfigType.MaxParallelTasks is on the field, not on int.
• sensitive is not standard: JSON Schema has no built-in sensitive marker. Encode it in description text only.
• Existing keys with apostrophes in config.yaml (e.g. "'email_sender") are user-side comment hacks — ignore them, they're not in any Go struct.

When to refuse

If the user asks to add a property to the schema that doesn't exist in ConfigType ("just add a foo field so my config validates"), refuse and explain: the schema is generated from Go. The fix is to add the field to the Go struct first, then regenerate.

If ConfigType has been heavily refactored and a previous schema entry no longer maps, propose the deletion explicitly before doing it — never silently drop entries that the user might have been relying on.