gitlab-download-releases 0.1.1
Download release assets from GitLab projects and groups
Requires Python: >=3.12
Keywords: assets, download, gitlab, releases

# gitlab-download-releases

Download release assets from GitLab projects and groups.

## Features

- Downloads uploaded release assets (not source code archives)
- Auto-detects whether a GitLab path is a **group** or **project**
- Recursively processes all projects within a group (including subgroups)
- Version filtering: full releases only, beta included, or all versions
- Skips existing files (use `--overwrite` to re-download)
- Token authentication for private groups and projects
- Parallel downloads (32 threads by default, configurable via `--jobs`)
- JSON output for list modes (`--json`)
- Config file support for persistent settings
- Python 3.12+ with zero external dependencies

## Installation

```bash
pip install gitlab-download-releases
```

Or install from source:

```bash
git clone https://gitlab.com/cyberassessmentlabs/public/tools/gitlab-download-releases.git
cd gitlab-download-releases
pip install .
```

## Usage

```bash
# Download releases from a single project (full releases only)
gitlab-download-releases \
  --gitlab-url https://gitlab.com \
  --path group/subgroup/project \
  --output ./downloads

# Download releases from all projects in a group
gitlab-download-releases -u https://gitlab.com -p group/subgroup -o ./downloads

# Download from a private GitLab instance
gitlab-download-releases -u https://gitlab.example.com -p group -o ./downloads -t glpat-xxx

# Include beta versions
gitlab-download-releases -u https://gitlab.com -p group/project -o ./downloads -m beta

# Download all versions (including pre-release)
gitlab-download-releases -u https://gitlab.com -p group/project -o ./downloads -m all

# Filter projects within a group
gitlab-download-releases -u https://gitlab.com -p group -o ./downloads -f myproject

# List projects in a group (no download)
gitlab-download-releases -u https://gitlab.com -p group --list-projects

# List releases with asset counts (no download)
gitlab-download-releases -u https://gitlab.com -p group --list-releases

# Overwrite existing files
gitlab-download-releases -u https://gitlab.com -p group/project -o ./downloads -F
```

## Options

| Option | Short | Description |
|--------|-------|-------------|
| `--gitlab-url` | `-u` | GitLab instance URL |
| `--path` | `-p` | Group or project path (required) |
| `--output` | `-o` | Output directory for downloaded assets |
| `--token` | `-t` | Access token for private groups/projects |
| `--config` | `-c` | Config file path |
| `--version-filter` | `-m` | Version filter: `release`, `beta`, or `all` (default: `release`) |
| `--project-filter` | `-f` | Filter projects by name (substring, group mode only) |
| `--list-projects` | `-L` | List projects and exit (no download) |
| `--list-releases` | `-R` | List releases and exit (no download) |
| `--json` | `-j` | Output in JSON format (with list modes) |
| `--overwrite` | `-F` | Overwrite existing files instead of skipping |
| `--jobs` | | Number of parallel download threads (default: 32) |
| `--verbose` | `-v` | Verbose output (use twice for debug) |
| `--no-colour` | | Disable coloured output |
| `--help` | `-h` | Show help message |
| `--version` | | Show version |

## Version Filter Modes

- `release` (default) - Only full semantic versions (x.y.z)
- `beta` - Full releases plus beta pre-releases (x.y.z-beta, x.y.zb1, etc.)
- `all` - All releases including any pre-release tags

## Output Structure

Downloads are organised by project (when using groups) and release tag:

```
downloads/
├── project-a/
│   ├── v1.0.0/
│   │   ├── binary-linux-amd64
│   │   └── binary-darwin-amd64
│   └── v2.0.0/
│       └── binary-linux-amd64
└── subgroup/project-b/
    └── v1.0.0/
        └── release.tar.gz
```

## Authentication

For private GitLab groups and projects, provide an access token via CLI, environment variable, or config file:

```bash
# Via CLI
gitlab-download-releases -u https://gitlab.example.com -p group -o ./downloads --token glpat-xxx

# Via environment variable
export GITLAB_DOWNLOAD_RELEASES_TOKEN=glpat-xxx
gitlab-download-releases -u https://gitlab.example.com -p group -o ./downloads
```

## Configuration File

Settings can be stored in `~/.config/gitlab-download-releases/config.json`:

```json
{
    "gitlab_url": "https://gitlab.example.com",
    "token": "glpat-xxxxxxxxxxxxxxxxxxxx",
    "base_group": "myorg",
    "output": "./downloads",
    "version_filter": "release",
    "project_filter": "backend",
    "parallel": 32,
    "no_colour": false
}
```

All fields are optional:

| Field | Type | Description |
|-------|------|-------------|
| `gitlab_url` | string | GitLab instance URL |
| `token` | string | Access token for private groups/projects |
| `base_group` | string | Default root group; `--path` becomes relative to this |
| `output` | string | Output directory for downloaded release assets |
| `version_filter` | string | Version filter mode: `release`, `beta`, or `all` |
| `project_filter` | string | Filter projects by name (substring match, group mode only) |
| `parallel` | integer | Number of parallel download threads (default: 32) |
| `no_colour` | boolean | Disable coloured output |

The config file path can be overridden via `--config` or the `GITLAB_DOWNLOAD_RELEASES_CONFIG` environment variable. Settings priority: CLI arg > environment variable > config file > default.

## Requirements

- Python 3.12 or higher
- No external dependencies (uses only Python standard library)

## Development

```bash
# Set up development environment
make dev

# Run linting and type checks
make check

# Format code
make format

# Build package
make build
```

## Licence

MIT License — Copyright (c) 2026 Cyber Assessment Labs