Setting up org invariants
Org invariants are rules that apply to every change in your organization. Instead of adding “requires authentication” to every spec, you define it once as an invariant and it’s checked automatically.
In this tutorial, you’ll create a security invariant that enforces authentication on HTTP handlers.
Time: 10 minutes
Prerequisites:
Admin access to your Aviator organization
Completed the Your first spec tutorial (recommended)
What you’ll do
Create an org invariant for authentication
Test it against an existing change
See how invariants appear in verification results
Step 1: Navigate to invariants
Go to Verify → Settings → Org Invariants.
You’ll see a list of existing invariants (possibly empty) and a button to create new ones.
Step 2: Create a new invariant
Click New Invariant.
Give it a name: security-baseline
Add a description: Core security requirements for all code changes
Step 3: Define the rules
In the invariant editor, add your security rules:
These rules are written in natural language. Verify understands them semantically.
Step 4: Configure scope
Invariants can apply to all files or specific paths. For this security baseline:
Applies to: All files (default)
Some invariants might only apply to certain areas:
API rules might apply only to
src/handlers/**Database rules might apply only to
src/db/**
For security, we want it everywhere. Leave it as “All files.”
Step 5: Save and enable
Click Save Invariant.
The invariant is now active. Toggle the Enabled switch if it isn’t already on.
Step 6: Test with a verification
Let’s see the invariant in action. Go back to one of your PRs that has verification results, or create a new spec and implement it.
When verification runs, you’ll see the invariant checks in the results:
Step 7: See a violation
Create a spec and implementation that violates an invariant. For example, add a hardcoded API key:
When verification runs:
The invariant caught the violation even though the spec didn’t mention credentials.
Step 8: Add an exception path
Some code legitimately doesn’t need certain checks. For example, your health check endpoint from the previous tutorial shouldn’t require authentication.
Edit the security-baseline invariant and add an exceptions section:
Save the invariant. Now the authentication rule won’t fail for health check handlers.
How invariants work with specs
Invariants and spec criteria work together:
Spec criteria
Requirements specific to this change
Org invariants
Organization-wide rules that always apply
You don’t need to repeat invariant rules in your specs. If authentication is an invariant, you don’t need to add “requires authentication” to every spec—it’s checked automatically.
But you can override invariants in a spec. If your spec explicitly says “does not require authentication” and has a valid reason in the intent, verification understands the exception.
What you learned
Org invariants define rules that apply to all changes
Rules are written in natural language
Invariants are checked alongside spec criteria
Exceptions can be defined for legitimate edge cases
You don’t need to repeat invariant rules in individual specs
Next steps
How-to: Add more invariants - Common invariant patterns
Configuration options - All invariant settings
Verification layers - How invariants, domain contracts, and specs work together
Last updated
Was this helpful?