Merge pull request #912 from docker/scope

Add scope input to set scopes for the authentication token

Author: crazy-max

.github/workflows/ci.yml

@@ -207,7 +207,7 @@ jobs:
         with:
           registry: public.ecr.aws
 
-  github-container:
+  ghcr:
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false
@@ -356,3 +356,125 @@ jobs:
             echo "::error::Should have failed"
             exit 1
           fi
+
+  scope-dockerhub:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v6
+      -
+        name: Login to Docker Hub
+        uses: ./
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          scope: '@push'
+      -
+        name: Print config.json files
+        shell: bash
+        run: |
+          shopt -s globstar nullglob
+          for file in ~/.docker/**/config.json; do
+            echo "## ${file}"
+            jq '(.auths[]?.auth) |= "REDACTED"' "$file"
+            echo ""
+          done
+
+  scope-dockerhub-repo:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v6
+      -
+        name: Login to Docker Hub
+        uses: ./
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          scope: 'docker/buildx-bin@push'
+      -
+        name: Print config.json files
+        shell: bash
+        run: |
+          shopt -s globstar nullglob
+          for file in ~/.docker/**/config.json; do
+            echo "## ${file}"
+            jq '(.auths[]?.auth) |= "REDACTED"' "$file"
+            echo ""
+          done
+
+  scope-ghcr:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v6
+      -
+        name: Login to GitHub Container Registry
+        uses: ./
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          scope: '@push'
+      -
+        name: Print config.json files
+        shell: bash
+        run: |
+          shopt -s globstar nullglob
+          for file in ~/.docker/**/config.json; do
+            echo "## ${file}"
+            jq '(.auths[]?.auth) |= "REDACTED"' "$file"
+            echo ""
+          done
+
+  scope-ghcr-repo:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os:
+          - ubuntu-latest
+          - windows-latest
+    steps:
+      -
+        name: Checkout
+        uses: actions/checkout@v6
+      -
+        name: Login to GitHub Container Registry
+        uses: ./
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+          scope: 'docker/login-action@push'
+      -
+        name: Print config.json files
+        shell: bash
+        run: |
+          shopt -s globstar nullglob
+          for file in ~/.docker/**/config.json; do
+            echo "## ${file}"
+            jq '(.auths[]?.auth) |= "REDACTED"' "$file"
+            echo ""
+          done

README.md

