Template Project for Digital.ai Release Integrations

This project serves as a template for developing a Python-based container plugin for Digital.ai Release. Each task is a Python class in src/ that is packaged into a Docker image and run by Release as a container task.

The task code is built on the digitalai-release-sdk — tasks subclass its BaseTask (or ApiBaseTask) to read inputs, set outputs, and call the Release APIs. It is the project's main dependency and is pinned in requirements.txt.

Building the project produces two artifacts:

• a plugin zip — the plugin metadata from resources/, installed into Release.
• a Docker image — the src/ task code and its dependencies, pushed to a container registry and run by Release.

Tip

Writing your own tasks? Start with the Plugin Development Guide — it explains how a container plugin works, how to add a task, and how each bundled example was built.

Important

Using this as a template? This README documents the template itself. After you create your own repo from it, follow After creating your repository to personalize the clone.

Contents

• After creating your repository
• Quick start
• Project layout
• Prerequisites
• Development
• Run Release locally
• Build & publish
• Install the plugin into Release
• First successful run
• Clean up the local environment
• Related resources
• License

After creating your repository

The release-integration-template-python repository is a template. On its main page, click Use this template → Create a new repository. Then, before developing your integration, complete these steps:

1. Replace this README with the generated-plugin starter: mv README-plugin.md README.md (or move /Y README-plugin.md README.md on Windows).
2. Set PLUGIN, VERSION, REGISTRY_URL, and REGISTRY_ORG in project.properties. Use the naming convention [publisher]-release-[target]-integration (e.g. acme-release-example-integration).
3. Remove or adapt the example tasks in src/, resources/type-definitions.yaml, and tests/.
4. Update the plugin description and task details in the new README.
5. Run uv sync --extra dev and uv run pytest tests/unit before building.

The develop-release-integration skill guides you (or your AI agent) through these steps, including the README swap. The generated README is the one users of your plugin will see — keep these template-specific instructions only while developing from the template.

Quick start

From the repository root:

uv sync --extra dev                  # set up the local environment (.venv)
docker compose up -d --build         # start Release, the runner, and the local registry

Wait for the Release container log to show Digital.ai Release has started. Before building, add 127.0.0.1 container-registry to your hosts file — this requires administrator/sudo rights (see Run Release locally). Then build and install the plugin. The --upload step reads your Release server details from .xebialabs/config.yaml (defaults point at the local server):

# macOS / Linux
./build.sh --upload

# Windows (PowerShell or Command Prompt)
.\build.bat --upload

The default local Release server is available at http://localhost:5516. After the upload completes, confirm the plugin is listed under Manage plugins, then create a template with the Hello task (containerExamples.Hello) and run it. Each step is detailed below.

Project layout

Path	Purpose
src/	Task implementations. This code ships inside the Docker image. See the Plugin Development Guide.
tests/	Tests for the task classes — unit/ (fast) and integration/ (network). Not shipped in the image.
resources/	Plugin metadata packaged into the plugin zip: type-definitions.yaml (task types), the plugin icon (test.png), and plugin-version.properties (name/version, filled from project.properties at build).
requirements.txt	Runtime dependencies installed into the Docker image. Source of truth for the container.
pyproject.toml	Local development environment, managed by uv.
Dockerfile	Builds the container image that runs the tasks.
build.sh / build.bat	Builds the plugin zip and the Docker image, and uploads them to Release.
project.properties	Plugin name, version, and registry coordinates used by the build scripts.
docker-compose.yaml	A local Dockerized Release server (+ runner + container registry) for testing.
dev-environment/	Build contexts and config used by docker-compose.yaml.
docs/	Contributor docs: PLUGIN_DEVELOPMENT.md (detailed guide), AGENTS.md (conventions/guardrails for AI agents), and SKILL.md (portable develop-release-integration skill that routes to the docs above).
README-plugin.md	Starter README for the generated plugin — copy over README.md after creating your repo (see the note above).

Note

This is not a pure Python package — it is not published to PyPI. The src/ tree is copied into a Docker image and executed there by the Release task wrapper.

Prerequisites

• Python 3.10+
• uv — for the local development environment
• Docker — to build and run the container image
• Git

Install uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Development

This project uses uv to manage a local virtual environment for writing and testing tasks. The container image itself is built from requirements.txt (see Build & publish).

Set up the environment

# Creates .venv and installs runtime + dev dependencies
uv sync --extra dev

Run the tests

Tests are split into tests/unit/ (fast, no external dependencies) and tests/integration/ (hit the network or external services, and are also marked with @pytest.mark.integration).

