Skip to content

Issue 401 GitHub action outputs#1403

Open
lilfetz22 wants to merge 6 commits intopython-semantic-release:masterfrom
lilfetz22:issue-401-github-action-outputs
Open

Issue 401 GitHub action outputs#1403
lilfetz22 wants to merge 6 commits intopython-semantic-release:masterfrom
lilfetz22:issue-401-github-action-outputs

Conversation

@lilfetz22
Copy link
Contributor

@lilfetz22 lilfetz22 commented Jan 1, 2026

Purpose

Resolves: #401

Adds four new GitHub Action outputs to provide access to release asset information:

  • id: The GitHub release ID for API interactions
  • upload_url: The upload URL template for adding additional assets
  • assets: JSON array of all uploaded asset metadata
  • assets_dist: JSON object organizing distribution files by type (wheel/sdist)

These outputs enable downstream workflow steps to programmatically access and process release artifacts, download specific distribution files, or interact with the release via the GitHub API.

Rationale

The implementation follows the existing pattern established in VersionGitHubActionsOutput:

  1. Data Structure: Created a ReleaseInfo NamedTuple in the GitHub HVCS to encapsulate release metadata (id, upload_url, assets) returned from the GitHub API. This provides a clean, typed structure for passing release information.

  2. Property Design: Added validated properties to VersionGitHubActionsOutput that:

    • Accept optional values (can be None for non-release scenarios)
    • Perform type validation in setters
    • Return empty strings/structures when unset (consistent with existing outputs)

  3. JSON Serialization: Used json.dumps() for complex data structures (assets list and assets_dist dict) to ensure proper formatting in GitHub Actions output files.

  4. Computed Property: Implemented assets_dist as a computed property that categorizes assets by file extension (.whl → "wheel", .tar.gz → "sdist"). This provides convenience for common use cases without requiring users to parse the assets array.

  5. Type Safety: Updated the HVCS base class and all implementations to maintain type consistency with Union types, ensuring compatibility across different hosting services.

Problems Avoided:

  • Breaking changes: All new outputs use default empty values, so existing workflows continue to work
  • Type errors: Comprehensive type hints and validation prevent runtime issues
  • Line ending issues: Tests properly handle platform-specific line endings (CRLF on Windows)

How did you test?

Unit Tests (9 new tests in test_github_actions_output.py)

  1. Property getters/setters: Verified each new property correctly stores and retrieves values
  2. Type validation: Tested that TypeError is raised for invalid types (e.g., passing string instead of int for release_id)
  3. Computed property logic: Validated assets_dist correctly categorizes .whl and .tar.gz files
  4. Output formatting: Confirmed new fields appear in output with correct JSON serialization
  5. File writing: Verified JSON structures are properly written to GITHUB_OUTPUT file and can be parsed
  6. Updated existing test: Modified test_version_github_actions_output_format to expect new fields with proper line ending handling

E2E Test (updated test_version_writes_github_actions_output)

  • Verified new outputs are written to GITHUB_OUTPUT file during actual CLI execution
  • Tested with --no-push flag where fields are empty (no GitHub release created)
  • Validated output format matches expected structure

Manual Validation

  • Ran ruff format and ruff check - all checks pass
  • Ran mypy . - no type errors
  • All 19 unit tests pass
  • E2E test passes (6.37s execution time)

Edge Cases Considered:

  • Empty/None values for optional properties
  • Non-release scenarios (outputs remain empty)
  • Platform-specific line endings (Windows CRLF vs Unix LF)
  • Assets without recognized extensions (categorized by actual extension)

How to Verify

  1. Checkout and setup:

    git checkout issue-401-github-action-outputs
pip install -e .[dev,test]

  2. Run unit tests:

    pytest tests/unit/semantic_release/cli/test_github_actions_output.py -v

    All 19 tests should pass, including the 9 new tests for release asset outputs.

  3. Run E2E test:

    pytest tests/e2e/cmd_version/test_version_github_actions.py::test_version_writes_github_actions_output -v

    Test should pass and verify new fields are written to GITHUB_OUTPUT.

  4. Run type checking:

    mypy src

    Should complete with no errors.

  5. Run linting:

    ruff check .
