skip to content

Some private repositories authenticate with a token in an HTTP header rather than basic auth. How do you configure that in Gradle?

level: middleimportance: should knowfreq 45%

answer

  1. HttpHeaderCredentials name + value
  2. authentication { create<HttpHeaderAuthentication>() }
  3. token from gradle.properties / env
  4. Private-Token / Authorization Bearer
  5. preemptive header, not 401 challenge

basics

~10 s

Use credentials(HttpHeaderCredentials::class) to set a header name and value (e.g. a bearer token), then declare authentication { create<HttpHeaderAuthentication>("header") } so Gradle sends that header.

solid answer

~30 s

When a repo expects a token-style header (e.g. `Authorization: Bearer ...` or a custom `Private-Token` header) instead of HTTP Basic auth, you switch from `PasswordCredentials` to `HttpHeaderCredentials`. Inside the repo block you supply `credentials(HttpHeaderCredentials::class) { name = "Authorization"; value = "Bearer $token" }`, sourcing the token from gradle.properties or an env var. Crucially you also declare an `authentication { create<HttpHeaderAuthentication>("header") }` scheme — without it Gradle doesn't know to use header-based auth and may fall back to other schemes. This is the standard pattern for GitLab package registries and similar token-gated repositories.

code

kotlin · 12 lines
kotlin
repositories {
    maven {
        url = uri("https://gitlab.example.com/api/v4/projects/42/packages/maven")
        credentials(HttpHeaderCredentials::class) {
            name = "Private-Token"
            value = providers.gradleProperty("gitlabToken").get()
        }
        authentication {
            create<HttpHeaderAuthentication>("header")
        }
    }
}

go deeper

for a junior

Recognize that some repos use a header token and Gradle has HttpHeaderCredentials for it; details optional at this level.

for a middle

Configure both credentials(HttpHeaderCredentials::class) and the authentication{ HttpHeaderAuthentication } scheme, sourcing the token externally.

for a senior

Explain preemptive header auth vs 401-challenge negotiation and why token endpoints need the explicit scheme; wire CI token injection.

for a principal

Govern token rotation, scoped/short-lived tokens, and standardizing the registry auth pattern across many builds.

## When basic auth isn't enough HTTP Basic auth (username + password) is the common case, but many registries authenticate with a *token carried in an HTTP header*. Examples: a GitLab package registry that wants `Private-Token: <token>` or `Job-Token`, or a service expecting `Authorization: Bearer <jwt>`. Gradle models this with the `HttpHeaderCredentials` type plus an explicit `HttpHeaderAuthentication` scheme. ## The two pieces **Credentials** describe *what* to send; **authentication** schemes describe *how* Gradle should authenticate. For headers you need both: ```kotlin repositories { maven { url = uri("https://gitlab.example.com/api/v4/projects/42/packages/maven") credentials(HttpHeaderCredentials::class) { name = "Private-Token" value = providers.gradleProperty("gitlabToken").get() } authentication { create<HttpHeaderAuthentication>("header") } } } ``` The `name`/`value` pair becomes a literal request header. The `authentication {}` block registers the scheme so Gradle actually applies header auth rather than negotiating basic/digest. ## Sourcing the token As with passwords, the token must not be hardcoded. Read it via `providers.gradleProperty("gitlabToken")` (backed by `~/.gradle/gradle.properties`) or from an environment variable. In CI you typically pass `ORG_GRADLE_PROJECT_gitlabToken` from the secret store, or use the platform's built-in job token. ## Why the explicit scheme is required Gradle supports several authentication schemes (`BasicAuthentication`, `DigestAuthentication`, `HttpHeaderAuthentication`). The credentials type alone doesn't fully determine behavior for headers — declaring `HttpHeaderAuthentication` tells Gradle to send the header preemptively on every request instead of waiting for a 401 challenge, which token endpoints generally require.

  • Why do you need the authentication {} block when you've already set HttpHeaderCredentials?
    The credentials only describe the header to send; the HttpHeaderAuthentication scheme tells Gradle to actually use header-based (preemptive) auth instead of negotiating basic/digest on a 401.
  • Can you use HttpHeaderCredentials to send an Authorization: Bearer token?
    Yes — set name = "Authorization" and value = "Bearer <token>". The name/value pair is sent verbatim as an HTTP request header.

saying these in an interview costs you the question

  • Setting HttpHeaderCredentials but forgetting the authentication { HttpHeaderAuthentication } scheme, so the header is never applied.
  • Trying to cram a token into PasswordCredentials' password field for a header-only endpoint.

context

resolving links…