GitHub Action Utils

Warnings

• breaking GitHub Actions deprecated the `::set-output::` and `::save-state::` commands via stdout, shifting to environment files (`$GITHUB_OUTPUT`, `$GITHUB_STATE`). The `github-action-utils` library updated its `set_output` and `save_state` implementations in version `1.1.0` to align with these new GitHub recommendations. While the function signatures in the library remained the same, the underlying mechanism changed.
  Fix: Upgrade to `github-action-utils>=1.1.0`. Ensure your workflow runners are up-to-date (version 2.298.2 or greater for warnings, and generally updated to avoid failures for direct stdout commands). Users relying on the *old internal behavior* of these functions might need to verify compatibility, though the library aims to provide the correct interface for the new GitHub spec.
• gotcha The `group()` context manager had a bug in versions prior to `1.0.2` where the `end_group()` function call might not correctly pass the `use_subprocess` parameter, leading to inconsistent behavior if subprocess execution was desired.
  Fix: Upgrade to `github-action-utils>=1.0.2` to ensure consistent handling of the `use_subprocess` parameter within the `group()` context manager.
• gotcha By default, `github-action-utils` might directly interact with GitHub Action workflow commands through standard output. In some highly restrictive or isolated environments, it might be necessary to force commands to run via Python's `subprocess` module. This can be controlled via the `use_subprocess` parameter in functions or the `COMMANDS_USE_SUBPROCESS` environment variable.
  Fix: If encountering issues with workflow commands not being recognized, try setting `use_subprocess=True` on individual function calls (e.g., `gha_utils.echo("msg", use_subprocess=True)`) or setting the environment variable `COMMANDS_USE_SUBPROCESS=true` for the workflow step.

Install

• pip install github-action-utils Install latest version

Imports

• All functions

  import github_action_utils as gha_utils

• Specific functions

  from github_action_utils import set_output, save_state, group

Quickstart

This quickstart demonstrates how to use various utility functions provided by `github-action-utils` within a Python script running as part of a GitHub Action workflow. It covers setting outputs and state, logging messages at different levels, and appending content to the job summary. Outputs and state variables are automatically registered with the GitHub Actions runner.

import github_action_utils as gha_utils
import os

# Example usage within a GitHub Action workflow
# Outputs and state are typically picked up by the GitHub Actions runner.

# Using a group to organize log output
with gha_utils.group("My Python Script Group"):
    # Set an output variable
    gha_utils.set_output("my_output_key", "my_output_value")
    print(f"Set output: my_output_key='my_output_value'")

    # Save a state variable (for subsequent jobs in the same workflow)
    gha_utils.save_state("my_state_key", "my_state_value")
    print(f"Saved state: my_state_key='my_state_value'")

    # Log messages with different severities
    gha_utils.debug("This is a debug message.")
    gha_utils.notice("This is a notice message.")
    gha_utils.warning("This is a warning message.", title="Python Warning")
    gha_utils.error("This is an error message.", title="Python Error")

    # Append content to the job summary
    gha_utils.append_job_summary("# Python Script Summary\n\n- Task A Completed\n- Task B Completed")
    print("Appended to job summary.")

# Retrieve environment variables set by GitHub Actions
repo_owner = os.environ.get('GITHUB_REPOSITORY_OWNER', 'unknown_owner')
print(f"Running in repository owned by: {repo_owner}")