Skip to main content

​
About DockerHub

The DockerHub integration connects Serval to Docker Hub, the container image registry. Once connected with a Docker Hub username and a Personal Access Token (PAT), Serval can list the repositories in your namespace, read repository details, browse and inspect image tags, and grant a team access to a repository. The username you configure is stored with the connection itself, so Serval always knows which namespace it is working with. Organization management (members, teams, invites) is handled by the separate DockerHub Organization integration. Authentication: Username + Personal Access Token (PAT). Docker Hub does not accept a raw PAT on API calls, so Serval automatically exchanges your username and PAT for a short-lived access token and refreshes it just before it expires. Your PAT is stored encrypted and is never exposed to workflows. Data sync: On-demand only. There is no background sync or data ingestion - Serval calls Docker Hub live whenever a workflow or health check needs it.

​
What the DockerHub integration enables

CapabilityDescription
List repositories in a namespaceBrowse the repositories in your connected namespace, with optional filtering by name and sorting by name, last updated, or pull count, in ascending or descending order. Results are paginated (10 per page by default, up to 100).
Get repository detailsRead full repository metadata, including your permission level (read, write, or admin), the full description, collaborator count, and immutable-tags settings.
List tags for a repositoryPage through a repository’s image tags, including per-architecture image entries, sizes, digests, and last pulled and pushed timestamps.
Get a specific tagLook up a single tag and see its status, full size, digest, and image details.
Grant a team access to a repositoryGive one of your organization’s teams read, write, or admin access to a repository. Look the team up through the DockerHub Organization integration first.
These operations follow the official Docker Hub API. Endpoints that require an Organization Access Token (members, teams, invites) are deliberately excluded from this integration and live in the DockerHub Organization integration.

​
Get your credentials

You need a Docker Hub Personal Access Token created under the account whose username you will enter in Serval. Ideally this is a dedicated service account added to your organization with the minimum role needed. See the official Docker Hub personal access tokens guide for details.
1

Log in to Docker Hub

Go to Docker Hub, sign in, and select your avatar in the top-right corner.
2

Open the token settings

From the avatar drop-down menu select Account settings, then select Personal access tokens.
3

Generate a new token

Select Generate new token and give it a recognizable description (for example, “Serval integration - production”).
4

Set the expiration date and access permissions

Docker Hub asks for an expiration date and the token’s access permissions (Read, Write, or Delete). Read access is enough for browsing repositories and tags; include Write if your workflows will grant teams access to repositories. These three names are the only ones Docker Hub shows at this screen; where scope names like Public Repo Read, Read & Write, or Repo:Read appear elsewhere on this page, choose Read to cover the read scopes and add Write to cover Read & Write.
5

Copy the token

Select Generate and copy the token immediately - Docker Hub will not show it again.
Docker Hub shows the token only once, at creation. If you navigate away before copying it, you will need to generate a new one.
Create the token under a dedicated service account where possible, and grant that account the minimum role it needs in your organization. The token only works for the account that created it, so the username you enter in Serval must match.

​
Connect in Serval

1

Open the DockerHub integration in Serval

Find DockerHub in Serval’s integrations and start a new connection.
2

Enter the Username (required)

The DockerHub username that owns the Personal Access Token. This is also the default namespace for repository operations. Leading and trailing spaces are removed automatically. Leaving it blank stops submission with “This field is required”; a value of only spaces is rejected by Serval with an error that includes “Username is required.”
3

Enter the Personal Access Token (required)

Paste the token you copied from Docker Hub. The field’s helper text notes that it requires at least the Public Repo Read scope; use Read & Write for full repository management. Submitting without a token is rejected by Serval with an error that includes “Personal Access Token is required.”
4

Enter an Instance Name (required)

A name to identify this DockerHub connection (for example, “Production” or “Build Bot”). It is required to distinguish between multiple DockerHub connections on the same team and is shown as the connection’s display name. Leaving it blank stops submission with “This field is required”; a value of only spaces is rejected by Serval with an error that includes “Instance Name is required to distinguish multiple DockerHub connections.”
5

