github-action-utils 1.1.0

Description:

githubactionutils 1.1.0

GitHub Action Utils






This package is a collection of python functions that can be used to run GitHub Action Workflow Commands from a python script inside an action workflow run.
Requirements
Python: 3.6, 3.7, 3.8, 3.9, 3.10, 3.11
Installation
Install github-action-utils using pip:
pip install github-action-utils

Example
Example Code
import github_action_utils as gha_utils

with gha_utils.group("My Group"):
gha_utils.set_output("test_var", "test_value")
gha_utils.save_state("state", "val")

gha_utils.debug("Debug message")

gha_utils.warning(
"Warning message", title="Warning Title", file="example.py",
col=1, end_column=2, line=5, end_line=6,
)
gha_utils.warning("Another warning message")

gha_utils.error(
"Error message", title="Error Title", file="example.py",
col=1, end_column=2, line=1, end_line=2,
)
gha_utils.notice("Another notice message")

gha_utils.append_job_summary("# Hello World")
gha_utils.append_job_summary("- Point 1")
gha_utils.append_job_summary("- Point 2")

Can be used inside a Workflow
name: run-python-script

on:
pull_request:
branches: [ "main" ]

jobs:
build:

runs-on: ubuntu-latest

steps:
- uses: actions/checkout@v3

- name: Set up Python 3.10
uses: actions/setup-python@v3
with:
python-version: "3.10"

- name: Install dependencies
run: python -m pip install github-action-utils

- name: Run Python Script
shell: python
run: |
import github_action_utils as gha_utils

with gha_utils.group("My Group"):
gha_utils.error(
"Error message", title="Error Title", file="example.py",
col=1, end_column=2, line=1, end_line=2,
)
gha_utils.notice("Another notice message")
gha_utils.append_job_summary("# Hello World")

Colorful Grouped Build Log Output

Log Annotations and Build Summery

Log Annotations Associated with a File

Available Functions
This section documents all the functions provided by github-action-utils. The functions in the package should be used inside a workflow run.
Note: You can run the commands using python's subprocess module by using use_subprocess function parameter or COMMANDS_USE_SUBPROCESS environment variable.
echo(message, use_subprocess=False)
Prints specified message to the action workflow console.
example:
>> from github_action_utils import echo

>> echo("Hello World")

# Output:
# Hello World

debug(message, use_subprocess=False)
Prints colorful debug message to the action workflow console.
GitHub Actions Docs: debug
example:
>> from github_action_utils import debug

>> debug("Hello World")

# Output:
# ::debug ::Hello World

notice(message, title=None, file=None, col=None, end_column=None, line=None, end_line=None, use_subprocess=False)
Prints colorful notice message to the action workflow console.
GitHub Actions Docs: notice
example:
>> from github_action_utils import notice

>> notice(
"test message",
title="test title",
file="abc.py",
col=1,
end_column=2,
line=4,
end_line=5,
)

# Output:
# ::notice title=test title,file=abc.py,col=1,endColumn=2,line=4,endLine=5::test message=

warning(message, title=None, file=None, col=None, end_column=None, line=None, end_line=None, use_subprocess=False)
Prints colorful warning message to the action workflow console.
GitHub Actions Docs: warning
example:
>> from github_action_utils import warning

>> warning(
"test message",
title="test title",
file="abc.py",
col=1,
end_column=2,
line=4,
end_line=5,
)

# Output:
# ::warning title=test title,file=abc.py,col=1,endColumn=2,line=4,endLine=5::test message

error(message, title=None, file=None, col=None, end_column=None, line=None, end_line=None, use_subprocess=False)
Prints colorful error message to the action workflow console.
GitHub Actions Docs: error
example:
>> from github_action_utils import error

>> error(
"test message",
title="test title",
file="abc.py",
col=1,
end_column=2,
line=4,
end_line=5,
)

# Output:
# ::error title=test title,file=abc.py,col=1,endColumn=2,line=4,endLine=5::test message

set_output(name, value)
Sets a step's output parameter by writing to GITHUB_OUTPUT environment file. Note that the step will need an id to be defined to later retrieve the output value.
GitHub Actions Docs: set_output
example:
>> from github_action_utils import set_output

>> set_output("my_output", "test value")

save_state(name, value)
Creates an environment variable by writing this to the GITHUB_STATE environment file which is available to workflow's pre: or post: actions.
GitHub Actions Docs: save_state
example:
>> from github_action_utils import save_state

