Remote providers

Choose your provider below. For cloud storage, create the bucket or container first. Run the commands inside your Gat repository; replace the example storage names with yours.

Keep credentials in environment variables or use identity-based authentication—not in remote URLs. Gat saves URLs as entered, even with --local. Redacted output does not protect secrets stored in configuration.

Choose a provider

In cloud URLs, /gat is an optional for your objects, not a local directory.

S3
Azure
GCS
OSS
Local

Amazon S3 and S3-compatible services use s3://.

Set credentials

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. For temporary credentials, also set AWS_SESSION_TOKEN.AWS profiles and configured ECS, EC2, or web-identity credentials also work.

Add the remote

gat remote add origin 's3://my-bucket/gat?region=eu-west-1'

A signing region is required. Gat checks region, then AWS_REGION, then AWS_DEFAULT_REGION. It does not read the region from a profile or detect it from the bucket.

S3-compatible storage

Set your service’s and signing region. Use its credentials in the same AWS environment variables. For local MinIO:

gat remote add minio 's3://my-bucket/gat?region=us-east-1&endpoint=http://localhost:9000'

Use HTTPS for non-local endpoints.

Named profiles and SSO

gat remote add origin 's3://my-bucket/gat?region=eu-west-1&profile=prod'

Without profile, Gat uses AWS_PROFILE or default. Static environment credentials take precedence over profiles.Modern sso_session profiles and credential_process are not loaded directly. For SSO, export credentials from the AWS CLI:

aws sso login --profile prod
eval "$(aws configure export-credentials --profile prod --format env)"

The export command also works with credential_process profiles. Repeat the export when credentials expire; Gat does not refresh exported tokens.

Public buckets

Use skip_signature=true for unsigned requests. A region is still required.

gat remote add public 's3://my-bucket/public?region=eu-west-1&skip_signature=true'

This does not grant permissions. Public buckets usually allow reads, not uploads.

Azure Blob Storage uses azblob://.

Choose credentials

Method	Environment variables
Shared key	`AZURE_STORAGE_ACCOUNT_NAME` + `AZURE_STORAGE_ACCOUNT_KEY`
SAS token	`AZURE_STORAGE_SAS_TOKEN`
Bearer token	`AZURE_STORAGE_BEARER_TOKEN`

Configured managed identity, workload identity, and service-principal credentials also work.

Add the remote

gat remote add origin 'azblob://my-container/gat?endpoint=https://myaccount.blob.core.windows.net'

Set the storage account endpoint explicitly. The container name and credential variables do not supply it.

Gat does not use az login automatically. Export a storage token from your existing CLI session:

export AZURE_STORAGE_BEARER_TOKEN="$(
  az account get-access-token \
    --resource https://storage.azure.com/ \
    --query accessToken -o tsv
)"

Repeat when the token expires. Existing shared-key or SAS credentials take precedence over the bearer token.

Google Cloud Storage uses gcs://.

Set up Application Default Credentials

For local development:

gcloud auth application-default login

Use this command, not gcloud auth login. Alternatively, set GOOGLE_APPLICATION_CREDENTIALS to a credential file. On Google Cloud, an attached service account or configured GKE workload identity can supply credentials.

Add the remote

gat remote add origin 'gcs://my-bucket/gat'

Set an explicit credential file

Keep machine-specific paths in local configuration:

gat remote add --local origin 'gcs://my-bucket/gat?credential_path=/path/to/service-account.json'

credential_path reads JSON from a file. The separate credential option expects base64-encoded JSON, not a filename. Prefer a file: base64 is not encryption. If you use credential=${GCS_CREDENTIAL}, supply the original base64 value without additional URL encoding.

Alibaba Cloud Object Storage Service uses oss://.

Set credentials

Set ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET. For temporary credentials, also set ALIBABA_CLOUD_SECURITY_TOKEN.Configured ECS RAM roles and OIDC federation also work.

Add the remote

gat remote add origin 'oss://my-bucket/gat?endpoint=https://oss-cn-hangzhou.aliyuncs.com'

Set the endpoint for your bucket’s region.

Local directories and mounted filesystems use file://. No cloud credentials are needed.

Check filesystem access

You need filesystem permissions for the operations you run. Hard-link support is not required. Mount network storage locally rather than using file://host/....

Add the remote

gat remote add --local origin 'file:///mnt/backup/gat'

gat remote add --local origin 'file:///C:/Users/alice/gat-cache'

Use three slashes and an absolute path. On Windows, use forward slashes. file://path is not valid.

Path overrides and filesystem behavior

