Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

add support for checking out to Git refs #1026

Merged
merged 1 commit into from
Feb 16, 2023
Merged

add support for checking out to Git refs #1026

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 9 additions & 7 deletions api/v1beta2/gitrepository_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`

Expand Down Expand Up @@ -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"`

Expand All @@ -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"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Let's add here a kubebuilder regex that matches refs/<any>/<any>

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The validation is much more complex than just refs/...: https://git-scm.com/docs/git-check-ref-format#_description

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would rather just let the Git implementation figure out if the arbitrary reference is correct.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we include the ref name in the error message: https://github.com/fluxcd/pkg/blob/main/git/gogit/clone.go#L372 and we have some basic validation: https://github.com/fluxcd/pkg/blob/main/git/gogit/clone.go#L402-L404. given these, i don't think we have a pressing need to validate the ref name at the API level

// +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"`
}
Expand Down
19 changes: 11 additions & 8 deletions config/crd/bases/source.toolkit.fluxcd.io_gitrepositories.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions controllers/gitrepository_controller.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
27 changes: 18 additions & 9 deletions docs/api/source.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand Down Expand Up @@ -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>
Expand Down Expand Up @@ -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
Expand All @@ -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>
Expand Down Expand Up @@ -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>
Expand Down
26 changes: 25 additions & 1 deletion docs/spec/v1beta2/gitrepositories.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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`:
Expand Down