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.
Python: 3.6, 3.7, 3.8, 3.9, 3.10, 3.11
Install github-action-utils using pip:
pip install github-action-utilsimport 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")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")
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.
Prints specified message to the action workflow console.
example:
>> from github_action_utils import echo
>> echo("Hello World")
# Output:
# Hello WorldPrints 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 Worldnotice(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 messageerror(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 messageSets 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")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")Gets state environment variable from running workflow.
example:
>> from github_action_utils import get_state
>> get_state("test_name")
# Output:
# test_valueGets user input from running workflow.
example:
>> from github_action_utils import get_user_input
>> get_user_input("my_input")
# Output:
# my valuebegin_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::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::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 valueCreates 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")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"}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.comSets 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")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")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()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")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"}...}The code in this project is released under the MIT License.
![@github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=64&v=4){kind=small}
![@dependabot[bot]](https://avatars.githubusercontent.com/in/29110?s=64&v=4){kind=small}