# argocd app create: Define an Application

> argocd app create registers an Argo CD Application from a repo path or Helm chart. Reference for --repo, --path, --dest-namespace, --sync-policy, and CI errors.

Source: https://latchkey.dev/learn/command-reference/argocd-app-create  
Updated: 2026-06-30

argocd app create registers a new Application that maps a Git repo path to a destination cluster and namespace.

An Application is the core Argo CD object: source repo plus destination plus sync policy. Creating it from the CLI lets a pipeline bootstrap or update the definition.

## What it does

argocd app create defines an Application resource pointing at a source (--repo plus --path, or a Helm chart) and a destination (--dest-server or --dest-name, plus --dest-namespace). Without --sync-policy the app is created OutOfSync and waits for a manual sync.

## Common usage

```Terminal
argocd app create guestbook \
  --repo https://github.com/acme/manifests.git \
  --path guestbook --revision main \
  --dest-server https://kubernetes.default.svc \
  --dest-namespace guestbook \
  --sync-policy automated --auto-prune
```

## Options

| Flag | What it does |
| --- | --- |
| --repo <url> | Source Git repository URL |
| --path <dir> | Directory within the repo holding manifests |
| --revision <ref> | Git branch, tag, or commit to track |
| --dest-server / --dest-name | Target cluster API URL or registered name |
| --dest-namespace <ns> | Namespace to deploy into |
| --sync-policy automated | Enable auto-sync (default is manual) |
| --helm-set key=value | Override a Helm value for a chart source |

## Common errors in CI

"FATA[0000] rpc error: code = NotFound desc = repository not found" means the --repo was never added with argocd repo add (or lacks credentials). "application destination ... is not permitted in project" means the AppProject restricts that cluster/namespace; widen the project or use --project. "cluster ... not found" means --dest-server is not a registered cluster.

## 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

### argocd app create: Define an Application?

An Application is the core Argo CD object: source repo plus destination plus sync policy. Creating it from the CLI lets a pipeline bootstrap or update the definition.

### What it does?

argocd app create defines an Application resource pointing at a source (--repo plus --path, or a Helm chart) and a destination (--dest-server or --dest-name, plus --dest-namespace). Without --sync-policy the app is created OutOfSync and waits for a manual sync.

### Common errors in CI?

"FATA[0000] rpc error: code = NotFound desc = repository not found" means the --repo was never added with argocd repo add (or lacks credentials). "application destination ... is not permitted in project" means the AppProject restricts that cluster/namespace; widen the project or use --project. "cluster ...

---

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