# flux create source git: Track a Repository

> flux create source git defines a GitRepository source for Flux to pull from. Reference for --url, --branch, --tag, --secret-ref, and the auth errors in CI.

Source: https://latchkey.dev/learn/command-reference/flux-create-source-git  
Updated: 2026-06-30

flux create source git creates a GitRepository object telling Flux which repo, branch, or tag to pull manifests from.

A source is what a Kustomization or HelmRelease points at. create source git is how you register a repo for Flux to watch.

## What it does

flux create source git creates a GitRepository custom resource defining a URL and a checkout target (--branch, --tag, or --tag-semver). For private repos it references a Secret (--secret-ref) or generates one from --username/--password.

## Common usage

```Terminal
flux create source git podinfo \
  --url=https://github.com/stefanprodan/podinfo \
  --branch=master \
  --interval=1m
# private repo using an existing secret
flux create source git app \
  --url=ssh://git@github.com/acme/app \
  --branch=main --secret-ref=app-ssh
```

## Options

| Flag | What it does |
| --- | --- |
| --url <url> | Git repository URL (https:// or ssh://) |
| --branch / --tag / --tag-semver | Checkout target |
| --interval <dur> | How often Flux pulls (e.g. 1m, 5m) |
| --secret-ref <name> | Secret holding credentials for a private repo |
| --username / --password | Generate a credentials Secret inline |

## In CI

After creating a source, flux reconcile source git <name> forces an immediate fetch instead of waiting for --interval. Use ssh:// URLs with a deploy key Secret for private repos; an https:// URL needs a token in --secret-ref.

## Common errors in CI

"✗ GitRepository source reconciliation failed: ... authentication required" means a private repo with no or wrong --secret-ref. "unable to clone ... reference not found" means the --branch or --tag does not exist. "✗ timed out waiting for condition" means the source-controller could not reach the repo (network/DNS).

## Using this in CI

A runner has no kubeconfig, no cached context, and no interactive auth. Every kubectl invocation in CI needs the context supplied explicitly, and most confusing CI failures here are the command running against the wrong cluster or no cluster at all.

```Terminal
# never rely on the ambient context on a runner
kubectl --context "$KUBE_CONTEXT" -n "$NAMESPACE" get pods

# confirm what you are actually connected to before mutating anything
kubectl config current-context
kubectl cluster-info

# fail fast instead of hanging on an unreachable API server
kubectl --request-timeout=30s get nodes
```

> Always set `--request-timeout` in CI. Without it an unreachable API server hangs until the job times out, which turns a thirty-second failure into a twenty-minute one.

## FAQ

### flux create source git: Track a Repository?

A source is what a Kustomization or HelmRelease points at. create source git is how you register a repo for Flux to watch.

### What it does?

flux create source git creates a GitRepository custom resource defining a URL and a checkout target (--branch, --tag, or --tag-semver). For private repos it references a Secret (--secret-ref) or generates one from --username/--password.

### In CI?

After creating a source, flux reconcile source git <name> forces an immediate fetch instead of waiting for --interval. Use ssh:// URLs with a deploy key Secret for private repos; an https:// URL needs a token in --secret-ref.

### Common errors in CI?

"✗ GitRepository source reconciliation failed: ... authentication required" means a private repo with no or wrong --secret-ref. "unable to clone ... reference not found" means the --branch or --tag does not exist. "✗ timed out waiting for condition" means the source-controller could not reach the repo (network/DNS).

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt