foundry-anvil-template

README

Explore the docs »
Report Bug · Request Feature

Introduction

This repository is a consumer starter for Anvil, not the Anvil engine source itself. It gives you:

• a project-local tasks/ package already registered through the anvil.tasks entry-point group
• a starter task at tasks/project_check.py
• a starter config at yaml/noop.yaml
• example configs and GitHub Actions workflows you can adapt for your own environments

Use this template when you want a repo that can:

• install Anvil directly from your GitHub repository
• expose project-local tasks without forking Anvil
• validate task discovery quickly with a noop config
• give other teams a predictable layout for YAML, examples, docs, and CI wiring

If you want the deeper explanation of how Anvil itself works, see docs/README.md.

Usage

Quick start

1. Create the environment and install this template project:
   1. uv sync
2. Update yaml/noop.yaml:
   1. Set profile
   2. Set regions
   3. Set role_name if your member-account role differs
3. Validate that Anvil can discover the shipped starter task:
   1. uv run anvil tasks list
   2. uv run anvil tasks validate
4. Run the starter config:
   1. uv run anvil run --config-file .\yaml\noop.yaml --dry-run

The shipped noop config is the smallest first run for validating auth, discovery, and result output before you switch over to custom tasks. yaml/noop.yaml is the smallest config you use to prove that Anvil is wired correctly before building larger multi-org workflows.

This template pins Anvil directly from GitHub because it is not published to PyPI yet.

Examples

Start with the curated examples in this repository:

• examples/01-single-org-explicit-profile.yaml
• examples/02-complete-org-reference.yaml
• examples/03-complete-account-reference.yaml
• examples/github-actions

These are the examples that should stay aligned with the template repo's intended consumer experience.

For broader or deeper Anvil examples that live with the engine source, see the Anvil source repository examples:

• JSChronicles/anvil examples

For a complete GitHub Actions example that runs Anvil with AWS OIDC and uploads the generated JSON results as workflow artifacts, see examples/github-actions.