api: rename repository branch and path to revision and dir

Breaking change to v1alpha1:

- spec.repository.branch is now spec.repository.revision. It takes a
  branch name or a full ref such as refs/tags/v1.0.0. Bare tag names and
  commit hashes follow once sources are read with func's
  NewFunctionFromGit.
- spec.repository.path is now spec.repository.dir, matching func's
  build.source.dir and --source-dir.
- status.git.resolvedBranch is now status.git.resolvedRevision.

The operator no longer defaults an empty revision to main: the clone
takes the remote's default branch and resolvedRevision reports its name,
so repositories whose default branch is not main work without a
revision.

The sample CR used fields the CRD never had (spec.source.repositoryUrl,
spec.registry.path) and is rewritten against the current schema.

knative/func's Function CR sync still writes branch and path through
func-operator v0.2.1. The API server drops those unknown fields, so func
needs a matching change.

Author: gauron99

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/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

docs/architecture.md

@@ -22,14 +22,14 @@ Defined in `api/v1alpha1/function_types.go`. A `Function` resource represents a
 
 **Spec** (user-provided):
 - `repository.url` — Git repository containing the function source
-- `repository.branch` — Branch to track (optional, defaults to repo default)
-- `repository.path` — Subdirectory within the repo (for monorepos)
+- `repository.revision` - Branch name or full ref to build (optional, defaults to the repo's default branch)
+- `repository.dir` - Directory within the repo that holds the function (for monorepos)
 - `repository.authSecretRef` — Secret for private repo authentication
 - `registry.authSecretRef` — Secret for container registry authentication
 - `autoUpdateMiddleware` — Override operator default (optional)
 
 **Status** (operator-managed):
-- `git` — Resolved branch, observed commit, last check time
+- `git` - Resolved revision, observed commit, last check time
 - `deployment` — Current image, build time, deployer, runtime
 - `middleware` — Current/available versions, auto-update config, rebuild state
 - `service` — URL and readiness of the underlying Knative Service

internal/controller/function_controller.go

@@ -193,7 +193,7 @@ func (r *FunctionReconciler) prepareSource(ctx context.Context, function *v1alph
 		}
 	}
 
-	repo, err := r.GitManager.CloneRepository(ctx, function.Spec.Repository.URL, function.Spec.Repository.Path, function.Spec.Repository.Branch, gitAuthSecret.Data)
+	repo, err := r.GitManager.CloneRepository(ctx, function.Spec.Repository.URL, function.Spec.Repository.Dir, function.Spec.Repository.Revision, gitAuthSecret.Data)
 	if err != nil {
 		function.MarkSourceNotReady("GitCloneFailed", "Failed to clone repository: %s", err.Error())
 		return nil, nil, fmt.Errorf("failed to setup git repository: %w", err)
@@ -208,7 +208,7 @@ func (r *FunctionReconciler) prepareSource(ctx context.Context, function *v1alph
 	// Source is ready - git clone and metadata read succeeded
 	function.MarkSourceReady()
 
-	function.Status.Git.ResolvedBranch = repo.Branch
+	function.Status.Git.ResolvedRevision = repo.Revision
 	function.Status.Git.ObservedCommit = repo.Commit
 	function.Status.Git.LastChecked = metav1.Now()
 

internal/controller/function_controller_test.go

@@ -58,8 +58,8 @@ var _ = Describe("Function Controller", func() {
 
 		defaultSpec := functionsdevv1alpha1.FunctionSpec{
 			Repository: functionsdevv1alpha1.FunctionSpecRepository{
-				URL:    "https://github.com/foo/bar",
-				Branch: "my-branch",
+				URL:      "https://github.com/foo/bar",
+				Revision: "my-branch",
 			},
 		}
 
@@ -177,7 +177,7 @@ var _ = Describe("Function Controller", func() {
 					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "my-branch", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
 				},
 			}),
-			Entry("should use main as default branch", reconcileTestCase{
+			Entry("should clone the default branch when no revision is set", reconcileTestCase{
 				spec: functionsdevv1alpha1.FunctionSpec{
 					Repository: functionsdevv1alpha1.FunctionSpecRepository{
 						URL: "https://github.com/foo/bar",
@@ -191,15 +191,19 @@ var _ = Describe("Function Controller", func() {
 					}, nil)
 					funcMock.EXPECT().GetLatestMiddlewareVersion(mock.Anything, mock.Anything, mock.Anything).Return("v1.0.0", nil)
 
-					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "main", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
+					// an empty revision clones the remote's default branch, which the git manager reports back
+					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}, WithRepoOptionRevision("trunk")), nil)
+				},
+				statusChecks: func(status *functionsdevv1alpha1.FunctionStatus) {
+					Expect(status.Git.ResolvedRevision).Should(Equal("trunk"))
 				},
 			}),
 
 			Entry("should contain the git information in the status", reconcileTestCase{
 				spec: functionsdevv1alpha1.FunctionSpec{
 					Repository: functionsdevv1alpha1.FunctionSpecRepository{
-						URL:    "https://github.com/foo/bar",
-						Branch: "my-branch",
+						URL:      "https://github.com/foo/bar",
+						Revision: "my-branch",
 					},
 				},
 				configureMocks: func(funcMock *funccli.MockManager, gitMock *git.MockManager) {
@@ -210,10 +214,10 @@ var _ = Describe("Function Controller", func() {
 					}, nil)
 					funcMock.EXPECT().GetLatestMiddlewareVersion(mock.Anything, mock.Anything, mock.Anything).Return("v1.0.0", nil)
 
-					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "my-branch", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}, WithRepoOptionBranch("my-branch"), WithRepoOptionCommit("foobar")), nil)
+					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "my-branch", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}, WithRepoOptionRevision("my-branch"), WithRepoOptionCommit("foobar")), nil)
 				},
 				statusChecks: func(status *functionsdevv1alpha1.FunctionStatus) {
-					Expect(status.Git.ResolvedBranch).Should(Equal("my-branch"))
+					Expect(status.Git.ResolvedRevision).Should(Equal("my-branch"))
 					Expect(status.Git.ObservedCommit).Should(Equal("foobar"))
 				},
 			}),
