Skip to content

Update ImageBuilder infrastructure guidance #2193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
lbussell merged 1 commit into from
Jul 29, 2026
Merged

Update ImageBuilder infrastructure guidance #2193

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 5 additions & 28 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,8 @@ The primary tool is ImageBuilder, a .NET CLI app that orchestrates builds from m
| `src/ImageBuilder.Models/` | Manifest and image metadata models |
| `src/ImageBuilder.Tests/` | MSTest, Moq, and Shouldly tests |
| `src/ImageBuilder.Updater/` | ImageBuilder infrastructure update PR utility |
| `eng/docker-tools/` | Shared scripts and Azure Pipelines templates synchronized to other .NET Docker repositories |
| `src/Infrastructure/Content/` | Source for shared infrastructure shipped in the next ImageBuilder |
| `eng/docker-tools/` | Shared infrastructure consumed by this repository |

ImageBuilder commands inherit from `Command<TOptions>` and use System.CommandLine.
The manifest schema starts at `src/ImageBuilder.Models/Manifest/Manifest.cs`; generated image
Expand All @@ -28,9 +29,8 @@ See `src/README.md` for local ImageBuilder container-image build instructions.

## Repository invariants

- `eng/docker-tools/` is the source of truth for infrastructure synchronized to consuming
repositories. Document breaking changes there in `eng/docker-tools/CHANGELOG.md` with
actionable migration steps.
- Make shared infrastructure changes in `src/Infrastructure/Content/`; they automatically flow to
`eng/docker-tools/` through the ImageBuilder update process.
- Files under `eng/common/` come from dotnet/arcade and are overwritten by automation. Do not
edit them here; make the source change in Arcade.
- `publishConfig` is the source of truth for registry authentication. Registry service
Expand All @@ -42,29 +42,6 @@ See `src/README.md` for local ImageBuilder container-image build instructions.
`reference-service-connections.yml` with only the connections they need. Templates
supporting Linux and Windows must pass `dockerClientOS`.

## ImageBuilder deployment constraint

ImageBuilder builds its own published container image. Pipelines select that image through
`imageNames.imageBuilder` in `eng/docker-tools/templates/variables/docker-images.yml`.
Changes that require both new ImageBuilder behavior and pipeline adoption normally use two pull requests:

1. Merge and publish the ImageBuilder code change.
2. After automation updates the ImageBuilder tag, merge the dependent pipeline or manifest change.

For combined development validation, use the engineering validation unofficial pipeline defined
in `eng/pipelines/dotnet-docker-tools-eng-validation-unofficial.yml` with the parameter
`bootstrapImageBuilder: true`; each job then builds and uses ImageBuilder from the current source.

## Bundled infrastructure

ImageBuilder embeds `eng/docker-tools/` under `src/Infrastructure/Content/` so source and
pipeline-template changes can be developed together. The copy lives under `src/` because that is
the ImageBuilder container build context.

The copies intentionally differ between releases: update `src/Infrastructure/Content/` for content
the next ImageBuilder will ship; automation refreshes `eng/docker-tools/` when the repository
adopts that ImageBuilder version. See `src/Infrastructure/README.md`.

## Documentation

Update only the narrowest documentation affected by the change:
Expand All @@ -74,5 +51,5 @@ Update only the narrowest documentation affected by the change:
| Pipeline architecture, workflows, or capabilities | `eng/docker-tools/DEV-GUIDE.md` |
| ImageBuilder container-image build workflow | `src/README.md` |
| Manifest schema | `documentation/manifest-file.md` |
| Breaking shared template behavior | `eng/docker-tools/CHANGELOG.md` |
| Breaking change to shared infrastructure | `src/Infrastructure/Content/CHANGELOG.md` |
| Fundamental project or agent workflow | `AGENTS.md` |