Repository Configuration¶
This guide demonstrates how to configure a GitHub Repository using git-hubby.
We continue with the Acme Corp example, configuring their order-service repository.
For the complete field reference, see the API Documentation.
Example: Order Service¶
apiVersion: github.interhyp.de/v1alpha1
kind: Repository
metadata:
name: order-service
namespace: git-hubby-system
spec:
# --- Organization Reference ---
organizationRef:
name: acme-corp # Must match an Organization CR
# --- Identity ---
name: order-service # Repository name on GitHub
visibility: internal # internal | private | public
# --- Metadata ---
about:
description: "Order management service - handles cart, checkout, and order lifecycle"
website: "https://docs.acme-corp.com/order-service"
topics:
- go
- grpc
- kubernetes
- orders
- checkout
# --- Custom Properties ---
# Values for properties defined in the Organization
customProperties:
- propertyName: team
value: checkout
- propertyName: service-tier
value: critical
- propertyName: compliance
values:
- pci-dss
- gdpr
- propertyName: slack-channel
value: "#checkout-alerts"
# --- Merge Settings ---
mergeStrategies:
- type: squash # Only allow squash merges
# --- Repository Features ---
hasIssues: true
hasWiki: false
hasProjects: false
hasDiscussions: false
allowAutoMerge: true
deleteBranchOnMerge: true
allowForking: false
webCommitSignoffRequired: true
# --- Team Permissions ---
teams:
- name: checkout-team
permission: push
- name: platform-team
permission: admin
- name: security-team
permission: triage
# --- Webhooks ---
webhookPresets:
- name: ci-webhooks
- name: security-scanning
# --- Branch Protection ---
rulesetPresets:
- name: default-branch-protection
rulesets:
- name: release-branches
target: branch
enforcement: active
conditions:
refName:
include:
- "refs/heads/release/*"
rules:
pullRequest:
requiredApprovingReviewCount: 2
dismissStaleReviewsOnPush: true
deletion: true
# --- Security ---
attachedCodeSecurityConfiguration:
name: strict-security
# --- Deploy Keys ---
deployKeys:
- title: "ArgoCD Read-Only"
key: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIExample..."
readOnly: true
Key Concepts¶
Organization Reference¶
Every repository must belong to an Organization:
The Organization CR must exist before creating Repository CRs that reference it.
Custom Properties¶
Set values for properties defined in your Organization:
# In Organization: defines the property schema
customProperties:
- propertyName: team
valueType: single_select
allowedValues: [platform, checkout, payments]
# In Repository: sets the value
customProperties:
- propertyName: team
value: checkout # single_select uses 'value'
- propertyName: compliance
values: # multi_select uses 'values'
- pci-dss
- gdpr
Team Permissions¶
Assign GitHub teams with specific access levels:
| Permission | Capabilities |
|---|---|
pull |
Clone, view code and issues |
triage |
+ Manage issues and PRs (no code changes) |
push |
+ Push code, create branches |
maintain |
+ Manage settings (except sensitive) |
admin |
Full access including settings and secrets |
Webhooks¶
Using Presets (recommended for consistency):
Inline webhooks for repository-specific needs:
webhooks:
- payloadUrl: "https://deploy.acme-corp.com/webhook/{{ .Name }}" # Go templates are rendered against the GitHub repository
contentType: json
secret:
name: webhook-secrets # Secret in the Repository's namespace
key: deploy-secret
events:
- push
- release
active: true
Inline webhooks support exactly the same fields as a WebhookPreset spec. Their behaviour:
- The operator reconciles the union of inline
webhooksand the referencedwebhookPresets. At most 10 inline webhooks are allowed. - A webhook is identified by its (templated) payload URL, content type and events. If several definitions (inline or from presets) share this identity:
- identical definitions are applied once and a warning is written to the operator log;
- different definitions (e.g. a different
active,sslVerifyor secret) are a conflict: no webhooks are changed on GitHub, theWebhooksSyncedcondition is set toFalse(reasonUserActionRequired) with the conflict in its message, andReadybecomesFalse.
- Secrets of inline webhooks must live in the Repository's namespace.
secret.namespacemay only be omitted or set to the Repository's namespace; other values are rejected by the validation webhook and by the reconciler. Prefersecretover the plaintextsecretValue. - A rotated secret is picked up on the next reconciliation (at the latest with the periodic success requeue); referenced Secrets are not watched.
Webhook Ignores¶
Existing webhooks whose URL matches an ignore rule are never deleted by the operator, e.g. webhooks managed by other tools.
webhookIgnorePresets:
- name: ignore-legacy-hooks # References a WebhookIgnorePreset CR
webhookIgnores:
- ignoreURLRegex: "^https://legacy\\.acme-corp\\.com/.*"
The operator uses the union of inline webhookIgnores and the referenced webhookIgnorePresets. At most 10 inline ignore rules are allowed; each must define a valid ignoreURLRegex.
Autolinks¶
autolinksPresets:
- name: jira-autolinks # References an AutolinksPreset CR
autolinks:
- keyPrefix: "TICKET-"
urlTemplate: "https://tickets.acme-corp.com/browse/TICKET-<num>"
isAlphanumeric: false
- The operator reconciles the union of inline
autolinksand the autolinks of the referencedautolinksPresets. At most 25 inline autolinks are allowed, and theirkeyPrefixes must be unique. - An autolink is identified by its
keyPrefix(GitHub requires unique key prefixes per repository). If several definitions share akeyPrefix:- identical definitions are applied once and a warning is written to the operator log;
- different definitions are a conflict: no autolinks are changed on GitHub and the
AutolinksSyncedcondition is set toFalse(reasonUserActionRequired). This also applies to conflicts between twoAutolinksPresets.
Rulesets¶
Using Presets applies organization-wide rules:
Inline rulesets for repository-specific rules:
rulesets:
- name: release-branches
target: branch
enforcement: active
conditions:
refName:
include:
- "refs/heads/release/*"
rules:
pullRequest:
requiredApprovingReviewCount: 2
# requiredReviewers requires ENABLE_REQUIRED_REVIEWERS_RULES=true (GitHub beta feature)
requiredReviewers:
- minimumApprovals: 1
filePatterns:
- "src/**"
reviewer:
slug: security-team # resolved to ID at reconciliation time
type: Team
requiredStatusChecks:
checks:
- context: "ci/build"
- context: "ci/test"
deletion: true # Prevent branch deletion
nonFastForward: true # Prevent force-push
Inline rulesets support exactly the same fields as a RulesetPreset spec. Their behaviour:
- The operator reconciles the union of inline
rulesetsand the referencedrulesetPresets. - At most 10 inline rulesets are allowed, and their names must be unique. Larger or shared sets of rules belong in
RulesetPresets. - If an inline ruleset and a referenced preset (or two referenced presets) have the same name:
- identical definitions are applied once and a warning is written to the operator log;
- different definitions are a conflict: no rulesets are changed on GitHub, the
RulesetsSyncedcondition is set toFalse(reasonUserActionRequired) with the conflict in its message, andReadybecomesFalse.
- Rulesets with
target: repository(inline or from presets) are only supported at organization level. At repository level they are filtered out, i.e. neither checked nor applied.
Extending rulesets¶
A RulesetPreset or an inline ruleset can extend another RulesetPreset (in the same namespace) via
extends and only state its differences. This avoids copying a whole preset just to add a bypass actor or a
status check:
apiVersion: github.interhyp.de/v1alpha1
kind: RulesetPreset
metadata:
name: default-branch-protection-release-bot
spec:
name: default-branch-protection-release-bot
extends: default-branch-protection # parent preset, all its settings are inherited
bypassActors: # added to the parent's bypass actors
- actorType: Integration
actorSlug: release-bot
bypassMode: always
rules:
requiredStatusChecks:
checks: # added to the parent's checks
- context: "build / build"
The resolved ruleset is computed with fixed rules per field; there is no way to remove inherited values (restructure the chain instead, e.g. extract a smaller base):
| Field | Merge behaviour |
|---|---|
name, extends |
Always the child's own value, never inherited |
target, enforcement, boolean rules, requiredApprovingReviewCount, strictPolicy, … |
Inherited unless set by the child (0/unset counts as "not set") |
conditions, allowedMergeMethods, *Pattern rules |
Replaced as a whole if set by the child |
rules, rules.pullRequest, rules.requiredStatusChecks, rules.copilotReview, rules.workflows |
Merged field by field |
bypassActors |
Union; same actorType + slug/id → child entry wins |
requiredStatusChecks.checks |
Union; same context + appSlug/integrationId → applied once (the same check from different apps is kept separately) |
pullRequest.requiredReviewers |
Union; same reviewer type + slug/id → child entry wins |
workflows.workflows |
Union; same repository + path → child entry wins |
- Chains may be up to 5 levels deep.
targetdefaults tobranchafter resolution;enforcementandrulesare only required on rulesets withoutextends. - Resolution happens in memory from the operator cache and is fast. Changing a preset reconciles all
Repositories/Organizations using it directly, via an inline
extends, or via any preset extending it. - Fail closed: if a chain cannot be resolved (missing parent, cycle, too deep, no enforcement), only that
ruleset is skipped. The existing GitHub ruleset is neither updated nor deleted, all other rulesets are still
synced, and
RulesetsSyncedbecomesFalsewith the reason in its message. The resource is not retried with backoff; it is reconciled again as soon as a preset in the chain is created or changed (or the resource itself changes). Transient read errors are retried as usual. A directly referenced preset that does not exist still fails the whole ruleset sync, as before. - A preset extending itself is rejected at admission. A missing parent is deliberately not rejected, because GitOps tools may apply a child before its parent; the ruleset is skipped until the parent exists.
Note: The
requiredReviewersfield in pull-request rules uses a GitHub API feature that is currently in beta. Reconciliation of this field is disabled by default and must be explicitly opted in by setting the environment variableENABLE_REQUIRED_REVIEWERS_RULES=trueon the controller manager. When the flag is not set, anyrequiredReviewersentries defined in the spec are ignored and will not be applied to or compared against GitHub. See Feature Flags for all available flags.
Deploy Keys¶
SSH keys for CI/CD systems to access the repository:
deployKeys:
- title: "ArgoCD Read-Only"
key: "ssh-ed25519 AAAAC3..."
readOnly: true # Can only clone/pull
- title: "Release Bot"
key: "ssh-ed25519 AAAAC3..."
readOnly: false # Can also push
Deletion Behavior¶
When a Repository CR is deleted, the behavior depends on the REPOSITORY_FINALIZER_MODE environment variable:
| Mode | Behavior |
|---|---|
ignore (default) |
Repository unchanged on GitHub, only CR removed |
archive |
Repository archived on GitHub (read-only, preserves data) |
delete |
Repository permanently deleted from GitHub |
This protects against accidental data loss. The default ignore mode requires manual cleanup on GitHub.
Related Resources¶
- Organization Configuration - Configure the parent organization
- API Reference - Complete field reference