1# `crane`
2
3[`crane`](doc/crane.md) is a tool for interacting with remote images
4and registries.
5
6<img src="../../images/crane.png" width="40%">
7
8A collection of useful things you can do with `crane` is [here](recipes.md).
9
10## Installation
11
12### Install from Releases
13
141. Get the [latest release](https://github.com/google/go-containerregistry/releases/latest) version.
15
16 ```sh
17 $ VERSION=$(curl -s "https://api.github.com/repos/google/go-containerregistry/releases/latest" | jq -r '.tag_name')
18 ```
19
20 or set a specific version:
21
22 ```sh
23 $ VERSION=vX.Y.Z # Version number with a leading v
24 ```
25
261. Download the release.
27
28 ```sh
29 $ OS=Linux # or Darwin, Windows
30 $ ARCH=x86_64 # or arm64, x86_64, armv6, i386, s390x
31 $ curl -sL "https://github.com/google/go-containerregistry/releases/download/${VERSION}/go-containerregistry_${OS}_${ARCH}.tar.gz" > go-containerregistry.tar.gz
32 ```
33
341. Verify the signature. We generate [SLSA 3 provenance](https://slsa.dev) using
35 the OpenSSF's [slsa-framework/slsa-github-generator](https://github.com/slsa-framework/slsa-github-generator).
36 To verify our release, install the verification tool from [slsa-framework/slsa-verifier#installation](https://github.com/slsa-framework/slsa-verifier#installation)
37 and verify as follows:
38
39 ```sh
40 $ curl -sL https://github.com/google/go-containerregistry/releases/download/${VERSION}/multiple.intoto.jsonl > provenance.intoto.jsonl
41 $ # NOTE: You may be using a different architecture.
42 $ slsa-verifier-linux-amd64 verify-artifact go-containerregistry.tar.gz --provenance-path provenance.intoto.jsonl --source-uri github.com/google/go-containerregistry --source-tag "${VERSION}"
43 PASSED: Verified SLSA provenance
44 ```
45
461. Unpack it in the PATH.
47
48 ```sh
49 $ tar -zxvf go-containerregistry.tar.gz -C /usr/local/bin/ crane
50 ```
51
52### Install manually
53
54Install manually:
55
56```sh
57go install github.com/google/go-containerregistry/cmd/crane@latest
58```
59
60### Install via brew
61
62If you're macOS user and using [Homebrew](https://brew.sh/), you can install via brew command:
63
64```sh
65$ brew install crane
66```
67
68### Install on Arch Linux
69
70If you're an Arch Linux user you can install via pacman command:
71
72```sh
73$ pacman -S crane
74```
75
76### Setup on GitHub Actions
77
78You can use the [`setup-crane`](https://github.com/imjasonh/setup-crane) action
79to install `crane` and setup auth to [GitHub Container
80Registry](https://github.com/features/packages) in a GitHub Action workflow:
81
82```
83steps:
84- uses: imjasonh/setup-crane@v0.1
85```
86
87## Images
88
89You can also use crane as docker image
90
91```sh
92$ docker run --rm gcr.io/go-containerregistry/crane ls ubuntu
9310.04
9412.04.5
9512.04
9612.10
97```
98
99And it's also available with a shell, at the `:debug` tag:
100
101```sh
102docker run --rm -it --entrypoint "/busybox/sh" gcr.io/go-containerregistry/crane:debug
103```
104
105Tagged debug images are available at `gcr.io/go-containerregistry/crane/debug:[tag]`.
106
107### Using with GitLab
108
109```yaml
110# Tags an existing Docker image which was tagged with the short commit hash with the tag 'latest'
111docker-tag-latest:
112 stage: latest
113 only:
114 refs:
115 - main
116 image:
117 name: gcr.io/go-containerregistry/crane:debug
118 entrypoint: [""]
119 script:
120 - crane auth login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
121 - crane tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHORT_SHA latest
122```
View as plain text