@@ -25,6 +25,7 @@ ___
   * [Quay.io](#quayio)
   * [DigitalOcean](#digitalocean-container-registry)
   * [Authenticate to multiple registries](#authenticate-to-multiple-registries)
+  * [Set scopes for the authentication token](#set-scopes-for-the-authentication-token)
 * [Customizing](#customizing)
   * [inputs](#inputs)
 * [Contributing](#contributing)
@@ -527,8 +528,8 @@ jobs:
 ```
 
 You can also use the `registry-auth` input for raw authentication to
-registries, defined as YAML objects. Each object can contain `registry`,
-`username`, `password` and `ecr` keys similar to current inputs:
+registries, defined as YAML objects. Each object have the same attributes as
+current inputs (except `logout`):
 
 > [!WARNING]
 > We don't recommend using this method, it's better to use the action multiple
@@ -557,6 +558,60 @@ jobs:
               password: ${{ secrets.GITHUB_TOKEN }}
 ```
 
+### Set scopes for the authentication token
+
+The `scope` input allows limiting registry credentials to a specific repository
+or namespace scope when building images with Buildx.
+
+This is useful in GitHub Actions to avoid overriding the Docker Hub
+authentication token embedded in GitHub-hosted runners, which is used for
+pulling images without rate limits. By scoping credentials, you can
+authenticate only where needed (typically for pushing), while keeping
+unauthenticated pulls for base images.
+
+When `scope` is set, credentials are written to the Buildx configuration
+instead of the global Docker configuration. This means:
+* Authentication applies only to the specified scope
+* The default Docker Hub credentials remain available for pulls
+* Credentials are used only by Buildx during the build
+
+> [!IMPORTANT]
+> Credentials written to the Buildx configuration are only accessible by Buildx.
+> They are not available to `docker pull`, `docker push`, or any other Docker
+> CLI commands outside Buildx.
+
+> [!NOTE]
+> This feature requires Buildx version 0.31.0 or later.
+
+```yaml
+name: ci
+
+on:
+  push:
+    branches: main
+
+jobs:
+  login:
+    runs-on: ubuntu-latest
+    steps:
+      -
+        name: Login to Docker Hub (scoped)
+        uses: docker/login-action@v3
+        with:
+          username: ${{ vars.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          scope: 'myorg/myimage@push'
+      -
+        name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          push: true
+          tags: myorg/myimage:latest
+```
+
+In this example, base images are pulled using the embedded GitHub-hosted runner
+credentials, while authenticated access is used only to push `myorg/myimage`.
+
 ## Customizing
 
 ### inputs
@@ -568,13 +623,13 @@ The following inputs can be used as `step.with` keys:
 | `registry`      | String | `docker.io` | Server address of Docker registry. If not set then will default to Docker Hub |
 | `username`      | String |             | Username for authenticating to the Docker registry                            |
 | `password`      | String |             | Password or personal access token for authenticating the Docker registry      |
+| `scope`         | String |             | Scope for the authentication token                                            |
 | `ecr`           | String | `auto`      | Specifies whether the given registry is ECR (`auto`, `true` or `false`)       |
 | `logout`        | Bool   | `true`      | Log out from the Docker registry at the end of a job                          |
 | `registry-auth` | YAML   |             | Raw authentication to registries, defined as YAML objects                     |
 
 > [!NOTE]
-> The `registry-auth` input is mutually exclusive with `registry`, `username`,
-> `password` and `ecr` inputs.
+> The `registry-auth` input cannot be used with other inputs except `logout`.
 
 ## Contributing
 

__tests__/docker.test.ts

@@ -50,7 +50,7 @@ test('logout calls exec', async () => {
 
   const registry = 'https://ghcr.io';
 
-  await logout(registry);
+  await logout(registry, '');
 
   expect(execSpy).toHaveBeenCalledTimes(1);
   const callfunc = execSpy.mock.calls[0];

action.yml

@@ -19,6 +19,9 @@ inputs:
   ecr:
     description: 'Specifies whether the given registry is ECR (auto, true or false)'
     required: false
+  scope:
+    description: 'Scope for the authentication token'
+    required: false
   logout:
     description: 'Log out from the Docker registry at the end of a job'
     default: 'true'

dist/index.js

@@ -1,21 +1,90 @@
+import path from 'path';
 import * as core from '@actions/core';
+import * as yaml from 'js-yaml';
+
+import {Buildx} from '@docker/actions-toolkit/lib/buildx/buildx';
+import {Util} from '@docker/actions-toolkit/lib/util';
 
 export interface Inputs {
   registry: string;
   username: string;
   password: string;
+  scope: string;
   ecr: string;
   logout: boolean;
   registryAuth: string;
 }
 
+export interface Auth {
+  registry: string;
+  username: string;
+  password: string;
+  scope: string;
+  ecr: string;
+  configDir: string;
+}
+
 export function getInputs(): Inputs {
   return {
     registry: core.getInput('registry'),
     username: core.getInput('username'),
     password: core.getInput('password'),
+    scope: core.getInput('scope'),
     ecr: core.getInput('ecr'),
     logout: core.getBooleanInput('logout'),
     registryAuth: core.getInput('registry-auth')
   };
 }
+
+export function getAuthList(inputs: Inputs): Array<Auth> {
+  if (inputs.registryAuth && (inputs.registry || inputs.username || inputs.password || inputs.scope || inputs.ecr)) {
+    throw new Error('Cannot use registry-auth with other inputs');
+  }
+  let auths: Array<Auth> = [];
+  if (!inputs.registryAuth) {
+    auths.push({
+      registry: inputs.registry || 'docker.io',
+      username: inputs.username,
+      password: inputs.password,
+      scope: inputs.scope,
+      ecr: inputs.ecr || 'auto',
+      configDir: scopeToConfigDir(inputs.registry, inputs.scope)
+    });
+  } else {
+    auths = (yaml.load(inputs.registryAuth) as Array<Auth>).map(auth => {
+      core.setSecret(auth.password); // redacted in workflow logs
+      return {
+        registry: auth.registry || 'docker.io',
+        username: auth.username,
+        password: auth.password,
+        scope: auth.scope,
+        ecr: auth.ecr || 'auto',
+        configDir: scopeToConfigDir(auth.registry || 'docker.io', auth.scope)
+      };
+    });
+  }
+  if (auths.length == 0) {
+    throw new Error('No registry to login');
+  }
+  return auths;
+}
+
+export function scopeToConfigDir(registry: string, scope?: string): string {
+  if (scopeDisabled() || !scope || scope === '') {
+    return '';
+  }
+  let configDir = path.join(Buildx.configDir, 'config', registry === 'docker.io' ? 'registry-1.docker.io' : registry);
+  if (scope.startsWith('@')) {
+    configDir += scope;
+  } else {
+    configDir = path.join(configDir, scope);
+  }
+  return configDir;
+}
+
+function scopeDisabled(): boolean {
+  if (process.env.DOCKER_LOGIN_SCOPE_DISABLED) {
+    return Util.parseBool(process.env.DOCKER_LOGIN_SCOPE_DISABLED);
+  }
+  return false;
+}