Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.serval.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The DockerHub integration lets you automate routine container-registry work against Docker Hub. Connect Serval to DockerHub to audit images across your namespace, prune stale tags, keep repository metadata in sync, and weave Docker Hub state into broader IT and security workflows.

Key Features

  • List repositories in a user or organization namespace
  • List and filter image tags
  • Update repository descriptions
  • Delete stale or unused tags
  • Look up user and organization metadata

Common Use Cases

  • Scheduled cleanup of tags older than a retention window
  • On-call audit of repositories pushed in the last 24 hours
  • Bulk-update repository descriptions during a rebrand
  • Surface DockerHub state in tickets and approval flows

​
Prerequisites

1

Docker Hub account

An active Docker Hub account that owns or has access to the repositories you want to automate.
2

Personal Access Token (PAT)

Docker Hub does not expose third-party OAuth, so authentication is via a Personal Access Token created under your Docker Hub account settings.
3

Namespace decision

Decide whether you’ll connect a personal namespace or an organization namespace. For organization automation, create the PAT from a service account user that has been added to the org with the appropriate role.

​
Setup Instructions

​
Step 1: Generate a Personal Access Token

1

Open token settings

Log in to Docker Hub, open the avatar menu, and go to Account Settings → Personal access tokens.
2

Create a new token

Click Generate new token. Give it a clear description (for example, “Serval integration — production”) so it can be identified later.
3

Choose the access scope

Pick the smallest scope that satisfies your workflows:
  • Public Repo Read — list public repositories and tags only.
  • Public Repo Read & Write — also push and update public repos.
  • Read-only (Repo Read) — list private repos, list tags, view image metadata.
  • Read & Write (Repo Read & Write) — recommended default. Includes everything in Read-only, plus updates to repository descriptions.
  • Public Repo Admin — full administration of repos in the namespace, including delete.
For destructive automation (deleting tags or repos), use a separate PAT with the elevated scope and gate the workflow on an approval procedure.
4

Copy the token

Click Generate, copy the token value, and store it somewhere secure for the next step. Docker Hub will not show it again.

​
Step 2: Configure the integration in Serval

  1. Navigate to the Integrations page in Serval.
  2. Find DockerHub and click Configure.
  3. Enter your configuration details.
​
username
string
required
The Docker Hub username that owns the Personal Access Token. This is also the default namespace for repository operations in workflows.
​
personalAccessToken
string
required
The Personal Access Token from Step 1. Serval stores this encrypted and never exposes it to workflow code.
​
instanceName
string
required
A friendly label to distinguish this connection from others (for example, Production, Build Bot, or Org Audit). Required when you have multiple Docker Hub connections on the same team.
  1. Click Submit to establish the integration.
Integration configured. Serval will perform a healthcheck by exchanging the PAT for a bearer token and calling GET /v2/user/.

​
How authentication works

Docker Hub does not accept a Personal Access Token directly as a bearer token — calls return 403 token issued from personal access token is not allowed. Behind the scenes, Serval exchanges your username and PAT at POST hub.docker.com/v2/users/login for a short-lived JWT, caches that JWT in the proxy until shortly before its expiry, and refreshes it automatically.Your workflows never need to handle this. Just call apiRequest.

​
API surface

All paths use the canonical /v2/namespaces/{namespace}/... form from Docker Hub’s public OpenAPI spec. The older /v2/repositories/{namespace}/... paths are deprecated and now reject PAT-derived JWTs with 403 token issued from personal access token is not allowed.
All require Public Repo Read or Repo:Read scope.
  • GET /v2/namespaces/{namespace}/repositories — list repositories in a namespace, with page, page_size, name, and ordering query parameters
  • GET /v2/namespaces/{namespace}/repositories/{repository} — repository details
  • GET /v2/namespaces/{namespace}/repositories/{repository}/tags — list tags
  • GET /v2/namespaces/{namespace}/repositories/{repository}/tags/{tag} — get a specific tag
Granting and revoking a team’s access to a repository lives on the PAT-allowed surface despite the team semantics (Docker Hub’s spec intentionally keeps this endpoint PAT-callable):
  • POST /v2/repositories/{namespace}/{repository}/groups — grant a team access. Body: { group_id, permission: "read" | "write" | "admin" }. Resolve group_id via the DockerHub Organization integration first.
Identifying the connected user does not require an API call. The configured username is captured at install time and exposed in the workflow context as ctx.integrations.dockerhub.username. /v2/user/ no longer exists in the current Hub API.

​
What this integration cannot do

These endpoints are explicitly marked OAT-only in Docker Hub’s spec. Calls from this integration will return 403 token issued from personal access token is not allowed — use the DockerHub Organization integration instead:
  • List or search org members
  • Create, update, or delete teams (groups)
  • Add or remove members from teams
  • List or cancel invites
  • Read or list audit logs
Other constraints to be aware of:
  • PAT-derived tokens cannot manage other tokens. /v2/access-tokens rejects PAT-issued JWTs.
  • SSO-enabled organizations cannot rotate PATs through the API. PATs must be rotated manually in the Docker Hub UI until Docker addresses this. Reference: docker/hub-feedback#2514.
  • Repository description updates and tag deletes are not in the current public spec. They may still work via deprecated /v2/repositories/... paths in some configurations, but treat the typed schema in sdk/spec/schema.ts as the source of truth.
  • Container pull/push (registry-1.docker.io) is not part of this integration. That surface uses a different token flow and is out of scope.

​
Best Practices

Use a dedicated service account. Create a Docker Hub user solely for Serval automation, add it to your organization with the minimum role needed, and generate the PAT under that account. This decouples integration access from any individual employee.
Rotate PATs on a schedule. Set a calendar reminder to regenerate the PAT periodically and update the configuration in Serval — there is no expiration enforced by Docker Hub itself.
Never put PATs in workflow code. Workflow code talks to Docker Hub through Serval’s proxy by integration ID. If a workflow tries to set its own Authorization header, the proxy will replace it with the integration’s bearer token.

​
Additional Resources

Docker Hub API reference

Complete reference for the Hub REST API.

Personal access tokens

Docker’s documentation on creating, scoping, and rotating PATs.
Need help? Contact support@serval.com for assistance with your DockerHub integration.