github-artifacts

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

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

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:

export GH_PAT=ghp_xxxxxxxxxxxxxxxxxxxxx

Usage

Basic Usage

Set up authentication and workflow names:

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

Download artifacts (uses environment variables):

github-artifacts download owner/repo

Show Version

github-artifacts --version
github-artifacts info

Override Workflows via Flag

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):

# 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

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

Complete Example

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:

pip install -e ".[dev]"

Run tests:

pytest

Author

Pandiyaraj Karuppasamy — pandiyarajk@live.com

License

MIT © 2026 Pandiyaraj Karuppasamy