Skip to content

feat: add OCI multi-registry support (ghcr.io, quay.io, mcr.microsoft.com, etc.) #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
EpicTGuy wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: add OCI multi-registry support (ghcr.io, quay.io, mcr.microsoft.com, etc.) #7

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 24 additions & 8 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,8 @@
The `docker-image-extract` script pulls and extracts all files from an image
in [Docker Hub](https://hub.docker.com/). For multi-platform images, you can
choose the platform-specific image to pull.
in [Docker Hub](https://hub.docker.com/) or any OCI-compliant registry
(e.g. [GHCR](https://ghcr.io), [Quay](https://quay.io),
[GitLab Registry](https://docs.gitlab.com/ee/user/packages/container_registry/)).
For multi-platform images, you can choose the platform-specific image to pull.

`docker-image-extract` has minimal dependencies that should exist in pretty
much any Linux environment, with the possible exception of `curl`/`wget`:
Expand All @@ -17,24 +19,23 @@ much any Linux environment, with the possible exception of `curl`/`wget`:

If you are using [BusyBox](https://busybox.net/), version 1.34.0 or later is
required, as the `wget` implementation in earlier versions does not recognize
the HTTP 307/308 redirects returned by Docker Hub.
the HTTP 307/308 redirects returned by some registries.

## Usage

```
./docker-image-extract [OPTIONS...] IMAGE[:REF]

IMAGE can be a community user image (like 'some-user/some-image') or a
Docker official image (like 'hello-world', which contains no '/').
IMAGE can be:
- A Docker Hub image: 'hello-world', 'some-user/some-image'
- An OCI registry image: 'ghcr.io/user/image', 'quay.io/user/image'

REF is either a tag name or a full SHA-256 image digest (with a 'sha256:' prefix).
The default ref is the 'latest' tag.

Options:

-p PLATFORM Pull image for the specified platform (default: linux/amd64)
For a given image on Docker Hub, the 'Tags' tab lists the
platforms supported for that image.
-o OUT_DIR Extract image to the specified output dir (default: ./output)
-h Show help with usage examples

Expand All @@ -46,13 +47,28 @@ $ ./docker-image-extract hello-world:latest
# Same as above; ref defaults to the 'latest' tag.
$ ./docker-image-extract hello-world

# Pull the 'hello-world' image for the 'linux/arm64/v8' platform.
# Pull from GitHub Container Registry.
$ ./docker-image-extract ghcr.io/user/image:latest

# Pull the image for the 'linux/arm64/v8' platform.
$ ./docker-image-extract -p linux/arm64/v8 hello-world

# Pull an image by digest.
$ ./docker-image-extract hello-world:sha256:90659bf80b44ce6be8234e6ff90a1ac34acbeb826903b02cfa0da11c82cbc042
```

## OCI registry support

For non-Docker Hub registries, the script dynamically discovers the
authentication endpoint by probing `GET /v2/` and parsing the
`WWW-Authenticate: Bearer realm="...",service="..."` header returned on a 401
response (per the [OCI Distribution Spec](https://github.com/opencontainers/distribution-spec)).
Registries that serve public images without authentication (e.g.
`mcr.microsoft.com`) are also supported.

Tested against: `docker.io`, `ghcr.io`, `quay.io`, `registry.gitlab.com`,
`mcr.microsoft.com`.

## Sample output

```
Expand Down
Loading