In this demo tutorial, we'll explore a simple hello-world action. By the end of this, we'll have an action that we can use as shown below, and it will return a phrase containing a greeting message based on its input parameter name.
- name: Running Hello-world
uses: username/pyaction-hello-world@v0.1.0
with:
name: Sadra
Initialization
If you plan to publish your action to GitHub Marketplace, check out this page before initializing your action.
First, you need to create a basic structure for your action. To start, after installing pyaction[cli], generate a base template for the action using the init command.
pyaction init
We’re naming our action PyAction Hello World. Change your current directory to pyaction-hello-world/ to begin the development.
cd pyaction-hello-world/
Development
Once we have our action set up, it's time to initialize a Git directory. This allows us to push it to a GitHub repository and keep track of it.
git init && git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin git@github.com:<username>/pyaction-hello-world.git
Don’t forget to replace <username> with your actual GitHub username.
Action Configuration (action.yml)
This YAML file indicates the basic configurations of the action. We can define the action name, description, and branding there.
More importantly, this is where we declare the inputs and outputs of the action, so let’s define one input parameter called name and one output called phrase.
...
inputs:
...
name:
required: false
description: the person/thing you want to greet
default: World
outputs:
phrase:
description: output message
Action Entrypoint (main.py)
This is the main Python file that gets executed when the workflow container starts. In this file, we have access to all the input parameters and we can write outputs to the workflow.
from pyaction import PyAction
from pyaction.workflow.stream import WorkflowContext
workflow = PyAction()
@workflow.action
def my_action(name: str) -> None:
context = WorkflowContext(
{
"phrase": f"Hi {name}!",
}
)
workflow.write(context)
All my_action arguments should be input parameters of the action, so make sure they are correctly set in the pipeline.
Deploy & Run
To run this action, we have the .github/workflows/test.yml file, which should include the steps. Since we're using an action located in the same repository, we locate the action using uses: ./.
name: Greeting Action
on:
push:
branches:
- main
jobs:
build:
runs-on: ubuntu-latest
name: Running the action
steps:
- name: checkout
uses: actions/checkout@v4
- name: Running Hello-world
id: hello_world
uses: ./
with:
name: Sadra
- name: Output
run: echo ${{ steps.hello_world.outputs.phrase }}
In the end, we simply echo the phrase output from our hello-world action, which should include "Hi Sadra!".
Stage and commit the changes that we’ve made.
git add . && git commit -m "updated"
Also, add a new tag and finally, push to the repository.
git tag v0.1.0
git push origin main --tags
The pyaction-hello-world demo is available here. Feel free to check it out.