LogoActions is a collection of GitHub Actions designed to facilitate the setup and execution of NetLogo models within GitHub workflows. These actions enable researchers and developers to automate the installation of NetLogo, run and test simulations, and integrate NetLogo with other tools and platforms, such as Quarto, logolink and pyNetLogo.
Currently, the repository includes:
setup-netlogo: Installs NetLogo on the runner machinecheck-netlogo: Runs all BehaviorSpace experiments in a repository's NetLogo models to verify they execute without errors
Along with these actions, a series of workflows examples are provided to demonstrate how to use the action in practice. See the Usage section below for more details.
If you find this project useful, please consider giving it a star!
The continuous development of
LogoActionsdepends on community support. If you can afford to do so, please consider becoming a sponsor.
This workflow shows how to use the check-netlogo action to automatically verify that all BehaviorSpace experiments in a repository's NetLogo models run without errors. This is particularly useful for continuous integration (CI) workflows, ensuring that any changes to the models or experiments do not introduce issues.
You can view this workflow in action on the repository's actions page. See the LogoClim model for a real-world example of how this action can catch errors early in the development process.
Below is a basic workflow configuration. To use it, create a file named check-netlogo.yaml with the content below and place it in the .github/workflows folder at the root of your repository.
on:
push:
branches: [main, master]
name: NetLogo check
permissions: read-all
jobs:
check-netlogo:
name: Check NetLogo models
runs-on: ubuntu-latest
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up NetLogo
uses: danielvartan/logoactions/setup-netlogo@v1
- name: Check NetLogo models
uses: danielvartan/logoactions/check-netlogo@v1This workflow shows how to set up NetLogo and run BehaviorSpace experiments in headless mode. Experiment results are saved as CSV files and uploaded as artifacts for later retrieval. This approach is useful for automating simulation runs, conducting parameter sweeps, or integrating NetLogo experiments into data analysis pipelines.
You can view this workflow in action on the repository's actions page. The complete workflow file is available here.
Below is a basic workflow configuration.
on:
push:
branches: [main, master]
name: Run BehaviorSpace experiments
permissions: read-all
jobs:
run-experiments:
name: Run experiments
runs-on: ubuntu-latest
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:
- name: Checkout Repository
uses: actions/checkout@v4
- name: Set up NetLogo
uses: danielvartan/logoactions/setup-netlogo@v1
- name: Create artifacts directory
id: artifacts-dir
run: |
# Create artifacts directory
artifacts_dir="${RUNNER_TEMP}/artifacts"
mkdir -p "${artifacts_dir}"
echo "path=${artifacts_dir}" >> "${GITHUB_OUTPUT}"
shell: bash
- name: Run experiment
run: |
# Run experiment
artifacts_dir="${{ steps.artifacts-dir.outputs.path }}"
model_dir="${NETLOGO_HOME}/models/Sample Models/Biology"
model_file='Wolf Sheep Predation.nlogox'
experiment_name='Wolf Sheep Crossing'
table_file="${artifacts_dir}/experiment-table.csv"
netlogo \
--headless \
--model "${model_dir}/${model_file}" \
--experiment "${experiment_name}" \
--table "${table_file}"
cat "${table_file}"
shell: bash
- name: Upload artifacts
uses: actions/upload-artifact@v4
with:
name: experiments-output
path: ${{ steps.artifacts-dir.outputs.path }}
retention-days: 90This workflow shows how to combine NetLogo with Quarto and the logolink R package to run experiments and generate reproducible reports. It installs all required dependencies, renders the Quarto document, and deploys the output to GitHub Pages. An example report is available here.
You can view this workflow in action on the repository's actions page. The complete workflow file is available here.
Below is a basic workflow configuration.
on:
push:
branches: [main, master]
name: Run experiments with Quarto and logolink
permissions: read-all
jobs:
run-logolink:
runs-on: ubuntu-latest
name: Run experiments
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
permissions:
contents: write
pages: write
steps:
- name: Check out repository
uses: actions/checkout@v4
- name: Set up NetLogo
uses: danielvartan/logoactions/setup-netlogo@v1
- name: Set up R
uses: r-lib/actions/setup-r@v2
- name: Set up Quarto
uses: quarto-dev/quarto-actions/setup@v2
- name: Install system dependencies
if: runner.os == 'Linux'
run: |
# Install system dependencies
sudo apt-get update -qq
sudo apt-get install -y -qq \
libfontconfig1-dev \
pandoc
shell: bash
- name: Install R dependencies
run: |
# Install R dependencies
options(repos=c(CRAN="https://cloud.r-project.org"))
install.packages(
c(
"rmarkdown",
"knitr"
)
)
shell: Rscript {0}
- name: Check if renv is initialized
id: renv-check
run: |
# Check if renv is initialized
if [ -f "renv.lock" ]; then
echo "exists=true" >> $GITHUB_OUTPUT
else
echo "exists=false" >> $GITHUB_OUTPUT
fi
shell: bash
- name: Set up renv
if: steps.renv-check.outputs.exists == 'true'
uses: r-lib/actions/setup-renv@v2
- name: Install and initialize renv
if: steps.renv-check.outputs.exists == 'false'
run: |
# Install and initialize renv
install.packages("renv")
renv::init()
shell: Rscript {0}
- name: Render Quarto
run: |
# Render Quarto
quarto render
shell: bash
- name: Deploy to GitHub Pages
uses: JamesIves/github-pages-deploy-action@v4.5.0
with:
clean: false
branch: gh-pages
folder: docsFor information on workflow RAM, storage, and time limits, refer to the GitHub Actions usage limits page.
The setup-netlogo action is what allows all the examples shown above to run NetLogo models in GitHub Actions workflows. You can easily customize the action to fit your needs.
The action can be integrated into your GitHub Actions workflow simply by adding the following step:
- name: Set up NetLogo
uses: danielvartan/logoactions/setup-netlogo@v1You must also set the GH_TOKEN environment variable to enable authenticated GitHub API requests.
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}This will make NetLogo available for use in subsequent steps.
The action sets up a NetLogo environment by performing the following tasks:
- Download the specified NetLogo version
- Cache the installation (optional)
- Set environment variables:
NETLOGO_HOME: Installation directory pathNETLOGO_CONSOLE: Console executable pathNETLOGO_VERSION: Installed version (e.g.,7.0.3)
- Add
NETLOGO_HOMEtoPATH - Create
netlogoandNetLogosymlinks
After the action completes, you can run NetLogo commands in subsequent steps using netlogo:
- name: Test NetLogo
run: netlogo --headless --versionYou can view setup-netlogo in action on the repository's actions page.
The following inputs are supported:
version: A single-quoted (!important!) character string indicating the NetLogo version to use (e.g.,'7.0.3'). Use'release'to get the latest stable release. Only versions 6.4.0 and above are supported (default:'release').cache: A single-quoted (!important!) boolean value indicating whether the NetLogo installation should be cached across runs (default:'true').
Use the with keyword to change the default values. Example:
- name: Set up NetLogo
uses: danielvartan/logoactions/setup-netlogo@v1
with:
version: '6.4.0'
cache: 'false'The runners ubuntu-latest, windows-latest, and macos-latest are supported. We recommend using ubuntu-latest whenever possible.
The check-netlogo action automates the verification of BehaviorSpace experiments across all NetLogo models in a repository. It ensures experiments run correctly in headless mode, making it ideal for CI pipelines that need to catch model errors early.
The action can be integrated into your GitHub Actions workflow simply by adding the following step:
- name: Check NetLogo models
uses: danielvartan/logoactions/check-netlogo@v1Before using check-netlogo, ensure you check out the repository and set up NetLogo with the setup-netlogo action.
You must also set the GH_TOKEN environment variable to enable authenticated GitHub API requests in setup-netlogo.
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}The action test NetLogo models by performing the following tasks:
- Search the repository for NetLogo model files (
.nlogo,.nlogo3d,.nlogox,.nlogox3d), excluding any paths specified in theignoreinput. - Identify all BehaviorSpace experiments defined within each model.
- Execute each experiment in headless mode using NetLogo's command-line interface.
- Save a table output of each experiment as an artifact (optional).
Note that models with .nlogo and .nlogo3d extensions are skipped when using NetLogo 7 or higher, as these formats are deprecated in recent versions. Similarly, .nlogox and .nlogox3d files are skipped when using NetLogo 6 or lower, as these formats are not supported in earlier versions.
You can view check-netlogo in action on the repository's actions page.
The following inputs are supported:
ignore: A single-quoted (!important!) character string specifying paths to exclude when searching for NetLogo models. Supports glob patterns (e.g.,'models/old/**'). Multiple paths can be separated by commas (e.g.,'models/old/**, docs/**'). No paths are ignored by default (default:'').artifacts: A single-quoted (!important!) boolean value indicating whether to save experiment output tables as artifacts (default:'true').
Use the with keyword to change the default values. Example:
- name: Check NetLogo models
uses: danielvartan/logoactions/check-netlogo@v1
with:
ignore: 'models/old/**, docs/**'
artifacts: 'false'The runners ubuntu-latest, windows-latest, and macos-latest are supported. We recommend using ubuntu-latest whenever possible.
If you use LogoActions in your work, please cite it to acknowledge the effort invested in its development and maintenance. Your citation helps support the ongoing improvement of the project.
To cite LogoActions in publications please use the following format:
Vartanian, D. (n.d.). LogoActions: GitHub Actions for the NetLogo community [Computer software]. https://doi.org/10.5281/zenodo.18102378
A BibLaTeX entry for LaTeX users is:
@software{vartanian,
title = {LogoActions: GitHub Actions for the NetLogo community},
author = {Daniel Vartanian},
doi = {10.5281/zenodo.18102378},
note = {Computer software}
}Contributions are always welcome! Whether you want to report bugs, suggest new features, or help improve the code or documentation, your input makes a difference.
Before opening a new issue, please check the issues tab to see if your topic has already been reported.
You can also support the development of LogoActions by becoming a
sponsor.
Click here to make a
donation. Please mention LogoActions in your donation message.
Copyright (C) 2025 Daniel Vartanian
LogoActions is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the Free
Software Foundation, either version 3 of the License, or (at your option) any
later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with
this program. If not, see <https://www.gnu.org/licenses/>.
LogoActions is an independent project with no affiliation to NetLogo or its developers.
LogoActions brand identity is based on the NetLogo 7 brand identity.