{"id":13542558,"url":"https://github.com/isometry/docker-credential-env","last_synced_at":"2026-04-01T23:48:55.739Z","repository":{"id":49855212,"uuid":"421020950","full_name":"isometry/docker-credential-env","owner":"isometry","description":"Environment-driven Docker credential helper","archived":false,"fork":false,"pushed_at":"2026-03-22T14:45:36.000Z","size":386,"stargazers_count":10,"open_issues_count":0,"forks_count":4,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-03-23T05:54:56.855Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/isometry.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2021-10-25T12:48:10.000Z","updated_at":"2026-03-22T14:44:39.000Z","dependencies_parsed_at":"2023-02-05T22:30:53.771Z","dependency_job_id":"63dc0ad9-181e-455d-bc96-449938f4c11b","html_url":"https://github.com/isometry/docker-credential-env","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/isometry/docker-credential-env","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fdocker-credential-env","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fdocker-credential-env/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fdocker-credential-env/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fdocker-credential-env/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isometry","download_url":"https://codeload.github.com/isometry/docker-credential-env/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isometry%2Fdocker-credential-env/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31293123,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T10:01:10.675Z","updated_at":"2026-04-01T23:48:55.720Z","avatar_url":"https://github.com/isometry.png","language":"Go","readme":"# Docker Credentials from the Environment\n\nA [Docker credential helper](https://docs.docker.com/engine/reference/commandline/login/#credential-helpers) to streamline repository interactions in scenarios where the cacheing of credentials to `~/.docker/config.json` is undesirable, including CI/CD pipelines, or anywhere ephemeral credentials are used.\n\nAll OCI registry clients that support `~/.docker/config.json` are supported, including [`oras`](https://oras.land/), [`crane`](https://github.com/google/go-containerregistry/blob/main/cmd/crane/README.md), [`grype`](https://github.com/anchore/grype), etc.\n\nIn addition to handling basic username:password credentials, the credential helper also includes special support for:\n\n* Amazon Elastic Container Registry (ECR) repositories using [standard AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-envvars.html), including automatic cross-account role assumption.\n* [GitHub Packages](https://ghcr.io/) via the common `GITHUB_TOKEN` environment variable.\n\n## Environment Variables\n\nFor the docker repository `https://repo.example.com/v1`, the credential helper expects to retrieve credentials from the following environment variables:\n\n* `DOCKER_repo_example_com_USR` containing the repository username\n* `DOCKER_repo_example_com_PSW` containing the repository password, token or secret.\n\nIf no environment variables for the target repository's FQDN is found, then:\n\n1. The helper will remove DNS labels from the FQDN one-at-a-time from the right, and look again, for example:\n   `DOCKER_repo_example_com_USR` =\u003e `DOCKER_example_com_USR` =\u003e `DOCKER_com_USR` =\u003e `DOCKER__USR`.\n2. If the target repository is a private AWS ECR repository (FQDN matches the regex `^[0-9]+\\.dkr\\.ecr\\.[-a-z0-9]+\\.amazonaws\\.com$`):\n* By default, it will attempt to exchange local AWS credentials (most likely exposed through `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` environment variables) for short-lived ECR login credentials, including automatic sts:AssumeRole if `role_arn` is specified (e.g. via `AWS_ROLE_ARN`).\n* **Account Suffixed Credentials**: The helper can also use AWS credentials from environment variables suffixed with a specific AWS Account ID. These credentials are expected to be in the format:\n  * `AWS_ACCESS_KEY_ID_\u003caccount_id\u003e`\n  * `AWS_SECRET_ACCESS_KEY_\u003caccount_id\u003e`\n  * `AWS_SESSION_TOKEN_\u003caccount_id\u003e` (optional)\n  * `AWS_ROLE_ARN_\u003caccount_id\u003e` (optional)\n  * `AWS_PROFILE_\u003caccount_id\u003e` (optional)\n\n### AWS Profile Selection\n\nThe helper supports using AWS named profiles for authentication:\n\n* `AWS_PROFILE`: Specifies which profile to use from your AWS shared configuration files. This is used when no account-specific credentials or profile is found.\n* `AWS_PROFILE_\u003caccount_id\u003e`: Account-specific profile selection. When accessing an ECR repository for a specific AWS account, you can set this environment variable to use a specific named profile from your AWS shared configuration files.\n\nThe profile selection follows this order of precedence:\n1. Account-specific profile (`AWS_PROFILE_\u003caccount_id\u003e`)\n2. Standard AWS credentials for the specific account (if any account-specific credentials are found)\n3. Standard AWS profile (`AWS_PROFILE`) if no account-specific settings are found\n\nImportant note: The helper will first look for account-suffixed AWS credentials (e.g. AWS_ACCESS_KEY_ID_123456789012).\nIf ANY account-suffixed credentials are found, even partially, the helper requires ALL mandatory credentials to be\npresent with that account suffix. Only if NO account-suffixed credentials exist will the helper fall back to using\nstandard AWS credentials (AWS_ACCESS_KEY_ID etc).\n\nHyphens within DNS labels are transformed to underscores (`s/-/_/g`) for credential lookup.\n\n### Debug Mode\n\nSet the environment variable `DOCKER_CREDENTIAL_ENV_DEBUG=true` to enable diagnostic output. When enabled, the helper will print information about credential sources to stderr, which can help troubleshoot authentication issues, especially with AWS ECR repositories.\n\n## Configuration\n\nThe `docker-credential-env` binary must be installed to `$PATH`, and is enabled via `~/.docker/config.json` (or `$DOCKER_CONFIG/config.json` if the `DOCKER_CONFIG` environment variable is set):\n\nThe `docker-credential-env` binary includes a `setup` sub-command to help configure Docker to use the credential helper.\n\n* Configure all Docker authentication to use the `env` credential helper:\n  ```bash\n  docker-credential-env setup default\n  ```\n  or\n  ```json\n  {\n    \"credsStore\": \"env\"\n  }\n  ```\n\n* Configure a specific registry to use the `env` credential helper:\n  ```bash\n  docker-credential-env setup artifactory.example.com\n  docker-credential-env setup ghcr.io\n  docker-credential-env setup 123456789012.dkr.ecr.us-east-1.amazonaws.com\n  ```\n\n  ```json\n  {\n    \"credHelpers\": {\n      \"artifactory.example.com\": \"env\",\n      \"ghcr.io\": \"env\",\n      \"123456789012.dkr.ecr.us-east-1.amazonaws.com\": \"env\"\n    }\n  }\n  ```\n\nBy default, attempts to explicitly `docker {login,logout}` for registries configured to use the `env` credential helper will generate an error. To ignore these errors, set the environment variable `IGNORE_DOCKER_LOGIN=1`.\n\n* Show current configuration for the `env` credential helper:\n  ```bash\n  docker-credential-env setup show\n  ```\n\nThe setup command respects the `DOCKER_CONFIG` environment variable for locating and updating the Docker client configuration file.\n\n## Example Usage\n\n### Jenkins\n\n```groovy\nstages {\n    stage('Push Image to Artifactory') {\n        environment {\n            DOCKER_artifactory_example_com = credentials('jenkins.artifactory') // (Vault) Username-Password credential\n        }\n        steps {\n            sh 'docker push artifactory.example.com/example/example-image:1.0'\n        }\n    }\n\n    stage('Push Image to Docker Hub') {\n        environment {\n            DOCKER_docker_com = credentials('hub.docker.com') // Username-Password credential, exploiting domain search\n        }\n        steps {\n            sh 'docker push hub.docker.com/example/example-image:1.0'\n        }\n    }\n\n    stage('Push Image to AWS-ECR (Standard Credentials)') {\n        environment {\n            // any standard AWS authentication mechanisms are supported\n            AWS_ROLE_ARN                = 'arn:aws:iam::123456789:role/jenkins-user' // triggers automatic sts:AssumeRole\n            // AWS_CONFIG_FILE          = file('AWS_CONFIG')\n            // AWS_PROFILE              = 'jenkins'\n            AWS_ACCESS_KEY_ID           = credentials('AWS_ACCESS_KEY_ID') // String credential\n            AWS_SECRET_ACCESS_KEY       = credentials('AWS_SECRET_ACCESS_KEY') // String credential\n            DOCKER_CREDENTIAL_ENV_DEBUG = 'true' // Enable debug output for credential helper\n        }\n        steps {\n            sh 'docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/example/example-image:1.0'\n        }\n    }\n\n    stage('Push Image to AWS-ECR (Account Suffixed Credentials)') {\n        environment {\n            // Make sure to include all required suffixed credentials\n            AWS_ROLE_ARN_987654321098          = credentials('AWS_ROLE_ARN') // String credential\n            AWS_ACCESS_KEY_ID_987654321098     = credentials('AWS_ACCESS_KEY_ID') // String credential\n            AWS_SECRET_ACCESS_KEY_987654321098 = credentials('AWS_SECRET_ACCESS_KEY') // String credential\n            // AWS_SESSION_TOKEN_987654321098  = credentials('AWS_SESSION_TOKEN') // Optional\n            DOCKER_CREDENTIAL_ENV_DEBUG        = 'true' // Enable debug output for credential helper\n        }\n        steps {\n            sh '''\n              docker push 987654321098.dkr.ecr.eu-west-1.amazonaws.com/another-example/another-image:2.0\n            '''\n        }\n    }\n\n    stage('Push Image to AWS-ECR (Using Named Profiles)') {\n      environment {\n        // Using standard profile for one account\n        AWS_PROFILE                    = 'default-profile'\n        // Using account-specific profile for another account\n        AWS_PROFILE_987654321098       = 'account-specific-profile'\n        DOCKER_CREDENTIAL_ENV_DEBUG    = 'true' // Enable debug output for credential helper\n      }\n      steps {\n        sh '''\n            # Uses AWS_PROFILE_987654321098\n            docker push 987654321098.dkr.ecr.eu-west-1.amazonaws.com/another-example/another-image:2.0\n\n            # Uses AWS_PROFILE for a different account\n            docker push 123456789.dkr.ecr.us-east-1.amazonaws.com/example/example-image:1.0\n          '''\n      }\n    }\n\n  stage('Push Image to GHCR') {\n        environment {\n            GITHUB_TOKEN = credentials('github') // String credential\n        }\n        steps {\n            sh 'docker push ghcr.io/example/example-image:1.0'\n        }\n    }\n}\n```\n","funding_links":[],"categories":["Go","others"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fdocker-credential-env","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisometry%2Fdocker-credential-env","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisometry%2Fdocker-credential-env/lists"}