@@ -233,7 +237,7 @@ var _ = Describe("Function Controller", func() {
 					}, nil)
 					funcMock.EXPECT().GetLatestMiddlewareVersion(mock.Anything, mock.Anything, mock.Anything).Return("v1.0.0", nil)
 
-					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "main", mock.Anything).Return(createTmpGitRepo(functions.Function{
+					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "", mock.Anything).Return(createTmpGitRepo(functions.Function{
 						Name:    "func-go",
 						Runtime: "node",
 						Deploy: functions.DeploySpec{
@@ -265,7 +269,7 @@ var _ = Describe("Function Controller", func() {
 
 					// no funcMock.EXPECT().Deploy call, as no redeploy expected!
 
-					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "main", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
+					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
 				},
 				operatorConfig: map[string]string{
 					"autoUpdateMiddleware": "false",
@@ -289,7 +293,7 @@ var _ = Describe("Function Controller", func() {
 
 					// no funcMock.EXPECT().Deploy call, as no redeploy expected!
 
-					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "main", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
+					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
 				},
 				operatorConfig: map[string]string{
 					"autoUpdateMiddleware": "true",
@@ -312,7 +316,7 @@ var _ = Describe("Function Controller", func() {
 					}, nil)
 					funcMock.EXPECT().GetLatestMiddlewareVersion(mock.Anything, mock.Anything, mock.Anything).Return("v2.0.0", nil)
 
-					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "main", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
+					gitMock.EXPECT().CloneRepository(mock.Anything, "https://github.com/foo/bar", "", "", mock.Anything).Return(createTmpGitRepo(functions.Function{Name: "func-go"}), nil)
 				},
 				statusChecks: func(status *functionsdevv1alpha1.FunctionStatus) {
 					Expect(status.Middleware.Current).Should(Equal("v2.0.0"))
@@ -551,8 +555,8 @@ var _ = Describe("Function Controller", func() {
 			By("Creating the Function with registry authSecretRef")
 			spec := functionsdevv1alpha1.FunctionSpec{
 				Repository: functionsdevv1alpha1.FunctionSpecRepository{
-					URL:    "https://github.com/foo/bar",
-					Branch: "my-branch",
+					URL:      "https://github.com/foo/bar",
+					Revision: "my-branch",
 				},
 				Registry: functionsdevv1alpha1.FunctionSpecRegistry{
 					AuthSecretRef: &v1.LocalObjectReference{
@@ -661,9 +665,9 @@ func WithRepoOptionSubPath(subPath string) RepoOption {
 	}
 }
 
-func WithRepoOptionBranch(branch string) RepoOption {
+func WithRepoOptionRevision(revision string) RepoOption {
 	return func(repo *git.Repository) {
-		repo.Branch = branch
+		repo.Revision = revision
 	}
 }
 

internal/git/manager.go

@@ -81,11 +81,17 @@ func (m *managerImpl) CloneRepository(ctx context.Context, repoUrl, subPath, ref
 		return nil, fmt.Errorf("failed to find head: %w", err)
 	}
 
+	// An empty reference clones the remote's default branch: report its name.
+	revision := reference
+	if revision == "" && head.Name().IsBranch() {
+		revision = head.Name().Short()
+	}
+
 	return &Repository{
 		CloneDir:      targetDir,
 		SubPath:       subPath,
 		Commit:        head.Hash().String(),
-		Branch:        reference,
+		Revision:      revision,
 		knownHostFile: tempFile,
 	}, nil
 }

internal/git/repository.go

@@ -9,7 +9,7 @@ type Repository struct {
 	CloneDir      string
 	SubPath       string
 	Commit        string
-	Branch        string
+	Revision      string
 	knownHostFile string
 }