The only supported query option is root, which overrides the URL path:

file:///?root=/mnt/backup/gat

file:///?root=C:/Users/alice/gat-cache

On Windows, use this form instead of appending query options to a drive-letter URL. atomic_write_dir and other options are rejected.Gat stages writes beside the destination and publishes by atomic rename, which may replace an existing object at the same key. Presence checks do not verify or repair existing content. Windows directory-entry durability after power loss depends on the platform.

Manage a remote

These examples use origin. Substitute your remote name as needed:

gat remote list
gat remote show origin

add and URL-changing update check configuration and backend capabilities—not connectivity or account permissions. list and show only inspect configuration.

Choose where settings are saved

Scope	File	Use for
`--project` (default)	`gat.yaml`	Shared repository settings
`--local`	`.gat/gat.yaml`	This repository on this machine; not committed
`--global`	`~/.gat/gat.yaml`	User-wide defaults

Local settings override project settings; project settings override global settings. See Config inheritance for how complete named definitions override one another.

Update a remote URL

gat remote update origin --url 's3://my-bucket/gat?region=eu-west-1'

Use the same scope flag as the original definition, such as --local. Changing the URL does not copy stored objects. Follow the storage migration workflow when moving content to a new store.

Use environment variables in a URL

export GAT_BUCKET=my-bucket
gat remote add origin 's3://${GAT_BUCKET}/gat?region=eu-west-1'

Single quotes preserve the . Set the variable before adding or updating the URL, and whenever a command uses the remote. Examples using export require a POSIX shell; use your shell’s equivalent on Windows.

Syntax	Result
`${NAME}`	Environment value; missing variables cause an error
`$NAME`	Literal text; braces are required
`$$`	Literal `$`
`$${NAME}`	Literal `${NAME}`

Names must match [A-Za-z_][A-Za-z0-9_]*. Expansion happens once; shell commands and ${NAME:-default} are not supported.

Troubleshooting and advanced options

Special characters in URL values

Use an environment reference when an option contains special characters:

gat remote add origin 'azblob://assets/gat?endpoint=https://myaccount.blob.core.windows.net&sas_token=${SAS_TOKEN}'

Set SAS_TOKEN to the token exactly as Azure supplies it. Gat preserves characters such as &, +, #, and % in query-value substitutions. Do not add URL encoding. If you previously pre-encoded a variable for Gat, remove that extra encoding layer.You can also set AZURE_STORAGE_SAS_TOKEN and omit sas_token from the URL. Literal URLs and whole-URL references retain normal URL semantics; use references for individual values rather than embedding raw tokens in them.

Redacted output and untrusted remotes

list and show redact sensitive URL values without expanding templates or opening a backend. The saved URL is unchanged.Review URLs and endpoints from untrusted repositories before using your credentials with them.

Private certificates and unsupported options

Private certificate authorities must be trusted by the build’s TLS transport. There is no generic remote query option; SSL_CERT_FILE and SSL_CERT_DIR are not portable overrides.Only the five schemes above are supported. Cloud options must be supported by Gat’s OpenDAL version (0.58.2), not merely by the provider’s SDK. In cloud URLs, the host and non-empty path override bucket/container and root query fields.

Readiness on first use

Before the first network transfer, Gat checks that it can list the configured storage root. Credentials must allow root listing, plus the read, write, or delete operations you intend to use. This check has a 5-second deadline. If connection setup needs longer, set a positive whole number of seconds:

export GAT_CONNECT_TIMEOUT=15
gat push

$env:GAT_CONNECT_TIMEOUT = '15'
gat push

Unset the variable to restore the default. This changes connection readiness only, not transfer timeouts.

Connection times out or listing is denied

For a timeout, check network access and the configured credential provider. A timeout does not prove credentials are missing. If listing is denied, check permission to list the configured bucket or container prefix.After fixing the problem, rerun the command. A successful connection check does not prove read, write, or delete access; test an actual transfer.

When the check runs

The check includes credential discovery, requests, and retries. Its result is reused within the command. Unused remotes, cache-only work, configuration inspection, and file:// remotes do not run it.

Getting Started

Concepts

Guides

References

Commands

Remote providers

Choose a provider

Manage a remote

Troubleshooting and advanced options

Readiness on first use

Next steps

Transfer files

Remote commands

​Choose a provider

​Manage a remote

​Troubleshooting and advanced options

​Readiness on first use

​Next steps

Transfer files

Remote commands

Choose a provider

Manage a remote

Troubleshooting and advanced options

Readiness on first use

Next steps