Skip to content

Introducing PyAction

PyAction is a Cookiecutter template that allows you to develop GitHub Actions using Python language. This documentation covers a fundamental overview of the project, a demo action, and the keynotes you need to remember if you want to push your actions to the GitHub Marketplace.

import os
import sys
from typing import List

from actions import io

def main(args: List[str]) -> None:
    """main function

        args (list[str]): STDIN arguments

    name = os.environ["INPUT_NAME"] #(1)

        "message": f"Hi {name}!" #(2)

if __name__ == "__main__":
  1. Simply read the values that your action users send via the with statement within their workflow YAML file.

      - uses: you/your-action@v0.1.0
          name: John


    Keep in mind that you have to update the action.yml file in order to support receiving the name variable from the users respectively.

  2. Here is how you can return data to the workflow, store it, and use it as inputs for other steps inside your workflow. To retrieve message, give an id to your action execution step and then access the value via ${{ steps.<id>.outputs.message }}.

      - id: greetings
        name: Using your-action
        uses: you/your-action@v0.1.0
          name: John
      - name: Echo message
        run: |
          echo ${{ steps.greetings.outputs.message }}

In Theory

Custom GitHub Actions can be developed in three ways.

  • Docker-based Actions
  • Javascript Actions
  • Composite Actions

PyAction is based on the Dockerfile implementation that GitHub recommends and has some workflow-related features that allow you to have access to the variables and data transferring during your workflow run.


The first step is to install the cookiecutter package on your machine.

pip install -U cookiecutter

To ensure that the installation process was successful, check out the installed version with the -V flag.

cookiecutter -V


Now, it's time to generate a template. Easily do this via the following command and after a few promptings, you'll have your action created!

cookiecutter gh:lnxpy/cookiecutter-pyaction

In the next section, we'll be taking a look over each question that's being asked and the proper answers you can give to each one.


These are the questions that by answering them, you'll have the most suited action for your case.


The name that you choose from your action.

If you want to publish to the marketplace..

Make sure that the slugged version of your action name is unique. To check if it's unique, all the following URLs should lead you to a 404 page.



Slugged version of your action name. The best option is to leave it as how it is by default.


A short description for your action. GitHub will use this description to showcase your action on their action explore page.


The action author's name. You can put your both first and last name together.


Choose an open-source license or notopensource if your action is not open-source.


The Python version that you want to use in your action. Both Python3.X and Python2.X are supported.


Answer y if your action has some additional dependencies. This option creates a requirements.txt file and adds a new Dockerfile layer before your action execution whereas it ensures that all your action dependencies are installed.


Creats a .github/workflows/test.yml basic configuration for self-testing your action.