GitRepository

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#

sources/gitrepository-auth-ssh.yaml
# 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://[email protected]/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. `aws` is the cloud provider AWS. `azure` is the cloud provider Azure. `gcp` is the cloud provider GCP.
`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. `clientSecret` is the OIDC authentication method using a client secret. `privateKeyJWT` is the OIDC authentication method using a private key JWT. `tlsClientAuth` is the OIDC authentication method using TLS client 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`	`[]string`list 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. `basic` is the authentication method using basic authentication. `cloudIdentity` is the authentication method using a cloud identity. `githubApp` is the authentication method using a GitHub App. `none` is the authentication method using no authentication. `oidc` is the authentication method using OIDC. `sshKey` is the authentication method using SSH key authentication. `token` is the authentication method using a token.
`spec.ignorePaths` accepted, not used	`[]string`list type: atomic	IgnorePaths is a list of paths to ignore in the Git repository.
`spec.includePaths` accepted, not used	`[]string`list 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`	`[]Condition`list 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`	`[]WebhookStatus`list 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.