git-workflow

Git Workflow for OSCAL Compliance Documents

Purpose

Provide version control and change tracking for OSCAL compliance documents using a two-branch strategy: baseline (<id>-initial) and review (<id>-review) branches.

Important: Opt-in Only

This workflow is NOT executed by default. Only use when user explicitly requests:

• "Use Git for version control"
• "Create a PR at the end"
• "I want to track changes with Git"
• Or similar explicit requests

Default behavior: Skip all Git operations unless specifically requested.

Default Workflow

Phase 1: Setup (After Markdown Deployment)

Create baseline branch to establish change tracking foundation:

git checkout -b "<id>-initial"
git add -A && git commit -m "<message>"

Purpose: Establish a baseline for tracking changes.

Phase 2: Review (After Editing Completion)

Create review branch and pull request for change review:

Note: Direct commits to <id>-initial are prohibited (protected branch)

git checkout <id>-initial
git checkout -b <id>-review
git add -A && git commit -m "<message>"
git push origin <id>-initial <id>-review
gh pr create --base <id>-initial --head <id>-review

Best Practice: Squash multiple commits into one before creating the PR.

Branch Naming Convention

• <id>-initial: Baseline branch containing the initial state
• <id>-review: Review branch containing your changes

Replace <id> with a meaningful identifier for the compliance document or project (e.g., "nist-800-53-low", "fedramp-moderate").

Rules

• Never execute Git operations unless user explicitly requests
• Always confirm branch identifier <id> with user before creating branches
• Protect <id>-initial branch from direct commits
• Use descriptive commit messages referencing control IDs when possible
• Squash commits before PR creation for clean history

When to Recommend This Workflow

Suggest this workflow when:

• User mentions formal change tracking or review processes
• Multiple people are collaborating on compliance documents
• User needs clear audit trail of changes
• Organization requires pull request reviews