Skip to content

Run.integrate()

Land a worktree's work in its parent. AGL merges the worktree's branch into the parent's worktree, then runs your repository's build there. The work lands only if the build passes. The parent is either the top-level Run or another worktree.

landing = await child.integrate()

The build is your repository's build setting. A workflow that integrates must list build in its [tool.agl] config. An empty build passes every landing.

If the build fails, AGL undoes the merge. landing.refused_by_the_gate is true, and landing.verdict holds the build's VerifierOutcome, with its output. Fix the work in the worktree with another step, then try again.

while landing.refused_by_the_gate:
    await child.step(fixer, landing.verdict, commit="Fix the build")
    await landing.retry()

If the merge conflicts, landing.conflicted is true, landing.conflict lists the files, and its summary names the worktree that holds the merge. Resolve them in the parent's worktree, stage them, and call retry(). Or give up with abort().

if landing.conflicted:
    await landing.abort()

A resolved merge goes through the build too. If the build fails, AGL undoes the merge, and the resolution with it.

Landings into one parent take turns. Until a landing lands or you abort() it, it holds the parent: steps on the parent, and other landings into it, wait. The top-level Run has no parent, so it can't integrate.

Reference

agl.sdk.Run.integrate() async

Merges this child's work into the worktree of the Run that opened it.

Returns:

Raises:

  • InputError –

    This is the top-level Run, or the workflow declares no build setting.

  • NotFoundError –

    A ref one of the two worktrees was cut from names nothing.

  • ConflictError –

    Another line of work is holding one of the two places.

  • UpstreamUnavailable –

    AGL couldn't run Git or the build command.

  • UpstreamUnexpected –

    Git refused the landing, or answered unreadably.

agl.sdk.Integration

One landing of a child's work into its parent, and where it stands.

conflicted abstractmethod property

Whether a conflict is holding the parent.

Returns:

  • bool –

    True while a conflict holds the parent, False once the work has landed or the landing has ended without it.

refused_by_the_gate abstractmethod property

Whether the build gate, not a merge conflict, stopped the landing.

Returns:

  • bool –

    True while the gate's refusal holds the parent, False while a merge conflict holds it and once the landing has ended.

verdict abstractmethod property

The build gate's outcome on the latest attempt.

Returns:

  • VerifierOutcome | None –

    The build's VerifierOutcome, or None where the latest attempt would not merge. If a later step takes it as an input and the build answers differently on a resume, even in its output, that step runs again and throws away every commit made since the step or landing before it.

conflict abstractmethod property

What stopped the landing.

Returns:

  • Conflict | None –

    The Conflict, or None if the work landed.

head abstractmethod property

The commit the parent is at once the work landed.

Returns:

  • str | None –

    The parent's new head, or None if the work hasn't landed.

retry() abstractmethod async

Tries the landing again, against the parent's worktree as it now stands.

Raises:

abort() abstractmethod async

Gives up a conflicted landing, leaving the parent as it was before it.

Raises:

agl.sdk.Conflict dataclass

The files that collided in a landing, if any, with a summary.

paths instance-attribute

The files left unresolved, and empty where the build gate refused or no file can be named.

summary instance-attribute

What collided and what state the parent is in, in words a screen can carry.