fetch-github-logs

Fetch GitHub Logs

A powerful CLI tool to download GitHub Actions workflow logs. Perfect for developers who need quick access to workflow logs for debugging and analysis.

🚀 Quick Start

Install Globally

npm install -g fetch-github-logs

Basic Usage

# Set your GitHub token
export GITHUB_TOKEN=your_github_token_here

# Download latest workflow logs
fetch-github-logs fetch-logs

# Push and wait for workflow, then download logs
fetch-github-logs after-push

📦 Installation

Global Installation (Recommended)

npm install -g fetch-github-logs

Local Installation

npm install --save-dev fetch-github-logs

Manual Installation

git clone https://github.com/Skeyelab/fetch-github-logs.git
cd fetch-github-logs
npm install
npm link  # for global usage

🎯 Use Cases

👥 Developers

• Quick access to GitHub Actions workflow logs without opening browser
• Automated log collection for debugging
• GitHub Actions workflow debugging
• Team collaboration on workflow issues

🔧 DevOps & CI/CD

• Automated log collection in scripts
• Integration with monitoring systems
• Debugging deployment and automation pipelines
• Workflow performance analysis

📖 Usage

Commands

fetch-logs - Download Workflow Logs

fetch-github-logs fetch-logs [options]

Options:

• -w, --workflow <workflow> - Workflow file name (default: build.yml)
• -r, --repo <repo> - Repository in owner/repo format (auto-detected)
• -i, --run-id <runId> - Specific run ID to download
• --wait - Wait for workflow run to appear
• --wait-for-completion - Wait for run to complete
• --timeout <seconds> - Wait timeout (default: 300)
• --interval <seconds> - Polling interval (default: 5)

Examples:

# Download latest workflow logs
fetch-github-logs fetch-logs

# Download logs for specific workflow
fetch-github-logs fetch-logs --workflow deploy.yml

# Wait for workflow to complete then download
fetch-github-logs fetch-logs --wait-for-completion

# Download specific run
fetch-github-logs fetch-logs --run-id 123456789

after-push - Push & Fetch Workflow Logs

fetch-github-logs after-push [options]

Options:

• -r, --remote <remote> - Git remote (default: origin)
• -b, --branch <branch> - Branch to push (auto-detected)
• --skip-push - Skip git push
• -w, --workflow <workflow> - Workflow file name (default: build.yml)
• --wait-for-completion - Wait for run to complete
• --timeout <seconds> - Wait timeout

Examples:

# Push current branch and wait for workflow
fetch-github-logs after-push

# Push specific branch to specific remote
fetch-github-logs after-push --remote upstream --branch feature-branch

# Just wait for workflow without pushing
fetch-github-logs after-push --skip-push

Environment Variables

Variable	Description	Default
GITHUB_TOKEN	GitHub personal access token	Required
GITHUB_REPO	Repository in "owner/repo" format	Auto-detected
GITHUB_WORKFLOW	Workflow file name	build.yml
RUN_ID	Specific run ID to download	Latest run
WAIT_FOR_RUN	Wait for workflow run to appear	false
WAIT_FOR_COMPLETION	Wait for run to complete	false
WAIT_TIMEOUT	Timeout in seconds	300
WAIT_INTERVAL	Polling interval in seconds	5
SKIP_PUSH	Skip git push in after-push	false

Programmatic Usage

const { fetchLogs, afterPush } = require('fetch-github-logs');

// Download logs programmatically
await fetchLogs({
  workflow: 'build.yml',
  repo: 'owner/repo',
  waitForCompletion: true
});

// Push and fetch logs
await afterPush({
  remote: 'origin',
  branch: 'main',
  waitForCompletion: true
});

📁 Output Structure

Logs are saved in the following structure:

log/github/
└── 123456789-abc1234/
    ├── run_123456789.zip          # Combined run logs
    ├── run_123456789_metadata.json # Run metadata
    ├── job_987654321_test.log     # Individual job logs
    ├── job_987654322_build.log
    └── job_987654323_deploy.log

🔐 Authentication

You need a GitHub personal access token with the following permissions:

• actions: read - to read workflow runs and download logs

Create a token:

• Go to GitHub Settings > Personal Access Tokens
• Generate a new token with Actions read permission
• Set as environment variable: export GITHUB_TOKEN=your_token_here

🛠️ Development

Setup

git clone https://github.com/Skeyelab/fetch-github-logs.git
cd fetch-github-logs
npm install

Testing

npm test
npm run test:watch

Linting

npm run lint
npm run lint:fix

Building

npm run prepare  # runs lint and test

🤝 Contributing

• Fork the repository
• Create a feature branch: git checkout -b feature/amazing-feature
• Make your changes
• Run tests: npm test
• Commit your changes: git commit -m 'Add amazing feature'
• Push to the branch: git push origin feature/amazing-feature
• Open a Pull Request

📝 Changelog

See CHANGELOG.md for version history.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚀 Automated Releases

This project uses GitHub Actions for automated npm publishing. There are two ways to trigger releases:

Option 1: Manual Release (Recommended)

• Push your changes to the main branch
• Go to GitHub Actions → Release & Publish to npm
• Click "Run workflow" and select version type (patch/minor/major)
• Workflow will:
  • Bump version automatically
  • Run tests and linting
  • Publish to npm
  • Create Git tag
  • Create GitHub release

Option 2: Release via Git Tag

• Update version manually:

  npm run release:patch   # or release:minor / release:major
  

• Commit and push changes:

  git add package.json package-lock.json
  git commit -m "chore: bump version to x.x.x"
  git push origin main
  

• Create a GitHub release:

  • Go to GitHub → Releases → Create new release
  • Tag: vx.x.x (must match package.json version)
  • Publish release

• GitHub Actions will automatically publish to npm

Setup Required

• Create npm token:

  npm login
  # Get token from: https://www.npmjs.com/settings/tokens
  

• Add to GitHub Secrets:

  • Go to repository Settings → Secrets and variables → Actions
  • Add: NPM_TOKEN = your npm token

Release Scripts

npm run release:patch   # 1.0.0 → 1.0.1
npm run release:minor   # 1.0.0 → 1.1.0
npm run release:major   # 1.0.0 → 2.0.0

🙏 Acknowledgments

• Built for developers who need fast access to GitHub Actions workflow logs
• Thanks to the GitHub Actions team for the excellent API

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: GitHub Wiki

Made with ❤️ for developers