SBOM Upload Action

A GitHub Action and CLI tool for uploading Software Bill of Materials (SBOM) files to Dependency Track.

✨ Features

• 🚀 GitHub Action Integration - Seamless CI/CD pipeline integration
• 📁 Multiple Upload Methods - Single SBOMs, batch uploads, or custom hierarchies
• 🏗️ Hierarchical Projects - Create parent/child project relationships
• 🎨 Auto Hierarchy Generation - Generate 3-level hierarchies from nested SBOM structures
• 🔄 Version Management - Semantic version comparison and latest detection
• 🧪 Local Testing - CLI for development and debugging
• 🎯 Auto-Detection - Extract project info from SBOM metadata
• 🔐 Secure - API key authentication with proper error handling
• 🆔 Unique Naming - UUID suffixes prevent project name conflicts

🚀 Quick Start

GitHub Action (Recommended)

name: Upload SBOM
on: [push]

jobs:
  upload:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: scality/sbom-upload@v1
        with:
          url: 'https://dependency-track.example.com'
          api-key: ${{ secrets.DEPENDENCY_TRACK_API_KEY }}
          project-sbom: 'sbom.json'

CLI Usage

# Set environment variables
export INPUT_URL="https://dependency-track.example.com"
export INPUT_API_KEY="your-api-key"

# Test connection
PYTHONPATH=src python src/main.py test-connection

# Upload single SBOM file
export INPUT_PROJECT_SBOM="sbom.json"
PYTHONPATH=src python src/main.py upload

# Upload SBOM with custom project details (via environment)
export INPUT_PROJECT_SBOM="sbom.json"
export INPUT_PROJECT_NAME="my-app" 
export INPUT_PROJECT_VERSION="1.0.0"
PYTHONPATH=src python src/main.py upload

📖 Documentation

• Quick Start Guide - Get started in minutes
• Usage Examples - Comprehensive examples for GitHub Actions and CLI
• Hierarchy Configuration - Advanced project structures
• CLI Reference - Complete command-line interface documentation

🛠️ Installation

For GitHub Actions

No installation required - just reference the action in your workflow.

For CLI Development

git clone https://github.com/scality/sbom-upload.git
cd sbom-upload
pip install -r requirements.txt

🎯 Use Cases

• CI/CD Integration - Automatically upload SBOMs on builds/releases
• Multi-Service Applications - Manage complex project hierarchies
• Security Compliance - Track dependencies across your organization
• Version Management - Maintain accurate version histories
• Development Workflows - Test uploads locally before deployment

📊 Supported Scenarios

Scenario	GitHub Action	CLI	Documentation
Single SBOM Upload	✅	✅	Examples
Multiple SBOMs	✅	✅	Examples
Nested Projects	✅	✅	Examples
Auto Hierarchy Generation	✅	✅	Usage Examples
Custom Hierarchies	❌	✅	Hierarchy Config
Version Detection	✅	✅	Usage Examples
Dry Run Testing	❌	✅	CLI Reference

🔧 Configuration

GitHub Action Inputs

Input	Required	Description	Example
url	✅	Dependency Track server URL	https://dt.example.com
api-key	✅	API key for authentication	${{ secrets.DT_API_KEY }}
project-sbom	✅*	Path to single SBOM file	dist/sbom.json
project-sbom-list	✅*	Path to file with SBOM list	sbom-files.txt
project-sbom-dir	✅*	Directory containing SBOMs	dist/sboms/
project-name	❌	Override project name	my-application
project-version	❌	Override project version	1.2.3
parent-project-name	❌	Parent project name	main-app
parent-project-version	❌	Parent project version	2.0.0
project-classifier	❌	Project type classifier	APPLICATION
parent-project-classifier	❌	Parent project classifier	APPLICATION
project-collection-logic	❌	Collection logic for children	AGGREGATE_DIRECT_CHILDREN
parent-project-collection-logic	❌	Parent collection logic	AGGREGATE_DIRECT_CHILDREN
is-latest	❌	Mark as latest version	true
auto-detect-latest	❌	Auto-detect latest flag	true
api-timeout	❌	API timeout (seconds)	300
dry-run	❌	Validate without uploading	true
project-prefix	❌	Prefix for project names	ci-
project-suffix	❌	Suffix for project names	-prod
project-tags	❌	Comma-separated tags	production,ci-cd
delete-on-version-suffix-match	❌	Delete existing leaf project when version matches suffix pattern (default false)	true
delete-version-suffix-pattern	❌	Case-insensitive regex evaluated against project version when delete is enabled (default dev)	dev$

*One of project-sbom, project-sbom-list, or project-sbom-dir is required.

View all inputs →

🧪 Local Development

# Start local Dependency Track instance
cd tests
docker-compose up -d

# Test connection
PYTHONPATH=src python src/main.py test-connection

# Upload test SBOM
export INPUT_PROJECT_SBOM="tests/single_sbom/nginx_12.9.1.json"
export INPUT_DRY_RUN="true"
PYTHONPATH=src python src/main.py upload

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

🔗 Related Projects

• Dependency Track - Software composition analysis platform
• CycloneDX - SBOM standard specification
• SPDX - Software package data exchange format

📞 Support

• 📚 Documentation
• 🐛 Issues
• 💬 Discussions