> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shiftlabs.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Registry

> Manage container registry credentials for pushing and pulling images

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

<CardGroup cols={2}>
  <Card title="Registry" icon="server">
    A container image storage service identified by its URL (e.g., ghcr.io, docker.io).
  </Card>

  <Card title="Credentials" icon="key">
    Username and password/token used to authenticate with the registry.
  </Card>

  <Card title="Push" icon="upload">
    Upload built container images to the registry during CI/CD pipelines.
  </Card>

  <Card title="Pull" icon="download">
    Download base images from private registries during container builds.
  </Card>
</CardGroup>

## Required Permissions

| Action            | Permission                         |
| ----------------- | ---------------------------------- |
| View registries   | `iam:project:cicd:registry:read`   |
| Create registries | `iam:project:cicd:registry:write`  |
| Edit registries   | `iam:project:cicd:registry:write`  |
| Delete registries | `iam:project:cicd:registry:delete` |

## Common Registries

| Registry                      | URL                                        | Username             |
| ----------------------------- | ------------------------------------------ | -------------------- |
| **Docker Hub**                | `docker.io` or `index.docker.io`           | Docker Hub username  |
| **GitHub Container Registry** | `ghcr.io`                                  | GitHub username      |
| **GitLab Container Registry** | `registry.gitlab.com`                      | GitLab username      |
| **Google Container Registry** | `gcr.io`                                   | `_json_key`          |
| **Amazon ECR**                | `<account>.dkr.ecr.<region>.amazonaws.com` | `AWS`                |
| **Azure Container Registry**  | `<name>.azurecr.io`                        | Service principal ID |

## How to Add a Registry

<Steps>
  <Step title="Click Add Registry">
    Click the **Add Registry** button in the header.
  </Step>

  <Step title="Enter Registry URL">
    Provide the registry hostname (e.g., `ghcr.io`, `docker.io`, `registry.acme.com`).
  </Step>

  <Step title="Enter Username">
    Provide the username for authentication.
  </Step>

  <Step title="Enter Password">
    Enter the password, access token, or service account key.
  </Step>

  <Step title="Enter Email (Optional)">
    Some registries require an email address for authentication.
  </Step>

  <Step title="Create">
    Click **Add Registry** to save the credentials.
  </Step>
</Steps>

<Info>
  Registry URL cannot be changed after creation. To use a different URL, delete and recreate the registry entry.
</Info>

## How to Edit a Registry

<Steps>
  <Step title="Find the Registry">
    Locate the registry in the list using search.
  </Step>

  <Step title="Click Edit">
    Click the edit (pencil) icon on the registry row.
  </Step>

  <Step title="Update Credentials">
    Modify username or email. Leave password blank to keep the existing value.
  </Step>

  <Step title="Save">
    Click **Save Changes** to apply updates.
  </Step>
</Steps>

<Tip>
  When rotating credentials, enter the new password. Leave it blank only if you want to keep the existing password.
</Tip>

## How to Delete a Registry

<Steps>
  <Step title="Find the Registry">
    Locate the registry to delete.
  </Step>

  <Step title="Click Delete">
    Click the delete (trash) icon.
  </Step>

  <Step title="Confirm">
    Confirm the deletion. This action cannot be undone.
  </Step>
</Steps>

<Warning>
  Deleting registry credentials will cause pipelines using that registry to fail. Update pipeline configurations before deleting.
</Warning>

## Registry-Specific Configuration

### Docker Hub

| Field            | Value                                             |
| ---------------- | ------------------------------------------------- |
| **Registry URL** | `docker.io` or `index.docker.io`                  |
| **Username**     | Your Docker Hub username                          |
| **Password**     | Docker Hub access token (recommended) or password |

Create an access token at Docker Hub → Account Settings → Security → Access Tokens.

### GitHub Container Registry (ghcr.io)

| Field            | Value                                             |
| ---------------- | ------------------------------------------------- |
| **Registry URL** | `ghcr.io`                                         |
| **Username**     | Your GitHub username                              |
| **Password**     | Personal access token with `write:packages` scope |

