Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
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
41 changes: 41 additions & 0 deletions .github/landing.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Shared operator policy for the Main and Landing duty workflows.
# The duty job points LANDING_CONFIG here; the feedback job copies this file from the trusted base
# revision, because its checkout contains candidate files. The bundled Action declares these inputs
# empty, so a non-empty workflow value (for example ${{ vars.LANDING_TRUST }}) still wins.
model_timeout_seconds: 120

# Duty bumping: help a failed same-repository candidate workflow after native CI fails.
bump_on_failure: true

# Static dependency update base. The duty workflow unions its prepared publishing identity and
# LANDING_DEPENDENCY_UPDATE_ACTORS additions on top of this list; a non-empty
# dependency-update-actors input replaces the list instead.
dependency_update_actors:
- dependabot[bot]
- renovate[bot]

modes:
gatekeeper:
instructions: |
Review the affected behavior in this PR. Use supplied native check results and relevant review
history; investigate only unresolved questions, and publish useful findings or a brief clean verdict.
Native checks are independent of Landing feedback; ignore the Landing feedback job itself when
assessing whether native checks completed.
Read the relevant diff through gh. Generated site/** output is excluded; inspect its source when
needed. For documentation, assess command, configuration and workflow accuracy. For implementation,
assess affected user behavior.
issuer:
instructions: |
Triage only the failures or evidence supplied for this event. Read the affected job logs through gh,
and deployment evidence when a release supplies it; reuse a matching issue and record an actionable
current problem. Do not scan unrelated open issues or create issues for resolved historical failures.
Update an existing issue only for new evidence, changed conditions or verified progress; otherwise
complete without a public write. A successful build does not establish deployed recovery.
bumper:
instructions: |
Maintain this repository's dependencies, scoped to the supplied candidate or alert when present.
Use uv for Python runtime and development dependencies; follow project version policy and preserve
pinning style.
You may publish new updates as draft PRs on fresh deps/landing-* branches and append repair commits
to the supplied PR's existing branch. You may start required independent CI following AGENTS.md and
maintain necessary tracking issues. Maintainers decide merge and alert dismissal.
39 changes: 16 additions & 23 deletions .github/workflows/landing-duty.yml
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,8 @@ permissions:

jobs:
duty:
# The job gate can only read repository variables; .github/landing.yml holds the
# bump-on-failure default and remains authoritative when the Action admits the event.
if: >-
vars.LANDING_MODEL != '' &&
(github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' ||
Expand All @@ -47,6 +49,10 @@ jobs:
GIT_AUTHOR_EMAIL: ${{ vars.LANDING_GIT_EMAIL || '41898282+github-actions[bot]@users.noreply.github.com' }}
GIT_COMMITTER_NAME: ${{ vars.LANDING_GIT_NAME || 'github-actions[bot]' }}
GIT_COMMITTER_EMAIL: ${{ vars.LANDING_GIT_EMAIL || '41898282+github-actions[bot]@users.noreply.github.com' }}
LANDING_MODEL: ${{ vars.LANDING_MODEL }}
LANDING_API_BASE: ${{ vars.LANDING_API_BASE }}
LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS }}
LANDING_CONFIG: .github/landing.yml
steps:
- uses: actions/checkout@v7
with:
Expand Down Expand Up @@ -84,52 +90,39 @@ jobs:
(github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release')
uses: ./
env:
LANDING_MODEL: ${{ vars.LANDING_MODEL }}
LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }}
LANDING_API_BASE: ${{ vars.LANDING_API_BASE }}
LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }}
LANDING_MODEL_TIMEOUT_SECONDS: '120'
with:
trust: ${{ vars.LANDING_TRUST || 'repository' }}
trust: ${{ vars.LANDING_TRUST }}
upstream-workflow: release-main
# Release admission is its own boundary: never inherit the dependency-bumping policy.
bump-on-failure: false
command: triage
checked-revision: ${{ github.event_name != 'workflow_run' && github.sha || '' }}
delivery-key: ${{ format('duty:{0}', github.event.comment.id || github.run_id) }}
# Static triage policy lives in .github/landing.yml mode instructions.
instruction: >-
Follow the triggering release only. Its conclusion is ${{ github.event.workflow_run.conclusion }}.
Read affected jobs or deployment evidence through gh. Search for a matching issue only when this event supplies relevant failure or recovery evidence.
Update an existing issue only for useful new evidence, changed conditions or verified progress; otherwise complete without a public write.
Do not scan unrelated open issues or resolved historical failures. A build does not establish deployed recovery.
- name: Handle dependency updates
if: >-
github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' ||
github.event_name == 'repository_dispatch' ||
(github.event_name == 'workflow_run' && github.event.workflow_run.event != 'release')
uses: ./
env:
LANDING_MODEL: ${{ vars.LANDING_MODEL }}
LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }}
LANDING_API_BASE: ${{ vars.LANDING_API_BASE }}
LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }}
LANDING_MODEL_TIMEOUT_SECONDS: '120'
with:
trust: ${{ vars.LANDING_TRUST || 'repository' }}
# Static dependency policy, the actor base and the bump-on-failure default live in
# .github/landing.yml. This step supplies only the dynamic publishing identity and the
# operator's additional actors, unioned with the configured base.
trust: ${{ vars.LANDING_TRUST }}
upstream-workflow: Main
bump-on-failure: ${{ vars.LANDING_BUMP_ON_FAILURE || 'true' }}
dependency-update-actors: |
dependabot[bot]
renovate[bot]
bump-on-failure: ${{ vars.LANDING_BUMP_ON_FAILURE }}
dependency-update-actor-additions: |
${{ env.LANDING_PUBLISHING_ACTOR }}
${{ vars.LANDING_DEPENDENCY_UPDATE_ACTORS }}
command: bump
checked-revision: ${{ github.event_name != 'workflow_run' && github.sha || '' }}
delivery-key: ${{ github.event_name != 'workflow_run' && format('duty:{0}', github.run_id) || '' }}
instruction: >-
Maintain this repository's dependencies, scoped to the supplied candidate or alert when present.
Use uv for Python runtime and development dependencies; follow project version policy and preserve pinning style.
You may publish new updates as draft PRs on fresh deps/landing-* branches and append repair commits to the supplied PR's existing branch.
You may start required independent CI following AGENTS.md and maintain necessary tracking issues.
Maintainers decide merge and alert dismissal.
- name: Collect browser evidence
if: always()
run: |
Expand Down
30 changes: 22 additions & 8 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,23 @@ jobs:
with:
fetch-depth: 0
persist-credentials: false
- name: Prepare operator policy from the trusted revision
# A pull_request checkout contains candidate files, so read the shared policy from the
# base revision and keep it outside the artifact directory.
env:
POLICY_REVISION: ${{ github.event.pull_request.base.sha || github.sha }}
POLICY_BRANCH: ${{ github.event.pull_request.base.ref }}
run: |
mkdir -p "$RUNNER_TEMP/policy"
policy="$RUNNER_TEMP/policy/landing.yml"
if ! git show "$POLICY_REVISION:.github/landing.yml" > "$policy" 2>/dev/null &&
! { [ -n "$POLICY_BRANCH" ] && git show "origin/$POLICY_BRANCH:.github/landing.yml" > "$policy" 2>/dev/null; }; then
rm -f "$policy"
echo "::warning::No operator policy at the base revision; Landing defaults apply."
fi
if [ -s "$policy" ]; then
echo "LANDING_CONFIG=$policy" >> "$GITHUB_ENV"
fi
- uses: ./.github/actions/setup-python-env
- uses: sersoft-gmbh/setup-gh-cli-action@v3
with:
Expand Down Expand Up @@ -186,21 +203,18 @@ jobs:
LANDING_MODEL: ${{ vars.LANDING_MODEL }}
LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }}
LANDING_API_BASE: ${{ vars.LANDING_API_BASE }}
LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }}
LANDING_MODEL_TIMEOUT_SECONDS: '120'
LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS }}
with:
trust: ${{ vars.LANDING_TRUST || 'repository' }}
trust: ${{ vars.LANDING_TRUST }}
command: ${{ (github.event_name == 'pull_request' || (inputs.number != '' && inputs.number != '0')) && 'review' || 'triage' }}
number: ${{ format('{0}', github.event.pull_request.number || inputs.number || 0) }}
head: ${{ github.event.pull_request.head.sha || inputs.head || '' }}
run-id: ${{ format('{0}', github.run_id) }}
checked-revision: ${{ github.sha }}
delivery-key: ${{ format('checks:{0}:{1}', github.run_id, github.run_attempt) }}
# Static review and triage policy lives in .github/landing.yml mode instructions; the
# step supplies only this run's native results and selected scope.
instruction: >-
Native checks: quality=${{ needs.quality.result }}, tests-and-type-check=${{ needs.tests-and-type-check.result }}, check-docs=${{ needs.check-docs.result }}, container=${{ needs.container.result }}.
Ignore the Landing feedback job when assessing native check completion.
${{ (github.event_name == 'pull_request' || (inputs.number != '' && inputs.number != '0')) && 'Review the affected behavior in this PR. Use supplied check results and relevant review history; investigate only unresolved questions and publish useful findings or a brief clean verdict.' || 'Triage only the native failures in these supplied results. Read the affected job logs using gh, reuse a matching issue, and record an actionable current problem. Do not create issues for resolved historical failures.' }}
${{ github.event_name == 'pull_request' && format('Selected scope: implementation={0}, documentation={1}. Read the relevant diff through gh. Generated site/** output is excluded; inspect its source when needed. For documentation, assess command, configuration and workflow accuracy. For implementation, assess affected user behavior.', needs.feedback-scope.outputs.implementation || 'false', needs.feedback-scope.outputs.documentation || 'false') || '' }}
${{ github.event_name == 'pull_request' && format('Selected scope: implementation={0}, documentation={1}.', needs.feedback-scope.outputs.implementation || 'false', needs.feedback-scope.outputs.documentation || 'false') || '' }}
- name: Report unsuccessful feedback
if: ${{ !cancelled() && steps.landing.outcome == 'failure' }}
run: echo "::warning::Landing feedback failed. Inspect the task logs and artifact; native checks determine acceptance."
Expand Down
58 changes: 35 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,24 @@
</picture>
</h1>

Landing explains CI failures, fixes delegated problems, triages issues, and publishes review feedback where your team works. It uses your existing tools and checks.
Landing delegates engineering work to a language model using the tools, checks, and identity you already prepared. It explains a failure, turns a problem into an actionable issue, repairs a demonstrated defect, reviews a candidate, or updates a dependency.

With Landing, you own and control the workflow. Choose the model, prepare the execution environment, and adapt instructions and skills to your project. Run it in CI, locally, or as a service. Landing is open source under Apache-2.0 and requires no hosted Landing account.
You bring the model endpoint, the execution environment, and the acceptance checks. Landing admits the work, runs the selected mode with your project guidance, verifies publication, and records the result in SQLite. It is an Apache-2.0 application; the documented paths need no hosted Landing account.

## Start in CI
## Quick start

[Set up your first PR review](https://getlanding.dev/get-started/). Configure a model, add the GitHub Action to your prepared workflow, and open a PR. Landing publishes review feedback with code comments for actionable findings. Your team decides what to accept using that feedback and independent checks.
With Python 3.12 or later, [uv](https://docs.astral.sh/uv/), and a POSIX host:

```text
Configure CI -> Open a PR -> Read the feedback -> Decide what to accept
```bash
uv tool install landing
export LANDING_MODEL="openai:gpt-4.1"
export LANDING_API_KEY="your-provider-api-key"
landing explain "Explain this failure and suggest the next useful check." --input check.log
```

Set the `LANDING_MODEL` repository variable and `LANDING_API_KEY` secret, and grant the review job `contents: read` and `pull-requests: write`. After checkout and successful native checks, add this step to your existing workflow:
Run it from your project checkout and use a saved UTF-8 log for `check.log`. The same install serves `triage`, `fix`, `review`, and `bump`; each command works independently. See [local use](https://getlanding.dev/guides/local/) for delegating work and reading the result.

To review pull requests instead, [add the Action to a GitHub workflow](https://getlanding.dev/get-started/): set the model, let your native checks run, and read the advisory review it publishes.

```yaml
- uses: bubbuild/landing@main
Expand All @@ -28,30 +33,37 @@ Set the `LANDING_MODEL` repository variable and `LANDING_API_KEY` secret, and gr
LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }}
with:
command: review
instruction: Native checks passed for this checkout. Review this PR using repository guidance and publish actionable findings inline.
instruction: Review this candidate against repository guidance and the native checks. Publish actionable findings.
```

The example follows `main`; pin a release tag or reviewed commit to keep the runtime fixed. `continue-on-error` keeps automatic feedback advisory; inspect the Action logs if no status comment appears. The Action uses your authenticated `gh`, project tools, and skills. It checks who can delegate before starting the agent. See [CI integration](https://getlanding.dev/guides/ci/) for other CI systems and [GitHub integration](https://getlanding.dev/guides/github/) for `/landing` commands, publishing identities, and trust policy.
The example follows `main`; pin a release tag or reviewed commit to keep the runtime fixed. `continue-on-error` keeps automatic feedback advisory, and the Action checks who may delegate before starting any work.

To build the same review and delegated-fix experience, ask your agent to read [Landing's workflows](https://github.com/bubbuild/landing/tree/main/.github/workflows) and [development guide](https://getlanding.dev/development/), then adapt the CI setup to your repository's tools and checks.
## Entry points

## Use it locally
| Entry point | Use it when |
| --- | --- |
| CLI | You work against a local checkout, or your CI is not GitHub Actions. |
| [GitHub Action and events](https://getlanding.dev/guides/github/) | Work is triggered by repository events, comments, or schedules. |
| [HTTP service](https://getlanding.dev/guides/server/) | Several callers share one queue and prepared environment. |

With Python 3.12 or later, [uv](https://docs.astral.sh/uv/), and a POSIX host:
All three accept the same modes, instructions, and inputs, and record the same action lifecycle; required checks apply to `fix`, `review`, and `bump`, not `explain` or `triage`. [CLI reference](https://getlanding.dev/reference/cli/) and [HTTP reference](https://getlanding.dev/reference/http/) list the exact contracts. The service also ships as an image: [deploy](https://getlanding.dev/guides/deploy/) covers Compose and `ghcr.io/bubbuild/landing`.

```bash
uv tool install landing
export LANDING_MODEL="openai:gpt-4.1"
export LANDING_API_KEY="your-provider-api-key"
landing explain "Explain this failure and the next useful check." --input check.log
```
## Configure and adapt

[Configuration](https://getlanding.dev/reference/configuration/) covers the model, skills, mode capabilities, MCP servers, and runner policy, including precedence and the values a settings file may set. [Make Landing work for you](https://getlanding.dev/make-it-yours/) covers project instructions, skills, tools, and required checks.

Keep in mind:

- Instructions and capability lists guide the agent; they do not sandbox it or grant authority. Enforce both in your tools and workflow permissions.
- Checks decide what a task may claim. Keep your required native checks independent of Landing's advice.
- Task completion, a published reply, and a passing check establish different things. Your team still accepts the work.

Run from your project checkout and use a saved UTF-8 log for `check.log`. The commands are `explain`, `triage`, `fix`, `review`, and `bump`; each works independently. [Local use](https://getlanding.dev/guides/local/) shows how to delegate work and inspect the result.
## Limits

## Work with your team
Landing runs where you install it and uses the credentials you give it. It does not supply a model, isolate an untrusted checkout, or configure your CI. A fork pull request normally runs native checks while receiving no model or publication credentials.

Reliable results draw on your documentation, work items, infrastructure, tests, benchmarks, and observability. [Working with Landing](https://getlanding.dev/working-with-landing/) explains how to connect that context and retain feedback. Automate the engineering work you can delegate, and use the time saved to stay involved with contributors and users. Community Over Code.
## Learn more

[Make Landing work for you](https://getlanding.dev/make-it-yours/) covers project instructions, skills, and tools. For shared execution, [run the server](https://getlanding.dev/guides/server/) or [deploy the container](https://getlanding.dev/guides/deploy/) from `ghcr.io/bubbuild/landing:latest`. Actions and model history are stored in SQLite; workspace files stay in your workspace, and model requests go to your chosen provider.
[Working with Landing](https://getlanding.dev/working-with-landing/) explains how engineering context and verification make delegated work reliable. [CI integration](https://getlanding.dev/guides/ci/) covers scope, concurrency, and ordinary CI commands; [troubleshooting](https://getlanding.dev/guides/troubleshooting/) starts from an observed failure. [Develop and dogfood](https://getlanding.dev/development/) describes how Landing itself is built and tested.

[Contributions](https://github.com/bubbuild/landing/blob/main/CONTRIBUTING.md) are welcome. Licensed under [Apache-2.0](https://github.com/bubbuild/landing/blob/main/LICENSE). Powered by [Bub](https://bub.build/) and [tape.systems](https://tape.systems/).
Contributions are welcome; see [CONTRIBUTING.md](https://github.com/bubbuild/landing/blob/main/CONTRIBUTING.md). Licensed under [Apache-2.0](https://github.com/bubbuild/landing/blob/main/LICENSE). Built on [Bub](https://bub.build/).
Loading
Loading