Skip to content

Authentication

Jump to bottom
Refringe edited this page Mar 8, 2026 · 1 revision

Authentication

Anchor LFS authenticates users by validating credentials against the GitHub API. Each endpoint can be independently configured with its own authentication method and visibility.

Authentication Methods

GitHub Authentication

The github authentication method validates GitHub Personal Access Tokens (PATs) against the GitHub API, checking repository-level permissions.

[[endpoints]]
name = "My Repository"
url = "https://github.com/org/repo"
endpoint = "/org/repo"
visibility = "public"
authentication = "github"

How it works:

  1. The Git LFS client sends a Personal Access Token as the Basic Auth password
  2. Anchor LFS calls the GitHub API to check the user's permissions on the repository
  3. Download operations require pull permission
  4. Upload operations require push permission

Token requirements:

The PAT must have access to the repository configured in the endpoint's url field. For fine-grained PATs, ensure the token has the appropriate repository permissions (read for downloads, write for uploads).

No Authentication

The none method allows all operations without credentials. This is intended for local development and testing only.

[[endpoints]]
name = "Local Dev"
url = "https://github.com/dev/test-repo"
endpoint = "/dev/test-repo"
visibility = "public"
authentication = "none"

When using none authentication, lock ownership uses the Basic Auth username if provided, or "anonymous" if not.

Visibility Modes

Each endpoint has a visibility setting that controls access:

Public

visibility = "public"
  • Downloads: Anonymous (no authentication required)
  • Uploads: Require authentication with push permission

Private

visibility = "private"
  • Downloads: Require authentication with pull permission
  • Uploads: Require authentication with push permission

GitHub Enterprise

To authenticate against a GitHub Enterprise instance, set the github_api_url field on the endpoint:

[[endpoints]]
name = "Enterprise Repo"
url = "https://github.example.com/org/repo"
endpoint = "/org/repo"
visibility = "private"
authentication = "github"
github_api_url = "https://github.example.com/api/v3/"

Notes:

  • The github_api_url must include the trailing slash
  • The repository URL must match the GitHub Enterprise hostname
  • Non-github.com repository URLs require github_api_url to be set; the server will reject the configuration otherwise
  • Endpoints targeting the same GitHub Enterprise instance share a single authenticator and cache for efficiency

Authentication Caching

To reduce load on the GitHub API, authentication results are cached in memory.

[options]
auth_cache_ttl = "60s"
  • Default TTL: 60 seconds
  • Cache entries are keyed by a hash of the token, endpoint, and operation
  • A background goroutine periodically sweeps expired entries
  • Transient failures (e.g., network errors) are not cached
  • Set to "0s" to disable caching entirely

When caching is enabled, permission changes on GitHub may take up to auth_cache_ttl to take effect on the LFS server.

How Git LFS Sends Credentials

Git LFS uses Git's credential system. When the server requires authentication, Git prompts for credentials or uses a configured credential helper.

The simplest approach is to configure Git to use a Personal Access Token:

# Store credentials in Git's credential helper
git credential approve <<EOF
protocol=https
host=lfs.example.com
username=your-github-username
password=ghp_your_personal_access_token
EOF

Or use a .netrc file:

machine lfs.example.com
login your-github-username
password ghp_your_personal_access_token

See Git LFS Client Setup for more details on client configuration.

Next Steps

Clone this wiki locally