Skip to main content
Container Registry credentials enable pipelines to push built images and pull base images from private registries. Configure credentials for Docker Hub, GitHub Container Registry, GitLab Registry, or any Docker-compatible registry.

​
Key Concepts

Registry

A container image storage service identified by its URL (e.g., ghcr.io, docker.io).

Credentials

Username and password/token used to authenticate with the registry.

Push

Upload built container images to the registry during CI/CD pipelines.

Pull

Download base images from private registries during container builds.

​
Required Permissions

ActionPermission
View registriesiam:project:cicd:registry:read
Create registriesiam:project:cicd:registry:write
Edit registriesiam:project:cicd:registry:write
Delete registriesiam:project:cicd:registry:delete

​
Common Registries

RegistryURLUsername
Docker Hubdocker.io or index.docker.ioDocker Hub username
GitHub Container Registryghcr.ioGitHub username
GitLab Container Registryregistry.gitlab.comGitLab username
Google Container Registrygcr.io_json_key
Amazon ECR<account>.dkr.ecr.<region>.amazonaws.comAWS
Azure Container Registry<name>.azurecr.ioService principal ID

​
How to Add a Registry

1

Click Add Registry

Click the Add Registry button in the header.
2

Enter Registry URL

Provide the registry hostname (e.g., ghcr.io, docker.io, registry.acme.com).
3

Enter Username

Provide the username for authentication.
4

Enter Password

Enter the password, access token, or service account key.
5

Enter Email (Optional)

Some registries require an email address for authentication.
6

Create

Click Add Registry to save the credentials.
Registry URL cannot be changed after creation. To use a different URL, delete and recreate the registry entry.

​
How to Edit a Registry

1

Find the Registry

Locate the registry in the list using search.
2

Click Edit

Click the edit (pencil) icon on the registry row.
3

Update Credentials

Modify username or email. Leave password blank to keep the existing value.
4

Save

Click Save Changes to apply updates.
When rotating credentials, enter the new password. Leave it blank only if you want to keep the existing password.

​
How to Delete a Registry

1

Find the Registry

Locate the registry to delete.
2

Click Delete

Click the delete (trash) icon.
3

Confirm

Confirm the deletion. This action cannot be undone.
Deleting registry credentials will cause pipelines using that registry to fail. Update pipeline configurations before deleting.

​
Registry-Specific Configuration

​
Docker Hub

FieldValue
Registry URLdocker.io or index.docker.io
UsernameYour Docker Hub username
PasswordDocker Hub access token (recommended) or password
Create an access token at Docker Hub → Account Settings → Security → Access Tokens.

​
GitHub Container Registry (ghcr.io)

FieldValue
Registry URLghcr.io
UsernameYour GitHub username
PasswordPersonal access token with write:packages scope
Create a PAT at GitHub → Settings → Developer settings → Personal access tokens.

​
GitLab Container Registry

FieldValue
Registry URLregistry.gitlab.com
UsernameYour GitLab username
PasswordPersonal access token with read_registry and write_registry scopes

​
Google Container Registry (GCR)

FieldValue
Registry URLgcr.io, us.gcr.io, eu.gcr.io, or asia.gcr.io
Username_json_key
PasswordService account JSON key (entire file contents)

​
Amazon ECR

FieldValue
Registry URL<account-id>.dkr.ecr.<region>.amazonaws.com
UsernameAWS
PasswordECR authorization token (expires every 12 hours)
Amazon ECR tokens expire every 12 hours. Consider using ECR credential helpers in your pipeline instead of static credentials.

​
Azure Container Registry

FieldValue
Registry URL<registry-name>.azurecr.io
UsernameService principal application ID or admin username
PasswordService principal password or admin password

​
Private/Self-Hosted Registries

FieldValue
Registry URLYour registry hostname (e.g., registry.example.com:5000)
UsernameRegistry username
PasswordRegistry password
Include the port if not using default (443 for HTTPS, 80 for HTTP).

​
Troubleshooting

  • Verify username is correct
  • Check if password/token has expired
  • Ensure token has required permissions (push/pull)
  • For Docker Hub, use access token instead of password
  • Verify registry credentials have write access
  • Check if the repository exists (some registries require pre-creation)
  • Ensure image tag follows registry naming conventions
  • Verify network connectivity to the registry
  • Verify credentials have read access
  • Check if the image exists in the registry
  • Ensure the image tag is correct
  • For private images, verify authentication is working
  • Use the correct hostname format
  • For Docker Hub, use docker.io not hub.docker.com
  • Include port number if using non-standard ports
  • Ensure HTTPS is supported by the registry
  • Edit the registry and enter a new password/token
  • For ECR, regenerate the authorization token
  • Check token expiration policies for your registry
  • Verify you have delete permission
  • Check if pipelines are actively using the registry
  • Try refreshing the page

​
FAQ

No. Each registry URL requires its own credential entry. Even if the same username/password works, you need separate entries for each registry hostname.
Yes. All passwords and tokens are encrypted at rest in the database. They are decrypted only when needed for registry operations.
Edit the registry entry and enter the new password. The old password is replaced immediately. Ensure all pipelines complete before rotating.
No. Container registries use username/password or token-based authentication. SSH keys are not supported for registry access.
Docker Hub now requires access tokens for automated systems. Create a token at Docker Hub → Account Settings → Security → Access Tokens.
ECR tokens expire every 12 hours. For CI/CD pipelines, use AWS credential helpers or generate tokens dynamically in your pipeline scripts.
Self-signed certificates may require additional pipeline configuration. Contact your administrator to configure trust for your registry’s CA.
Yes. Many registries support robot accounts (Harbor, Quay) or service accounts (GCR, ACR) for CI/CD. These are recommended over personal accounts.

​
Best Practices

​
Security

  • Use access tokens instead of passwords when available
  • Create dedicated CI/CD accounts or robot accounts
  • Use tokens with minimum required permissions (read-only where possible)
  • Rotate credentials regularly
  • Never share registry credentials between environments

​
Organization

  • Use descriptive names for easy identification
  • Document which pipelines use each registry
  • Keep credentials updated when team members change
  • Remove unused registry entries

​
Token Management

  • Set calendar reminders for token rotation
  • Use long-lived tokens for CI/CD where supported
  • Test authentication after credential rotation
  • Monitor for authentication failures in pipeline logs

​
Multi-Registry Setup

For organizations using multiple registries: 
docker.io          → Public base images
ghcr.io            → Team packages
registry.acme.com  → Production images
This allows:
  • Different access levels per registry
  • Separation of public and private images
  • Independent credential rotation schedules