GitLabgitlab-org
cli
main
1package download
3import (
4 "context"
5 "errors"
6 "fmt"
7 "io"
8 "io/fs"
9 "net/http"
10 "net/url"
11 "os"
12 "path"
13 "path/filepath"
14 "slices"
15 "strings"
17 "github.com/MakeNowJust/heredoc/v2"
18 "github.com/spf13/cobra"
20 gitlab "gitlab.com/gitlab-org/api/client-go/v3"
22 "gitlab.com/gitlab-org/cli/internal/api"
23 "gitlab.com/gitlab-org/cli/internal/cmdutils"
24 "gitlab.com/gitlab-org/cli/internal/commands/release/releaseutils/upload"
25 "gitlab.com/gitlab-org/cli/internal/glrepo"
26 "gitlab.com/gitlab-org/cli/internal/iostreams"
27 "gitlab.com/gitlab-org/cli/internal/mcpannotations"
28)
30type options struct {
31 tagName string
32 assetNames []string
33 dir string
34 clobber bool
35 skipExisting bool
37 io *iostreams.IOStreams
38 apiClient func(repoHost string) (*api.Client, error)
39 gitlabClient func() (*gitlab.Client, error)
40 baseRepo func() (glrepo.Interface, error)
41}
43func NewCmdDownload(f cmdutils.Factory) *cobra.Command {
44 opts := &options{
45 io: f.IO(),
46 apiClient: f.ApiClient,
47 gitlabClient: f.GitLabClient,
48 baseRepo: f.BaseRepo,
49 }
51 cmd := &cobra.Command{
52 Use: "download [<tag>]",
53 Short: "Download asset files from a GitLab release.",
54 Long: heredoc.Docf(`Download asset files from a GitLab release.
56 If no tag is specified, downloads assets from the latest release.
57 To specify a file name to download from the release assets, use %[1]s--asset-name%[1]s.
58 %[1]s--asset-name%[1]s flag accepts glob patterns.
60 If a file already exists in the download directory, the command stops with an error. Use %[1]s--clobber%[1]s to overwrite it, or %[1]s--skip-existing%[1]s to keep it and continue with the other assets.
61 `, "`"),
62 Args: cobra.MaximumNArgs(1),
63 Example: heredoc.Doc(`
64 # Download all assets from the latest release
65 glab release download
67 # Download all assets from the specified release tag
68 glab release download v1.1.0
70 # Download assets with names matching the glob pattern
71 glab release download v1.10.1 --asset-name="*.tar.gz"
73 # Replace files that were downloaded before
74 glab release download v1.1.0 --clobber
76 # Download only the assets that are missing
77 glab release download v1.1.0 --skip-existing`),
78 Annotations: map[string]string{
79 mcpannotations.Safe: "true",
80 },
81 RunE: func(cmd *cobra.Command, args []string) error {
82 opts.complete(args)
84 return opts.run(cmd.Context())
85 },
86 }
88 cmd.Flags().StringArrayVarP(&opts.assetNames, "asset-name", "n", []string{}, "Download only assets that match the name or a glob pattern.")
89 cmd.Flags().StringVarP(&opts.dir, "dir", "D", ".", "Directory to download the release assets to.")
90 cmd.Flags().BoolVar(&opts.clobber, "clobber", false, "Overwrite files that already exist in the download directory.")
91 cmd.Flags().BoolVar(&opts.skipExisting, "skip-existing", false, "Keep files that already exist in the download directory, and download only the missing assets.")
93 cmd.MarkFlagsMutuallyExclusive("clobber", "skip-existing")
95 return cmd
96}
98func (o *options) complete(args []string) {
99 if len(args) == 1 {
100 o.tagName = args[0]
101 }
102}
104func (o *options) run(ctx context.Context) error {
105 client, err := o.gitlabClient()
106 if err != nil {
107 return err
108 }
109 repo, err := o.baseRepo()
110 if err != nil {
111 return err
112 }
113 color := o.io.Color()
114 var resp *gitlab.Response
115 var release *gitlab.Release
116 var downloadableAssets []*upload.ReleaseAsset
118 if o.tagName == "" {
119 o.io.LogInfof("%s fetching latest release %s=%s\n",
120 color.ProgressIcon(),
121 color.Blue("repo"), repo.FullName())
122 releases, _, err := client.Releases.ListReleases(repo.FullName(), &gitlab.ListReleasesOptions{})
123 if err != nil {
124 return cmdutils.WrapError(err, "could not fetch latest release.")
125 }
126 if len(releases) < 1 {
127 return cmdutils.WrapError(errors.New("not found"), fmt.Sprintf("no release found for %q", repo.FullName()))
128 }
130 release = releases[0]
131 o.tagName = release.TagName
132 } else {
133 o.io.LogInfof("%s fetching release %s=%s %s=%s.\n",
134 color.ProgressIcon(),
135 color.Blue("repo"), repo.FullName(),
136 color.Blue("tag"), o.tagName)
138 release, resp, err = client.Releases.GetRelease(repo.FullName(), o.tagName)
139 if err != nil {
140 if resp != nil && (resp.StatusCode == http.StatusNotFound || resp.StatusCode == http.StatusForbidden) {
141 return cmdutils.WrapError(err, "release does not exist.")
142 }
143 return cmdutils.WrapError(err, "failed to fetch release.")
144 }
145 }
147 for _, link := range release.Assets.Links {
148 if len(o.assetNames) > 0 && (!matchAny(o.assetNames, link.Name)) {
149 continue
150 }
151 downloadableAssets = append(downloadableAssets, &upload.ReleaseAsset{
152 Name: &link.Name,
153 URL: &link.URL,
154 })
155 }
157 for _, source := range release.Assets.Sources {
158 name := path.Base(source.URL)
159 if len(o.assetNames) > 0 && (!matchAny(o.assetNames, name)) {
160 continue
161 }
162 downloadableAssets = append(downloadableAssets, &upload.ReleaseAsset{
163 Name: &name,
164 URL: &source.URL,
165 })
166 }
168 if len(downloadableAssets) < 1 {
169 o.io.LogInfof("%s no release assets found!\n",
170 color.DotWarnIcon())
171 return nil
172 }
173 o.io.LogInfof("%s downloading release assets %s=%s %s=%s\n",
174 color.ProgressIcon(),
175 color.Blue("repo"), repo.FullName(),
176 color.Blue("tag"), o.tagName)
178 err = downloadAssets(ctx, client, o.io, downloadableAssets, o.dir, o.existingFileAction())
179 if err != nil {
180 return cmdutils.WrapError(err, "failed to download release.")
181 }
183 o.io.LogInfof(color.Bold("%s release %q downloaded\n"), color.GreenCheck(), release.Name)
185 return nil
186}
188func matchAny(patterns []string, name string) bool {
189 for _, p := range patterns {
190 matched, err := filepath.Match(p, name)
191 if err == nil && matched {
192 return true
193 }
194 }
195 return false
196}
198// existingFileAction says what to do with a download target that is already
199// on disk.
200type existingFileAction int
202const (
203 // failOnExisting keeps the original behavior: an existing file stops the
204 // command, so a download never destroys a local file by accident.
205 failOnExisting existingFileAction = iota
206 overwriteExisting
207 keepExisting
208)
210func (o *options) existingFileAction() existingFileAction {
211 switch {
212 case o.clobber:
213 return overwriteExisting
214 case o.skipExisting:
215 return keepExisting
216 default:
217 return failOnExisting
218 }
219}
221func downloadAssets(ctx context.Context, client *gitlab.Client, io *iostreams.IOStreams, toDownload []*upload.ReleaseAsset, destDir string, onExisting existingFileAction) error {
222 color := io.Color()
223 for _, asset := range toDownload {
224 var sanitizedAssetName string
225 if asset.Name != nil {
226 sanitizedAssetName = sanitizeAssetName(*asset.Name)
227 }
228 destDir, err := filepath.Abs(destDir)
229 if err != nil {
230 return fmt.Errorf("resolving absolute download directory path: %w", err)
231 }
233 destPath := filepath.Join(destDir, sanitizedAssetName)
234 if !strings.HasPrefix(destPath, destDir) {
235 return fmt.Errorf("invalid file path name")
236 }
238 if onExisting == keepExisting {
239 exists, err := pathExists(destPath)
240 if err != nil {
241 return err
242 }
243 if exists {
244 io.LogInfof("%s skipping file, it exists already %s=%s\n",
245 color.DotWarnIcon(),
246 color.Blue("name"), sanitizedAssetName)
247 continue
248 }
249 }
251 io.LogInfof("%s downloading file %s=%s %s=%s.\n",
252 color.ProgressIcon(),
253 color.Blue("name"), *asset.Name,
254 color.Blue("url"), *asset.URL)
256 err = downloadAsset(ctx, client, *asset.URL, destPath, onExisting)
257 if err != nil {
258 return err
259 }
260 }
262 return nil
263}
265// pathExists uses Lstat, so a symlink counts as existing even when its target
266// is missing.
267func pathExists(path string) (bool, error) {
268 _, err := os.Lstat(path)
269 if errors.Is(err, fs.ErrNotExist) {
270 return false, nil
271 }
272 return err == nil, err
273}
275func errIfExists(path string) error {
276 exists, err := pathExists(path)
277 if err != nil {
278 return err
279 }
280 if exists {
281 return fmt.Errorf("file %q already exists. Use '--clobber' to overwrite it, or '--skip-existing' to keep it: %w", path, fs.ErrExist)
282 }
283 return nil
284}
286func sanitizeAssetName(asset string) string {
287 if !strings.HasPrefix(asset, "/") {
288 // Prefix the asset with "/" ensures that filepath.Clean removes all `/..`
289 // See rule 4 of filepath.Clean for more information: https://pkg.go.dev/path/filepath#Clean
290 asset = "/" + asset
291 }
292 return filepath.Clean(asset)
293}
295// downloadAsset writes to a temporary file in the destination directory and
296// renames it into place after the whole body arrives. A failed download then
297// keeps an existing file intact and leaves no partial one, and the rename
298// replaces a symlink at the destination instead of writing through it.
299func downloadAsset(ctx context.Context, client *gitlab.Client, assetURL, destinationPath string, onExisting existingFileAction) (err error) {
300 baseURL, err := url.Parse(assetURL)
301 if err != nil {
302 return fmt.Errorf("parsing release asset URL: %w", err)
303 }
305 if onExisting != overwriteExisting {
306 if err := errIfExists(destinationPath); err != nil {
307 return err
308 }
309 }
311 // A fixed prefix keeps the name short. An asset name near the 255-byte
312 // limit would otherwise make the temporary name too long.
313 tmp, err := os.CreateTemp(filepath.Dir(destinationPath), ".glab-download-*.tmp")
314 if err != nil {
315 return err
316 }
317 defer func() {
318 if err != nil {
319 err = errors.Join(err, os.Remove(tmp.Name()))
320 }
321 }()
323 if err := errors.Join(fetchAsset(ctx, client, baseURL, tmp), tmp.Close()); err != nil {
324 return err
325 }
327 // os.CreateTemp uses mode 0600, which would make the asset readable only
328 // by its owner.
329 if err := os.Chmod(tmp.Name(), 0o644); err != nil {
330 return err
331 }
333 // Another process can create the file while the download runs.
334 if onExisting != overwriteExisting {
335 if err := errIfExists(destinationPath); err != nil {
336 return err
337 }
338 }
340 return os.Rename(tmp.Name(), destinationPath)
341}
343func fetchAsset(ctx context.Context, client *gitlab.Client, baseURL *url.URL, f io.Writer) error {
344 // check if authenticated GitLab client should be used or not.
345 gitlabBaseURL := client.BaseURL()
346 if gitlabBaseURL.Scheme == baseURL.Scheme && gitlabBaseURL.Host == baseURL.Host {
347 // `glab release create` stores an uploaded file as a project Markdown
348 // upload, and the link it saves is a web route. Only a browser session
349 // authenticates that route, so a token request is redirected to the
350 // sign-in page, which answers 404 for a private project. The uploads
351 // API serves the same file and accepts the token.
352 if upload, ok := parseMarkdownUploadRef(gitlabBaseURL, baseURL); ok {
353 return downloadMarkdownUpload(ctx, client, upload, f)
354 }
356 r, err := client.NewRequestToURL(http.MethodGet, baseURL, http.NoBody, []gitlab.RequestOptionFunc{
357 gitlab.WithContext(ctx),
358 gitlab.WithHeader("Accept", "application/octet-stream"),
359 })
360 if err != nil {
361 return err
362 }
363 _, err = client.Do(r, f)
364 return err
365 } else {
366 r, err := http.NewRequestWithContext(ctx, http.MethodGet, baseURL.String(), http.NoBody)
367 if err != nil {
368 return err
369 }
370 r.Header.Add("Accept", "application/octet-stream")
372 resp, err := http.DefaultClient.Do(r)
373 if err != nil {
374 return err
375 }
376 defer resp.Body.Close()
378 if resp.StatusCode > 299 {
379 return errors.New(resp.Status)
380 }
381 _, err = io.Copy(f, resp.Body)
382 return err
383 }
384}
386// markdownUploadRef identifies a project Markdown upload behind a release
387// asset link.
388type markdownUploadRef struct {
389 project string // numeric project ID, or a namespace and project path
390 secret string
391 filename string
392}
394// parseMarkdownUploadRef recognizes the two link shapes GitLab stores for a
395// project Markdown upload:
396//
397// /-/project/<project_id>/uploads/<secret>/<filename> GitLab 17.0 and later
398// /<namespace>/<project>/uploads/<secret>/<filename> earlier versions
399//
400// Any other link returns false, which keeps package registry links, release
401// evidence, and source archives on their existing download path.
402func parseMarkdownUploadRef(baseURL, assetURL *url.URL) (markdownUploadRef, bool) {
403 assetPath := strings.TrimPrefix(assetURL.EscapedPath(), instanceBasePath(baseURL))
404 segments := strings.Split(strings.Trim(assetPath, "/"), "/")
406 // The shortest match is <namespace>/<project>/uploads/<secret>/<filename>.
407 if len(segments) < 5 {
408 return markdownUploadRef{}, false
409 }
411 uploadsAt := len(segments) - 3
412 if segments[uploadsAt] != "uploads" {
413 return markdownUploadRef{}, false
414 }
416 secret, err := url.PathUnescape(segments[uploadsAt+1])
417 if err != nil || secret == "" {
418 return markdownUploadRef{}, false
419 }
421 filename, err := url.PathUnescape(segments[uploadsAt+2])
422 if err != nil || filename == "" {
423 return markdownUploadRef{}, false
424 }
426 project := segments[:uploadsAt]
427 if len(project) == 3 && project[0] == "-" && project[1] == "project" {
428 return markdownUploadRef{project: project[2], secret: secret, filename: filename}, true
429 }
431 // A project always sits in a namespace, so a single segment cannot be one.
432 // GitLab reserves `-` as a path name: it ends the project path and starts
433 // a project route, such as /-/raw/ or /-/blob/, which is not an upload.
434 if len(project) < 2 || slices.Contains(project, "-") {
435 return markdownUploadRef{}, false
436 }
437 return markdownUploadRef{project: strings.Join(project, "/"), secret: secret, filename: filename}, true
438}
440// instanceBasePath returns the path prefix of an instance that is served from
441// a subfolder. client.BaseURL points at the API root, so the API segments are
442// removed to leave that prefix.
443func instanceBasePath(baseURL *url.URL) string {
444 return strings.TrimSuffix(strings.TrimSuffix(baseURL.EscapedPath(), "/"), "/api/v4")
445}
447func downloadMarkdownUpload(ctx context.Context, client *gitlab.Client, ref markdownUploadRef, w io.Writer) error {
448 body, _, err := client.ProjectMarkdownUploads.DownloadProjectMarkdownUploadBySecretAndFilename(
449 ref.project, ref.secret, ref.filename, gitlab.WithContext(ctx))
450 if err != nil {
451 return err
452 }
453 defer body.Close()
455 _, err = io.Copy(w, body)
456 return err
457}
Diagnostics8 git calls · 43 ms
CallStatusSizeTime043 ms
discover200185 B2 ms
git.upload-pack discover http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=185 git.server.agent=git/2.56.g1891de4-Linux git.server.object_format=sha1 git.server.caps=agent ls-refs fetch server-option object-format git.server.fetch=shallow wait-for-done filter git.protocol.version=2 git.pkt.frames=9 git.pkt.data=7 git.pkt.flush=2 git.pkt.delim=0 git.pkt.bytes=185 git.pkt.payload.max=35
ls-refs20058 KiB · hit2 ms
git.upload-pack ls-refs http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=ls-refs git.upstream.dur_ms=2 git.response.bytes=59849 git.response.cache=HIT git.response.duration_ms=2 git.protocol.version=2 git.pkt.frames=731 git.pkt.data=730 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=59849 git.pkt.payload.max=143 git.ls_refs.count=730 git.ls_refs.head=refs/heads/main
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=32926 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=10 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=22 git.pkt.data=20 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=32926 git.pkt.payload.max=32046 git.sideband.band1.bytes=32046 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=80 git.pack.bytes=32046 git.pack.ofs_delta=36 git.pack.ref_delta=0 git.pack.chain.max=2 git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91 git.pack.full=44Open pack map
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit4 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=4 git.response.bytes=4273 git.response.cache=HIT git.response.duration_ms=4 git.fetch.filter=combine:blob:none+tree:2 git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9 git.fetch.haves.count=0 git.fetch.deepen=1 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=7 git.pkt.data=5 git.pkt.flush=1 git.pkt.delim=1 git.pkt.bytes=4273 git.pkt.payload.max=4173 git.sideband.band1.bytes=4173 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=11 git.pack.bytes=4173 git.fetch.wide.objects=11 git.fetch.wide.extra_bytes=3930 git.fetch.wide.blobs=0
fetchtree:02001.8 KiB · hit3 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=3 git.response.bytes=1857 git.response.cache=HIT git.response.duration_ms=3 git.fetch.filter=tree:0 git.fetch.wants=dce174ff8c632a19d17eea99c8a9b7c37fb2b592 git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=1857 git.pkt.payload.max=1830 git.sideband.band1.bytes=1830 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=1830 git.pack.trailer=fb03183b7909876778f740d196d7516811003517Open pack map
fetchtree:0200350 B · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=350 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=b2a837e646ba305993f35203fafafb109e57a7ca git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=350 git.pkt.payload.max=323 git.sideband.band1.bytes=323 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=323 git.pack.trailer=1232131042f2ba4c9c4dbd99382667a1f0849e15Open pack map
fetchtree:0200178 B · hit2 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=2 git.response.bytes=178 git.response.cache=HIT git.response.duration_ms=2 git.fetch.filter=tree:0 git.fetch.wants=17d7a4e972314f40abefc6eac0a09f9eb4ccf7cc git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=178 git.pkt.payload.max=151 git.sideband.band1.bytes=151 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0 git.pack.objects=1 git.pack.bytes=151 git.pack.trailer=a4a10e7178122a1f1b1ad28fec85c87cc0de9191Open pack map
fetch2004.5 KiB · hit30 ms
git.upload-pack fetch http.response.status_code=200 git.upstream.cf_ray=- git.upstream.phase=fetch git.upstream.dur_ms=29 git.response.bytes=4622 git.response.cache=HIT git.response.duration_ms=30 git.fetch.wants=177fa96873de4ab949021c47e33749069859375e git.fetch.haves.count=0 git.fetch.deepen=0 git.fetch.thin_pack=false git.fetch.ofs_delta=true git.protocol.version=2 git.pkt.frames=4 git.pkt.data=3 git.pkt.flush=1 git.pkt.delim=0 git.pkt.bytes=4622 git.pkt.payload.max=4595 git.sideband.band1.bytes=4595 git.sideband.band2.bytes=0 git.sideband.band3.bytes=0
Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.
- Remote
- https://gitlab.com/gitlab-org/cli
- Ref
- refs/heads/main
- Commit
- 0dd7574dce9e385c5c30540e6c15657adc6bdce9
- cf-ray
- a5e343193ebd6e2a
- Request
- c71b27fe…
- Protocol
- v2 · sha1
- Agent
- git/2.56.g1891de4-Linux
- Filter
- advertised
- Fetch
- shallow wait-for-done filter
- Capabilities
- agent ls-refs fetch server-option object-format