Skip to content

Collection of python functions that can be used to run GitHub Action Workflow Commands

License

Notifications You must be signed in to change notification settings

saadmk11/github-action-utils

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

64 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

GitHub Action Utils

GitHub release (latest by date) Django Tests Codecov GitHub GitHub stars

Actions Workflow Run

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

s3

Log Annotations and Build Summery

s2

Log Annotations Associated with a File

s

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.