ALActions - Github Actions for the Assembly Line project

Shared actions, used over many different Assembly Line projets.

Usage

You can use the actions in repo github workflows by refering the subfolder of the desired action and the a specific branch or tagged version you want to run:

jobs:
my-workflow:
...steps:
- uses: SuffolkLITLab/ALActions/pythontests@main 

For assembly line projects, you should refer to the main branch, as that will allow bug fixes to the actions to immediately propagate to the AssemblyLine repos.

The Actions

pythontest

pythontest sets up a python environment around the package, and runs any unittest tests in the package.

Usage

jobs:
my-workflow:
...# No inputssteps:
- uses: SuffolkLITLab/ALActions/pythontests@main 

black-formatting

Runs black, a python formatter, over the python code in your package.

Usage

jobs:
my-workflow:
...steps:
- uses: SuffolkLITLab/ALActions/black-formatting@main

black will also read configs from pyproject.toml. In most projects, we include the following:

[tool.black]
extend-exclude = '(__init__.py|setup.py)'

da_playground_install

playground_install mirrors the options of the Docassemble /api/playground_install endpoint.

It can be used to install the contents of a repository to a specified Docassemble playground and project. This can be useful to make it simple to do interactive end-to-end testing of new versions of your project, especially if you want to enable testing of multiple versions on a single server.

Usage

Create a new file in .github/workflows/, named "playground_publish.yml" or a .yml name of your choice.

The contents should look like:

name: Deploy to Docassemble Playgroundon:
push:
branches:
- main # Trigger the workflow on push to main branchjobs:
deploy:
runs-on: ubuntu-lateststeps:
- name: Checkout Repositoryuses: actions/checkout@v3
- name: Deploy to Docassemble Playgrounduses: SuffolkLITLab/ALActions/da_playground_install@dogfoodwith:
SERVER_URL: ${{ secrets.SERVER_URL }}DOCASSEMBLE_DEVELOPER_API_KEY: ${{ secrets.DOCASSEMBLE_DEVELOPER_API_KEY }}PROJECT_NAME: ${{ secrets.PROJECT_NAME }}

You can either directly edit the SERVER_URL and PROJECT_NAME parameters, or add them as GitHub repository secrets. The server URL should look like this:

https://apps-dev.example.com, without the trailing slash.

da_package

The da_package action is like the da_playground_install action, except that it installs the current GitHub repository server-wide.

While it can be used to install the package directly from the repository by uploading it as a .zip file, typically you will want to use the GitHub url instead to make it possible to click the update button manually.

docsig

docsig checks all of the docstrings in the python package to ensure that they match the function signature and have consistent styles. Since we use Google style for our docstrings, the packages should use that, even though docsig allows NumPy and sphinx styles as well.

Usage

jobs:
my-workflow:
...steps:
- uses: SuffolkLITLab/ALActions/docsig@main

docsig can be configured by using pyproject.toml. See the docsig README.md for more info.

word_diff

word_diff converts any changed .docx files into Markdown (without introducing extra hard line wraps), diffing the rendered text so reviewers can read the changes directly in GitHub.

Usage

on:
pull_request:
workflow_dispatch:
jobs:
docx-review:
runs-on: ubuntu-lateststeps:
- name: Diff Word documentsuses: SuffolkLITLab/ALActions/word_diff@mainwith:
# Optional: override the base commit if needed# base_ref: mainartifact_name: word-doc-diffoutput_dir: word_diffssummary_file: word_diff_summary.md

• Unified diffs are written to the job log and appended to the GitHub Actions step summary so you can skim changes without downloading artifacts.
• HTML side-by-side diffs, plus the converted Markdown files, are uploaded as an artifact (with an index.html table of contents by default) for richer review.
• The action automatically determines the correct comparison commits for pull requests and pushes. For manually dispatched runs, supply base/head inputs on the workflow or pass a base_ref input to the action directly.
• To make the diff run on every push, add a push trigger to your workflow or follow the pattern in .github/workflows/word_diff.yml to toggle push/PR execution via environment variables.

valid_jinja2

valid_jinja2 validates DOCX templates to ensure all embedded Jinja2 expressions have valid syntax. It checks both newly added and modified .docx files, distinguishing between syntax errors (which fail the build) and unknown filters (which generate warnings).

Key Features

