Authentication

nem can authenticate outbound requests to the GitHub API, GitHub release asset downloads, and arbitrary HTTP artifact servers. Authentication is configured in ~/.nem/config.yaml under the optional auth: block. When auth: is absent, every request is unauthenticated.

Schema

auth:
  github:
    token: '{{ env "GITHUB_TOKEN" }}'
  http:
    - host: artifacts.corp.example
      bearer: '{{ env "CORP_TOKEN" }}'
    - host: registry.internal:8443
      basic:
        username: ci
        password: '{{ env "CI_PASS" }}'
    - host: api.thirdparty.io
      header:
        name: X-API-Key
        value: '{{ env "THIRDPARTY_KEY" }}'
  oci:
    - registry: ghcr.io
      username: myuser
      password: '{{ env "GHCR_TOKEN" }}'

auth.github.token

A GitHub personal access token. When set, it is sent as Authorization: Bearer <token> to:

• api.github.com — covers release/tag listing and checksumGitHubAsset (and the sha256GitHubAsset alias) lookups
• codeload.github.com — covers github_tag source tarballs

It is not sent to *.githubusercontent.com. GitHub redirects private asset downloads to a presigned URL on that host; the presigned URL carries its own signature in the query string and 400s if an Authorization header is present. This behavior matches gh and other GitHub clients.

A token raises the GitHub API rate limit from 60 req/hr to 5,000+/hr and allows downloading assets from private releases.

auth.http

An ordered list of per-host credentials. Each entry has a required host: and exactly one of bearer:, basic:, or header:.

host: is matched against the URL’s full host[:port], lowercased and compared literally — host: Foo.Example matches foo.example, and host: foo.example:8443 matches only the explicit port. The first entry that matches wins; later duplicates are ignored.

If an auth.http entry matches a GitHub host, its bearer: or basic: Authorization header replaces the automatic GitHub-token injection. A custom header: entry (e.g. X-API-Key) is sent in addition to the GitHub-token Authorization, since they don’t collide.

auth.oci

An ordered list of per-registry credentials for OCI registries. Each entry requires registry:, username:, and password:.

registry: is matched against the registry host (lowercased, literal). The first matching entry wins.

OCI credential resolution order: Docker credential store (~/.docker/config.json) → auth.oci entry → anonymous.

The env template function

Every string value under auth: is a Go template. The function env, available only inside auth: values, returns the value of an environment variable:

token: '{{ env "GITHUB_TOKEN" }}'

If the named variable is unset or empty, nem fails at startup with an error. Make sure the variable is set in your shell before invoking nem if you depend on auth being applied.

Schema errors in the auth: block (missing host:, multiple schemes on one entry, malformed template, etc.) likewise cause nem to fail at startup.

Literal values are allowed (e.g. token: gh_xxx), but in that case you should chmod 600 ~/.nem/config.yaml to limit who can read it.

trimPrefix, trimSuffix, and replace are also available inside auth: values.

Security notes

• Tokens are never logged and are not written anywhere outside ~/.nem/config.yaml.
• The env function is available only inside auth:; it cannot be invoked from any other configuration surface.
• Authentication for git catalogs registered with nem catalog add git flows through your system’s git configuration (credential helper, SSH agent). nem does not handle git credentials directly.