Skip to main content

atmos git clone

Clone a named repository configured under git.repositories, the single configured repository when only one exists, an ad hoc URI, or — in CI — the current repository as a replacement for actions/checkout. Clone is a reconcile operation: if the destination already exists, Atmos fetches and fast-forwards instead of failing, so restored CI caches and re-runs are always safe.

atmos git clone --help

Usage​

atmos git clone [name-or-uri] [flags] [-- <native git args>]

Configure repositories once in atmos.yaml, then clone them by name:

git:
  repositories:
    flux-deploy:
      uri: https://github.com/acme/flux-deploy.git
      branch: main
      clone:
        depth: 1
        single_branch: true
atmos git clone flux-deploy

Examples​

# Clone a named managed repository (destination: automatic XDG workdir)
atmos git clone flux-deploy

# Clone the single configured repository when only one exists
atmos git clone

# Clone/reconcile every repository configured under git.repositories
atmos git clone --all

# Clone an ad hoc HTTPS URI (destination: <cwd>/<repo-name>, like plain git clone)
atmos git clone https://github.com/acme/repo.git

# SCP-style URI
atmos git clone git@github.com:acme/repo.git

# go-getter style URI — same syntax used in vendoring and `source` configs
atmos git clone "git::https://github.com/acme/repo.git?ref=main&depth=1"

# Shallow, single-branch clone into an explicit destination
atmos git clone flux-deploy --depth=1 --single-branch --workdir=./deploy

# In CI (ci.enabled: true): check out the current repository into the
# working directory — replaces actions/checkout
atmos git clone

# Pass native arguments to the underlying git clone invocation
atmos git clone flux-deploy -- --no-tags

Clone Destinations​

The destination depends on the argument form:

Clone formDestination
Named managed repository (atmos git clone flux-deploy)Automatic XDG workdir ($XDG_CACHE_HOME/atmos/git/repositories/<name>), captured by the native CI cache
Single configured repository (atmos git clone with exactly one repository outside CI)Automatic XDG workdir ($XDG_CACHE_HOME/atmos/git/repositories/<name>)
No-arg CI checkout replacement (atmos git clone with CI checkout enabled and detected CI metadata)The working directory (e.g., GITHUB_WORKSPACE), exactly like actions/checkout
Ad hoc URI (atmos git clone https://...)<cwd>/<repo-name>, like plain git clone

--workdir=<path> overrides the destination in all forms.

CI Checkout Replacement​

When invoked with no argument in CI, atmos git clone infers the repository and ref from CI provider metadata. This requires:

  1. CI checkout enabled by ci.enabled: true, --ci, or ATMOS_CI=true.
  2. A detected CI provider (for example, GitHub Actions).
  3. Repository metadata supplied by the provider.

--ci and ATMOS_CI=true are useful before the repository is checked out, when its atmos.yaml is not available yet. --ci=false or ATMOS_CI=false explicitly opts out of the CI checkout path and uses normal no-argument repository resolution instead. The command-line flag takes precedence over ATMOS_CI.

Outside CI, no-arg clone reconciles the single configured repository when exactly one repository exists under git.repositories. If zero or multiple repositories are configured, pass a repository name, URI, or --all.

Fork-PR safety gate​

Because atmos git clone replaces actions/checkout, it inherits the same "pwn request" risk: cloning untrusted fork code in a job that holds the base repository's secrets. Mirroring actions/checkout v7, Atmos refuses by default to clone fork content under the elevated pull_request_target and workflow_run events.

The gate engages only on the dangerous combination — an elevated event and a fork-targeting clone:

  • an explicit --branch / ref override that is a pull-request ref (e.g. refs/pull/<N>/merge or refs/pull/<N>/head), or
  • an ad hoc clone URI whose owner/repo differs from the base GITHUB_REPOSITORY.

The safe no-arg checkout (base repository at its base ref) is never gated, and non-elevated events (pull_request, push, merge_group) are unaffected.

Recommended: use a pull_request workflow (which withholds fork secrets) for clone-and-plan of fork contributions; reserve pull_request_target / workflow_run for trusted, secret-free steps.

To bypass the gate deliberately, set the intentionally named --allow-unsafe-fork flag, ATMOS_ALLOW_UNSAFE_FORK_EXECUTION=true, or ci.allow_unsafe_fork_execution: true in atmos.yaml. The environment variable and the config key set the same value, and they also release the posting gate that holds CI comments, statuses, exports, and SARIF uploads for fork pull requests.

Fetch depth and atmos describe affected

Affected detection requires merge-base history. If atmos describe affected runs against the clone, use --depth=0 (full history) or a depth large enough to include the merge base — the same guidance that applies to fetch-depth with actions/checkout.

Arguments​

name-or-uri (optional)

A repository name configured under git.repositories, or a Git URI. Supported URI forms:

  • HTTPS: https://github.com/acme/repo.git
  • SCP-style: git@github.com:acme/repo.git
  • go-getter style: git::https://github.com/acme/repo.git?ref=main&depth=1 — the git:: prefix is stripped, ?ref= maps to the branch/ref and ?depth= to clone depth; unknown query parameters are rejected

When omitted: with CI checkout enabled (ci.enabled: true, --ci, or ATMOS_CI=true) and a detected CI provider, performs the current-repository checkout; otherwise, reconciles the single configured repository when exactly one entry exists under git.repositories. When zero or multiple repositories are configured, pass a repository name, a URI, or --all.

Flags​

--all (optional)

Clone/reconcile every repository configured under git.repositories, concurrently. Every repository is attempted; failures are aggregated and reported at the end. Mutually exclusive with a positional argument. Environment variable: ATMOS_GIT_CLONE_ALL

--ci (optional)

Explicitly enable the current-repository CI checkout for a no-argument clone. Set --ci=false to opt out, even when CI is detected or ci.enabled is true. This selector does not change named, URI, or --all clones. Environment variable: ATMOS_CI

--repo-uri (optional)

Remote repository URI (overrides the configured URI). Environment variable: ATMOS_GIT_REPO_URI

--branch / -b (optional)

Branch to clone. Precedence: flag > ?ref= query parameter > repository config > remote default branch. Environment variable: ATMOS_GIT_BRANCH

--remote (optional)

Remote name. Default: origin. Environment variable: ATMOS_GIT_REMOTE

--workdir (optional)

Override the destination directory for all clone forms. Environment variable: ATMOS_GIT_WORKDIR

--depth (optional)

Shallow clone depth. 0 (the default) means full history. Precedence: flag > ?depth= query parameter > clone.depth config > default. Environment variable: ATMOS_GIT_DEPTH

--filter (optional)

Partial-clone filter spec (e.g., blob:none), matching Git's own --filter flag. Environment variable: ATMOS_GIT_FILTER

--single-branch (optional)

Limit the clone to the specified branch. Environment variable: ATMOS_GIT_SINGLE_BRANCH

--submodules (optional)

Initialize submodules after clone. Off by default. Environment variable: ATMOS_GIT_SUBMODULES

--allow-unsafe-fork (optional)

Opt out of the fork-PR safety gate and allow cloning untrusted fork content in pull_request_target / workflow_run events. Unsafe — only set this when a fork-facing workflow has a documented reason to bypass the gate. Off by default. Environment variable: ATMOS_ALLOW_UNSAFE_FORK_EXECUTION

--identity (optional)

Atmos Auth identity to use for this operation (global flag). Overrides the repository's auth.identity. Environment variable: ATMOS_IDENTITY

Native Git Arguments​

Arguments after -- are passed verbatim to the underlying git clone invocation. They apply only when a fresh clone runs; reconciling an existing workdir (fetch + fast-forward) does not invoke git clone.

atmos git clone flux-deploy -- --no-tags

Related​