• Ensures all Jinja2 blocks ({{ }}, {% %}) have correct syntax
• Recognizes 70+ common Docassemble and Jinja2 filters, treating unknown filters as warnings rather than errors
• Generates HTML artifacts and Markdown summaries for easy review
• Automatically detects added and changed DOCX files in commits and pull requests
  • NOTE: it will only use changes commited to git, so be sure to commit your fixed DOCX if testing locally

Sample Workflow

Create .github/workflows/validate-docx.yml in your repository:

name: Validate DOCX Templateson:
pull_request:
paths:
- '**/*.docx'push:
paths:
- '**/*.docx'workflow_dispatch:
jobs:
validate-docx:
runs-on: ubuntu-lateststeps:
- name: Checkout repositoryuses: actions/checkout@v4with:
fetch-depth: 0# Needed for git diff comparison
- name: Validate DOCX Jinja2 templatesuses: SuffolkLITLab/ALActions/valid_jinja2@mainwith:
# Optional: customize artifact and output namesartifact_name: jinja-validation-reportoutput_dir: jinja_validationsummary_file: jinja_validation_summary.md

Input Parameters

Parameter	Description	Default	Required
base_ref	Git reference for comparison base	Auto-detected from event	No
artifact_name	Name for the uploaded validation artifact	jinja-validation	No
output_dir	Directory for HTML validation reports	jinja_validation	No
summary_file	Path for Markdown summary file	jinja_validation_summary.md	No

Behavior

• Syntax Errors: Invalid Jinja2 syntax causes the workflow to fail
• Unknown Filters: Unrecognized filters generate warnings but don't fail the build
• Known Filters: Common Docassemble filters (like currency, date, title_case) don't generate warnings
• Artifacts: Only generated when there are validation issues (errors, warnings, or missing files)
• Summary: Always creates a Markdown summary showing validation results for each file

Artifacts should be visible in the Summary of the action results.

Hall Monitor

hall_monitor checks a given docassemble server to make sure that all of the installed interviews can load their first page correctly, acting like a hall monitor peaking through doors, but not investigating any further.

Usage

You will likely want to run this action on a schedule, several times a day. You can see more about how to define this schedule in the github on.schedule documentation.

on:
schedule:
# Runs at 6:00am, and 18:00 (6:00pm)
- cron: "0 6,18 * * *"jobs:
my-workflow:
...steps:
- uses: SuffolkLITLab/ALActions/hall_monitor@mainwith:
SERVER_URL: "https://my-docassemble.example.com"

This also supports sending email notifications (separate from GitHub's notification system, which doesn't let you notify arbitrary people about an action failing) to multiple, comma separated emails, using Sendgrid and Mailgun.

Here's a code example for sendgrid:

jobs:
my-workflow:
...steps:
- uses: SuffolkLITLab/ALActions/hall_monitor@mainwith:
SERVER_URL: "https://my-docassemble.example.com"SENDGRID_API_KEY: ${{ secrets.MY_SENDGRID_API_KEY }}ERROR_FROM_EMAIL: Monitor <alert@example.com>ERROR_EMAILS: example@example.com,example2@example.com

And one for Mailgun

jobs:
my-workflow:
...steps:
- uses: SuffolkLITLab/ALActions/hall_monitor@mainwith:
SERVER_URL: "https://my-docassemble.example.com"MAILGUN_API_KEY: ${{ secrets.MY_MAILGUN_API_KEY }}MAILGUN_DOMAIN: ${{ secrets.MY_MAILGUN_DOMAIN }}ERROR_FROM_EMAIL: Monitor <alert@example.com>ERROR_EMAILS: example@example.com,example2@example.com

DA Build

da_build confirms:

• The package can build
• Python all compiles
• The interview file is minimally correct (python code blocks compile, mako statements compile, we are using known Docassemble keys in the YAML)
• Absolute URLs in docassemble/*/data/questions do not return HTTP 404 (excluding example.com links)

Usage

name: Build and install docassembleon: pushjobs:
build-n-check:
runs-on: ubuntu-lateststeps:
- uses: SuffolkLITLab/ALActions/da_build@mainwith:
python-version: "3.12"# Optional: disable URL checks for environments without network accessskip-url-check: "true"# Optional: comma/newline-separated URLs to skip in url_checkignore-urls: | https://example.com/known-flaky-endpoint https://another.example.org/blocked-from-ci

Development Details

Using codeql-action as a template for this repo.

This repo is mostly composite actions, as opposed to javascript or docker actions. Visit Github's documentation on composite actions for more info.