GitRepository
A Git repository and the credentials to read it.
A GitRepository is a reusable source: a URL and credentials. It does not select a version. Each
Release selects the branch, tag or commit in spec.source.gitRepository.ref, so many Releases
can use one GitRepository.
| API group | source.convoy.kumodo.io/v1alpha1 |
| Scope | Namespaced |
| Subresources | /status |
| Conditions | Ready |
Example#
# GitRepository with SSH key auth. Requires two things:
# - a Secret holding the private key (sshKeyRef)
# - a ConfigMap holding known_hosts (knownHostsRef) — MANDATORY: convoy verifies
# the server host key against it (no insecure "ignore host key" mode).
# known_hosts must use PLAINTEXT host entries (hashed |1|… entries are rejected).
# Get the entries with, e.g.: ssh-keyscan github.com
apiVersion: v1
kind: Secret
metadata:
name: git-ssh
namespace: default
type: Opaque
stringData:
identity: |
-----BEGIN OPENSSH PRIVATE KEY-----
...replace with your private key...
-----END OPENSSH PRIVATE KEY-----
---
apiVersion: v1
kind: ConfigMap
metadata:
name: git-known-hosts
namespace: default
data:
known_hosts: |
github.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIOMqqnkVzrm0SdG6UOoqKLsabgH5C9okWi0dh2l9GKJl
---
apiVersion: source.convoy.kumodo.io/v1alpha1
kind: GitRepository
metadata:
name: private-repo-ssh
namespace: default
spec:
url: ssh://git@github.com/example/private-repo.git
auth:
type: sshKey
sshKey:
sshKeyRef:
name: git-ssh
key: identity
knownHostsRef:
name: git-known-hosts
key: known_hosts
interval: 1m0s
minSyncInterval: 30s
Verification#
The controller lists the remote refs of the repository (like git ls-remote) with the configured
credentials. A Release fetches content only when it needs a ref.
The controller verifies again at each periodic informer resync. It does not use
spec.interval.
Auth types#
spec.auth is required. For a public repository, set type: none.
auth.type | Implemented | Fields |
|---|---|---|
none | Yes | |
basic | Yes | basic.username (a string) and basic.passwordRef ({name, key} of a Secret) |
token | Yes | token.tokenRef. convoy sends the token as the HTTP basic password with the username git. |
sshKey | Yes | sshKey.sshKeyRef (a Secret key) and sshKey.knownHostsRef (a ConfigMap key, required). Only plain known_hosts lines work. Hashed lines are rejected. @cert-authority lines are skipped. |
githubApp, oidc, cloudIdentity | No | Ready=False, reason Unsupported. |
A problem with the SSH key or the known_hosts data gives reason Unsupported, not
VerifyFailed. See Credentials for all kinds.
TLS#
Only tls.insecureSkipVerify works. tls.caPublicCertRef is accepted, but not used.
Fields#
| Field | Type | Description |
|---|---|---|
spec | GitRepositorySpec | GitRepositorySpec defines the desired state of the GitRepository. |
spec.auth required | GitRepositoryAuthSpec | Auth is the authentication method used to access the Git repository. |
spec.auth.basic | BasicAuthSpec | Basic is the basic authentication used to access the Git repository. |
spec.auth.basic.passwordRef required | SecretKeySelector | PasswordRef is the name and the key of the Secret containing the password. |
spec.auth.basic.username required | string | Username is the username used for authentication. |
spec.auth.cloudIdentity | CloudIdentitySpec | CloudIdentity is the cloud identity configuration used to access the Git repository. |
spec.auth.cloudIdentity.provider required | string | Provider is the cloud provider.
|
spec.auth.githubApp | GithubAppAuthSpec | GithubApp is the GitHub App configuration used to access the Git repository. |
spec.auth.githubApp.appID required | integer | AppID is the ID of the GitHub App. |
spec.auth.githubApp.installationID required | integer | InstallationID is the ID of the GitHub App installation. |
spec.auth.githubApp.privateKeyRef required | SecretKeySelector | PrivateKeyRef is the name and the key of the Secret containing the private key. |
spec.auth.oidc | OIDAuthSpec | OIDC is the OIDC configuration used to access the Git repository. |
spec.auth.oidc.audience | string | Audience is the OIDC audience. |
spec.auth.oidc.clientAuth required | OIDCClientAuthSpec | ClientAuth is the OIDC authentication method used for authentication. |
spec.auth.oidc.clientAuth.clientSecret | OIDCAuthClientSecretSpec | ClientSecret is the reference to the Secret and the key of the Secret containing the OIDC client secret. |
spec.auth.oidc.clientAuth.clientSecret.clientSecretRef required | SecretKeySelector | ClientSecretRef is the name and the key of the Secret containing the OIDC client secret. |
spec.auth.oidc.clientAuth.privateKeyJWT | OIDCAuthPrivateKeyJWTSpec | PrivateKeyJWT is the reference to the Secret and the key of the Secret containing the OIDC private key JWT. |
spec.auth.oidc.clientAuth.privateKeyJWT.privateKeyRef required | SecretKeySelector | PrivateKeyRef is the name and the key of the Secret containing the OIDC private key JWT. |
spec.auth.oidc.clientAuth.tlsClientAuth | OIDCAuthTLSClientAuthSpec | TLSClientAuth is the reference to the Secrets and the keys of the Secret(s) containing the OIDC client certificate and key. |
spec.auth.oidc.clientAuth.tlsClientAuth.certRef required | SecretKeySelector | CertRef is the name and the key of the Secret containing the OIDC client certificate. |
spec.auth.oidc.clientAuth.tlsClientAuth.keyRef required | SecretKeySelector | KeyRef is the name and the key of the Secret containing the OIDC client certificate key. |
spec.auth.oidc.clientAuth.type required | string | Type is the OIDC authentication method type used for authentication.
|
spec.auth.oidc.clientID required | string | ClientID is the OIDC client ID. |
spec.auth.oidc.issuerURL required | string | IssuerURL is the URL of the OIDC issuer. |
spec.auth.oidc.scopes | []stringlist type: atomic | Scopes are the OIDC scopes. |
spec.auth.oidc.tls | TLSSpec | TLS is the issuer TLS configuration. |
spec.auth.oidc.tls.caPublicCertRef required | ConfigMapKeySelector | CAPublicCertRef is the name and the key of the ConfigMap containing the CA public certificate. The CA certificate is used to verify the IdP server's certificate. |
spec.auth.oidc.tls.insecureSkipVerify required | boolean | InsecureSkipVerify is a flag to skip the certificate verification. |
spec.auth.sshKey | SSHKeyAuthSpec | SSHKey is the SSH key used to access the Git repository. |
spec.auth.sshKey.knownHostsRef required | ConfigMapKeySelector | KnownHostsRef is the name and the key of the ConfigMap containing the known hosts. |
spec.auth.sshKey.sshKeyRef required | SecretKeySelector | SSHKeyRef is the name and the key of the Secret containing the SSH key. |
spec.auth.token | TokenAuthSpec | Token is the token used to access the Git repository. |
spec.auth.token.tokenRef required | SecretKeySelector | TokenRef is the name and the key of the Secret containing the token. |
spec.auth.type required | string | Type is the authentication method used to access the Git repository.
|
spec.ignorePaths accepted, not used | []stringlist type: atomic | IgnorePaths is a list of paths to ignore in the Git repository. |
spec.includePaths accepted, not used | []stringlist type: atomic | IncludePaths is a list of paths to include in the Git repository. |
spec.interval required accepted, not used | Duration | Interval is the poll interval for ref resolution and content fetching. |
spec.minSyncInterval required accepted, not used | Duration | MinSyncInterval is the minimum interval between syncs. Used to rate limit syncs. |
spec.tls | TLSSpec | TLS is the TLS configuration used to verify the Git repository. |
spec.tls.caPublicCertRef required accepted, not used | ConfigMapKeySelector | CAPublicCertRef is the name and the key of the ConfigMap containing the CA public certificate. The CA certificate is used to verify the IdP server's certificate. |
spec.tls.insecureSkipVerify required | boolean | InsecureSkipVerify is a flag to skip the certificate verification. |
spec.url required | string | URL is the URL of the Git repository. |
| Field | Type | Description |
|---|---|---|
status | GitRepositoryStatus | GitRepositoryStatus reflects the observed state of the GitRepository. |
status.conditions | []Conditionlist type: map, keys: type | Conditions is the list of conditions related to the GitRepository. |
status.lastSuccessfulProbeAt | Time | LastSuccessfulProbeAt is the last time source was successfully probe. |
status.observedGeneration | integer | ObservedGeneration is the last generation that was observed by the controller. |
status.releaseCount | integer | ReleaseCount is the number of Release referencing the GitRepository. |
status.webhooks | []WebhookStatuslist type: map, keys: name | Webhooks is the list of statuses of webhooks that are configured for the GitRepository. |
status.webhooks[].filteredCount | integer | FilteredCount is the number of times the webhook was filtered. |
status.webhooks[].lastReceived | Time | LastReceived is the last time the webhook was received. |
status.webhooks[].lastRejection | LastRejectionStatus | LastRejection is the last time, reason and message the webhook was rejected. |
status.webhooks[].lastRejection.message | string | Message is the message of the webhook rejection. |
status.webhooks[].lastRejection.reason | string | Reason is the reason the webhook was rejected. |
status.webhooks[].lastRejection.rejectedAt | Time | RejectedAt is the time the webhook was rejected. |
status.webhooks[].lastTriggered | Time | LastTriggered is the last time the webhook was triggered. |
status.webhooks[].name required | string | Name is the name of the webhook. |
status.webhooks[].receivedCount | integer | ReceivedCount is the number of times the webhook was received. |
status.webhooks[].rejectedCount | integer | RejectedCount is the number of times the webhook was rejected. |
status.webhooks[].triggersCount | integer | TriggersCount is the number of times the webhook was triggered. |
status.webhooks[].url required | string | URL is the URL of the webhook. |
The top-level webhook field is for planned push triggers. convoy has no webhook receiver yet.
Conditions#
Ready · written by convoy-controller-manager
| Reason | Status | Meaning |
|---|---|---|
Verified | True | convoy listed the remote refs of the repository with the configured credentials. |
Unsupported | False | The auth type is not implemented, or the SSH key or known_hosts data cannot be used. convoy does not retry with backoff. The periodic resync checks the source again. |
VerifyFailed | False | convoy could not list the remote refs, for example because of the network or the credentials. convoy retries. |
In the code
convoy v0.9.0
internal/controller/gitrepository.(*gitFetcher).cloneinternal/controller/gitrepository/fetcher.go:132internal/controller/gitrepository.(*Controller).syncHandlerinternal/controller/gitrepository/controller.go:70