Gitlab Community Edition Instance

Skip to content

Feature: Snapshots

Marcel Hellkamp requested to merge feature-snapshots into master

Snapshots are named point-in-time copies of the payload (files and metadata) of an archive. They can be used to implement versioning, or to 'freeze' the current state of an archive for publication. Users can later access the preserved payload state, even if the archive was modified after the snapshot was created.

Concepts:

  • Snapshots only preserve payload (files, metadata). Administrative metadata (ACLs, profile, owner, ...) is not preserved.
  • Snapshots are permanent. Once created, they cannot be modified, only removed.
  • Snapshot names are unique per archive and cannot be re-assigned even after a snapshot is removed.
  • Deleting an archive also deletes all snapshots. They are not meant to be used as backups.
  • Creating and storing snapshots should be significantly cheaper than a full archive copy.

Form the HTTP API perspective, snapshot payload can be accessed (read-only) just like archive payload, by appending the snapshot name to the archive ID in the HTTP endpoint path. Most endpoints will accept {archive}@{tag} instead of just {archive} and then return payload from the snapshot instead of the archive. If a response would contain information that is not part of the snapshot (e.g. ACL), then information from the archive itself is returned. For example, to list files in a snapshot, call GET /v3/ab587f42c257@v1?files. To download a file from a snapshot, call GET /v3/ab587f42c257@v1/data.csv.

Merge request reports