Save the connection

Save, then run the health checks below to confirm everything works.
When editing an existing connection, Username and Instance Name come pre-filled and the Personal Access Token appears as an obfuscated value (bullets plus its last 4 characters) with a Replace button. Leave the token untouched and the stored value is kept, so you can rename the connection without re-entering the token. Any field that reaches Serval empty keeps its current stored value; if no value can be determined for a required field, the update is rejected with an error that includes “Username, Personal Access Token, and Instance Name are required.”

​
Verifying the connection

When the connection is created, Serval verifies it by listing the repositories in your namespace. The integration also ships three named health checks you can run at any time. Validate DockerHub API Connection - confirms your stored credentials can be exchanged for a working access token by listing your namespace’s repositories.
  • Success: Successfully authenticated with DockerHub as “[username]” ([number] repositories in namespace).
  • Failure: Unable to authenticate with DockerHub. Verify the username and Personal Access Token, and confirm the PAT has not been revoked. If the error message mentions token issued from personal access token is not allowed, the endpoint being called requires an Organization Access Token (OAT) — use the dockerhub-org integration for those operations.
List DockerHub Repositories - confirms the token can list repositories in your configured namespace and reports the total count plus up to five repository names.
  • Success: Successfully listed repositories in the [username] namespace ([number] total).
  • Failure: Unable to list DockerHub repositories. Ensure the Personal Access Token has at least the Public Repo Read scope, and that the configured username matches a real DockerHub namespace.
Verify DockerHub Tag Access - fetches one tag from the first repository in your namespace to confirm the deeper tag-level lookups workflows rely on are reachable. If the namespace has no repositories yet, the check still passes with: Namespace “[username]” has no repositories yet; tag-access check skipped.
  • Success: Successfully fetched tag listing for “[namespace]/[repository]” ([number] tags).
  • Failure: Unable to fetch tag listings. This typically indicates the PAT lacks Repo:Read scope, or the repository in the namespace is private and the PAT does not have access to it.
If all three checks are green but a workflow step that manages organization members, teams, or invites fails with “token issued from personal access token is not allowed”, that is expected: those operations need the DockerHub Organization integration, not this one.

​
Gotchas and troubleshooting

Listing or searching organization members, creating or deleting teams, adding or removing team members, and managing invites all require an Organization Access Token and fail here with “token issued from personal access token is not allowed”. Use the DockerHub Organization integration for those operations.
Docker Hub does not accept a raw PAT for API calls, so Serval automatically exchanges your username and token for a short-lived access token behind the scenes - you never need to manage tokens yourself. If you still see this error, the operation either requires an Organization Access Token (see above) or is using an older, deprecated style of Docker Hub endpoint that no longer accepts PAT-based access. The one deliberate exception on the older endpoint style is granting a team access to a repository, which still works with a PAT and is supported by this integration.
On the edit form, the Personal Access Token is shown obfuscated with a Replace button, and any field that reaches Serval empty keeps its stored value. This means you can safely change just the Instance Name without re-entering the token. To rotate the PAT, click Replace and paste the full new token.
The Verify DockerHub Tag Access check reports success when the namespace has no repositories (“…has no repositories yet; tag-access check skipped.”). Until at least one repository exists in the namespace, a green result there does not confirm tag-level access.
Neither operation is part of the API surface this integration supports. An earlier version of this page listed both as features; they are not supported.
This integration only talks to Docker Hub’s management interface at hub.docker.com. Actually pulling or pushing container images uses a different system with its own authentication and is not part of this integration.
Docker Hub lets you set an expiration date when you create a token, and SSO-enabled organizations cannot rotate PATs through the API as of this writing - rotation is done manually in the Docker Hub UI. Set a rotation schedule, generate the new token in Docker Hub, then edit the Serval connection, click Replace on the token field, and paste the new token.
Need help? Contact support@serval.com for assistance with your DockerHub integration.