README.md

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.