ruff format --check .

    All checks should pass.

  6. Review documentation:
    Open docs/configuration/automatic-releases/github-actions.rst and verify:

    • New output definitions for id, upload_url, assets, assets_dist
    • "Using Release Assets Outputs" example section with practical usage

  7. Review action definition:
    Check action.yml to confirm all four outputs are defined with descriptions.

PR Completion Checklist

  • Reviewed & followed the Contributor Guidelines

  • Changes Implemented & Validation pipeline succeeds

  • Commits follow the Conventional Commits standard
    and are separated into the proper commit type and scope (recommended order: test, build, feat/fix, docs)

  • Appropriate Unit tests added/updated

  • Appropriate End-to-End tests added/updated

  • Appropriate Documentation added/updated and syntax validated for sphinx build (see Contributor Guidelines)

@lilfetz22
feat(github-actions): add asset-related outputs to GitHub Action
a99e90c 
Add support for new GitHub Action outputs to expose release asset information:
- id: The release ID from the remote VCS
- upload_url: URL for uploading additional assets to the release
- assets: JSON array containing information about all uploaded assets
- assets_dist: JSON object of Python dist assets organized by type (wheel, sdist)

These outputs enable users to programmatically access release metadata and
uploaded asset information in their GitHub workflows. Asset information includes
details such as name, size, content_type, and browser_download_url.

Changes:
- Updated VersionGitHubActionsOutput class with new properties for release_id,
  upload_url, assets, and assets_dist
- Modified Github.create_release() to return ReleaseInfo namedtuple containing
  release ID, upload URL, and asset details
- Updated upload_release_asset() to return asset metadata from API response
- Added new output definitions to action.yml with detailed descriptions
- Updated type signatures across HVCS implementations to support ReleaseInfo
- Updated version command to populate new outputs after release creation

Implements: python-semantic-release#401
@lilfetz22
test(github-actions): add unit tests for new output properties
2e9b477 
Adds comprehensive unit tests for the new GitHub Actions output properties:
- release_id property and validation
- upload_url property and validation
- assets list property and validation
- assets_dist computed property (categorizes by wheel/sdist)
- Output format includes new fields
- File writing with JSON serialization

Also updates existing test_version_github_actions_output_format to expect
the new fields in the output with proper line ending handling.
@lilfetz22
docs(github-actions): document new release asset outputs
8ea9899 
Adds documentation for the new GitHub Actions outputs:
- id: Release ID from GitHub API
- upload_url: URL for uploading additional assets
- assets: JSON array of all uploaded asset metadata
- assets_dist: JSON object organizing assets by type (wheel/sdist)

Includes a new 'Using Release Assets Outputs' example section demonstrating:
- How to download specific distribution files
- How to list all assets
- How to use the release ID with the GitHub API
@lilfetz22
test(e2e): update GitHub Actions output test for new fields
eee92c1 
Updates test_version_writes_github_actions_output to verify the new
output fields (id, upload_url, assets, assets_dist) are correctly
written to the GITHUB_OUTPUT file. When using --no-push, these fields
will be empty strings or empty JSON structures since no GitHub release
is created.
@lilfetz22
style(github-actions): format multiline output generation
7f53427 
Wraps the conditional expression for multiline output values in
parentheses to improve readability and comply with code style
guidelines. This change improves the formatting of the list
comprehension that generates GitHub Actions output lines.

The logic remains unchanged - it still generates either a heredoc
format (<<EOF) for non-empty values or an empty assignment for
empty values.
@lilfetz22
style(cmd-version): format build error log statement
5eb8c63 
Splits the logger.error() call across multiple lines to improve
code readability and comply with line length guidelines. The
error message formatting remains functionally identical.

This change addresses a formatting issue in the build_distributions
function where the error logging statement exceeded preferred line
length limits.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

feat: add GitHub action outputs

1 participant

@lilfetz22