glpkg 1.6.0

Tool to make GitLab generic package registry operations easy.

glpkg - GitLab Generic Package tools

glpkg is a tool that makes it easy to work with GitLab generic packages.

Generic package registries of GitLab projects are supported. Group registries are not, as the GitLab REST API for groups is very limited.

Installation

Install the command line tool from with pipx:

pipx install glpkg

Alternatively use pip for the installation:

pip install glpkg

Either way, to check the installation and glpkg version, run:

glpkg --version

If you see a version in the terminal, you're good to go!

Usage

When in doubt

glpkg --help

might help

By default, glpkg uses gitlab.com as a host. If you use a self-hosted GitLab, use argument --host my-gitlab.net with the commands.

Only https scheme is supported.

To authenticate with the package registry in any of the commands below, use --token readapitoken123 argument where the readapitoken123 is a personal or project access token, with read API scope. In case the package registry is public, you can omit this argument.

Alternatively you can use a token stored in your .netrc file by setting --netrc argument.

If you use the tool in GitLab CI, read below on how to use the CI_JOB_TOKEN.

The arguments related to the GitLab host or authentication (--token, --netrc, and --ci) are omitted in the examples below to focus on the commands.

In general, run glpkg --help when needed.

Listing package versions

To list the versions of a generic package, run

glpkg list --project 12345 --name mypackagename

Where:

• 12345 is your projects ID (Find the Project ID) or the path of the project (like namespace/project)
• mypackagename is the name of the generic package

The output will be, if package is found, something like:

Name            Version
mypackagename   1.0
mypackagename   1.5
mypackagename   2.0

Download generic package

To download all files from a specific version of a generic package, run

glpkg download --project 12345 --name mypackagename --version 1.0

Where:

• 12345 is your projects ID (Find the Project ID) or the path of the project (like namespace/project)
• mypackagename is the name of the generic package
• 1.0 is the version of the generic package from which the files are downloaded

By default the files will be downloaded in the current working directory. To download the files to another directory, add argument --destination to the command. In case the package contains files that would override local files, the download will not download the files unless --force flag is set.

To download only a specific file from the package, add --file argument.

glpkg download --project 12345 --name mypackagename --version 1.5 --file the_only_one --destination /temp

If a package has multiple files with the same filename, the tool can only download the newest file. This is a restriction of GitLab API.

Downloading a list of packages

To download multiple packages or versions from one or more projects, a package file can be used together with --from-file argument with download:

glpkg download --from-file my-packages.txt --destination my-downloads

Where my-packages.txt file lists all wanted packages with their versions and projects, each line in format <package-name>==<package-version>@<project-id>. For example my-packages.txt could look like this:

mypackage==2.3.6-beta@namespace/project
yourpackage==1.2.3@12345

The <project-id> can be either the path to the project in string format or the project ID in numeric.

When --from-file argument is used, --file, --project, --version, and --name arguments are unused.

The --destination argument can be used to download the files from the packages to a different folder. In case the package contains files that would override local files, the package download will not download the files unless --force flag is set.

Whatever credentials (--token, --ci, or --netrc) you run the download command with will be used for all package downloads in the list. Make sure that the credential has access to all projects.

Upload a file to a generic package

To upload a file to a version of a generic package, run

glpkg upload --project 12345 --name mypackagename --version 1.0 --file my-file.txt

Where:

• 12345 is your projects ID (Find the Project ID) or the path of the project (like namespace/project)
• mypackagename is the name of the generic package
• 1.0 is the version of the generic package to which the file is uploaded
• my-file.txt is the file that is uploaded to the generic package. Only relative paths are supported, and the relative path (e.g. folder/file.txt) is preserved when uploading the file to the package.

A GitLab generic package may have multiple files with the same file name. However, it likely is not a great idea, as they cannot be downloaded separately from the GitLab API. To upload a file that already exists in GitLab package registry, set --force flag.

To upload multiple files, or to upload a single file from a different directory, use --source argument. If no --file argument is set, all of the files in the source directory are uploaded, recursively. As an example, to upload all files from a upload folder to the package:

glpkg upload --project 12345 --name mypackagename --version 1.0 --source upload

Note: a file in upload folder will be uploaded to the root of the package. If you want to upload the file to a dir folder in the package, make a structure in the upload folder, like upload/dir/.

Delete a file from a generic package

To delete a file from a specific generic package, run

glpkg delete --project 12345 --name mypackagename --version 1.0 --file my-file.txt

Where

• 12345 is your projects ID (Find the Project ID) or the path of the project (like namespace/project)
• mypackagename is the name of the generic package
• 1.0 is the version of the generic package from the file is deleted
• my-file.txt is the file that is deleted. Only relative paths are supported. Note that the package may contain multiple files with same name. In this case, one file of them is deleted.

The token that is used to delete files must have at least Maintainer role in the project.

Delete a package version

To delete a specific generic package version, run

glpkg delete --project 12345 --name mypackagename --version 1.0

Where

• 12345 is your projects ID (Find the Project ID) or the path of the project (like namespace/project)
• mypackagename is the name of the generic package
• 1.0 is the version of the generic package that is deleted

The token that is used to delete packages must have at least Maintainer role in the project.

Use in GitLab pipelines

If you use the tool in a GitLab pipeline, setting argument --ci uses GitLab predefined variables to configure the tool. In this case CI_SERVER_HOST, CI_PROJECT_ID, and CI_JOB_TOKEN environment variables are used. The --host, --project, and --token arguments can still be used to override the host, project ID, or to use a personal or project access token instead of CI_JOB_TOKEN.

In other words, you don't need to give the --host, --project, or --token arguments if you are interacting with the package registry of the project where the pipeline is running. Example: uploading my-file.txt to generic package mypackagename version 1.0 in the project package registry in CI:

glpkg upload --ci --name mypackagename --version 1.0 --file my-file.txt

To use the CI_JOB_TOKEN with package registry of another projects, add --project <otherproject ID> argument. Remember that you may need to add permissions for the CI_JOB_TOKEN in the other project.