# Run every test
uv run pytest

# Run only the fast unit tests
uv run pytest tests/unit          # or: uv run pytest -m "not integration"

Integration tests that need a live Digital.ai Release server skip themselves automatically when none is reachable. Some integration tests call external services directly, so they require internet access. Point Release-backed tests at a server (defaults shown) with:

# macOS / Linux
RELEASE_SERVER_URL=http://localhost:5516 RELEASE_USERNAME=admin RELEASE_PASSWORD=admin uv run pytest tests/integration

# Windows (PowerShell)
$env:RELEASE_SERVER_URL="http://localhost:5516"; $env:RELEASE_USERNAME="admin"; $env:RELEASE_PASSWORD="admin"; uv run pytest tests/integration

REM Windows (Command Prompt)
set RELEASE_SERVER_URL=http://localhost:5516 && set RELEASE_USERNAME=admin && set RELEASE_PASSWORD=admin && uv run pytest tests/integration

Add a dependency

Because the container is built from requirements.txt, a new runtime dependency must be added in two places so local dev matches the image:

1. Add it to requirements.txt (used by the Dockerfile).

2. Add it to pyproject.toml, then refresh the lockfile:

   uv add <package>     # updates pyproject.toml and uv.lock

A dev-only dependency (e.g. a test helper) goes in the dev extra only:

uv add --optional dev <package>

Run Release locally

Run a local Release server, its remote runner, and a container registry, using Docker.

docker compose up -d --build

Configure your hosts file

Release must be able to reach the local container registry by name. Add this entry:

• macOS / Linux — /etc/hosts (requires sudo)
• Windows — C:\Windows\System32\drivers\etc\hosts (run as administrator)

127.0.0.1 container-registry

Build & publish

The build scripts read project.properties, build the plugin zip from resources/, build the Docker image from the Dockerfile, and push the image to the configured registry.

The --image, default, and --upload workflows require Docker to be running and the registry in REGISTRY_URL to be reachable. For the local Docker Compose environment, start the stack first and add 127.0.0.1 container-registry to your hosts file as described in Run Release locally. For a remote registry, make sure Docker is authenticated and that REGISTRY_URL and REGISTRY_ORG in project.properties are correct.

Command	Result
./build.sh	Build the zip and the image, and push the image.
./build.sh --zip	Build only the plugin zip.
./build.sh --image	Build only the Docker image and push it.
./build.sh --upload	Build the zip and image, push the image, and upload the zip to Release.

On Windows, use build.bat with the same arguments (works in both PowerShell and Command Prompt), for example:

.\build.bat --upload

Install the plugin into Release

Option A — command line

Set your Release server details in .xebialabs/config.yaml (the same file used by the Quick start --upload step), then make sure the Release server is running and use the command for your platform:

# macOS / Linux
./build.sh --upload

# Windows
.\build.bat --upload

Option B — Release UI

In the Release Manage plugins page (http://localhost:5516/#/pluginManager), upload the zip from build/ (named <PLUGIN>-<VERSION>.zip, e.g. publisher-release-target-integration-0.0.1.zip with the current project.properties).

Verify the plugin is installed

However you uploaded it, reload the Release server from the UI to pick up the new task types:

1. Open http://localhost:5516/#/pluginManager (Manage plugins).
2. Select Installed plugins and search for your plugin — it should appear with the version from project.properties.
3. If the task still doesn't show up when you build a template, hard-refresh the browser (Ctrl/Cmd+Shift+R) to clear the UI cache.

First successful run

The Quick start covers the happy path end to end. Once the plugin is installed, verify the workflow in the Release UI:

1. Open http://localhost:5516, create a template, and add containerExamples.Hello.
2. Run the release and verify the task produces its greeting output.

If a step fails, see Run Release locally, Build & publish, and Install the plugin into Release for the full setup and troubleshooting details.

Clean up the local environment

When you finish testing, stop the local Release server, runner, and registry:

docker compose down

This stops the containers but preserves the local registry/server data mounted under dev-environment/. To reset the development environment and remove that test state, run docker compose down and remove the generated contents under that directory before starting the stack again.

Related resources

• Digital.ai Release API Client Documentation — API Classes and Models reference for the Python client library.
• Digital.ai Python SDK Documentation — Comprehensive guide to using the Python SDK and building custom tasks.
• SDK Template Project for integration plugins — A starting point for building custom integrations using Digital.ai Release and Python.
• Digital.ai Release Python SDK — The official SDK package for integrating with Digital.ai Release, on PyPI.

License

See LICENSE.md.