Build separate api/ package

.github/dependabot.yml

@@ -2,7 +2,10 @@ version: 2
 updates:
   # Enable version updates for Go modules
   - package-ecosystem: "gomod"
-    directory: "/"
+    # api/ is a separate Go module with its own go.mod
+    directories:
+      - "/"
+      - "/api"
     schedule:
       interval: "daily"
     open-pull-requests-limit: 10
@@ -14,6 +17,12 @@ updates:
         patterns:
           - "k8s.io/*"
           - "sigs.k8s.io/*"
+    ignore:
+      # Pinned to a commit on func's main branch for the git-source API
+      # (knative/func#4064), which no func release contains yet. Release-branch
+      # tags such as v0.50.3 sort higher but lack it, so updates would break the
+      # build. Remove once a func release includes #4064.
+      - dependency-name: "knative.dev/func"
 
   # Enable version updates for GitHub Actions
   - package-ecosystem: "github-actions"

.github/workflows/lint.yml

@@ -29,3 +29,10 @@ jobs:
 
       - name: Run linter
         uses: golangci/golangci-lint-action@v9
+
+      # api/ is a separate Go module, so lint it on its own
+      - name: Run linter (api module)
+        uses: golangci/golangci-lint-action@v9
+        with:
+          working-directory: api
+          args: --config=../.golangci.yml

.github/workflows/test.yml

@@ -30,4 +30,5 @@ jobs:
       - name: Running Tests
         run: |
           go mod tidy
+          (cd api && go mod tidy)
           make test

AGENTS.md

@@ -21,7 +21,7 @@ Before committing, test locally following the table below:
 
 ## Project Structure
 
-- `api/v1alpha1/` - Function CRD types
+- `api/` - CRD types (`v1alpha1/` Function, `sources/v1alpha1/` ObjectBucketSource). A separate Go module (`api/go.mod`), so other projects such as knative/func can import the types without the operator's dependencies. The root `go.mod` points it at `./api` with a `replace`; `make fmt vet test lint` cover both modules
 - `internal/` - controller and business logic
 - `test/e2e/` - e2e tests using in-cluster Gitea
 - `test/utils/` - e2e test helpers (RepositoryProvider, func CLI wrappers)

CONTRIBUTING.md

