Quickstart

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, make sure to 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
🎤 Action name
   PyAction Hello World
🎤 Action's slug
   pyaction-hello-world
🎤 Short description
   This actions says Hello to you!
🎤 Author's name
   John Doe
🎤 Python version
   3.12
🎤 Include workflow testing pipeline
   Yes

Copying from template version None
    create  pyaction-hello-world
    create  pyaction-hello-world/.github
    create  pyaction-hello-world/.github/workflows
    create  pyaction-hello-world/.github/workflows/test.yml
    create  pyaction-hello-world/action.yml
    create  pyaction-hello-world/Dockerfile
    create  pyaction-hello-world/README.md
    create  pyaction-hello-world/.dockerignore
    create  pyaction-hello-world/.gitignore
    create  pyaction-hello-world/.env
    create  pyaction-hello-world/main.py
    create  pyaction-hello-world/pyproject.toml

✨ Your action `pyaction-hello-world` has been created successfully!
🔗 Visit https://pyaction.imsadra.me/docs/quickstart for a quick demonstration.

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 also available here. Feel free to look over it.

Updated on