Getting Started

Popper is a workflow execution engine based on Github Actions (GHA) written in Python. With Popper, you can execute HCL syntax workflows locally on your machine without having to use Github’s platform.


We provide a pip package for Popper. To install simply run:

pip install popper

Depending on your Python distribution or specific environment configuration, using Pip might not be possible (e.g. you need administrator privileges) or using pip directly might incorrectly install Popper. We highly recommend to install Popper in a Python virtual environment using virtualenv. The following installation instructions assume that virtualenv is installed in your environment (see here for more). Once virtualenv is available in your machine, we proceed to create a folder where we will place the Popper virtual environment:

# create a folder for storing virtual environments
mkdir $HOME/virtualenvs

We then create a virtualenv for Popper. This will depend on the method with which virtualenv was installed. Here we present three alternatives that cover most of these alternatives:

# 1) virtualenv installed via package, e.g.:
# - apt install virtualenv (debian/ubuntu)
# - yum install virtualenv (centos/redhat)
# - conda install virtualenv (conda)
# - pip install virtualenv (pip)
virtualenv $HOME/virtualenvs/popper

# 2) virtualenv installed via Python 3.6+ built-in module
python -m venv $HOME/virtualenvs/popper
NOTE: in the case of conda, we recommend the creation of a new environment before virtualenv is installed in order to avoid issues with packages that might have been installed previously.

We then load the environment we just created above:

source $HOME/virtualenvs/popper/bin/activate

Finally, we install Popper in this environment using pip:

pip install popper

To test all is working as it should, we can show the version we installed:

popper version

And to get a list of available commands:

popper --help
NOTE: given that we are using virtualenv, once the shell session is ended (when we close the terminal window or tab), the environment is unloaded and newer sessions (new window or tab) will not have the popper command available in the PATH variable. In order to have the environment loaded again we need to execute the source command (see above). In the case of conda we need to load the Conda environment (conda activate command).

Create a Git repository

Create a project repository (if you are not familiar with Git, look here):

mkdir myproject
cd myproject
git init
echo '# myproject' >
git add .
git commit -m 'first commit'

Create a workflow

First, we create an example .workflow file with a pre-defined workflow:

popper scaffold

The above generates an example workflow that you can use as the starting point of your project. We first commit the files that got generated:

git add .
git commit -m 'Adding example workflow.'

To learn more about how to modify this workflow in order to fit your needs, please take a look at the workflow language documentation read this tutorial, or take a look at some examples.

Run your workflow

To execute the workflow you just created:

popper run

You should see the output of actions printed to the terminal.

Continuously Run Your Workflow on Travis

For this, we need to login to Travis CI using our Github credentials. Once this is done, we activate the project so it is continuously validated.

Generate .travis.yml file:

popper ci travis

And commit the file:

git add .travis.yml
git commit -m 'Adds TravisCI config file'

Trigger an execution by pushing to github:

git push

Go to the TravisCI website to see your experiments being executed.