@@ -100,6 +100,14 @@ This runs three sub-targets:
 - `manifests` — CRDs, ClusterRoles, and webhook configurations
 - `gen-mocks` — Mock implementations via [mockery](https://github.com/vektra/mockery)
 
+## Go Modules
+
+`api/` is a separate Go module (`github.com/functions-dev/func-operator/api`), so other projects such as knative/func can import the CRD types without pulling in the operator's dependencies.
+
+- The root `go.mod` requires it and points it at the local folder with `replace github.com/functions-dev/func-operator/api => ./api`, so the operator always builds against the types in the same commit.
+- `./...` from the repository root does not include `api/`. The `fmt`, `vet`, `test` and `lint` make targets run a second time inside `api/`; do the same when running Go commands by hand, e.g. `cd api && go mod tidy`.
+- Other projects use released versions of the module, tagged with an `api/` prefix (e.g. `api/v0.4.0`).
+
 ## Testing
 
 ### Unit Tests

Dockerfile

@@ -7,6 +7,9 @@ WORKDIR /workspace
 # Copy the Go Modules manifests
 COPY go.mod go.mod
 COPY go.sum go.sum
+# api/ is its own Go module, required through a local replace in go.mod
+COPY api/go.mod api/go.mod
+COPY api/go.sum api/go.sum
 # cache deps before building and copying source so that we don't need to re-download as much
 # and so that source changes don't invalidate our downloaded layer
 RUN go mod download

Dockerfile.source-objectbucket

@@ -7,6 +7,9 @@ WORKDIR /workspace
 # Copy the Go Modules manifests
 COPY go.mod go.mod
 COPY go.sum go.sum
+# api/ is its own Go module, required through a local replace in go.mod
+COPY api/go.mod api/go.mod
+COPY api/go.sum api/go.sum
 # cache deps before building and copying source so that we don't need to re-download as much
 # and so that source changes don't invalidate our downloaded layer
 RUN go mod download

Makefile

@@ -108,17 +108,24 @@ manifests: controller-gen ## Generate WebhookConfiguration, ClusterRole and Cust
 generate: controller-gen ## Generate code containing DeepCopy, DeepCopyInto, and DeepCopyObject method implementations.
 	$(CONTROLLER_GEN) object:headerFile="hack/boilerplate.go.txt" paths="./..."
 
+# api/ is a separate Go module (see api/go.mod), so ./... from the repository
+# root does not include it. Go commands below run once more inside api/.
+# controller-gen (manifests, generate) crosses module boundaries on its own.
+
 .PHONY: fmt
 fmt: ## Run go fmt against code.
 	go fmt ./...
+	cd api && go fmt ./...
 
 .PHONY: vet
 vet: ## Run go vet against code.
 	go vet ./...
+	cd api && go vet ./...
 
 .PHONY: test
 test: manifests generate fmt vet setup-envtest ## Run tests.
 	KUBEBUILDER_ASSETS="$(shell $(ENVTEST) use $(ENVTEST_K8S_VERSION) --bin-dir $(LOCALBIN) -p path)" go test $$(go list ./... | grep -v e2e) -coverprofile cover.out
+	cd api && go test ./... -coverprofile cover.out
 
 .PHONY: test-e2e ## Run e2e tests.
 test-e2e: ginkgo
@@ -135,10 +142,12 @@ install-olm-in-cluster: operator-sdk ## Install OLM in cluster if not already in
 .PHONY: lint
 lint: golangci-lint ## Run golangci-lint linter
 	$(GOLANGCI_LINT) run
+	cd api && $(GOLANGCI_LINT) run --config ../.golangci.yml
 
 .PHONY: lint-fix
 lint-fix: golangci-lint ## Run golangci-lint linter and perform fixes
 	$(GOLANGCI_LINT) run --fix
+	cd api && $(GOLANGCI_LINT) run --fix --config ../.golangci.yml
 
 .PHONY: lint-config
 lint-config: golangci-lint ## Verify golangci-lint linter configuration

README.md

@@ -204,7 +204,7 @@ kubectl get func my-function -o yaml
 
 The status will include:
 - Function name and conditions
-- Git information (branch, commit, last checked time)
+- Git information (revision, commit, last checked time)
 - Deployment details (image, runtime, build time, deployer)
 - Middleware status (current and available versions, auto-update settings, pending rebuild status)
 - Service status (URL and readiness)
@@ -213,7 +213,7 @@ The status will include:
 
 ### Functions in Monorepos
 
-For functions located in a subdirectory of a repository (e.g., in a monorepo), use the `repository.path` field to specify the path to your function:
+For functions located in a subdirectory of a repository (e.g., in a monorepo), use the `repository.dir` field to specify the directory that holds your function:
 
 ```yaml
 apiVersion: functions.dev/v1alpha1
@@ -224,7 +224,7 @@ metadata:
 spec:
   repository:
     url: https://github.com/your-org/your-monorepo.git
-    path: functions/my-function
+    dir: functions/my-function
     authSecretRef:
       name: git-credentials
   registry:
@@ -291,8 +291,8 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contr
 | Field                       | Type    | Required | Description                                                                                      |
 |-----------------------------|---------|----------|--------------------------------------------------------------------------------------------------|
 | `repository.url`            | string  | Yes      | URL of the Git repository. Supports HTTPS, HTTP, SSH (`ssh://`), and SCP-style (`git@host:path`) |
-| `repository.branch`         | string  | No       | Branch of the repository                                                                         |
-| `repository.path`           | string  | No       | Path to the function inside the repository. Defaults to "."                                      |
+| `repository.revision`       | string  | No       | Revision to build: a branch name or a full ref such as `refs/tags/v1.0.0`. Defaults to the repository's default branch |
+| `repository.dir`            | string  | No       | Directory within the repository that holds the function (its `func.yaml`). Defaults to the repository root |
 | `repository.authSecretRef`  | object  | No       | Reference to the auth secret for private repository authentication                               |
 | `registry.authSecretRef`    | object  | No       | Reference to the secret containing credentials for registry authentication                       |
 | `autoUpdateMiddleware`      | boolean | No       | Defines if the operator should rebuild when outdated middleware is detected. When not specified, defaults to the operator-wide setting in the `func-operator-controller-config` ConfigMap (default: `true`). Function-level setting takes precedence over operator default |
@@ -303,7 +303,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contr
 |-------|------|-------------|
 | `name` | string | Function name from metadata |
 | `conditions` | array | Status conditions (see below) |
-| `git.resolvedBranch` | string | Git branch that is being monitored |
+| `git.resolvedRevision` | string | Revision that was checked out: `repository.revision`, or the default branch name when that is empty |
 | `git.observedCommit` | string | Latest Git commit SHA observed |
 | `git.lastChecked` | timestamp | Last time the repository was checked |
 | `deployment.image` | string | Container image of the deployed function |

api/go.mod

@@ -0,0 +1,27 @@
+module github.com/functions-dev/func-operator/api
+
+go 1.26.0
+
+require (
+	k8s.io/api v0.37.1
+	k8s.io/apimachinery v0.37.1
+)
+
+require (
+	github.com/fxamacker/cbor/v2 v2.9.1 // indirect
+	github.com/go-logr/logr v1.4.3 // indirect
+	github.com/json-iterator/go v1.1.12 // indirect
+	github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd // indirect
+	github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee // indirect
+	github.com/x448/float16 v0.8.4 // indirect
+	go.yaml.in/yaml/v2 v2.4.4 // indirect
+	golang.org/x/net v0.57.0 // indirect
+	golang.org/x/text v0.40.0 // indirect
+	gopkg.in/inf.v0 v0.9.1 // indirect
+	k8s.io/klog/v2 v2.140.0 // indirect
+	k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad // indirect
+	k8s.io/utils v0.0.0-20260626114624-be93311217bd // indirect
+	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
+	sigs.k8s.io/randfill v1.0.0 // indirect
+	sigs.k8s.io/structured-merge-diff/v6 v6.4.2 // indirect
+)

api/go.sum

@@ -0,0 +1,58 @@
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
+github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fxamacker/cbor/v2 v2.9.1 h1:2rWm8B193Ll4VdjsJY28jxs70IdDsHRWgQYAI80+rMQ=
+github.com/fxamacker/cbor/v2 v2.9.1/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/gofuzz v1.0.0/go.mod h1:dBl0BpW6vV/+mYPU4Po3pmUjxk6FQPldtuIdl/M65Eg=
+github.com/json-iterator/go v1.1.12 h1:PV8peI4a0ysnczrg+LtxykD8LfKY9ML6u2jnxaEnrnM=
+github.com/json-iterator/go v1.1.12/go.mod h1:e30LSqwooZae/UwlEbR2852Gd8hjQvJoHmT4TnhNGBo=
+github.com/modern-go/concurrent v0.0.0-20180228061459-e0a39a4cb421/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd h1:TRLaZ9cD/w8PVh93nsPXa1VrQ6jlwL5oN8l14QlcNfg=
+github.com/modern-go/concurrent v0.0.0-20180306012644-bacd9c7ef1dd/go.mod h1:6dJC0mAP4ikYIbvyc7fijjWJddQyLn8Ig3JB5CqoB9Q=
+github.com/modern-go/reflect2 v1.0.2/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee h1:W5t00kpgFdJifH4BDsTlE89Zl93FEloxaWZfGcifgq8=
+github.com/modern-go/reflect2 v1.0.3-0.20250322232337-35a7c28c31ee/go.mod h1:yWuevngMOJpCy52FWWMvUC8ws7m/LJsjYzDa0/r8luk=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 h1:Jamvg5psRIccs7FGNTlIRMkT8wgtp5eCXdBlqhYGL6U=
+github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/spf13/pflag v1.0.10 h1:4EBh2KAYBwaONj6b2Ye1GiHfwjqyROoF4RwYO+vPwFk=
+github.com/spf13/pflag v1.0.10/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+go.yaml.in/yaml/v2 v2.4.4 h1:tuyd0P+2Ont/d6e2rl3be67goVK4R6deVxCUX5vyPaQ=
+go.yaml.in/yaml/v2 v2.4.4/go.mod h1:gMZqIpDtDqOfM0uNfy0SkpRhvUryYH0Z6wdMYcacYXQ=
+golang.org/x/net v0.57.0 h1:K5+3DljvIuDG9/Jv9rvyMywYNFCQ9RSUY6OOTTkT+tE=
+golang.org/x/net v0.57.0/go.mod h1:KpXc8iv+r3XplLAG/f7Jsf9RPszJzdR0f58q9vGOuEU=
+golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
+golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
+gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
+gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
+k8s.io/api v0.37.1 h1:l6N77U7tjwB5L056bgrBTJIEdevac/naBZ3iSvDNfpM=
+k8s.io/api v0.37.1/go.mod h1:zSlbB1YpJ1YQlFVQy20UYll81UJSJJUMLhkhvg6Z78M=
+k8s.io/apimachinery v0.37.1 h1:hGCYyvKHCwtwMitj2vU4vYx0Z16N9GyZk9BBnz0wDAE=
+k8s.io/apimachinery v0.37.1/go.mod h1:jF84AyUi/IRIXRot5f+lm6MpxoWI+F1XgjaMmwCdTFw=
+k8s.io/klog/v2 v2.140.0 h1:Tf+J3AH7xnUzZyVVXhTgGhEKnFqye14aadWv7bzXdzc=
+k8s.io/klog/v2 v2.140.0/go.mod h1:o+/RWfJ6PwpnFn7OyAG3QnO47BFsymfEfrz6XyYSSp0=
+k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad h1:oXImqH8mQNk7PmvzKhmN3ddJoY6OnyM225MXwGHPm0A=
+k8s.io/kube-openapi v0.0.0-20260721132016-d427ff9ee9ad/go.mod h1:0/mqHCVhlumdJ3BhCfnjSZQE037nAhNodh1/hK0T8/I=
+k8s.io/utils v0.0.0-20260626114624-be93311217bd h1:Ea7fgQ5we8Y9T0OX5o0dAHzQOBRI07D/dEYRaB9ZZEs=
+k8s.io/utils v0.0.0-20260626114624-be93311217bd/go.mod h1:xDxuJ0whA3d0I4mf/C4ppKHxXynQ+fxnkmQH0vTHnuk=
+sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 h1:IpInykpT6ceI+QxKBbEflcR5EXP7sU1kvOlxwZh5txg=
+sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730/go.mod h1:mdzfpAEoE6DHQEN0uh9ZbOCuHbLK5wOm7dK4ctXE9Tg=
+sigs.k8s.io/randfill v1.0.0 h1:JfjMILfT8A6RbawdsK2JXGBR5AQVfd+9TbzrlneTyrU=
+sigs.k8s.io/randfill v1.0.0/go.mod h1:XeLlZ/jmk4i1HRopwe7/aU3H5n1zNUcX6TM94b3QxOY=
+sigs.k8s.io/structured-merge-diff/v6 v6.4.2 h1:qdOxHwrl2Kaag1aQEarlYcOA9vSyGCp3CIki3aW8c4Q=
+sigs.k8s.io/structured-merge-diff/v6 v6.4.2/go.mod h1:M3W8sfWvn2HhQDIbGWj3S099YozAsymCo/wrT5ohRUE=
+sigs.k8s.io/yaml v1.6.0 h1:G8fkbMSAFqgEFgh4b1wmtzDnioxFCUgTZhlbj5P9QYs=
+sigs.k8s.io/yaml v1.6.0/go.mod h1:796bPqUfzR/0jLAl6XjHl3Ck7MiyVv8dbTdyT3/pMf4=

api/v1alpha1/function_defaults.go

@@ -23,10 +23,6 @@ func (r *FunctionSpecRepository) SetDefaults(ctx context.Context) {
 	if r == nil {
 		return
 	}
-
-	if r.Branch == "" {
-		r.Branch = "main"
-	}
 }
 
 func (r *FunctionSpecRegistry) SetDefaults(ctx context.Context) {

api/v1alpha1/function_types.go

@@ -56,15 +56,17 @@ type FunctionSpecRepository struct {
 	URL string `json:"url"`
 
 	// +kubebuilder:validation:Optional
-	// Branch of the repository
-	Branch string `json:"branch,omitempty"`
+	// Revision of the repository to build: a branch name or a full ref such as refs/tags/v1.0.0.
+	// Defaults to the repository's default branch.
+	Revision string `json:"revision,omitempty"`
 
 	// AuthSecretRef defines the reference to the auth secret in case the repository is private and needs authentication
 	AuthSecretRef *v1.LocalObjectReference `json:"authSecretRef,omitempty"`
 
 	// +kubebuilder:validation:Optional
-	// Path points to the function inside the repository. Defaults to "."
-	Path string `json:"path,omitempty"`
+	// Dir is the directory within the repository that holds the function (its func.yaml).
+	// Defaults to the repository root.
+	Dir string `json:"dir,omitempty"`
 }
 
 type FunctionSpecRegistry struct {
@@ -92,9 +94,11 @@ type FunctionStatusHistoryEntry struct {
 }
 
 type FunctionStatusGit struct {
-	ResolvedBranch string      `json:"resolvedBranch,omitempty"`
-	ObservedCommit string      `json:"observedCommit,omitempty"`
-	LastChecked    metav1.Time `json:"lastChecked,omitempty"`
+	// ResolvedRevision is the revision that was checked out: spec.repository.revision,
+	// or the name of the default branch when that is empty.
+	ResolvedRevision string      `json:"resolvedRevision,omitempty"`
+	ObservedCommit   string      `json:"observedCommit,omitempty"`
+	LastChecked      metav1.Time `json:"lastChecked,omitempty"`
 }
 
 type FunctionStatusDeployment struct {

config/crd/bases/functions.dev_functions.yaml

@@ -101,12 +101,15 @@ spec:
                         type: string
                     type: object
                     x-kubernetes-map-type: atomic
-                  branch:
-                    description: Branch of the repository
+                  dir:
+                    description: |-
+                      Dir is the directory within the repository that holds the function (its func.yaml).
+                      Defaults to the repository root.
                     type: string
-                  path:
-                    description: Path points to the function inside the repository.
-                      Defaults to "."
+                  revision:
+                    description: |-
+                      Revision of the repository to build: a branch name or a full ref such as refs/tags/v1.0.0.
+                      Defaults to the repository's default branch.
                     type: string
                   url:
                     description: URL of the Git repository containing the function
@@ -196,7 +199,10 @@ spec:
                     type: string
                   observedCommit:
                     type: string
-                  resolvedBranch:
+                  resolvedRevision:
+                    description: |-
+                      ResolvedRevision is the revision that was checked out: spec.repository.revision,
+                      or the name of the default branch when that is empty.
                     type: string
                 type: object
               history:

config/samples/v1alpha1_function.yaml

@@ -7,11 +7,14 @@ metadata:
   name: function-sample
   namespace: default
 spec:
-  source:
-    repositoryUrl: https://github.com/your-org/your-function.git
+  repository:
+    url: https://github.com/your-org/your-function.git
+    # optional: branch name or full ref (e.g. refs/tags/v1.0.0); defaults to the default branch
+    revision: main
+    # optional: directory holding the function's func.yaml; defaults to the repository root
+    dir: .
     authSecretRef:
       name: git-credentials
   registry:
-    path: quay.io/your-username/my-function
     authSecretRef:
-      name: registry-credentials
+      name: registry-credentials