add support for checking out to Git refs

Add a new field `.spec.ref.name` which points to a Git reference which enables checking out to a particular commit pointed to by the specified reference. Signed-off-by: Sanskar Jaiswal <jaiswalsanskar078@gmail.com>
fluxcd · Feb 16, 2023 · 146262f · 146262f
1 parent 1de3b13
commit 146262f
Show file tree

Hide file tree

Showing 5 changed files with 64 additions and 25 deletions.
diff --git a/api/v1beta2/gitrepository_types.go b/api/v1beta2/gitrepository_types.go
@@ -106,7 +106,6 @@ type GitRepositorySpec struct {
 
  // RecurseSubmodules enables the initialization of all submodules within
  // the GitRepository as cloned from the URL, using their default settings.
- // This option is available only when using the 'go-git' GitImplementation.
  // +optional
  RecurseSubmodules bool `json:"recurseSubmodules,omitempty"`
 
@@ -156,9 +155,6 @@ func (in *GitRepositoryInclude) GetToPath() string {
 // GitRepositoryRef specifies the Git reference to resolve and checkout.
 type GitRepositoryRef struct {
  // Branch to check out, defaults to 'master' if no other field is defined.
- //
- // When GitRepositorySpec.GitImplementation is set to 'go-git', a shallow
- // clone of the specified branch is performed.
  // +optional
  Branch string `json:"branch,omitempty"`
 
@@ -170,11 +166,17 @@ type GitRepositoryRef struct {
  // +optional
  SemVer string `json:"semver,omitempty"`
 
+ // Name of the reference to check out; takes precedence over Branch, Tag and SemVer.
+ //
+ // It must be a valid Git reference: https://git-scm.com/docs/git-check-ref-format#_description
+ // Examples: "refs/heads/main", "refs/tags/v0.1.0", "refs/pull/420/head", "refs/merge-requests/1/head"
+ // +optional
+ Name string `json:"name,omitempty"`
+
  // Commit SHA to check out, takes precedence over all reference fields.
  //
- // When GitRepositorySpec.GitImplementation is set to 'go-git', this can be
- // combined with Branch to shallow clone the branch, in which the commit is
- // expected to exist.
+ // This can be combined with Branch to shallow clone the branch, in which
+ // the commit is expected to exist.
  // +optional
  Commit string `json:"commit,omitempty"`
 }

diff --git a/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml b/config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml
@@ -462,25 +462,28 @@ spec:
  recurseSubmodules:
  description: RecurseSubmodules enables the initialization of all submodules
  within the GitRepository as cloned from the URL, using their default
- settings. This option is available only when using the 'go-git'
- GitImplementation.
+ settings.
  type: boolean
  ref:
  description: Reference specifies the Git reference to resolve and
  monitor for changes, defaults to the 'master' branch.
  properties:
  branch:
- description: "Branch to check out, defaults to 'master' if no
- other field is defined. \n When GitRepositorySpec.GitImplementation
- is set to 'go-git', a shallow clone of the specified branch
- is performed."
+ description: Branch to check out, defaults to 'master' if no other
+ field is defined.
  type: string
  commit:
  description: "Commit SHA to check out, takes precedence over all
- reference fields. \n When GitRepositorySpec.GitImplementation
- is set to 'go-git', this can be combined with Branch to shallow
+ reference fields. \n This can be combined with Branch to shallow
  clone the branch, in which the commit is expected to exist."
  type: string
+ name:
+ description: "Name of the reference to check out; takes precedence
+ over Branch, Tag and SemVer. \n It must be a valid Git reference:
+ https://git-scm.com/docs/git-check-ref-format#_description Examples:
+ \"refs/heads/main\", \"refs/tags/v0.1.0\", \"refs/pull/420/head\",
+ \"refs/merge-requests/1/head\""
+ type: string
  semver:
  description: SemVer tag expression to check out, takes precedence
  over Tag.

diff --git a/controllers/gitrepository_controller.go b/controllers/gitrepository_controller.go
@@ -787,6 +787,7 @@ func (r *GitRepositoryReconciler) gitCheckout(ctx context.Context,
  cloneOpts.Commit = ref.Commit
  cloneOpts.Tag = ref.Tag
  cloneOpts.SemVer = ref.SemVer
+ cloneOpts.RefName = ref.Name
  }
 
  // Only if the object has an existing artifact in storage, attempt to

diff --git a/docs/api/source.md b/docs/api/source.md
@@ -436,8 +436,7 @@ bool
 <td>
 <em>(Optional)</em>
 <p>RecurseSubmodules enables the initialization of all submodules within
-the GitRepository as cloned from the URL, using their default settings.
-This option is available only when using the &lsquo;go-git&rsquo; GitImplementation.</p>
+the GitRepository as cloned from the URL, using their default settings.</p>
 </td>
 </tr>
 <tr>
@@ -1671,8 +1670,6 @@ string
 <td>
 <em>(Optional)</em>
 <p>Branch to check out, defaults to &lsquo;master&rsquo; if no other field is defined.</p>
-<p>When GitRepositorySpec.GitImplementation is set to &lsquo;go-git&rsquo;, a shallow
-clone of the specified branch is performed.</p>
 </td>
 </tr>
 <tr>
@@ -1701,6 +1698,20 @@ string
 </tr>
 <tr>
 <td>
+<code>name</code><br>
+<em>
+string
+</em>
+</td>
+<td>
+<em>(Optional)</em>
+<p>Name of the reference to check out; takes precedence over Branch, Tag and SemVer.</p>
+<p>It must be a valid Git reference: <a href="https://git-scm.com/docs/git-check-ref-format#_description">https://git-scm.com/docs/git-check-ref-format#_description</a>
+Examples: &ldquo;refs/heads/main&rdquo;, &ldquo;refs/tags/v0.1.0&rdquo;, &ldquo;refs/pull/420/head&rdquo;, &ldquo;refs/merge-requests/1/head&rdquo;</p>
+</td>
+</tr>
+<tr>
+<td>
 <code>commit</code><br>
 <em>
 string
@@ -1709,9 +1720,8 @@ string
 <td>
 <em>(Optional)</em>
 <p>Commit SHA to check out, takes precedence over all reference fields.</p>
-<p>When GitRepositorySpec.GitImplementation is set to &lsquo;go-git&rsquo;, this can be
-combined with Branch to shallow clone the branch, in which the commit is
-expected to exist.</p>
+<p>This can be combined with Branch to shallow clone the branch, in which
+the commit is expected to exist.</p>
 </td>
 </tr>
 </tbody>
@@ -1875,8 +1885,7 @@ bool
 <td>
 <em>(Optional)</em>
 <p>RecurseSubmodules enables the initialization of all submodules within
-the GitRepository as cloned from the URL, using their default settings.
-This option is available only when using the &lsquo;go-git&rsquo; GitImplementation.</p>
+the GitRepository as cloned from the URL, using their default settings.</p>
 </td>
 </tr>
 <tr>

diff --git a/docs/spec/v1beta2/gitrepositories.md b/docs/spec/v1beta2/gitrepositories.md
@@ -228,7 +228,7 @@ is `60s`.
 
 `.spec.ref` is an optional field to specify the Git reference to resolve and
 watch for changes. References are specified in one or more subfields
-(`.branch`, `.tag`, `.semver`, `.commit`), with latter listed fields taking
+(`.branch`, `.tag`, `.semver`, `.name`, `.commit`), with latter listed fields taking
 precedence over earlier ones. If not specified, it defaults to a `master`
 branch reference.
 
@@ -287,6 +287,30 @@ spec:
 This field takes precedence over [`.branch`](#branch-example) and
 [`.tag`](#tag-example).
 
+
+#### Name example
+
+To Git checkout a specfied [reference](https://git-scm.com/book/en/v2/Git-Internals-Git-References),
+use `.spec.ref.name`:
+
+```yaml
+---
+apiVersion: source.toolkit.fluxcd.io/v1beta2
+kind: GitRepository
+metadata:
+ name: <repository-name>
+spec:
+ ref:
+ # Ref name format reference: https://git-scm.com/docs/git-check-ref-format#_description
+ name: <reference name>
+```
+
+Valid examples are: `refs/heads/main`, `refs/tags/v0.1.0`, `refs/pull/420/head`,
+`refs/merge-requests/1/head`.
+
+This field takes precedence over [`.branch`](#branch-example),
+[`.tag`](#tag-example), and [`.semver`](#semver-example).
+
 #### Commit example
 
 To Git checkout a specified commit, use `.spec.ref.commit`: