auth

README

docker-auth

A GitLab Function that configures Docker authentication for CI/CD pipelines. It generates a DOCKER_AUTH_CONFIG that can be used to authenticate with container registries.

Features

• Username/Password Authentication: Authenticate to any container registry using credentials
• Credential Helper Support: Configure Docker credential helpers for specific registries
• Credential Store Support: Set a default credential store for all registries
• Preserves Existing Config: Merges with existing ~/.docker/config.json if present

Usage

Add the function as a step in your .gitlab-ci.yml:

my-job:
  run:
    - name: docker_auth
      step: registry.gitlab.com/functions/docker/auth:1
      inputs:
        registry: ${{ vars.CI_REGISTRY }}
        username: ${{ vars.CI_REGISTRY_USER }}
        password: ${{ vars.CI_REGISTRY_PASSWORD }}

Inputs

Input	Type	Required	Description
registry	string	Yes*	Registry URL (e.g., registry.gitlab.com)
username	string	No	Username for authentication
password	string	No	Password for authentication
helper_name	string	No	Credential helper name (e.g., ecr-login, gcr)
store_name	string	No	Default credential store name
config_file	string	No	Path to existing config.json (default: ~/.docker/config.json)

*Required when using username or helper_name

Note: You must provide exactly one of: username, helper_name, or store_name.

Outputs

Output	Type	Description
auth	struct	Contains DOCKER_AUTH_CONFIG with the generated Docker configuration

Examples

Authenticate to GitLab Container Registry

build-image:
  run:
    - name: docker_auth
      step: registry.gitlab.com/functions/docker/auth:1
      inputs:
        registry: ${{ vars.CI_REGISTRY }}
        username: ${{ vars.CI_REGISTRY_USER }}
        password: ${{ vars.CI_REGISTRY_PASSWORD }}

Use AWS ECR Credential Helper

build-image:
  run:
    - name: docker_auth
      step: registry.gitlab.com/functions/docker/auth:1
      inputs:
        registry: 123456789.dkr.ecr.us-east-1.amazonaws.com
        helper_name: ecr-login

Set Default Credential Store

build-image:
  run:
    - name: docker_auth
      step: registry.gitlab.com/functions/docker/auth:1
      inputs:
        store_name: secretservice

How It Works

The function generates a Docker configuration JSON that includes your authentication credentials. When using username/password authentication, credentials are base64-encoded in the standard Docker config format:

{
  "auths": {
    "registry.gitlab.com": {
      "auth": "base64-encoded-credentials"
    }
  }
}

The output DOCKER_AUTH_CONFIG can be used by Docker and container tools to authenticate when pulling or pushing images.

Contributing

Contributions are welcome! Please open an issue or merge request.

License

See the project license for details.

Documentation

Index

• func Run(p Params) error
• type AuthEntry
• type DockerConfig
• type OutputFile
• type Params

Functions

func Run

func Run(p Params) error

Run validates p, reads the existing Docker config, applies the requested auth configuration, and writes the result to the specified output files.

Types

type AuthEntry

type AuthEntry struct {
	Auth string `json:"auth,omitempty"`
}

AuthEntry holds base64-encoded credentials for a single registry.

type DockerConfig

type DockerConfig struct {
	Auths       map[string]AuthEntry `json:"auths,omitempty"`
	CredHelpers map[string]string    `json:"credHelpers,omitempty"`
	CredsStore  string               `json:"credsStore,omitempty"`
}

DockerConfig represents the structure of a Docker config.json file.

type OutputFile

type OutputFile struct {
	Name  string          `json:"name"`
	Value json.RawMessage `json:"value"`
}

OutputFile is the envelope format written to output and export files.

type Params

type Params struct {
	ConfigPath string // Path to an existing Docker config.json. If empty or non-existent, an empty config is used.
	Registry   string
	Username   string
	Password   string
	HelperName string
	StoreName  string
	OutputFile string
	ExportFile string
}

Params holds the resolved inputs for configuring Docker auth. All paths must be fully resolved — the library does not apply defaults (e.g. it will not locate ~/.docker/config.json when ConfigPath is empty).