>> save_state("my_state", "test value")

get_state(name)
Gets state environment variable from running workflow.
example:
>> from github_action_utils import get_state

>> get_state("test_name")

# Output:
# test_value

get_user_input(name)
Gets user input from running workflow.
example:
>> from github_action_utils import get_user_input

>> get_user_input("my_input")

# Output:
# my value

begin_stop_commands(token=None, use_subprocess=False) and end_stop_commands(token, use_subprocess=False)
Stops processing any workflow commands. This special command allows you to log anything without accidentally running a workflow command.
GitHub Actions Docs: stop_commands
example:
>> from github_action_utils import echo, begin_stop_commands, end_stop_commands, stop_commands

>> begin_stop_commands(token="my_token")
>> echo("Hello World")
>> end_stop_commands("my_token")

# Output:
# ::stop-commands ::my_token
# Hello World
# ::my_token::

# ====================
# Using Stop Commands Context Manager
# ====================

>> with stop_commands(token="my_token"):
... echo("Hello World")

# Output:
# ::stop-commands ::my_token
# Hello World
# ::my_token::

start_group(title, use_subprocess=False) and end_group(use_subprocess=False)
Creates an expandable group in the workflow log.
GitHub Actions Docs: group
example:
>> from github_action_utils import echo, start_group, end_group, group

>> start_group("My Group Title")
>> echo("Hello World")
>> end_group()

# Output:
# ::group ::My Group Title
# Hello World
# ::endgroup::

# ====================
# Using Group Context Manager
# ====================

>> with group("My Group Title"):
... echo("Hello World")

# Output:
# ::group ::My Group Title
# Hello World
# ::endgroup::

add_mask(value, use_subprocess=False)
Masking a value prevents a string or variable from being printed in the workflow console.
GitHub Actions Docs: add_mask
example:
>> from github_action_utils import add_mask

>> add_mask("test value")

# Output:
# ::add-mask ::test value

set_env(name, value)
Creates an environment variable by writing this to the GITHUB_ENV environment file which is available to any subsequent steps in a workflow job.
GitHub Actions Docs: set_env
example:
>> from github_action_utils import set_env

>> set_env("my_env", "test value")

get_workflow_environment_variables()
Gets all environment variables from the GITHUB_ENV environment file which is available to the workflow.
GitHub Actions Docs: set_env
example:
>> from github_action_utils import get_workflow_environment_variables

>> get_workflow_environment_variables()

# Output:
# {"my_env": "test value"}

get_env(name)
Gets all environment variables from os.environ or the GITHUB_ENV environment file which is available to the workflow.
This can also be used to get environment variables set by GitHub Actions.
GitHub Actions Docs: set_env
example:
>> from github_action_utils import get_env

>> get_env("my_env")
>> get_env("GITHUB_API_URL")

# Output:
# test value
# https://api.github.com

append_job_summary(markdown_text)
Sets some custom Markdown for each job so that it will be displayed on the summary page of a workflow run.
GitHub Actions Docs: append_job_summary
example:
>> from github_action_utils import append_job_summary

>> append_job_summary("# test summary")

overwrite_job_summary(markdown_text)
Clears all content for the current step, and adds new job summary.
GitHub Actions Docs: overwrite_job_summary
example:
>> from github_action_utils import overwrite_job_summary

>> overwrite_job_summary("# test summary")

remove_job_summary()
completely removes job summary for the current step.
GitHub Actions Docs: remove_job_summary
example:
>> from github_action_utils import remove_job_summary

>> remove_job_summary()

add_system_path(path)
Prepends a directory to the system PATH variable (GITHUB_PATH) and automatically makes it available to all subsequent actions in the current job.
GitHub Actions Docs: add_system_path
example:
>> from github_action_utils import add_system_path

>> add_system_path("var/path/to/file")

event_payload()
Get GitHub Event payload that triggered the workflow.
More details: GitHub Actions Event Payload
example:
>> from github_action_utils import event_payload

>> event_payload()

# Output:
# {"action": "opened", "number": 1, "pull_request": {"url": "https://api.github.com/repos/octocat/Hello-World/pulls/1"}, "repository": {"url": "https://api.github.com/repos/octocat/Hello-World"}, "sender": {"login": "octocat"}...}

License
The code in this project is released under the MIT License.