Create a PAT at GitHub → Settings → Developer settings → Personal access tokens.

### GitLab Container Registry

| Field            | Value                                                                  |
| ---------------- | ---------------------------------------------------------------------- |
| **Registry URL** | `registry.gitlab.com`                                                  |
| **Username**     | Your GitLab username                                                   |
| **Password**     | Personal access token with `read_registry` and `write_registry` scopes |

### Google Container Registry (GCR)

| Field            | Value                                                |
| ---------------- | ---------------------------------------------------- |
| **Registry URL** | `gcr.io`, `us.gcr.io`, `eu.gcr.io`, or `asia.gcr.io` |
| **Username**     | `_json_key`                                          |
| **Password**     | Service account JSON key (entire file contents)      |

### Amazon ECR

| Field            | Value                                            |
| ---------------- | ------------------------------------------------ |
| **Registry URL** | `<account-id>.dkr.ecr.<region>.amazonaws.com`    |
| **Username**     | `AWS`                                            |
| **Password**     | ECR authorization token (expires every 12 hours) |

<Warning>
  Amazon ECR tokens expire every 12 hours. Consider using ECR credential helpers in your pipeline instead of static credentials.
</Warning>

### Azure Container Registry

| Field            | Value                                              |
| ---------------- | -------------------------------------------------- |
| **Registry URL** | `<registry-name>.azurecr.io`                       |
| **Username**     | Service principal application ID or admin username |
| **Password**     | Service principal password or admin password       |

### Private/Self-Hosted Registries

| Field            | Value                                                      |
| ---------------- | ---------------------------------------------------------- |
| **Registry URL** | Your registry hostname (e.g., `registry.example.com:5000`) |
| **Username**     | Registry username                                          |
| **Password**     | Registry password                                          |

Include the port if not using default (443 for HTTPS, 80 for HTTP).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Authentication failed" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot push images" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Cannot pull images" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Registry URL not recognized" icon="circle-question">
    * 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
  </Accordion>

  <Accordion title="Token expired" icon="circle-question">
    * Edit the registry and enter a new password/token
    * For ECR, regenerate the authorization token
    * Check token expiration policies for your registry
  </Accordion>

  <Accordion title="Cannot delete registry" icon="circle-question">
    * Verify you have delete permission
    * Check if pipelines are actively using the registry
    * Try refreshing the page
  </Accordion>
</AccordionGroup>

## FAQ

<AccordionGroup>
  <Accordion title="Can I use the same credentials for multiple registries?">
    No. Each registry URL requires its own credential entry. Even if the same username/password works, you need separate entries for each registry hostname.
  </Accordion>

  <Accordion title="Are passwords encrypted?">
    Yes. All passwords and tokens are encrypted at rest in the database. They are decrypted only when needed for registry operations.
  </Accordion>

  <Accordion title="How do I rotate registry credentials?">
    Edit the registry entry and enter the new password. The old password is replaced immediately. Ensure all pipelines complete before rotating.
  </Accordion>

  <Accordion title="Can I use SSH keys for registry authentication?">
    No. Container registries use username/password or token-based authentication. SSH keys are not supported for registry access.
  </Accordion>

  <Accordion title="Why is Docker Hub requiring an access token?">
    Docker Hub now requires access tokens for automated systems. Create a token at Docker Hub → Account Settings → Security → Access Tokens.
  </Accordion>

  <Accordion title="How do I handle ECR token expiration?">
    ECR tokens expire every 12 hours. For CI/CD pipelines, use AWS credential helpers or generate tokens dynamically in your pipeline scripts.
  </Accordion>

  <Accordion title="What if my registry uses a self-signed certificate?">
    Self-signed certificates may require additional pipeline configuration. Contact your administrator to configure trust for your registry's CA.
  </Accordion>

  <Accordion title="Can I use robot accounts or service accounts?">
    Yes. Many registries support robot accounts (Harbor, Quay) or service accounts (GCR, ACR) for CI/CD. These are recommended over personal accounts.
  </Accordion>
</AccordionGroup>

## 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