Metadata-Version: 2.4
Name: github-artifacts
Version: 0.1.0
Summary: Download GitHub Actions workflow artifacts with date filtering
Author-email: Pandiyaraj Karuppasamy <pandiyarajk@live.com>
License: MIT License
        
        Copyright (c) 2026 Pandiyaraj Karuppasamy
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/pandiyarajk/github-artifacts
Project-URL: Repository, https://github.com/pandiyarajk/github-artifacts
Project-URL: Issues, https://github.com/pandiyarajk/github-artifacts/issues
Keywords: github,actions,artifacts,workflow,ci,download
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Utilities
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Dynamic: license-file

# github-artifacts

> Download GitHub Actions workflow artifacts with date filtering, concurrent downloads, and comprehensive logging.

[![PyPI version](https://badge.fury.io/py/github-artifacts.svg)](https://pypi.org/project/github-artifacts/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Features

- **Date Range Filtering**: Download artifacts from specific date ranges (default: last Friday to today)
- **Concurrent Downloads**: Multi-threaded downloads with configurable worker count
- **Smart Skip Logic**: Automatically skips already-downloaded artifacts using marker files
- **Rate Limit Handling**: Automatically handles GitHub API rate limits
- **TSV Logging**: Comprehensive tab-separated log file for tracking downloads
- **Workflow Filtering**: Target specific workflows by name

## Installation

```bash
pip install github-artifacts
```

## Authentication

You need a GitHub Personal Access Token (PAT) with `repo` scope to download artifacts.

1. Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Generate a new token with `repo` scope
3. Set the token as an environment variable:

```bash
export GH_PAT=ghp_xxxxxxxxxxxxxxxxxxxxx
```

## Usage

### Basic Usage

Set up authentication and workflow names:

```bash
export GH_PAT=ghp_xxxxx
export GITHUB_WORKFLOWS="Build workflow,Test workflow"
```

Download artifacts (uses environment variables):

```bash
github-artifacts download owner/repo
```

### Show Version

```bash
github-artifacts --version
github-artifacts info
```

### Override Workflows via Flag

```bash
github-artifacts download owner/repo --workflows "Build workflow,Test workflow"
```

### Custom Date Range

By default, downloads artifacts from last Friday to today (or today to today if today is Friday):

```bash
# Download from March 1 to March 14, 2026
github-artifacts download owner/repo --start 2026-03-01 --end 2026-03-14
```

### Custom Output Directory and Worker Count

```bash
github-artifacts download owner/repo --output ./my_artifacts --workers 16
```

### Complete Example

```bash
github-artifacts download pandiyarajk/my-repo \
  --start 2026-03-01 \
  --end 2026-03-14 \
  --workflows "Build,Test,Deploy" \
  --output ./artifacts \
  --workers 8 \
  --token ghp_xxxxx \
  --log downloads.log
```

## Command Reference

### `download`

Download artifacts from a GitHub repository.

**Arguments:**

- `repo` (required): Repository in `OWNER/REPO` format
- `--start`: Start date (YYYY-MM-DD). Default: last Friday OR today if today is Friday
- `--end`: End date (YYYY-MM-DD). Default: today
- `--workflows`: Comma-separated workflow names (can also use `GITHUB_WORKFLOWS` env var)
- `--output`: Output directory (default: `./artifacts`)
- `--workers`: Number of concurrent download threads (default: 8)
- `--token`: GitHub PAT (or use `GH_PAT` env var)
- `--log`: Log file path (default: `artifacts_download.log`)

### `info`

Show version and author information.

## Artifact Naming

Downloaded artifacts are saved with the following naming convention:

```
{run_id}_{artifact_name}_{original_filename}
```

Example: `12345678_build-output_app.zip`

## Log Format

The TSV log file contains the following columns:

```
timestamp	workflow	run_id	filename
2026-04-03T23:15:00Z	Build workflow	12345678	12345678_build-output_app.zip
```

## Skip Logic

The tool creates marker files (`.artifact_{artifact_id}.done`) to track downloaded artifacts. If an artifact has already been downloaded, it will be skipped automatically.

## Rate Limiting

The tool automatically handles GitHub API rate limits by:

1. Detecting 403 responses with rate limit messages
2. Reading the `X-RateLimit-Reset` header
3. Sleeping until the reset time (plus a small buffer)

## Development

Install in development mode:

```bash
pip install -e ".[dev]"
```

Run tests:

```bash
pytest
```

## Author

**Pandiyaraj Karuppasamy** — pandiyarajk@live.com

## License

MIT © 2026 Pandiyaraj Karuppasamy
