Skip to content

GitHub Workflow

This page describes how work flows through the HomeKube repository — from idea to merged code.

Issue lifecycle

Open → In Progress → Review → Closed
  1. Open — use one of the issue templates (Feature, Bug, ADR).
  2. Triage — assign to a milestone so it appears in the project board.
  3. In Progress — create a branch, reference the issue in commit messages.
  4. Review — open a pull request with Closes #<n> in the description.
  5. Closed — automatically closed when the PR merges into main.

Milestones

Issues are grouped into milestones that map to feature epics:

Milestone Focus
Workloads Sample apps, HPA, PVC, image automation
Policy & Observability Policy engine, distributed tracing
CI/CD Pipeline tooling, multi-env promotion
Platform Tooling Kubernetes UI dashboard, documentation hosting

Branch strategy

Branch off main for every change. Use the following naming scheme:

Pattern When to use
feat/<issue>-<slug> New feature — e.g. feat/1-podinfo-workload
fix/<issue>-<slug> Bug fix — e.g. fix/42-keycloak-crash
docs/<slug> Docs-only change
chore/<slug> Maintenance, dependency updates
flux/image-updates Automated — written by Flux image automation

Delete the branch after merge.

Commit conventions

All commits must follow Conventional Commits. The commit-msg prek hook enforces this locally.

<type>(<optional scope>): <subject>

Types: feat, fix, docs, chore, refactor, test, ci.

# Good
feat(apps): add podinfo HelmRelease and ingress
fix(identity): correct keycloak realm import path
docs(adrs): add ADR-016 workload pattern

# Bad (no type, uppercase subject, trailing period)
Added podinfo.

Pull request workflow

branch → commits → PR → review → squash merge → main
  1. Push branch and create a draft PR targeting main — body is pre-filled from the PR template: 
    gh pr create --draft --title "feat(<scope>): <subject>" --body-file .github/PULL_REQUEST_TEMPLATE.md
  2. Fill in the PR description using gh pr edit, checking every checklist item honestly.
  3. Include Closes #<n> to auto-close the issue on merge.
  4. All prek hooks must pass (CI will also run them in a future workflow).
  5. Mark the PR ready: gh pr ready <number>
  6. Use Squash and merge — keeps main history linear and commit messages clean.

PR checklist highlights

  • Conventional Commit message
  • flux get all -A clean
  • No plaintext secrets in diff
  • ADR added for architectural decisions
  • Docs + mkdocs.yml nav updated if new pages added

Branch protection (main)

main is protected with the following rules:

  • Direct pushes are not allowed — all changes require a PR.
  • Branch must be up to date before merging.
  • Stale reviews are dismissed when new commits are pushed.

Labels

The project uses GitHub's default labels:

Label When to apply
enhancement New feature or improvement
bug Something broken
documentation Docs-only change
good first issue Beginner-friendly task
help wanted Needs input from others
question Clarification needed
wontfix Intentionally not addressed