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

# GitHub Container Registry

> Connect GitHub Container Registry (GHCR) with Qovery

## Overview

GitHub Container Registry (GHCR) is GitHub's container image registry service, integrated with GitHub repositories and Actions. It provides free storage for public images and supports private images for GitHub users.

## Registry URL

```
https://ghcr.io
```

## Image Format

```
ghcr.io/<owner>/<image-name>:<tag>
```

Examples:

* `ghcr.io/mycompany/api:latest`
* `ghcr.io/myusername/frontend:v1.2.3`

## Authentication

GitHub Container Registry uses GitHub Personal Access Tokens (PAT) for authentication.

### Required Permissions

Your Personal Access Token (classic) needs the following scopes:

* `read:packages` - Pull images from GHCR
* `read:org` - Required for Qovery to validate your organization access
* `write:packages` - Push images (only if needed)
* `repo` - Required only if your container packages are linked to private repositories (this is the default behavior on GitHub)

<Warning>
  If your container packages inherit their visibility from private repositories (GitHub's default), the `repo` scope is required even for read-only access. This is a GitHub limitation, not a Qovery requirement. You can avoid this by configuring your package visibility independently in your GitHub package settings.
</Warning>

## Configuration in Qovery

<Steps>
  <Step title="Create Personal Access Token">
    1. Go to GitHub → **Settings** → **Developer settings**
    2. Click **Personal access tokens** → **Tokens (classic)**
    3. Click **Generate new token (classic)**
    4. Give it a descriptive name (e.g., "Qovery GHCR Access")
    5. Select required scopes:
       * `read:packages`
       * `read:org`
       * `repo` (if your packages are linked to private repositories)
       * `write:packages` (only if pushing images)
    6. Click **Generate token** and copy immediately

    <Warning>
      GitHub shows the token only once. Save it securely.
    </Warning>
  </Step>

  <Step title="Access Organization Settings">
    Navigate to **Organization Settings** → **Container Registries** in Qovery
  </Step>

  <Step title="Add Registry">
    Click **Add Registry**
  </Step>

  <Step title="Select GitHub Container Registry">
    Choose **GitHub Container Registry** from the registry type dropdown
  </Step>

  <Step title="Enter Credentials">
    Provide:

    * **Container Registry Prefix**: Your GitHub organization name or username (e.g., `mycompany` for images like `ghcr.io/mycompany/my-app`)
    * **Personal Access Token**: Your GitHub Personal Access Token (classic) with the required scopes
  </Step>

  <Step title="Save">
    Qovery will verify the credentials and save the configuration
  </Step>
</Steps>

## Organization Access

For organization-owned packages:

* Ensure your PAT has access to the organization
* The token owner must be a member of the organization
* If your organization enforces SAML SSO, you must authorize the token for SSO after creation: go to **GitHub Settings** → **Developer settings** → **Personal access tokens (classic)** → select your token → **Configure SSO** → **Authorize** for your organization
* If your packages inherit visibility from private repositories, the `repo` scope is required on the token

## Integration with GitHub Actions

GHCR integrates seamlessly with GitHub Actions for CI/CD workflows:

```yaml theme={null}
- name: Push to GitHub Container Registry
  run: |
    echo ${{ secrets.GITHUB_TOKEN }} | docker login ghcr.io -u ${{ github.actor }} --password-stdin
    docker push ghcr.io/${{ github.repository }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Container Registry Management" icon="box" href="/configuration/organization/container-registry">
    Manage all container registries
  </Card>

  <Card title="Deploy Application" icon="rocket" href="/configuration/application">
    Deploy applications from container images
  </Card>

  <Card title="GitLab Container Registry" icon="https://mintcdn.com/qovery/Nvnl0g5BHzA0XQmy/images/logos/gitlab-icon.svg?fit=max&auto=format&n=Nvnl0g5BHzA0XQmy&q=85&s=7dbe862d57a8d223fd98d7182bb152de" href="/configuration/integrations/container-registries/gitlab-cr" width="24" height="24" data-path="images/logos/gitlab-icon.svg">
    Alternative Git-based registry
  </Card>

  <Card title="Docker Hub" icon="docker" href="/configuration/integrations/container-registries/docker-hub">
    Public container registry option
  </Card>
</CardGroup>