2. Understanding Repository Organization
Learning Objectives
By the end of this section, you will:
- Understand the branch strategy for STIG profiles
- Learn about semantic versioning in the context of STIG releases
- Know how to navigate tags and releases
Repository Structure Overview
The InSpec profile repository should have a structured branching and tagging strategy to manage STIG profile versions and updates. This organizational strategy ensures reliable tracking of changes and stable releases for production use.
Branch Strategy
Security developers and engineers should be putting actively developed changes and updates into feature branches. Once those feature branches have been completed and peer reviewed, they should be merged into the version branch for the respective guidance release. Once all required features, changes, bugfixes, etc. have been merged in, a release should be created - this means that the version branch should be merged into your main branch and a tag should be created. The main branch of the repository ought to be the latest, working version of the codebase.
Branches are not releases
Sometimes code ends up merged directly to the main branch - this is fine - the main branch is not a formal release.
| Main Branch | Version Branch (`v{x}r{xx}`) | |
|---|---|---|
| Purpose | Active development and testing | Work-in-progress tracking a major STIG benchmark release |
| Contains | Latest code and patches | Code that is becoming aligned to an official guidance release DISA usually releases updates to STIGs on a quarterly basis. See the [DISA STIG Document Library](https://public.cyber.mil/stigs/downloads/). |
| Example branch name | `main` or `master` | `v1r12` for Version 1, Release 12 |
Version Control and Tagging Strategy
Tags
Current Tag
We do not recommend using a current or latest tag - if someone needs the latest and greatest, they can pull directly from the main branch of the repository.
Major Tags
Major tags point to the latest patch releases of the benchmark. For example, v1, v1.3, and v1.3.0 all should point at the same commit representing the first release of the Red Hat Enterprise Linux 8 STIG V1R3 Benchmark. The v1.12.xx tag(s) would represent the V1R12 Benchmark releases as we find bugs, fixes, or general improvements to the testing profile.
Patch Releases
The latest patch release always points to the major release for the profile.
For example, after releasing v1.12.0, we will point v1.12 to that patch release: v1.12.0. When an issue is found, we will fix, tag, and release v1.12.1. We will then 'move' the v1.12 tag so that it points to tag v1.12.1. This way, your pipelines can choose if they want to pin on a specific release of the InSpec profile or always run using the latest code on the main branch.
Semantic Versioning (SemVer)
Format: MAJOR.RELEASE.PATCH
- MAJOR: Matches STIG version
- RELEASE: Matches STIG release
- PATCH: Profile updates between STIG releases