Actions Tools

• Install
• Usage
• Support
• Contributing

A Typed Python GitHub Actions Tookit similar to actions/toolkit.

• http://actions-tools.cssnr.com

Note

This project is in active development.
Please let us know what features you want to see.

Install

From PyPI: https://pypi.org/p/actions-tools

python -m pip install actions-tools

With PyGithub (for GitHub API access).

python -m pip install actions-tools[github]

Install from GitHub.

python -m pip install git+https://github.com/cssnr/actions-tools.git

Install from source.

git clone https://github.com/cssnr/actions-tools
python -m pip install actions-tools

Uninstall.

python -m pip uninstall actions-tools

Usage

Tip

View the Usage Guide online.

Functionality from @actions/toolkit

from actions import core, context

# Input
my_str = core.get_input("string")  # -> str
my_req = core.get_input("string", True)  # required
my_bool = core.get_bool("boolean")  # -> bool
my_list = core.get_list("list")  # -> list
my_dict = core.get_dict("dict")  # -> dict - from json or yaml
my_data = core.get_data("data")  # -> Any - from json or yaml

# Context
# https://docs.github.com/en/actions/reference/workflows-and-actions/variables
core.info(f"event_name: {context.event_name}")
core.info(f"ref_name: {context.ref_name}")
core.info(f"runner_temp: {context.runner_temp}")

# Event
# https://docs.github.com/en/webhooks/webhook-events-and-payloads
event = core.get_event()  # -> dict
core.info(str(event))
repository = event.get("repository")

# Logging
core.info("info")  # alias for print
core.debug("debug")

# Annotations
# https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-commands#setting-a-notice-message
core.notice("notice")
core.warn("warn")
core.error("error", title="Title", file="File", col=1, endColumn=2, line=3, endLine=4)

# Blocks
core.start_group("Title")
core.info("This is folded.")
core.end_group()

with core.group("Title") as p:
    p("This is folded.")
    core.info("Also folded.")

# Environment
core.set_env("NAME", "value")

# State
name = core.set_state("name", "value")
value = core.get_state("name")

# System Path
core.add_path("/dev/null")

# Set Secret
core.mask("super-secret-string")

# Outputs
core.set_output("name", "cssnr")

# Commands
core.stop_commands()
core.info("::error::log output with commands")
core.start_commands()

# Abort
core.set_failed("Mayday!")

# Runner Debug
core.is_debug()

# PyGithub (Octokit)
# https://pygithub.readthedocs.io/en/stable/
token = core.get_input("token", True)
g = core.get_github(token)
repo = g.get_repo(context.repository)
core.info(f"repo.name: {repo.name}")

# OIDC Token
# https://docs.github.com/en/actions/reference/security/oidc
id_token = core.get_id_token()

# Summary
core.summary.add_raw("text")
# text\n
core.summary.add_eol()
# \n
core.summary.add_code("from actions import core", "python")
# \n<pre lang="python"><code>from actions import core</code></pre>\n\n
core.summary.add_list(["item 1", "item 2"])
# \n<ul><li>item 1</li>\n<li>item 2</li></ul>\n\n
core.summary.add_details("Summary", "Details...")
# \n<details><summary>Summary</summary>Details...</details>\n\n
core.summary.add_image("src", "alt", 100)
# \n<img src="src" alt="alt" width="100" height="auto">\n\n
core.summary.add_heading("Heading", 1)
# \n<h1>Heading</h1>\n\n
core.summary.add_hr()
# \n<hr>\n\n
core.summary.add_br()
# \n<br>\n\n
core.summary.add_quote("I broke it.", "ralf")
# \n<blockquote cite="ralf">I broke it.</blockquote>\n\n
core.summary.add_link("text", "href")
# \n<a href="href">text</a>\n\n
# \n<a href="href">text</a>\n\n
core.summary.add_table([["Head 1", "Head 2"], ["data 1", "data 2"]])
# \n<table><thead><tr><th>Head 1</th><th>Head 2</th></tr></thead>
# <tbody><tr><td>data 1</td><td>data 2</td></tr></tbody></table>\n\n

with core.summary.with_code("text") as add:
    add("line 1")
    add("line 2")
# \n<pre lang="text"><code>line 1\nline 2</code></pre>\n\n

with core.summary.with_list() as add:
    add("line 1")
    add("line 2")
# \n<ul>\n<li>line 1</li>\n<li>line 2</li>\n</ul>\n\n

with core.summary.with_details("Summary") as add:
    add("line 1")
    add("line 2")
# \n<details><summary>Summary</summary>\n\nline 1\nline 2\n\n</details>\n\n

• Full core reference: ../src/actions/core.py
• Full context reference: ../src/actions/context.py

Functionality new in actions-tools

from actions import core, context

# Context
core.info(f"repository_name: {context.repository_name}")

# Commands
core.command("warning", "Warned!")  # core.warn()

# Action Version
version = core.get_version()  # from GITHUB_WORKFLOW_REF

# Random
rand = core.get_random(32)

# Indent
core.start_indent(4)
core.info("Indented")  # only works with core.info
core.end_indent()

Example Actions.

• Create Files Action: cssnr/create-files-action
• Python Action Template: smashedr/test-action-py
• Python UV Action Template: smashedr/test-action-uv

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue: https://github.com/cssnr/actions-tools/issues
• Q&A Discussion: https://github.com/cssnr/actions-tools/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/actions-tools/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

Contributing

If you would like to submit a PR, please review the CONTRIBUTING.md.

Please consider making a donation to support the development of this project and additional open source projects.

Additionally, you can support other GitHub Actions I have published:

• Stack Deploy Action
• Portainer Stack Deploy Action
• Docker Context Action
• Actions Up Action
• Rhysd Actionlint Action
• Zensical Action
• VirusTotal Action
• Mirror Repository Action
• Update Version Tags Action
• Docker Tags Action
• TOML Action
• Update JSON Value Action
• JSON Key Value Check Action
• Parse Issue Form Action
• Cloudflare Purge Cache Action
• Mozilla Addon Update Action
• Package Changelog Action
• NPM Outdated Check Action
• Label Creator Action
• Algolia Crawler Action
• Upload Release Action
• Check Build Action
• Web Request Action
• Get Commit Action

❔ Unpublished Actions

These actions are not published on the Marketplace, but may be useful.

• cssnr/create-files-action - Create various files from templates.
• cssnr/draft-release-action - Keep a draft release ready to publish.
• cssnr/env-json-action - Convert env file to json or vice versa.
• cssnr/push-artifacts-action - Sync files to a remote host with rsync.
• smashedr/update-release-notes-action - Update release notes.
• smashedr/combine-release-notes-action - Combine release notes.

---

📝 Template Actions

These are basic action templates that I use for creating new actions.

• javascript-action - JavaScript
• typescript-action - TypeScript
• py-test-action - Dockerfile Python
• test-action-uv - Dockerfile Python UV
• docker-test-action - Docker Image Python

Note: The docker-test-action builds, runs and pushes images to GitHub Container Registry.

---

For a full list of current projects visit: https://cssnr.github.io/