fields.yaml

# Prose for the settings index in docs/configuration.md. `task settings-index`
# joins it with config/crd/bases and rewrites the generated block.
#
# This file owns the DESCRIPTION and the link to the section that explains a
# field. It does not own whether a field is required or what it defaults to:
# those come from the CRD schema, because a hand-written default is a claim that
# can be wrong, and three of them were.
#
# `default:` here describes what omitting a field DOES when the schema declares
# no default of its own ("anonymous access"). Setting it for a field the schema
# already defaults is an error.
#
# A path listed here is a leaf: its children are not required. A top-level field
# with no entry must have every child described, or the run fails naming it. That
# is how `commit.window` stays in the table while the message templates do not.

preamble: |
  ## Field overview

  Ready-made manifests for all ten objects live in [`config/samples/`](../config/samples/). They
  cross-reference the same `example-provider` / `example-target` names, so the set can be applied
  together and edited down, rather than assembled from the fragments below.

  Every field not marked **required** may be omitted. Sections linked from the tables explain the
  fields that need more than a line.

kinds:
  - kind: GitProvider
    title: "`GitProvider` (namespaced): where and how to push"
    fields:
      - path: url
        doc: Repository URL, SSH or HTTPS
      - path: allowedGitBranches
        default: "**no `GitBranch`**, its own namespace included"
        doc: >-
          Which namespaces' `GitBranch`es may claim which branches through this provider. Each grant
          has a `consumerNamespaces` block (`from`: `Same`, `Names`, `Selector`, `All`) and the
          `branchPatterns` it allows. See [the grants](#the-grants)
      - path: secretRef
        default: anonymous access
        doc: >-
          Secret holding the write credential. See
          [the credentials Secret](#gitproviderspecsecretref-the-credentials-secret)
      - path: knownHostsRef
        default: the Secret's own `known_hosts`
        doc: >-
          Optional ConfigMap or Secret sharing SSH host keys across providers. Host-key verification
          fails closed either way
      - path: commit.committer
        default: the operator's built-in identity
        doc: >-
          Name and email written as the commit committer. See
          [committer identity](#committer-identity)
      - path: commit.signing
        default: "off"
        doc: SSH commit signing. See [commit signing](#commit-signing)

  - kind: GitBranch
    title: "`GitBranch` (namespaced): one branch of the repository"
    intro: "Every field but `allowedGitTargets` is immutable: to change one, delete the `GitBranch` and create a new one."
    fields:
      - path: gitProviderRef
        doc: >-
          The `GitProvider` whose repository and credential write this branch: in this namespace, or
          `namespace` names another. Its `allowedGitBranches` must admit this namespace and `branch`
      - path: branch
        doc: >-
          Branch to write. Only one `GitBranch` holds a repository branch; see
          [who writes a repository branch](#who-writes-a-repository-branch)
      - path: allowedGitTargets
        doc: >-
          Which namespaces' `GitTarget`s may write through this branch, each grant with a
          `consumerNamespaces` block. Omitted, this branch's own namespace; `[]` admits nobody. The
          only mutable field. See [the grants](#the-grants)
      - path: parentBranch
        default: the remote's default branch
        doc: >-
          Branch a `branch` the remote does not have yet is created from. Only read, so it need not
          be allowed. See
          [starting the write branch from another branch](#starting-the-write-branch-from-another-branch-specparentbranch)

  - kind: GitReceiver
    title: "`GitReceiver` (namespaced): the endpoint a Git host notifies on a push"
    fields:
      - path: type
        doc: >-
          Payload and signature the host sends: `github`, `gitlab`, `gitea`, or `generic-hmac` for a
          relay of your own. See [`GitReceiver`](#gitreceiver)
      - path: secretRef
        doc: >-
          Secret, in this namespace, whose `token` key is the webhook secret. It also derives
          `status.webhookPath`

  - kind: KubeProvider
    title: "`KubeProvider` (namespaced): the source cluster"
    intro: "Set exactly one of `secretRef` and `inCluster`. Both are immutable: delete and recreate to repoint."
    fields:
      - path: secretRef
        default: none; set `inCluster` instead
        doc: >-
          Secret in this provider's namespace holding a kubeconfig for the source cluster. `key`
          defaults to `value`, then `value.yaml`. See [`KubeProvider`](#kubeprovider)
      - path: inCluster
        default: none; set `secretRef` instead
        doc: >-
          `{}` uses the operator's own identity. Honored only for a provider listed in
          `--in-cluster-kube-providers`. See
          [the operator's own identity](#the-operators-own-identity-specincluster)
      - path: allowedGitTargets
        doc: >-
          Which namespaces' `GitTarget`s may mirror through this provider, and what: each grant has a
          `consumerNamespaces` block, and `sourceNamespaces`, `clusterResources` or both. Omitted,
          this provider's own namespace mirrors the namespace of the same name; `[]` admits nobody.
          See [the grants](#the-grants)
      - path: allowedApplierClaims
        doc: >-
          Which namespaces' applier claims may hold an applier through this provider, and the
          `applierNamespaces` that applier may live in. Omitted, this provider's own namespace, for
          appliers in the namespace of the same name; `[]` admits nobody. See [the grants](#the-grants)
      - path: client.qps
        default: "`20`"
        doc: Client rate limit for this source cluster. Refused beside `inCluster`
      - path: client.burst
        default: "`30`"
        doc: Client burst for this source cluster. Refused beside `inCluster`
      - path: attribution.auditRoute
        default: "`<namespace>.<name>`"
        doc: >-
          Audit route this provider joins. A route is held by one namespace. See
          [audit route](#audit-route-and-auditfactsreceived)
      - path: commitRequests
        doc: >-
          Whether the `CommitRequest`s created on this cluster are served, and finished ones deleted:
          `Ignore`, `Reconcile`, `ReconcileAndDeleteFinished`. See
          [serving them](#serving-the-commitrequests-of-a-source-cluster)

  - kind: GitTarget
    title: "`GitTarget` (namespaced): which branch and folder"
    intro: "The destination fields are immutable: to move a target, delete it and create a new one."
    fields:
      - path: gitBranchRef
        doc: >-
          The `GitBranch` this target writes: its own namespace, or `namespace` names another. Its
          `allowedGitTargets` must admit this namespace
      - path: path
        doc: Folder within the repository. `.` targets the root; empty is rejected
      - path: kubeProviderRef
        doc: >-
          The `KubeProvider` to mirror from: its own namespace, or `namespace` names another. Its
          `allowedGitTargets` must admit this namespace
      - path: commit.window
        skip: a block; its two timers are listed below
      - path: commit.window.idleTimeout
        doc: >-
          Close a commit window after this much silence. `0s` commits every write on its own. See
          [the commit window](#the-commit-window-speccommitwindow)
      - path: commit.window.maxDuration
        doc: Close a commit window this long after it opened, however much keeps arriving
      - path: commit.message
        default: the built-in templates
        doc: How commits are phrased. See [commit messages](commit-messages.md)
      - path: allowedCommitRequests
        doc: >-
          The `CommitRequest`s that may save this target's windows: `consumerNamespaces` on the
          cluster GitOps Reverser runs in, `sourceNamespaces` on the one it mirrors. See
          [who may save](#who-may-save-specallowedcommitrequests)
      - path: placement.byType
        default: the built-in path
        doc: >-
          Per-type path templates for new documents. See
          [where new resources are written](#where-new-resources-are-written-specplacement)
      - path: placement.default
        default: the built-in path
        doc: Catch-all path template for types with no `byType` entry
      - path: placement.useKustomize
        default: "off"
        doc: >-
          Keep the folder a kustomize folder. See
          [keeping the folder a kustomize folder](#keeping-the-folder-a-kustomize-folder-specplacementusekustomize)
      - path: serializeNamespace
        default: inferred per document
        doc: >-
          Whether a committed document carries its own `metadata.namespace`. An explicit `false`
          admits exactly one source namespace. See
          [whether documents carry their namespace](#whether-documents-carry-their-namespace-specserializenamespace)
      - path: prune.mode
        doc: >-
          Which deletions reach Git. See
          [deletion policy](#deletion-policy-specprunemode)
      - path: applierClaimRef
        default: the applier applies on its own schedule
        doc: >-
          The `FluxClaim` or `ArgoCDClaim`, in this namespace, holding the applier of this
          folder, which GitOps Reverser then asks to apply. See
          [who applies this folder](#who-applies-this-folder-specapplierclaimref)
      - path: onRefusal
        doc: >-
          What happens to an edit with no legal destination. See
          [reverting a refused edit](#reverting-a-refused-edit-speconrefusal)
      - path: encryption
        default: "off"
        doc: SOPS + age encryption for sensitive resources
      - path: suspend
        default: "`false`"
        doc: >-
          Stop writing without deleting the target. See
          [stopping a target from writing](#stopping-a-target-from-writing-specsuspend)

  - kind: WatchRule
    title: "`WatchRule` (namespaced): what to capture"
    fields:
      - path: gitTargetRef
        doc: The `GitTarget` these rules feed
      - path: rules.resources
        doc: Plural resource names to watch
      - path: rules.apiGroups
        default: resolved from the resource name
        doc: >-
          API groups to match. `[""]` is the core group. Omitted resolves the named resource across
          the served surface, and selects nothing when more than one group serves that name
      - path: rules.apiVersions
        default: the preferred served version
        doc: API versions to match. `["*"]` watches every served version
      - path: rules.sourceNamespace
        default: the rule's own namespace
        doc: >-
          Namespace to watch in the source cluster, or `*`. See
          [watching a different source namespace](#watching-a-different-source-namespace)
      - path: rules.objectSelector
        default: every object
        doc: >-
          Label selector the API server applies to the item's LIST and WATCH. See
          [selecting objects by label](#selecting-objects-by-label-rulesobjectselector)

  - kind: ClusterWatchRule
    title: "`ClusterWatchRule` (cluster-scoped): what to capture, cluster-wide"
    intro: >-
      The same shape as a `WatchRule`, for cluster-scoped types. It selects no namespaces, so it has
      no `sourceNamespace`.
    fields:
      - path: gitTargetRef
        doc: The `GitTarget` these rules feed
      - path: rules.resources
        doc: Plural cluster-scoped resource names to watch
      - path: rules.apiGroups
        default: resolved from the resource name
        doc: >-
          API groups to match. Omitted resolves the named resource across the served surface, and
          selects nothing when more than one group serves that name
      - path: rules.apiVersions
        default: the preferred served version
        doc: API versions to match. `["*"]` watches every served version
      - path: rules.objectSelector
        default: every object
        doc: >-
          Label selector the API server applies to the item's LIST and WATCH. See
          [selecting objects by label](#selecting-objects-by-label-rulesobjectselector)

  - kind: FluxClaim
    title: "`FluxClaim` (namespaced): the Flux `Kustomization` GitOps Reverser asks to apply"
    intro: "The references are immutable: to hold another `Kustomization`, delete the applier claim and create a new one."
    fields:
      - path: kubeProviderRef
        doc: >-
          The `KubeProvider` whose cluster holds the `Kustomization`: the applier claim's own namespace, or
          `namespace` names another. Its `allowedApplierClaims` must admit this namespace
      - path: kustomizationRef
        doc: >-
          The `Kustomization` that applies the folders of the `GitTarget`s naming this applier claim. See
          [who applies this folder](#who-applies-this-folder-specapplierclaimref)
      - path: catchUpAfter
        doc: >-
          How long the `Kustomization` stays behind the branch after a push of GitOps Reverser's own
          before an apply of the tip is asked for. Such a push needs no apply for the cluster, but leaves
          `status.lastAppliedRevision` and the `GitRepository`'s artifact at the commit before it. The
          interval starts when the `Kustomization` is first seen behind, so a burst of saves costs one
          apply; the apply can still wait for startup, a retry backoff or edits being published, and an
          edit arriving before the resume defers it by an interval. `0s` never asks for this reason, and
          drops an apply it asked for that has not started; otherwise `10s` to `24h`

  - kind: ArgoCDClaim
    title: "`ArgoCDClaim` (namespaced): the Argo CD `Application` GitOps Reverser asks to sync"
    intro: "The references are immutable: to hold another `Application`, delete the applier claim and create a new one."
    fields:
      - path: kubeProviderRef
        doc: >-
          The `KubeProvider` whose cluster holds the `Application`: the applier claim's own namespace, or
          `namespace` names another. Its `allowedApplierClaims` must admit this namespace
      - path: applicationRef
        doc: >-
          The `Application`, with automated sync off, that syncs the folders of the `GitTarget`s
          naming this applier claim. See [who applies this folder](#who-applies-this-folder-specapplierclaimref)
      - path: catchUpAfter
        doc: >-
          As a `FluxClaim`'s: how long the `Application`'s last sync stays behind the branch after a push
          of GitOps Reverser's own before a sync of the tip is asked for. Off by default, since a sync runs
          the `Application`'s hooks and Argo CD's refresh already compares the live state against the tip.
          Otherwise `10s` to `24h`

  - kind: CommitRequest
    title: "`CommitRequest` (namespaced, here or on a source cluster): save now"
    fields:
      - path: gitTargetRef
        doc: >-
          The target whose commit window the request attaches to: in this namespace, or `namespace`
          names another, whose `allowedCommitRequests` must admit this one. On a source cluster
          `namespace` is required. See [where a request is created](#where-a-request-is-created)
      - path: message
        default: the target's templates
        doc: Commit message, committed verbatim unless `requestTemplate` frames it
      - path: window.attach
        doc: >-
          Which window to attach to: the author's current or next one, or only the next. See
          [the request window](#the-request-window-specwindow)
      - path: window.attachTimeout
        doc: How long to wait for a window to attach to
      - path: window.idleTimeout
        default: no idle close
        doc: Close the attached window after this much silence
      - path: window.maxDuration
        doc: Close the attached window this long after the attach
      - path: whenNothingToCommit
        doc: "`CommitEmpty` records the message in an empty commit when nothing changed"
      - path: catchUp
        doc: >-
          `AfterPush` asks the `GitTarget`'s applier to apply the branch tip right after the commit is
          pushed, instead of after the applier claim's `catchUpAfter`. The tip may hold later commits,
          and saves pushed close together can share one apply; the `Applied` condition reports it