# nscloud-checkout-action

```text theme={null}
namespacelabs/nscloud-checkout-action@v9
```

Namespace platform provides [Cache Volumes](/content/docs/solutions/github-actions/caching.md) feature that allows workflows to share data across invocations.

These caches can store Git repository mirrors for fast checkouts. This action uses the Namespace cache volumes to store and retrieve the git mirrors.

## Prerequisites

The git mirrors cache volumes must be enabled in the Runner Profile, or set in runners' labels. See [Caching Git Repositories](/content/docs/integrations/git-checkouts.md)

## Example

```yaml {7,11} theme={null}
jobs:
  build:
    name: Build large Git repository

# If you use Runner Profiles with Git mirror caching enabled
    runs-on:
      - namespace-profile-{profile name}

# Or, if you use runners labels
    runs-on:
      - nscloud-ubuntu-22.04-amd64-2x4-with-cache
      - nscloud-git-mirror-5gb

steps:
      - name: Checkout with Namespace Git mirrors cache
        uses: namespacelabs/nscloud-checkout-action@v9
        with:
          fetch-depth: 10
```

## Options

### repository

*`string`* Repository name with owner. For example, namespacelabs/foundation. Default: `${{ github.repository }}`.

### ref

*`string`* The branch, tag or SHA to checkout. When checking out the repository that triggered a workflow, this defaults to the reference or SHA for that event. Otherwise, uses the default branch.

### token

*`string`* Personal access token (PAT) used to fetch the repository. Default: `${{ github.token }}`.

### fetch-depth

*`string`* Number of commits to fetch. 0 indicates all history for all branches and tags. Default: 1.

### path

*`string`* Relative path under `$GITHUB_WORKSPACE` to place the repository.

### submodules

*`string`* Whether to checkout submodules: `true` to checkout submodules or `recursive` to recursively checkout submodules. Only available since version `v1`.

Starting with `v4`, submodule checkouts are also cached.

### dissociate

*`string`* Dissociate the checkout (and optionally submodules, if any) from the mirror. Default: "false".

Use "true" to dissociate the main repository or "recursive" to dissociate the main repository and all submodules.

Dissociate instructs git to copy all git objects to a checkout directory. After this, the checkout has no link to the Namespace Git mirror. This allows docker-based GitHub actions to perform git operations on the checkout, such as git status.

### persist-credentials

*`string`* Whether to configure the token or SSH key with the local git config. Default: "true".

### lfs

*`string`* Whether to download and cache Git-LFS files. Default: "false".

Supported from version `v6`.

### lfs-mode

*`string`* Controls how LFS objects are fetched into the cached Git mirror. Only takes effect when `lfs: true`. Default: "default".

Supported from version `v9`.

* `default`: pre-fetch LFS for every ref the mirror's git fetch just updated. Best across-ref cache reuse on warm mirrors, but on a cold cache this downloads the entire repository's LFS history across all branches and tags, which can be slow.
* `ref`: pre-fetch LFS only for the ref being checked out.
* `recent`: pre-fetch LFS for refs updated in the last `lfs.fetchrecentrefsdays` (default 7) days.

### filter

*`string`* Partially clone against a given filter. Optional.

### sparse-checkout

*`string`* Do a sparse checkout on given patterns. Each pattern should be separated with new lines. Optional.

### sparse-checkout-cone-mode

*`boolean`* Specifies whether to use cone-mode when doing a sparse checkout. Optional. Default is `true`.

### max-attempts

*`number`* Maximum number of attempts for git network operations. Set to `1` to disable retries. Optional. Default is `3`.

### trace

*`boolean`* Enable git tracing (`GIT_TRACE`) for debugging. Optional. Default is `false`.

## Advanced: Running GitHub Jobs in Containers

When using [containers to run GitHub Jobs](https://docs.github.com/en/actions/using-jobs/running-jobs-in-a-container), extra configuration is required to make the checkout action work correctly.

1. The Git mirror path must be mounted into the container.
2. The env var `NSC_GIT_MIRROR` must be set.

See the following snippet for a working example.

**With runner profiles**

```yaml {8,10} theme={null}
jobs:
  tests:
    runs-on: namespace-profile-my-profile-for-containers

container:
      image: mcr.microsoft.com/playwright:v1.39.0
      env:
        NSC_GIT_MIRROR: ${{ env.NSC_GIT_MIRROR }} # env.NSC_GIT_MIRROR contains the path to git mirror directory.
      volumes:
        - /gitmirror:/gitmirror # Where the Cache Volume containing the git mirror is mounted.

steps:
      - name: Checkout code
        uses: namespacelabs/nscloud-checkout-action@v8
```

**With runner labels**

```yaml {10,12} theme={null}
jobs:
  tests:
    runs-on:
      - nscloud-ubuntu-22.04-amd64-8x16-with-cache
      - nscloud-git-mirror-5gb

container:
      image: mcr.microsoft.com/playwright:v1.39.0
      env:
        NSC_GIT_MIRROR: ${{ env.NSC_GIT_MIRROR }} # env.NSC_GIT_MIRROR contains the path to git mirror directory, that lives under `/gitmirror`.
      volumes:
        - /gitmirror:/gitmirror # Where the Cache Volume containing the git mirror is mounted.

steps:
      - name: Checkout code
        uses: namespacelabs/nscloud-checkout-action@v8
```