Getting Started and Developer Tooling

Relevant source files

• .config.env.example
• .github/workflows/flux-local.yaml
• .github/workflows/fly-deploy.yaml
• .github/workflows/image-pull.yaml
• .github/workflows/label-sync.yaml
• .github/workflows/labeler.yaml
• .github/workflows/renovate.yaml
• .github/workflows/tag.yaml
• .github/workflows/terraform-publish.yaml
• .justfile
• .mise.toml
• .taskfiles/Repository/Taskfile.yaml
• docs/ai-context/CONVENTIONS.md
• infrastructure/ansible/requirements.txt
• infrastructure/terraform/proxmox/talos/inline-manifests/cilium-install.yaml
• infrastructure/terraform/s3/backblaze/b2.tf
• requirements.txt

This page covers the developer workflow for the home-ops repository. It details the local environment setup, the prerequisite toolchain managed via mise, and the operational workflows for managing the cluster using task and flux-local.

Developer Environment Setup

The repository utilizes a modern developer toolchain designed for consistency across different machines. The primary entry point for environment management is mise, which handles tool versions and environment variables.

Prerequisites

The following tools are required for cluster operations:

Tool	Purpose	Implementation Reference
mise	Polyglot tool manager and environment handler	.mise.toml1-18
task	Task runner for common operations	.github/workflows/fly-deploy.yaml62-67
sops	Secret encryption/decryption using Age	docs/ai-context/CONVENTIONS.md190-194
talosctl	Interaction with Talos Linux nodes	.github/workflows/image-pull.yaml105-109
kubectl	Kubernetes cluster management	-
flux-local	Local validation of Flux manifests	.mise.toml18

Environment Configuration

Local environment variables are managed via .mise.toml, which automatically loads configuration from .config.env and versions.env.

1. Global Paths: mise sets up KUBECONFIG, TALOSCONFIG, and SOPS_AGE_KEY_FILE to point to the repository root by default <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.mise.toml#L1-L6" min=1 max=6 file-path=".mise.toml">Hii</FileRef>.
2. Configuration Files: The system looks for .config.env for cluster-specific secrets and kubernetes/apps/system-upgrade/versions.env for software version pinning <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.mise.toml#L9-L12" min=9 max=12 file-path=".mise.toml">Hii</FileRef>.
3. Python Environment: Python dependencies, including makejinja for templating and ansible for host configuration, are defined in requirements.txt``<FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/requirements.txt#L1-L8" min=1 max=8 file-path="requirements.txt">Hii</FileRef> and infrastructure/ansible/requirements.txt``<FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/infrastructure/ansible/requirements.txt#L1-L9" min=1 max=9 file-path="infrastructure/ansible/requirements.txt">Hii</FileRef>.

Tooling Data Flow

The following diagram illustrates how local configuration files interact with the developer tools to manage the cluster.

Local Tooling Integration

[Flowchart Diagram]

Sources: <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.mise.toml#L1-L18" min=1 max=18 file-path=".mise.toml">Hii</FileRef>, <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/docs/ai-context/CONVENTIONS.md?plain=1#L190-L194" min=190 max=194 file-path="docs/ai-context/CONVENTIONS.md">Hii</FileRef>

Task Runner (Taskfile)

The repository uses go-task as a task runner to abstract complex commands into simple aliases. These tasks are organized into specialized files (e.g., .taskfiles/Repository/Taskfile.yaml).

Common Operations

• Bootstrapping: Initial cluster setup involves pre-installing CRDs via helmfile before handing over control to Flux <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/9.2. System Upgrades and Bootstrap" undefined file-path="9.2. System Upgrades and Bootstrap">Hii</FileRef>.
• Secret Management: SOPS is used for encrypting Kubernetes Secrets. Files must end in .sops.yaml to be recognized <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/docs/ai-context/CONVENTIONS.md?plain=1#L190-L194" min=190 max=194 file-path="docs/ai-context/CONVENTIONS.md">Hii</FileRef>.
• Validation: flux-local is used to verify that Kustomizations and HelmReleases are syntactically correct and will render properly in the cluster.

