Repository Structure

Veckl stores user data in the configured GitHub or GHES repository. It does not require a database or local Git clone.

Required Files and Directories

Veckl expects:

config/
  catalog.json
  components.yaml
  sequence-counters.yaml
test-cases/
  .gitkeep
README.md

If these are missing, use Admin > Initialize Repository.

test-cases/

Each test case is stored as a Markdown file.

The YAML frontmatter stores structured fields such as:

• ID.
• Primary control.
• Lifecycle.
• Status.
• Assessor.
• Satisfied controls.
• Prerequisites.
• Testing process.
• Overall results.

The Markdown body can hold supporting narrative content.

config/components.yaml

This file stores the component registry:

components:
  - code: RHEL9
    name: Red Hat Enterprise Linux 9
    description: Linux server baseline

Component codes are used in generated test case IDs.

config/catalog.json

This file stores the controls catalog used by pickers and validation. It can be imported from the latest NIST OSCAL source, from a Veckl catalog export, from raw OSCAL JSON, or from an existing Veckl catalog file.

config/sequence-counters.yaml

This file stores sequence counters used when Veckl generates new test case IDs.

Do not edit this file by hand unless you are intentionally repairing ID sequencing.

config/repo-target.yaml

When an admin changes the repository target from the UI, Veckl can persist the runtime owner, repository, and branch target in repository configuration.

Environment variables remain the initial operator configuration.

Git History

Veckl commits changes through the GitHub API. Use GitHub file history, commit history, and pull-request processes according to your team’s audit practices.