First Run

After installation, use the Admin area to prepare the repository and then create your first test case.

Sign In

1. Start Veckl with make dev or open your deployed URL.
2. Select Sign in with GitHub.
3. Complete the GitHub OAuth flow.

After sign-in, the top bar shows the connected repository and branch.

Check Repository Settings

Open Admin and review the repository target:

• Owner.
• Repository.
• Branch.

Use Test Connection before saving changes. The GitHub App installation must already have access to the repository you enter.

Initialize the Repository

If the repository is missing required files, the Admin screen shows Needs initialization.

Select Initialize Repository. Veckl creates the starter structure without overwriting existing files.

The initialized repository contains:

• test-cases/
• config/components.yaml
• config/catalog.json
• config/sequence-counters.yaml

Add Components

Components are the systems, products, environments, or assets your test cases apply to.

In Admin, open Components, then add entries such as:

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

Use short uppercase codes. Veckl uses the code when generating test case IDs.

Import the Controls Catalog

In Admin, open Catalog.

For connected environments:

1. Select Preview to check the latest NIST catalog release.
2. Select Commit Import to save it to config/catalog.json.

For disconnected environments:

1. Export a catalog from a connected Veckl environment.
2. Move the export file into the disconnected environment.
3. Use Air-Gapped Import to upload it.

Create a Test Case

1. Open Test Cases.
2. Select New Test Case.
3. Choose a primary security control.
4. Choose the component being tested.
5. Add the assessor.
6. Add prerequisites and step-by-step testing instructions.
7. Save as a draft or create the active test case.

Veckl writes the test case as Markdown in test-cases/ and commits it to GitHub.

Execute a Test Case

1. Open a test case.
2. Select Execute.
3. Mark each step as pass, fail, or not tested.
4. Review the rollup.
5. Save the execution results.

The overall status is calculated from the step statuses and committed back to the repository.