glpkg 1.5.0
Tool to make GitLab generic package registry operations easy.
Requires Python: >=3.9
Keywords: GitLab, packages, registry, generic

# glpkg - GitLab Generic Package tools 

glpkg is a tool that makes it easy to work with [GitLab generic packages](https://docs.gitlab.com/user/packages/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 tool from with pip:

```bash
pip install glpkg
```

To check the installation and version, run:

```bash
glpkg --version
```

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

## Usage

When in doubt

```bash
glpkg --help
```

might help

By default, the used GitLab host is gitlab.com. 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](https://docs.gitlab.com/user/profile/personal_access_tokens/#create-a-personal-access-token) or [project](https://docs.gitlab.com/user/project/settings/project_access_tokens/#create-a-project-access-token) 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](#Use-in-GitLab-pipelines) 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

```bash
glpkg list --project 12345 --name mypackagename
```

Where:
- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#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:

```bash
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

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

Where:
- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#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 all cases, as long as you have permissions to the destination directory, any pre-existing files will be overridden without warning.

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

```bash
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`:

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

The `my-packages.txt` lists all wanted packages with their versions and projects 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 packages contains files with same names, some files will be overwritten.

> 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

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

Where:
- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#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 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:

```bash
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

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

Where
- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#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

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

Where
- `12345` is your projects ID ([Find the Project ID](https://docs.gitlab.com/user/project/working_with_projects/#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](https://docs.gitlab.com/ci/variables/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:

```bash
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](https://docs.gitlab.com/ci/jobs/ci_job_token/#control-job-token-access-to-your-project) in the other project.