CI/CD and Validation Workflows

The developer workflow is mirrored in GitHub Actions to ensure that every Pull Request is validated before merging.

Flux Local Validation

The flux-local.yaml workflow performs two critical checks:

1. Test: Runs flux-local test against kubernetes/flux/cluster to ensure all manifests are valid <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/flux-local.yaml#L39-L48" min=39 max=48 file-path=".github/workflows/flux-local.yaml">Hii</FileRef>.
2. Diff: Runs flux-local diff for both helmrelease and kustomization resources. It compares the PR branch against the main branch and posts the diff as a comment on the PR <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/flux-local.yaml#L49-L131" min=49 max=131 file-path=".github/workflows/flux-local.yaml">Hii</FileRef>.

Image Management

To minimize downtime during node upgrades or application restarts, the image-pull.yaml workflow identifies new container images in a PR and uses talosctl to pre-pull them onto the nodes <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/image-pull.yaml#L105-L110" min=105 max=110 file-path=".github/workflows/image-pull.yaml">Hii</FileRef>.

CI/CD Pipeline Logic

sequenceDiagram
    participant Dev as Developer
    participant GHA as GitHub Actions
    participant FL as flux-local (CLI)
    participant T as talosctl
    Dev->>GHA: Push Pull Request
    GHA->>FL: flux-local test --path kubernetes/flux/cluster
    FL-->>GHA: Validation Results
    GHA->>FL: flux-local diff (helmrelease/kustomization)
    FL-->>GHA: Unified Patch
    GHA->>Dev: Post Diff Comment on PR
    GHA->>T: talosctl image pull (New Images)
    T-->>GHA: Success

Sources: <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/flux-local.yaml#L39-L131" min=39 max=131 file-path=".github/workflows/flux-local.yaml">Hii</FileRef>, <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/image-pull.yaml#L105-L110" min=105 max=110 file-path=".github/workflows/image-pull.yaml">Hii</FileRef>

Repository Maintenance

The repository uses several automated processes to maintain its health:

• Renovate: Runs hourly to update dependencies (Helm charts, Container images, Terraform providers) <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/renovate.yaml#L11-L12" min=11 max=12 file-path=".github/workflows/renovate.yaml">Hii</FileRef>. It follows strict rules for auto-merging and uses flux-local for PR validation.
• Label Sync: Synchronizes GitHub labels from .github/labels.yaml to maintain consistent categorization across the repository <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/label-sync.yaml#L30-L35" min=30 max=35 file-path=".github/workflows/label-sync.yaml">Hii</FileRef>.
• Versioning: A custom script generates CalVer-style tags (e.g., YYYY.MM.Patch) on a monthly schedule or via manual dispatch <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/tag.yaml#L7-L8" min=7 max=8 file-path=".github/workflows/tag.yaml">Hii</FileRef>, <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/tag.yaml#L40-L47" min=40 max=47 file-path=".github/workflows/tag.yaml">Hii</FileRef>.
• Terraform Publishing: When infrastructure changes are pushed, Terraform manifests are bundled into OCI artifacts and pushed to GHCR for the in-cluster tofu-controller to consume <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/terraform-publish.yaml#L41-L52" min=41 max=52 file-path=".github/workflows/terraform-publish.yaml">Hii</FileRef>.

Sources: <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/renovate.yaml#L1-L73" min=1 max=73 file-path=".github/workflows/renovate.yaml">Hii</FileRef>, <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/label-sync.yaml#L1-L35" min=1 max=35 file-path=".github/workflows/label-sync.yaml">Hii</FileRef>, <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/tag.yaml#L1-L71" min=1 max=71 file-path=".github/workflows/tag.yaml">Hii</FileRef>, <FileRef file-url="https://github.com/chaijunkin/home-ops/blob/b5f8d898/.github/workflows/terraform-publish.yaml#L1-L52" min=1 max=52 file-path=".github/workflows/terraform-publish.yaml">Hii</FileRef>