# Depot Registry Get started with the Depot Registry to store container builds, images or any other OCI-compliant artifacts. ## Install the Depot CLI Install the [Depot CLI](/content/docs/cli/reference/overview/index.html) on your machine to work with Depot Registry from your terminal. - **macOS** ``` brew install depot/tap/depot ``` - **Linux** ``` curl -L https://depot.dev/install-cli.sh | sh ``` - **All platforms** Download the binary file for your platform from the [Depot CLI releases page](https://github.com/depot/cli/releases) in GitHub. ## Authenticate to the registry Each Depot organization has its own registry subdomain: ``` {orgId}.registry.depot.dev ``` You can copy your org ID from the sidebar in the [Depot dashboard](/content/orgs/index.html) or run `depot org list` in your terminal. Use a registry access token to choose which repositories you can push to or pull from. Follow the steps below to create one. For other credentials and their scope, see [Authentication and permissions](/content/docs/registry/overview#authentication-and-permissions/index.html). ### Create a registry access token You must be an organization owner to create a registry access token in the dashboard. Registry access tokens are separate from the project-scoped tokens generated by `depot pull-token`. They can grant access to any repository names you select within the organization. 1. Open [Registry settings](/content/orgs/_/settings/registry/index.html). 2. Under **Registry access tokens**, click **Add access token**. 3. Enter a **Name** for the token. 4. Set **Permission** to **Push** to push and pull images, or **Pull** for pull-only access. 5. Choose an **Expiration**: 30, 60, or 90 days, one year, or **No expiration**. 6. In **Repository scopes**, enter the Depot repository names, separated by commas. For example, enter `your/app` for the push and pull examples below, or the name of your pull-through repository. 7. Click **Create access token**. 8. Copy the token and save it securely. Depot shows the token value only once. ### Log in with Docker Set the username to `x-token` and enter your token at the password prompt: ``` docker login {orgId}.registry.depot.dev -u x-token ``` For `depot pull` and `depot push`, the Depot CLI uses your existing CLI credentials to authenticate and `docker login` isn't required. ## Push images to the registry There are two ways to get images into Depot Registry: push an existing image with Docker, or save a build directly from `depot build`. ### With `docker push` Tag the image with your org subdomain and the repository name and tag you want, then push: ``` docker tag {orgId}.registry.depot.dev/your/app:v1 docker push {orgId}.registry.depot.dev/your/app:v1 ``` Repositories are created automatically on first push. For a workflow example, see [Push an image from Depot CI](/content/docs/container-builds/integrations/depot-ci#push-an-image-to-a-specific-registry-address/index.html). ### With `depot build` Save build output directly to the registry using the `--save` flag: ``` depot build --save --save-tag my-image . ``` The `--save-tag` flag is optional but useful for referencing the image by name instead of build ID. ## Pull images from the registry ### With `docker pull` Make sure you've [authenticated](/content/docs/registry/quickstart#authenticate-to-the-registry/index.html) with `docker login`, then pull using the full image reference: ``` docker pull {orgId}.registry.depot.dev/your/app:v1 ``` ### With `depot pull` The CLI authenticates with your existing Depot credentials so `docker login` isn't required. Specify a build ID or tag: ``` depot pull --project depot pull --project my-image ``` Omit the build ID or tag to display an interactive list of builds to choose from. ### With Kubernetes Create an image pull secret with a registry access token that has **Pull** permission for your repository: ``` kubectl create secret docker-registry regcred \ --docker-server={orgId}.registry.depot.dev \ --docker-username=x-token \ --docker-password= ``` Then reference the secret in your pod spec using `imagePullSecrets`. ## Manage registry access tokens ### Choose repository scopes Scopes match repository names within your organization. Don't include the registry hostname or an image tag. | Scope | Access | |-------------|---------------------------------------------------| | `frontend` | The `frontend` repository. | | `team/*` | Repositories one level below `team`, such as `team/api`. | | `team/**` | Repositories at any depth below `team`, such as `team/api` and `team/services/api`. | | `**` | All repositories in the organization. | Separate multiple scopes with commas. The token's permission applies to every scope. Create separate tokens if you need pull-only access to one repository and push access to another. ### Revoke a registry access token Organization owners can view and revoke tokens under **Registry access tokens** in [Registry settings](/content/orgs/_/settings/registry/index.html). Open the token's three-dot menu and select **Revoke**. To change a token's scopes or replace a lost token, create a new token, update the clients that use it, and revoke the old token. ## Copy images to another registry Use `depot push` to copy a saved build from Depot Registry to another registry. Authenticate to the target registry with `docker login` first, then run: ``` depot push --project -t : ``` The transfer happens directly from Depot infrastructure to your target registry, skipping your local machine. ## Backward compatibility [Depot Registry v2](/content/blog/now-available-depot-registry-v2/index.html) is backward compatible with v1. If you're already using the Depot Registry, you don't need to change anything. Existing project-scoped URLs and build tags continue to work: ``` registry.depot.dev/: ``` Use the org-subdomain format (`{orgId}.registry.depot.dev`) for new repositories and for using the registry as a primary registry with custom names.