From 7a890ac25b23d816d0e6ccd5c9975e02c90c4427 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 13:25:45 +0800 Subject: [PATCH 01/15] feat(github): accept operator policy from Landing YAML The GitHub runner read operator policy only from Action inputs and CLI options, so a local or hosted operator had to repeat the same trust scope, command prefix, upstream workflows, dependency accounts, bump flag, and checks on every invocation. `GitHubSettings` now extends a restricted policy source: the already-loaded Landing YAML may set those names, while task inputs, caller identity, event context, run identity, delivery keys, and the database stay with the invocation. Priority is explicit options, `INPUT_*`, YAML, then defaults; a missing file preserves the previous behavior. The CLI loads execution settings before constructing the event options so the existing YAML data covers both. This first commit keeps the same CLI, Action, and runner path and documents the admitted names. --- docs/reference/configuration.md | 11 ++++ src/landing/adapters/github.py | 29 +++++++-- src/landing/settings.py | 47 +++++++++++++- tests/test_github.py | 111 ++++++++++++++++++++++++++++++++ 4 files changed, 190 insertions(+), 8 deletions(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 50b5e6e..527d799 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -120,6 +120,17 @@ Local workspace defaults to the current directory. Servers register names with ` The runner uses prepared `GH_TOKEN` or gh login for publication and optional `GH_ADMISSION_TOKEN` for separate admission. Action inputs load from `INPUT_*`; explicit CLI options take precedence. Checks and upstream workflow names use multiline inputs. Native `GITHUB_*` identity and event context come from the execution environment; YAML cannot grant caller authority. An empty `checked-revision` input leaves check provenance unknown. +Landing YAML may also set operator policy for the GitHub runner: `command_prefix`, `trust`, `upstream_workflow`, `bump_on_failure`, `dependency_update_actors`, and `check`. CLI options, then `INPUT_*`, then YAML, then defaults decide each value. The file cannot set the repository, event file, command or instruction, issue or PR number, candidate head, checked revision, run identity, delivery key, database, or caller credentials. + +```yaml +command_prefix: "@team-bot" +trust: repository +upstream_workflow: [release-main] +check: + - uv run ty check + - uv run pre-commit run --all-files +``` + Commit attribution uses Git configuration or `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, and `GIT_COMMITTER_EMAIL`. Selecting a publication token alone does not change commit attribution. See [GitHub integration](../guides/github.md) for identity and trust, and [Action inputs](cli.md#github-action) for invocation. ## Container replication diff --git a/src/landing/adapters/github.py b/src/landing/adapters/github.py index a6cbbe6..9ffa069 100644 --- a/src/landing/adapters/github.py +++ b/src/landing/adapters/github.py @@ -10,7 +10,7 @@ from dataclasses import dataclass, field from pathlib import Path from string import Template -from typing import Annotated, Any, Literal, cast +from typing import Annotated, Any, ClassVar, Literal, cast from uuid import uuid4 import typer @@ -22,6 +22,7 @@ from landing.models import COMMANDS, Action, ActionRequest, Decision, FileInput, Mode from landing.runtime import Runtime +from landing.settings import PolicySettings REPOSITORY_GUIDANCE = ( "GitHub repository: $repository. Use the prepared gh CLI. In GitHub conversations use #number or owner/repo#number " @@ -113,12 +114,26 @@ class GitHubEnvironment(BaseSettings): admission_token: str | None = Field(default=None, validation_alias="GH_ADMISSION_TOKEN", repr=False) -class GitHubSettings(BaseSettings): - """Action inputs and explicit CLI overrides, independent of native authority.""" +class GitHubSettings(PolicySettings): + """Action inputs and explicit CLI overrides, independent of native authority. + + The loaded Landing YAML may set operator policy only: command prefix, caller trust, allowed + upstream workflows, dependency bumping, dependency update actors, and required checks. Task + inputs, caller identity, event context, run identity, database, and delivery keys stay with + the invocation. + """ model_config = SettingsConfigDict( env_prefix="INPUT_", env_ignore_empty=True, populate_by_name=True, extra="ignore", hide_input_in_errors=True ) + yaml_fields: ClassVar[frozenset[str]] = frozenset({ + "command_prefix", + "trust", + "upstream_workflow", + "bump_on_failure", + "dependency_update_actors", + "check", + }) repository: str = Field(validation_alias=AliasChoices("INPUT_REPOSITORY", "GITHUB_REPOSITORY")) event: FilePath | None = Field(default=None, validation_alias="GITHUB_EVENT_PATH") delegated_command: Literal["review", "fix", "triage", "explain", "bump"] = Field( @@ -819,9 +834,12 @@ def github_event( check: Annotated[list[str] | None, typer.Option(help="Required validation (repeatable).")] = None, ) -> None: """Admit and route an event, then confirm native publication.""" + from landing.cli import execution_runtime, execution_settings + + settings = execution_settings(ctx) parameters = {**locals(), "database": ctx.find_root().params.get("db")} options = GitHubSettings(**{ - name: value for name, value in parameters.items() if name != "ctx" and value is not None + name: value for name, value in parameters.items() if name not in {"ctx", "settings"} and value is not None }) context = GitHubEnvironment() payload = json.loads(options.event.read_text()) if options.event else None @@ -838,9 +856,6 @@ def github_event( ): write_outputs(None) raise typer.Exit() - from landing.cli import execution_runtime, execution_settings - - settings = execution_settings(ctx) upstream_run = (payload or {}).get("workflow_run", {}) if payload and ( upstream_run.get("event") == "pull_request" diff --git a/src/landing/settings.py b/src/landing/settings.py index 5562e41..317054a 100644 --- a/src/landing/settings.py +++ b/src/landing/settings.py @@ -1,11 +1,14 @@ """Landing configuration and Bub's native model settings.""" from pathlib import Path +from typing import Any, ClassVar from bub import config from bub.builtin.settings import AgentSettings +from bub.configure import get_config_data from pydantic import BaseModel, ConfigDict, Field -from pydantic_settings import BaseSettings, SettingsConfigDict +from pydantic.fields import FieldInfo +from pydantic_settings import BaseSettings, PydanticBaseSettingsSource, SettingsConfigDict from landing.models import Mode @@ -28,6 +31,48 @@ class ConfigurationFile(BaseSettings): ) +class YamlPolicySource(PydanticBaseSettingsSource): + """Operator policy from Landing's loaded YAML, restricted to names a component opts in to.""" + + def __init__(self, settings_cls: type[BaseSettings], fields: frozenset[str]) -> None: + super().__init__(settings_cls) + self.fields = fields + + def get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool]: + return None, field_name, False + + def __call__(self) -> dict[str, Any]: + return {name: value for name, value in get_config_data().items() if name in self.fields} + + +class PolicySettings(BaseSettings): + """Component settings that also accept named operator policy from Landing's YAML. + + Priority is explicit programmatic values, environment, YAML, then defaults. The allow-list is + the boundary: a component opts in to specific policy names, so the file cannot supply task + inputs, caller identity, event context, or credentials. + """ + + yaml_fields: ClassVar[frozenset[str]] = frozenset() + + @classmethod + def settings_customise_sources( + cls, + settings_cls: type[BaseSettings], + init_settings: PydanticBaseSettingsSource, + env_settings: PydanticBaseSettingsSource, + dotenv_settings: PydanticBaseSettingsSource, + file_secret_settings: PydanticBaseSettingsSource, + ) -> tuple[PydanticBaseSettingsSource, ...]: + return ( + init_settings, + env_settings, + YamlPolicySource(settings_cls, cls.yaml_fields), + dotenv_settings, + file_secret_settings, + ) + + @config() class Settings(AgentSettings): """Configure Bub's model policy using Landing's settings.""" diff --git a/tests/test_github.py b/tests/test_github.py index ad1b472..92246a5 100644 --- a/tests/test_github.py +++ b/tests/test_github.py @@ -1092,3 +1092,114 @@ def test_replayed_repair_does_not_claim_validation(tmp_path, platform, invoke, m assert replay.status == "failed" assert len(model[1]) == calls assert len(json.loads(platform.read_text())["comments"]) == 1 + + +@pytest.fixture +def operator_home(tmp_path, monkeypatch): + """Point HOME at a disposable directory whose operator YAML this test controls.""" + for name in tuple(os.environ): + if name.startswith("INPUT_"): + monkeypatch.delenv(name) + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.chdir(tmp_path) + path = tmp_path / ".landing" / "config.yml" + path.parent.mkdir() + return path + + +def test_operator_yaml_sets_event_policy_end_to_end(tmp_path, platform, model, monkeypatch, operator_home): + event = { + "repository": {"full_name": "example/landing"}, + "issue": {"number": 42}, + "comment": { + "body": "@team-bot review Inspect retry behavior.", + "user": {"type": "User", "login": "maintainer"}, + }, + } + source = tmp_path / "event.json" + source.write_text(json.dumps(event)) + for name, value in { + "GITHUB_EVENT_PATH": str(source), + "GITHUB_RUN_ID": "acceptance", + "INPUT_REPOSITORY": "example/landing", + "INPUT_DELIVERY_KEY": "policy", + "INPUT_DATABASE": str(tmp_path / "landing.sqlite3"), + }.items(): + monkeypatch.setenv(name, value) + default_prefix = CliRunner().invoke(create_cli_app(), ["github", "event"]) + assert default_prefix.exit_code == 0, default_prefix.stderr + assert not default_prefix.stdout + + operator_home.write_text("command_prefix: '@team-bot'\n") + responses, _ = model + responses.extend([ + completion( + tool="fs_write", + arguments={ + "path": "comment.json", + "content": json.dumps({"body": github.marker("gatekeeper", "policy") + "\nInspect retry behavior."}), + }, + ), + completion( + tool="bash", arguments={"command": "gh api repos/example/landing/issues/42/comments --input comment.json"} + ), + completion("Published the result."), + ]) + result = CliRunner().invoke(create_cli_app(), ["github", "event"]) + assert result.exit_code == 0, result.stderr + action = Action.model_validate_json(result.stdout) + assert action.mode == "gatekeeper" + assert action.instruction == "Inspect retry behavior." + + +def test_event_policy_precedence_and_excluded_keys(tmp_path, monkeypatch, operator_home): + operator_home.write_text( + "repository: other/landing\n" + "command_prefix: '@yaml'\n" + "trust: owner\n" + "upstream_workflow: release-main\n" + "check: |\n" + " unit\n" + " lint\n" + "bump_on_failure: true\n" + "number: 9\n" + "head: candidate-head\n" + "checked_revision: tested-head\n" + "run_id: 123\n" + "delivery_key: yaml-key\n" + "database: yaml.sqlite3\n" + "event: yaml-event.json\n" + ) + monkeypatch.setenv("INPUT_REPOSITORY", "example/landing") + monkeypatch.setenv("INPUT_COMMAND_PREFIX", "@env") + from bub.configure import load + + load(operator_home) + settings = github.GitHubSettings() + assert settings.command_prefix == "@env" + assert settings.trust == "owner" + assert settings.upstream_workflow == ["release-main"] + assert settings.check == ["unit", "lint"] + assert settings.bump_on_failure is True + assert settings.repository == "example/landing" + assert (settings.number, settings.head, settings.checked_revision) == (0, "", None) + assert settings.run_id == "" + assert settings.delivery_key is None + assert settings.event is None + assert settings.database is None + assert github.GitHubSettings(command_prefix="@explicit").command_prefix == "@explicit" + + +def test_missing_operator_yaml_keeps_defaults(tmp_path, monkeypatch): + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.setenv("INPUT_REPOSITORY", "example/landing") + from bub.configure import load + + load(tmp_path / ".landing" / "config.yml") + settings = github.GitHubSettings() + assert settings.command_prefix == "/landing" + assert settings.trust == "repository" + assert settings.upstream_workflow == [] + assert settings.check == [] + assert settings.bump_on_failure is False + assert settings.dependency_update_actors == ["dependabot[bot]", "renovate[bot]"] From 33377553b75fdf24896a93ec05c3bac72c371fc0 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 15:06:28 +0800 Subject: [PATCH 02/15] test(github): isolate native Actions context in policy checks --- tests/test_github.py | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/tests/test_github.py b/tests/test_github.py index 92246a5..ec3f6a2 100644 --- a/tests/test_github.py +++ b/tests/test_github.py @@ -1172,6 +1172,10 @@ def test_event_policy_precedence_and_excluded_keys(tmp_path, monkeypatch, operat ) monkeypatch.setenv("INPUT_REPOSITORY", "example/landing") monkeypatch.setenv("INPUT_COMMAND_PREFIX", "@env") + native_event = tmp_path / "native-event.json" + native_event.write_text("{}") + monkeypatch.setenv("GITHUB_RUN_ID", "native-run") + monkeypatch.setenv("GITHUB_EVENT_PATH", str(native_event)) from bub.configure import load load(operator_home) @@ -1183,9 +1187,9 @@ def test_event_policy_precedence_and_excluded_keys(tmp_path, monkeypatch, operat assert settings.bump_on_failure is True assert settings.repository == "example/landing" assert (settings.number, settings.head, settings.checked_revision) == (0, "", None) - assert settings.run_id == "" + assert settings.run_id == "native-run" assert settings.delivery_key is None - assert settings.event is None + assert settings.event == native_event assert settings.database is None assert github.GitHubSettings(command_prefix="@explicit").command_prefix == "@explicit" From 37b806f15fe471735a5da6048541d6056669f45c Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 15:38:04 +0800 Subject: [PATCH 03/15] fix(action): let omitted policy inputs defer to Landing YAML The composite Action declared released defaults for `trust`, `command-prefix`, `bump-on-failure`, and `dependency-update-actors`, and its step maps every input to `INPUT_*`. GitHub fills those defaults, so a hosted run always exported non-empty values that outranked the new YAML layer: a documented `trust: owner` resolved to `repository` and admitted write collaborators. Those four inputs now default to empty and keep the previous value in their description. The CLI already supplies the identical released defaults, so an omitted input defers to Landing YAML and then to the default, while an explicit workflow value, including `false` or a concrete actor list, still wins. Task inputs keep their non-empty or dynamic defaults. The regression tests read the shipped action.yml, export its declared defaults exactly as the composite step does, and assert YAML policy applies, explicit overrides win, and a missing file keeps released behavior. A hosted `trust: owner` run now skips a write collaborator and admits the owner. A metadata check keeps every declared input mapped. --- action.yml | 18 ++-- docs/reference/cli.md | 14 +-- docs/reference/configuration.md | 18 +++- tests/test_github.py | 158 ++++++++++++++++++++++++++++++++ 4 files changed, 191 insertions(+), 17 deletions(-) diff --git a/action.yml b/action.yml index 72ca784..237a6df 100644 --- a/action.yml +++ b/action.yml @@ -14,19 +14,17 @@ inputs: description: Workflow repository receiving the work; cross-repository targets are rejected. default: ${{ github.repository }} trust: - description: Native caller scope (repository writers or owner). - default: repository + description: Native caller scope (repository writers or owner). Empty leaves the Landing YAML value, then repository. + default: '' upstream-workflow: description: Allowed workflow_run source name; empty rejects workflow_run events. default: '' bump-on-failure: - description: Opt in to helping dependency update PRs after an allowed upstream workflow fails. - default: 'false' + description: Opt in to helping dependency update PRs after an allowed upstream workflow fails. Empty leaves the Landing YAML value, then false. + default: '' dependency-update-actors: - description: Allowed dependency PR authors, one per line. - default: | - dependabot[bot] - renovate[bot] + description: Allowed dependency PR authors, one per line. Empty leaves the Landing YAML value, then dependabot[bot] and renovate[bot]. + default: '' number: description: Issue or PR number; the event supplies it when available. default: '0' @@ -43,8 +41,8 @@ inputs: description: Stable identifier for a delegated delivery. default: '' command-prefix: - description: GitHub comment prefix, independent of the publishing account. - default: /landing + description: GitHub comment prefix, independent of the publishing account. Empty leaves the Landing YAML value, then /landing. + default: '' checks: description: Required check commands, one per line. default: '' diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 871db0d..65deafc 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -95,19 +95,21 @@ The `bubbuild/landing` Action executes work from GitHub workflow events. [Get st | `command` | `review` (default), `fix`, `triage`, `explain`, or `bump`; comment events route their own command. | | `instruction` | Task and acceptance criteria; defaults to carrying out the selected action using repository guidance. | | `repository` | Workflow repository; cross-repository targets fail. | -| `trust` | `repository` (default) or `owner`. | -| `upstream-workflow` | Allowed `workflow_run` name; empty rejects these events. | -| `bump-on-failure` | Default `false`; opt in to bump after an allowed same-repository PR or candidate dispatch workflow fails. | -| `dependency-update-actors` | Update account logins, one per line; defaults to `dependabot[bot]` and `renovate[bot]`. The current PR author must match. | +| `trust` | `repository` or `owner`; `repository` applies when the input is empty and no Landing YAML sets it. | +| `upstream-workflow` | Allowed `workflow_run` name; empty means Landing YAML, then rejecting these events. | +| `bump-on-failure` | Opt in to bump after an allowed same-repository PR or candidate dispatch workflow fails; empty means Landing YAML, then `false`. | +| `dependency-update-actors` | Update account logins, one per line; empty means Landing YAML, then `dependabot[bot]` and `renovate[bot]`. The current PR author must match. | | `number` | Issue or PR number; supplied by the event when available. | | `head` | Candidate head, distinct from the checked revision; PR events supply it. | | `checked-revision` | Actual checked commit, default `github.sha`. | | `run-id` | Native run to inspect, default the current run. | | `delivery-key` | Stable delivery identity; default run ID and attempt, or PR number and candidate head for automatic bump. | -| `command-prefix` | Comment prefix, default `/landing`. | -| `checks` | Required check commands, one per line. | +| `command-prefix` | Comment prefix; empty means Landing YAML, then `/landing`. | +| `checks` | Required check commands, one per line; empty means Landing YAML, then none. | | `database` | SQLite path, default `RUNNER_TEMP/landing/landing.sqlite3`. | +These six policy inputs default to empty, and the Action's composite step only forwards the values it receives, so an omitted input defers to Landing YAML and then to the documented default. An explicit input, including `false` or an empty list, still wins. Task inputs stay with the invocation. + Outputs are `id`, `status`, `decision`, and `result`. Unrelated or unauthorized events return `status: skipped` without task creation, model use, delegated tools or checks, or publication. Permission lookup errors fail the Action. Execution or required publication failure also fails the step; gate recommendations remain advisory. Automatic PR and candidate dispatch reviews update one status comment instead of requiring a new overview review per execution. Explicit review commands retain their required reply. Automatic unchanged issuer follow-up can finish without a public update. See [GitHub integration](../guides/github.md) for trust and publication. For automatic feedback, set GitHub's step-level `continue-on-error: true`; this is a workflow property, not an Action input. `steps.landing.outcome` remains `failure` even though its conclusion becomes `success`. Use the outcome to warn and retain logs and artifacts. Omit this property for strict delegations. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 527d799..83cd1d8 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -120,7 +120,7 @@ Local workspace defaults to the current directory. Servers register names with ` The runner uses prepared `GH_TOKEN` or gh login for publication and optional `GH_ADMISSION_TOKEN` for separate admission. Action inputs load from `INPUT_*`; explicit CLI options take precedence. Checks and upstream workflow names use multiline inputs. Native `GITHUB_*` identity and event context come from the execution environment; YAML cannot grant caller authority. An empty `checked-revision` input leaves check provenance unknown. -Landing YAML may also set operator policy for the GitHub runner: `command_prefix`, `trust`, `upstream_workflow`, `bump_on_failure`, `dependency_update_actors`, and `check`. CLI options, then `INPUT_*`, then YAML, then defaults decide each value. The file cannot set the repository, event file, command or instruction, issue or PR number, candidate head, checked revision, run identity, delivery key, database, or caller credentials. +Landing YAML may also set operator policy for the GitHub runner: `command_prefix`, `trust`, `upstream_workflow`, `bump_on_failure`, `dependency_update_actors`, and `check`. CLI options, then `INPUT_*`, then YAML, then defaults decide each value. The bundled Action ships empty defaults for these six inputs, so omitting a `with:` entry defers to the file; a workflow value such as `${{ vars.LANDING_TRUST }}` still wins when the variable is set. The file cannot set the repository, event file, command or instruction, issue or PR number, candidate head, checked revision, run identity, delivery key, database, or caller credentials. ```yaml command_prefix: "@team-bot" @@ -131,6 +131,22 @@ check: - uv run pre-commit run --all-files ``` +The bundled Action declares these six inputs empty, so a step that omits a `with:` entry inherits the file and then the default. To maintain static policy in one checked-in file, set `LANDING_CONFIG` once at job level and leave the policy entries out of every Action step: + +```yaml +jobs: + feedback: + runs-on: ubuntu-latest + env: + LANDING_CONFIG: .github/landing.yml + steps: + - uses: bubbuild/landing@v1 + with: + command: review +``` + +Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A workflow value always wins over the file, including an explicit `false`. + Commit attribution uses Git configuration or `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, and `GIT_COMMITTER_EMAIL`. Selecting a publication token alone does not change commit attribution. See [GitHub integration](../guides/github.md) for identity and trust, and [Action inputs](cli.md#github-action) for invocation. ## Container replication diff --git a/tests/test_github.py b/tests/test_github.py index ec3f6a2..a14346e 100644 --- a/tests/test_github.py +++ b/tests/test_github.py @@ -2,8 +2,10 @@ import json import os +from pathlib import Path import pytest +import yaml from typer.testing import CliRunner from landing.adapters import github @@ -1207,3 +1209,159 @@ def test_missing_operator_yaml_keeps_defaults(tmp_path, monkeypatch): assert settings.check == [] assert settings.bump_on_failure is False assert settings.dependency_update_actors == ["dependabot[bot]", "renovate[bot]"] + + +ACTION_METADATA = Path(__file__).resolve().parents[1] / "action.yml" +POLICY_INPUTS = ( + "trust", + "command-prefix", + "bump-on-failure", + "dependency-update-actors", + "upstream-workflow", + "checks", +) + + +def composite_inputs(monkeypatch) -> dict[str, str]: + """Export the bundled Action's declared defaults exactly as its composite step maps them.""" + declared = yaml.safe_load(ACTION_METADATA.read_text())["inputs"] + exported = {} + for name, specification in declared.items(): + value = str(specification.get("default", "")) + exported[f"INPUT_{name.upper().replace('-', '_')}"] = value + monkeypatch.setenv(f"INPUT_{name.upper().replace('-', '_')}", value) + return exported + + +def test_action_defaults_admit_operator_policy_and_keep_explicit_overrides(tmp_path, monkeypatch): + for name in tuple(os.environ): + if name.startswith(("INPUT_", "GITHUB_")): + monkeypatch.delenv(name) + monkeypatch.setenv("HOME", str(tmp_path)) + exported = composite_inputs(monkeypatch) + assert [exported["INPUT_" + name.upper().replace("-", "_")] for name in POLICY_INPUTS] == [""] * 6 + + config = tmp_path / ".landing" / "config.yml" + config.parent.mkdir() + config.write_text( + "trust: owner\n" + "command_prefix: '@team-bot'\n" + "upstream_workflow: release-main\n" + "bump_on_failure: true\n" + "dependency_update_actors: [maintainer]\n" + "check: |\n" + " unit\n" + " lint\n" + ) + from bub.configure import load + + load(config) + settings = github.GitHubSettings() + assert settings.trust == "owner" + assert settings.command_prefix == "@team-bot" + assert settings.upstream_workflow == ["release-main"] + assert settings.bump_on_failure is True + assert settings.dependency_update_actors == ["maintainer"] + assert settings.check == ["unit", "lint"] + + monkeypatch.setenv("INPUT_BUMP_ON_FAILURE", "false") + monkeypatch.setenv("INPUT_CHECKS", "integration") + monkeypatch.setenv("INPUT_TRUST", "repository") + overridden = github.GitHubSettings() + assert overridden.bump_on_failure is False + assert overridden.check == ["integration"] + assert overridden.trust == "repository" + assert overridden.command_prefix == "@team-bot" + + +def test_composite_maps_every_declared_input(): + """An input the composite step does not export would silently change behavior.""" + metadata = yaml.safe_load(ACTION_METADATA.read_text()) + exported = metadata["runs"]["steps"][-1]["env"] + assert {name.upper().replace("-", "_") for name in metadata["inputs"]} == { + key.removeprefix("INPUT_") for key in exported if key.startswith("INPUT_") + } + + +def test_action_defaults_keep_released_policy_without_operator_config(tmp_path, monkeypatch): + for name in tuple(os.environ): + if name.startswith(("INPUT_", "GITHUB_")): + monkeypatch.delenv(name) + monkeypatch.setenv("HOME", str(tmp_path)) + composite_inputs(monkeypatch) + from bub.configure import load + + load(tmp_path / ".landing" / "config.yml") + settings = github.GitHubSettings() + assert settings.trust == "repository" + assert settings.command_prefix == "/landing" + assert settings.bump_on_failure is False + assert settings.dependency_update_actors == ["dependabot[bot]", "renovate[bot]"] + assert (settings.upstream_workflow, settings.check) == ([], []) + + +def test_hosted_action_applies_owner_policy_to_a_write_collaborator(tmp_path, platform, model, monkeypatch): + for name in tuple(os.environ): + if name.startswith(("INPUT_", "GITHUB_")): + monkeypatch.delenv(name) + monkeypatch.setenv("HOME", str(tmp_path)) + monkeypatch.chdir(tmp_path) + state = json.loads(platform.read_text()) + state["owner"] = {"type": "User", "id": 1} + state["permission"] = "write" + platform.write_text(json.dumps(state)) + config = tmp_path / ".landing" / "config.yml" + config.parent.mkdir() + config.write_text("trust: owner\n") + event_path = tmp_path / "event.json" + event_path.write_text("{}") + exported = composite_inputs(monkeypatch) + for name, value in { + "GITHUB_ACTIONS": "true", + "GITHUB_EVENT_NAME": "issue_comment", + "GITHUB_EVENT_PATH": str(event_path), + "GITHUB_RUN_ID": "hosted-run", + "GITHUB_REPOSITORY": "example/landing", + "INPUT_REPOSITORY": "example/landing", + "INPUT_DELIVERY_KEY": "hosted-policy", + "INPUT_DATABASE": str(tmp_path / "landing.sqlite3"), + "INPUT_CHECKS": "", + }.items(): + monkeypatch.setenv(name, value) + assert exported["INPUT_TRUST"] == "" + + def event(user): + payload = { + "repository": {"full_name": "example/landing"}, + "issue": {"number": 42}, + "comment": {"body": "/landing explain Explain this failure.", "user": user}, + } + event_path.write_text(json.dumps(payload)) + return CliRunner().invoke(create_cli_app(), ["github", "event"]) + + writer = event({"type": "User", "id": 2, "login": "writer"}) + assert writer.exit_code == 0, writer.stderr + assert not writer.stdout + assert not model[1] + + answer = "The failure comes from the retry loop." + responses, _ = model + responses.extend([ + completion( + tool="fs_write", + arguments={ + "path": "reply.json", + "content": json.dumps({"body": github.marker("explainer", "hosted-policy") + "\n" + answer}), + }, + ), + completion( + tool="bash", arguments={"command": "gh api repos/example/landing/issues/42/comments --input reply.json"} + ), + completion(tool="confirm_reply", arguments={"comment_id": 1}), + completion(answer), + ]) + owner = event({"type": "User", "id": 1, "login": "owner"}) + assert owner.exit_code == 0, owner.stderr + admitted_action = Action.model_validate_json(owner.stdout) + assert admitted_action.mode == "explainer" + assert admitted_action.status == "completed" From ff836d651f04fc9b72990086bce104621d137a05 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 15:38:08 +0800 Subject: [PATCH 04/15] ci: set Landing model environment once per duty job Duty's two Action steps repeated the same model, endpoint, completion, and timeout environment, so a model or endpoint change meant editing both and could drift. The job now sets that static, non-secret environment once and the steps carry only their differing policy. The duty steps also take `trust` from the one repository variable through the Action's now-empty default instead of restating `repository`. Main keeps its step-scoped environment and drops `run-id` and `checked-revision`, which the Action already derives from the native run and `github.sha`. Distinct upstream workflow allow-lists stay separate. Task inputs, secrets, checkout refs, concurrency, and token boundaries are unchanged. --- .github/workflows/landing-duty.yml | 21 +++++++-------------- .github/workflows/main.yml | 4 +--- docs/development.md | 4 +++- 3 files changed, 11 insertions(+), 18 deletions(-) diff --git a/.github/workflows/landing-duty.yml b/.github/workflows/landing-duty.yml index f34689a..7d8913d 100644 --- a/.github/workflows/landing-duty.yml +++ b/.github/workflows/landing-duty.yml @@ -47,6 +47,11 @@ 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_KEY: ${{ secrets.LANDING_API_KEY }} + LANDING_API_BASE: ${{ vars.LANDING_API_BASE }} + LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }} + LANDING_MODEL_TIMEOUT_SECONDS: '120' steps: - uses: actions/checkout@v7 with: @@ -83,14 +88,8 @@ jobs: github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' || (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 command: triage checked-revision: ${{ github.event_name != 'workflow_run' && github.sha || '' }} @@ -106,14 +105,8 @@ jobs: 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' }} + trust: ${{ vars.LANDING_TRUST }} upstream-workflow: Main bump-on-failure: ${{ vars.LANDING_BUMP_ON_FAILURE || 'true' }} dependency-update-actors: | diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3cf49d8..c7f65f4 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -189,12 +189,10 @@ jobs: LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }} LANDING_MODEL_TIMEOUT_SECONDS: '120' 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) }} 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 }}. diff --git a/docs/development.md b/docs/development.md index 60dd320..ed600cc 100644 --- a/docs/development.md +++ b/docs/development.md @@ -100,7 +100,7 @@ Configure this repository's workflows with these GitHub variables and secrets: | Variable `LANDING_MODEL` | Model identifier; unset disables feedback. | | Variables `LANDING_API_BASE`, `LANDING_COMPLETION_ARGS` | Optional endpoint and completion options. | | Secret `LANDING_API_KEY` | Provider key. | -| Variable `LANDING_TRUST` | Caller policy, default `repository`. | +| Variable `LANDING_TRUST` | Optional caller policy; unset keeps the Landing YAML value, then `repository`. | | Secret `LANDING_ADMISSION_TOKEN` | Optional admission credential; organization owner checks need Members read. | | Secret `LANDING_GITHUB_TOKEN` | Publication token, default workflow token. | | Variables `LANDING_GIT_NAME`, `LANDING_GIT_EMAIL` | Optional commit identity; set both. Default is the standard Actions bot. | @@ -111,6 +111,8 @@ For a workflow-token candidate, start Main explicitly using the repository proce gh workflow run main.yml --ref BRANCH -f number=PR_NUMBER -f head=CANDIDATE_SHA ``` +Duty sets its model, endpoint, and credential environment once at job level, so its two Action steps no longer repeat the same block. Policy inputs a step omits defer to Landing YAML and then to the documented defaults; both duty steps pass `trust` from the same variable, and their distinct upstream workflow allow-lists stay separate. Main keeps its environment on its single Action step and omits the `checked-revision` and `run-id` entries the Action already derives from `github.sha` and `github.run_id`. + Candidate self-checks install Landing from that checkout. A duty task using the default-branch runtime does not reload it when the selected workspace changes. The repository includes a [Playwright MCP example](https://github.com/bubbuild/landing/blob/main/.agents/mcp.json) for demonstration and browser checks during development. From 12ae31db15a03bbd4e8f4786e4649b9f5d566786 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 15:42:31 +0800 Subject: [PATCH 05/15] docs(configuration): keep policy precedence in one place The GitHub runner section stated the Action's empty policy defaults twice, in the precedence paragraph and again under the example. Keep the statement next to the example that relies on it so a later default change has one place to update. --- docs/reference/configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 83cd1d8..974986e 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -120,7 +120,7 @@ Local workspace defaults to the current directory. Servers register names with ` The runner uses prepared `GH_TOKEN` or gh login for publication and optional `GH_ADMISSION_TOKEN` for separate admission. Action inputs load from `INPUT_*`; explicit CLI options take precedence. Checks and upstream workflow names use multiline inputs. Native `GITHUB_*` identity and event context come from the execution environment; YAML cannot grant caller authority. An empty `checked-revision` input leaves check provenance unknown. -Landing YAML may also set operator policy for the GitHub runner: `command_prefix`, `trust`, `upstream_workflow`, `bump_on_failure`, `dependency_update_actors`, and `check`. CLI options, then `INPUT_*`, then YAML, then defaults decide each value. The bundled Action ships empty defaults for these six inputs, so omitting a `with:` entry defers to the file; a workflow value such as `${{ vars.LANDING_TRUST }}` still wins when the variable is set. The file cannot set the repository, event file, command or instruction, issue or PR number, candidate head, checked revision, run identity, delivery key, database, or caller credentials. +Landing YAML may also set operator policy for the GitHub runner: `command_prefix`, `trust`, `upstream_workflow`, `bump_on_failure`, `dependency_update_actors`, and `check`. CLI options, then `INPUT_*`, then YAML, then defaults decide each value. The file cannot set the repository, event file, command or instruction, issue or PR number, candidate head, checked revision, run identity, delivery key, database, or caller credentials. ```yaml command_prefix: "@team-bot" @@ -131,7 +131,7 @@ check: - uv run pre-commit run --all-files ``` -The bundled Action declares these six inputs empty, so a step that omits a `with:` entry inherits the file and then the default. To maintain static policy in one checked-in file, set `LANDING_CONFIG` once at job level and leave the policy entries out of every Action step: +The bundled Action declares these six inputs empty, so a step that omits a `with:` entry inherits the file and then the default, while a workflow value such as `${{ vars.LANDING_TRUST }}` still wins when set. To maintain static policy in one checked-in file, set `LANDING_CONFIG` once at job level and leave the policy entries out of every Action step: ```yaml jobs: From cd59210bd6d1f9c7c7db24d820972837e7ac891e Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 15:50:35 +0800 Subject: [PATCH 06/15] fix(ci): keep provider credentials scoped to Action steps --- .github/workflows/landing-duty.yml | 5 ++++- docs/development.md | 2 +- docs/reference/cli.md | 2 +- docs/reference/configuration.md | 7 +++++-- 4 files changed, 11 insertions(+), 5 deletions(-) diff --git a/.github/workflows/landing-duty.yml b/.github/workflows/landing-duty.yml index 7d8913d..b57cadf 100644 --- a/.github/workflows/landing-duty.yml +++ b/.github/workflows/landing-duty.yml @@ -48,7 +48,6 @@ jobs: 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_KEY: ${{ secrets.LANDING_API_KEY }} LANDING_API_BASE: ${{ vars.LANDING_API_BASE }} LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }} LANDING_MODEL_TIMEOUT_SECONDS: '120' @@ -88,6 +87,8 @@ jobs: github.event_name == 'issue_comment' || github.event_name == 'pull_request_review_comment' || (github.event_name == 'workflow_run' && github.event.workflow_run.event == 'release') uses: ./ + env: + LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }} with: trust: ${{ vars.LANDING_TRUST }} upstream-workflow: release-main @@ -105,6 +106,8 @@ jobs: github.event_name == 'repository_dispatch' || (github.event_name == 'workflow_run' && github.event.workflow_run.event != 'release') uses: ./ + env: + LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }} with: trust: ${{ vars.LANDING_TRUST }} upstream-workflow: Main diff --git a/docs/development.md b/docs/development.md index ed600cc..08d31b9 100644 --- a/docs/development.md +++ b/docs/development.md @@ -111,7 +111,7 @@ For a workflow-token candidate, start Main explicitly using the repository proce gh workflow run main.yml --ref BRANCH -f number=PR_NUMBER -f head=CANDIDATE_SHA ``` -Duty sets its model, endpoint, and credential environment once at job level, so its two Action steps no longer repeat the same block. Policy inputs a step omits defer to Landing YAML and then to the documented defaults; both duty steps pass `trust` from the same variable, and their distinct upstream workflow allow-lists stay separate. Main keeps its environment on its single Action step and omits the `checked-revision` and `run-id` entries the Action already derives from `github.sha` and `github.run_id`. +Duty sets its non-secret model, endpoint, completion options, and timeout once at job level. Each Action step receives its provider key separately, so unrelated preparation steps do not inherit it. Policy inputs a step omits defer to Landing YAML and then to the documented defaults; both duty steps pass `trust` from the same variable, and their distinct upstream workflow allow-lists stay separate. Main keeps its environment on its single Action step and omits the `checked-revision` and `run-id` entries the Action already derives from `github.sha` and `github.run_id`. Candidate self-checks install Landing from that checkout. A duty task using the default-branch runtime does not reload it when the selected workspace changes. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 65deafc..f1cf496 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -108,7 +108,7 @@ The `bubbuild/landing` Action executes work from GitHub workflow events. [Get st | `checks` | Required check commands, one per line; empty means Landing YAML, then none. | | `database` | SQLite path, default `RUNNER_TEMP/landing/landing.sqlite3`. | -These six policy inputs default to empty, and the Action's composite step only forwards the values it receives, so an omitted input defers to Landing YAML and then to the documented default. An explicit input, including `false` or an empty list, still wins. Task inputs stay with the invocation. +These six policy inputs default to empty, and the Action's composite step only forwards the values it receives, so an omitted input defers to Landing YAML and then to the documented default. An explicit non-empty input, including `false`, still wins. Task inputs stay with the invocation. Outputs are `id`, `status`, `decision`, and `result`. Unrelated or unauthorized events return `status: skipped` without task creation, model use, delegated tools or checks, or publication. Permission lookup errors fail the Action. Execution or required publication failure also fails the step; gate recommendations remain advisory. Automatic PR and candidate dispatch reviews update one status comment instead of requiring a new overview review per execution. Explicit review commands retain their required reply. Automatic unchanged issuer follow-up can finish without a public update. See [GitHub integration](../guides/github.md) for trust and publication. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 974986e..d5c4ff8 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -140,12 +140,15 @@ jobs: env: LANDING_CONFIG: .github/landing.yml steps: - - uses: bubbuild/landing@v1 + - uses: actions/checkout@v7 + with: + persist-credentials: false + - uses: bubbuild/landing@main with: command: review ``` -Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A workflow value always wins over the file, including an explicit `false`. +The checkout supplies the configuration file. In privileged workflows, load operator policy from a trusted revision, not a candidate-controlled file. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`. Commit attribution uses Git configuration or `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, and `GIT_COMMITTER_EMAIL`. Selecting a publication token alone does not change commit attribution. See [GitHub integration](../guides/github.md) for identity and trust, and [Action inputs](cli.md#github-action) for invocation. From 48ec9d3fb6ddbd96726c8aae82311f4905d2644c Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 17:06:16 +0800 Subject: [PATCH 07/15] ci: read model timeout from shared landing.yml --- .github/landing.yml | 2 ++ .github/workflows/landing-duty.yml | 2 +- .github/workflows/main.yml | 2 +- 3 files changed, 4 insertions(+), 2 deletions(-) create mode 100644 .github/landing.yml diff --git a/.github/landing.yml b/.github/landing.yml new file mode 100644 index 0000000..9d3973c --- /dev/null +++ b/.github/landing.yml @@ -0,0 +1,2 @@ +# Shared model policy for the repository workflows. +model_timeout_seconds: 120 diff --git a/.github/workflows/landing-duty.yml b/.github/workflows/landing-duty.yml index b57cadf..80e6e5a 100644 --- a/.github/workflows/landing-duty.yml +++ b/.github/workflows/landing-duty.yml @@ -50,7 +50,7 @@ jobs: LANDING_MODEL: ${{ vars.LANDING_MODEL }} LANDING_API_BASE: ${{ vars.LANDING_API_BASE }} LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS || '{}' }} - LANDING_MODEL_TIMEOUT_SECONDS: '120' + LANDING_CONFIG: .github/landing.yml steps: - uses: actions/checkout@v7 with: diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index c7f65f4..b942d0a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -187,7 +187,7 @@ jobs: 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_CONFIG: .github/landing.yml with: trust: ${{ vars.LANDING_TRUST }} command: ${{ (github.event_name == 'pull_request' || (inputs.number != '' && inputs.number != '0')) && 'review' || 'triage' }} From 9e2318ae07bbefbe6b47502eeb803f149c527267 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 17:53:44 +0800 Subject: [PATCH 08/15] feat(config): move workflow operator policy into shared landing.yml --- .github/landing.yml | 39 ++++++++++++- .github/workflows/landing-duty.yml | 22 +++---- .github/workflows/main.yml | 22 +++++-- action.yml | 4 ++ docs/reference/cli.md | 3 +- docs/reference/configuration.md | 6 ++ src/landing/adapters/github.py | 17 +++++- tests/test_github.py | 94 +++++++++++++++++++++++++++++- 8 files changed, 181 insertions(+), 26 deletions(-) diff --git a/.github/landing.yml b/.github/landing.yml index 9d3973c..986b29e 100644 --- a/.github/landing.yml +++ b/.github/landing.yml @@ -1,2 +1,39 @@ -# Shared model policy for the repository workflows. +# Shared operator policy for the Main and Landing duty workflows. +# Both workflows set LANDING_CONFIG to this file; the bundled Action declares these inputs empty, +# so a non-empty workflow value (${{ vars.* }}) still overrides an entry here. 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 release evidence supplied for this event. Read the affected job logs and + deployment evidence through gh, reuse a matching issue, and record an actionable current problem. + Do not scan unrelated open issues, and do not create issues for resolved historical failures. + 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. diff --git a/.github/workflows/landing-duty.yml b/.github/workflows/landing-duty.yml index 80e6e5a..0e41555 100644 --- a/.github/workflows/landing-duty.yml +++ b/.github/workflows/landing-duty.yml @@ -49,7 +49,7 @@ jobs: 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_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS }} LANDING_CONFIG: .github/landing.yml steps: - uses: actions/checkout@v7 @@ -95,11 +95,9 @@ jobs: 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' || @@ -109,23 +107,19 @@ jobs: env: LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }} with: + # 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. + instruction: Carry out the delegated dependency maintenance. - name: Collect browser evidence if: always() run: | diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index b942d0a..23aa407 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -156,6 +156,17 @@ 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 shared policy from the base branch. + env: + POLICY_REF: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.event.pull_request.base.ref) || github.sha }} + run: | + mkdir -p "$RUNNER_TEMP/landing" + if git show "$POLICY_REF:.github/landing.yml" > "$RUNNER_TEMP/landing/landing.yml" 2>/dev/null; then + echo "LANDING_CONFIG=$RUNNER_TEMP/landing/landing.yml" >> "$GITHUB_ENV" + else + echo "::warning::No operator policy at $POLICY_REF; Landing defaults apply." + fi - uses: ./.github/actions/setup-python-env - uses: sersoft-gmbh/setup-gh-cli-action@v3 with: @@ -186,19 +197,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_CONFIG: .github/landing.yml - with: + LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS }} + with: 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 || '' }} 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." diff --git a/action.yml b/action.yml index 237a6df..8ec33d6 100644 --- a/action.yml +++ b/action.yml @@ -25,6 +25,9 @@ inputs: dependency-update-actors: description: Allowed dependency PR authors, one per line. Empty leaves the Landing YAML value, then dependabot[bot] and renovate[bot]. default: '' + dependency-update-actor-additions: + description: More allowed dependency PR authors, one per line, unioned with the effective list. Empty adds nothing. + default: '' number: description: Issue or PR number; the event supplies it when available. default: '0' @@ -81,6 +84,7 @@ runs: INPUT_UPSTREAM_WORKFLOW: ${{ inputs.upstream-workflow }} INPUT_BUMP_ON_FAILURE: ${{ inputs.bump-on-failure }} INPUT_DEPENDENCY_UPDATE_ACTORS: ${{ inputs.dependency-update-actors }} + INPUT_DEPENDENCY_UPDATE_ACTOR_ADDITIONS: ${{ inputs.dependency-update-actor-additions }} INPUT_COMMAND: ${{ inputs.command }} INPUT_INSTRUCTION: ${{ inputs.instruction }} INPUT_REPOSITORY: ${{ inputs.repository }} diff --git a/docs/reference/cli.md b/docs/reference/cli.md index f1cf496..8ef8e5b 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -98,7 +98,8 @@ The `bubbuild/landing` Action executes work from GitHub workflow events. [Get st | `trust` | `repository` or `owner`; `repository` applies when the input is empty and no Landing YAML sets it. | | `upstream-workflow` | Allowed `workflow_run` name; empty means Landing YAML, then rejecting these events. | | `bump-on-failure` | Opt in to bump after an allowed same-repository PR or candidate dispatch workflow fails; empty means Landing YAML, then `false`. | -| `dependency-update-actors` | Update account logins, one per line; empty means Landing YAML, then `dependabot[bot]` and `renovate[bot]`. The current PR author must match. | +| `dependency-update-actors` | Update account logins, one per line; empty means Landing YAML, then `dependabot[bot]` and `renovate[bot]`. A non-empty value replaces that list. The current PR author must match. | +| `dependency-update-actor-additions` | More update account logins, one per line, added to the effective list instead of replacing it; blank lines add nothing. | | `number` | Issue or PR number; supplied by the event when available. | | `head` | Candidate head, distinct from the checked revision; PR events supply it. | | `checked-revision` | Actual checked commit, default `github.sha`. | diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index d5c4ff8..7e1b03a 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -126,11 +126,17 @@ Landing YAML may also set operator policy for the GitHub runner: `command_prefix command_prefix: "@team-bot" trust: repository upstream_workflow: [release-main] +bump_on_failure: true +dependency_update_actors: + - dependabot[bot] + - renovate[bot] check: - uv run ty check - uv run pre-commit run --all-files ``` +`dependency_update_actors` sets the allowed update accounts. A non-empty `dependency-update-actors` input or `--dependency-update-actor` option replaces that list; `dependency-update-actor-additions` or `--dependency-update-actor-addition` adds logins to the effective list, so a workflow can union a prepared publishing identity and repository variables with the configured base. Blank additions add nothing. + The bundled Action declares these six inputs empty, so a step that omits a `with:` entry inherits the file and then the default, while a workflow value such as `${{ vars.LANDING_TRUST }}` still wins when set. To maintain static policy in one checked-in file, set `LANDING_CONFIG` once at job level and leave the policy entries out of every Action step: ```yaml diff --git a/src/landing/adapters/github.py b/src/landing/adapters/github.py index 9ffa069..fddcc5f 100644 --- a/src/landing/adapters/github.py +++ b/src/landing/adapters/github.py @@ -146,6 +146,7 @@ class GitHubSettings(PolicySettings): dependency_update_actors: Annotated[list[str], NoDecode] = Field( default_factory=lambda: ["dependabot[bot]", "renovate[bot]"] ) + dependency_update_actor_additions: Annotated[list[str], NoDecode] = Field(default_factory=list) command_prefix: str = "/landing" number: int = Field(default=0, ge=0) head: str = "" @@ -155,7 +156,9 @@ class GitHubSettings(PolicySettings): database: Path | None = None check: Annotated[list[str], NoDecode] = Field(default_factory=list, validation_alias="INPUT_CHECKS") - @field_validator("check", "upstream_workflow", "dependency_update_actors", mode="before") + @field_validator( + "check", "upstream_workflow", "dependency_update_actors", "dependency_update_actor_additions", mode="before" + ) @classmethod def multiline_inputs(cls, value): return [line for line in value.splitlines() if line.strip()] if isinstance(value, str) else value @@ -279,10 +282,16 @@ def rows(endpoint: str, repository: str) -> list[dict]: return [item for page in json.loads(gh(["api", endpoint, "--paginate", "--slurp"], repository)) for item in page] +def update_actors(options: GitHubSettings) -> set[str]: + """Effective allowed update accounts: the configured or replaced list plus dynamic additions.""" + names = [*options.dependency_update_actors, *options.dependency_update_actor_additions] + return {name.strip().casefold() for name in names if name.strip()} + + def dependency_pull(options: GitHubSettings, event: dict) -> dict | None: """Resolve an opted-in update account's failed CI to its current, same-repository PR.""" run = required(event, "workflow_run") - actors = {name.strip().casefold() for name in options.dependency_update_actors if name.strip()} + actors = update_actors(options) pulls = required(run, "pull_requests") head = required(run, "head_sha") if not pulls: @@ -825,6 +834,10 @@ def github_event( list[str] | None, typer.Option("--dependency-update-actor", help="Allowed dependency update account (repeatable)."), ] = None, + dependency_update_actor_additions: Annotated[ + list[str] | None, + typer.Option("--dependency-update-actor-addition", help="Additional allowed update account (repeatable)."), + ] = None, command_prefix: Annotated[str | None, typer.Option(help="Comment command prefix.")] = None, number: Annotated[int | None, typer.Option(min=0, help="Issue or PR number.")] = None, head: Annotated[str | None, typer.Option(help="Candidate commit.")] = None, diff --git a/tests/test_github.py b/tests/test_github.py index a14346e..0cda8b7 100644 --- a/tests/test_github.py +++ b/tests/test_github.py @@ -11,6 +11,7 @@ from landing.adapters import github from landing.cli import create_cli_app from landing.models import Action +from landing.settings import Settings from tests.conftest import completion @@ -278,6 +279,44 @@ def test_failed_dependency_pr_gets_one_bump_reply( assert json.loads(platform.read_text())["comments"] == delivered["comments"] +def test_dynamic_actor_additions_extend_the_configured_base( + tmp_path, platform, invoke, model, monkeypatch, dependency_ci +): + monkeypatch.setenv("INPUT_BUMP_ON_FAILURE", "true") + state = json.loads(platform.read_text()) + state["target"]["user"]["login"] = "example-publisher" + platform.write_text(json.dumps(state)) + monkeypatch.setenv("INPUT_DEPENDENCY_UPDATE_ACTOR_ADDITIONS", "\n example-publisher \n") + (tmp_path / "reply.json").write_text(json.dumps({"body": github.marker("bumper", "bump:42:candidate-head")})) + model[0].extend([ + completion( + tool="bash", + arguments={"command": "gh api repos/example/landing/issues/42/comments --input reply.json"}, + ), + completion("Reported the dependency candidate's blocker."), + ]) + action = invoke(dependency_ci, key=None) + assert action is not None and action.mode == "bumper" + assert len(json.loads(platform.read_text())["comments"]) == 1 + + +@pytest.mark.parametrize("author", ["contributor", "dependabot[bot]"]) +def test_actor_additions_keep_the_base_and_reject_unlisted_authors( + platform, invoke, model, monkeypatch, dependency_ci, author +): + monkeypatch.setenv("INPUT_BUMP_ON_FAILURE", "true") + monkeypatch.setenv("INPUT_DEPENDENCY_UPDATE_ACTOR_ADDITIONS", " \n") + state = json.loads(platform.read_text()) + state["target"]["user"]["login"] = author + platform.write_text(json.dumps(state)) + expected = author == "dependabot[bot]" + if expected: + model[0].extend([completion("Reported the dependency candidate's blocker.")]) + action = invoke(dependency_ci, key=None) + assert (action is not None) is expected + assert not json.loads(platform.read_text())["comments"] + + @pytest.mark.parametrize("condition", ["disabled", "success", "unapproved-workflow", "foreign-source"]) def test_dependency_ci_failure_skips_ineligible_candidates( platform, invoke, model, monkeypatch, dependency_ci, condition @@ -1196,6 +1235,51 @@ def test_event_policy_precedence_and_excluded_keys(tmp_path, monkeypatch, operat assert github.GitHubSettings(command_prefix="@explicit").command_prefix == "@explicit" +def test_shared_repository_config_sets_workflow_policy(tmp_path, monkeypatch): + for name in tuple(os.environ): + if name.startswith(("INPUT_", "GITHUB_")): + monkeypatch.delenv(name) + monkeypatch.setenv("HOME", str(tmp_path)) + composite_inputs(monkeypatch) + from bub.configure import load + + load(SHARED_CONFIG) + settings = github.GitHubSettings(repository="example/landing") + assert settings.bump_on_failure is True + assert settings.dependency_update_actors == ["dependabot[bot]", "renovate[bot]"] + assert github.update_actors(settings) == {"dependabot[bot]", "renovate[bot]"} + assert settings.trust == "repository" + assert settings.command_prefix == "/landing" + + monkeypatch.setenv("INPUT_BUMP_ON_FAILURE", "false") + monkeypatch.setenv("INPUT_DEPENDENCY_UPDATE_ACTOR_ADDITIONS", "\n \n") + overridden = github.GitHubSettings(repository="example/landing") + assert overridden.bump_on_failure is False + assert github.update_actors(overridden) == {"dependabot[bot]", "renovate[bot]"} + + +def test_shared_repository_config_supplies_mode_instructions(tmp_path, monkeypatch): + monkeypatch.setenv("HOME", str(tmp_path)) + from bub.configure import ensure_config, load + + load(SHARED_CONFIG) + modes = ensure_config(Settings).modes + assert "assess affected user behavior" in modes["gatekeeper"].instructions + assert "resolved historical failures" in modes["issuer"].instructions + assert "preserve" in modes["bumper"].instructions + + +def test_workflows_leave_static_policy_to_the_shared_config(): + """A static value copied back into a workflow silently defeats the shared operator config.""" + for path in WORKFLOWS: + text = path.read_text() + assert "LANDING_CONFIG" in text, path + assert "dependabot[bot]" not in text, path + assert "renovate[bot]" not in text, path + assert "|| 'true'" not in text, path + assert "|| '{}'" not in text, path + + def test_missing_operator_yaml_keeps_defaults(tmp_path, monkeypatch): monkeypatch.setenv("HOME", str(tmp_path)) monkeypatch.setenv("INPUT_REPOSITORY", "example/landing") @@ -1211,12 +1295,16 @@ def test_missing_operator_yaml_keeps_defaults(tmp_path, monkeypatch): assert settings.dependency_update_actors == ["dependabot[bot]", "renovate[bot]"] -ACTION_METADATA = Path(__file__).resolve().parents[1] / "action.yml" +REPOSITORY = Path(__file__).resolve().parents[1] +SHARED_CONFIG = REPOSITORY / ".github" / "landing.yml" +WORKFLOWS = (REPOSITORY / ".github/workflows/main.yml", REPOSITORY / ".github/workflows/landing-duty.yml") +ACTION_METADATA = REPOSITORY / "action.yml" POLICY_INPUTS = ( "trust", "command-prefix", "bump-on-failure", "dependency-update-actors", + "dependency-update-actor-additions", "upstream-workflow", "checks", ) @@ -1239,7 +1327,9 @@ def test_action_defaults_admit_operator_policy_and_keep_explicit_overrides(tmp_p monkeypatch.delenv(name) monkeypatch.setenv("HOME", str(tmp_path)) exported = composite_inputs(monkeypatch) - assert [exported["INPUT_" + name.upper().replace("-", "_")] for name in POLICY_INPUTS] == [""] * 6 + assert [exported["INPUT_" + name.upper().replace("-", "_")] for name in POLICY_INPUTS] == [""] * len( + POLICY_INPUTS + ) config = tmp_path / ".landing" / "config.yml" config.parent.mkdir() From 70f927a012544f509cd83b703ad5626404f5ae28 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 17:58:49 +0800 Subject: [PATCH 09/15] fix(ci): load shared policy from the trusted revision and keep release admission separate --- .github/landing.yml | 9 +++++---- .github/workflows/landing-duty.yml | 2 ++ .github/workflows/main.yml | 15 ++++++++------- docs/guides/github.md | 2 +- docs/reference/configuration.md | 2 +- tests/test_github.py | 29 ++++++++++++++++++++++++++--- 6 files changed, 43 insertions(+), 16 deletions(-) diff --git a/.github/landing.yml b/.github/landing.yml index 986b29e..d2d9836 100644 --- a/.github/landing.yml +++ b/.github/landing.yml @@ -25,10 +25,11 @@ modes: assess affected user behavior. issuer: instructions: | - Triage only the failures or release evidence supplied for this event. Read the affected job logs and - deployment evidence through gh, reuse a matching issue, and record an actionable current problem. - Do not scan unrelated open issues, and do not create issues for resolved historical failures. - A successful build does not establish deployed recovery. + 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. diff --git a/.github/workflows/landing-duty.yml b/.github/workflows/landing-duty.yml index 0e41555..81d082c 100644 --- a/.github/workflows/landing-duty.yml +++ b/.github/workflows/landing-duty.yml @@ -92,6 +92,8 @@ jobs: with: 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) }} diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 23aa407..76a3bd1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -157,15 +157,16 @@ jobs: fetch-depth: 0 persist-credentials: false - name: Prepare operator policy from the trusted revision - # A pull_request checkout contains candidate files, so read shared policy from the base branch. + # 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_REF: ${{ github.event_name == 'pull_request' && format('origin/{0}', github.event.pull_request.base.ref) || github.sha }} + POLICY_REVISION: ${{ github.event.pull_request.base.sha || github.sha }} run: | - mkdir -p "$RUNNER_TEMP/landing" - if git show "$POLICY_REF:.github/landing.yml" > "$RUNNER_TEMP/landing/landing.yml" 2>/dev/null; then - echo "LANDING_CONFIG=$RUNNER_TEMP/landing/landing.yml" >> "$GITHUB_ENV" + mkdir -p "$RUNNER_TEMP/policy" + if git show "$POLICY_REVISION:.github/landing.yml" > "$RUNNER_TEMP/policy/landing.yml" 2>/dev/null; then + echo "LANDING_CONFIG=$RUNNER_TEMP/policy/landing.yml" >> "$GITHUB_ENV" else - echo "::warning::No operator policy at $POLICY_REF; Landing defaults apply." + echo "::warning::No operator policy at $POLICY_REVISION; Landing defaults apply." fi - uses: ./.github/actions/setup-python-env - uses: sersoft-gmbh/setup-gh-cli-action@v3 @@ -198,7 +199,7 @@ jobs: LANDING_API_KEY: ${{ secrets.LANDING_API_KEY }} LANDING_API_BASE: ${{ vars.LANDING_API_BASE }} LANDING_COMPLETION_ARGS: ${{ vars.LANDING_COMPLETION_ARGS }} - with: + with: 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) }} diff --git a/docs/guides/github.md b/docs/guides/github.md index a581dce..6dd0add 100644 --- a/docs/guides/github.md +++ b/docs/guides/github.md @@ -72,7 +72,7 @@ Automatic help requires one open same-repository PR whose head matches the faile New updates produce an authorized draft and independent CI. Compatibility repair waits for current candidate CI failure. Existing PRs receive authorized repairs on their original branch and retain their draft status; missing write access does not justify a replacement PR. Added commits can affect a bot's [automatic maintenance](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/manage-dependabot-prs). A new head receives a new assessment; if automatic repair leaves the same failure unresolved, the agent replies with the blocker instead of repeating speculative edits. -Landing's duty workflow invokes the same bump task every Monday at 02:23 UTC or on manual dispatch. It covers open Dependabot alerts and Python dependencies using uv under project version policy, preserving pinning style when versions change. New candidates use `deps/landing-*` draft PRs; existing candidates are reused. Automatic help allows Dependabot, Renovate and the prepared publisher's `deps/landing-*` PRs; `LANDING_DEPENDENCY_UPDATE_ACTORS` adds logins. Set `LANDING_BUMP_ON_FAILURE=false` to disable it. +Landing's duty workflow invokes the same bump task every Monday at 02:23 UTC or on manual dispatch. It covers open Dependabot alerts and Python dependencies using uv under project version policy, preserving pinning style when versions change. New candidates use `deps/landing-*` draft PRs; existing candidates are reused. Automatic help allows Dependabot, Renovate and the prepared publisher's `deps/landing-*` PRs. The static base lives in the duty workflow's `.github/landing.yml`; `LANDING_DEPENDENCY_UPDATE_ACTORS` and the prepared publishing identity add logins to it instead of replacing it. Set `LANDING_BUMP_ON_FAILURE=false` to disable it. ### Handle security alerts and unresolved blockers diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 7e1b03a..5b16627 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -154,7 +154,7 @@ jobs: command: review ``` -The checkout supplies the configuration file. In privileged workflows, load operator policy from a trusted revision, not a candidate-controlled file. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`. +The checkout supplies the configuration file. In privileged workflows, load operator policy from a trusted revision, not a candidate-controlled file. Landing's feedback job checks out the candidate, so it copies `.github/landing.yml` from the PR base revision into the runner temp directory and points `LANDING_CONFIG` there; the duty job checks out the default branch and reads the checked-in file directly. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`. Commit attribution uses Git configuration or `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, and `GIT_COMMITTER_EMAIL`. Selecting a publication token alone does not change commit attribution. See [GitHub integration](../guides/github.md) for identity and trust, and [Action inputs](cli.md#github-action) for invocation. diff --git a/tests/test_github.py b/tests/test_github.py index 0cda8b7..7081259 100644 --- a/tests/test_github.py +++ b/tests/test_github.py @@ -279,6 +279,30 @@ def test_failed_dependency_pr_gets_one_bump_reply( assert json.loads(platform.read_text())["comments"] == delivered["comments"] +def test_release_admission_keeps_its_own_bump_policy(tmp_path, invoke, model, monkeypatch): + """A release step must not inherit the shared dependency-bumping policy.""" + from bub.configure import load + + load(SHARED_CONFIG) + monkeypatch.setenv("GITHUB_ACTIONS", "true") + monkeypatch.setenv("GITHUB_EVENT_NAME", "workflow_run") + monkeypatch.setenv("INPUT_BUMP_ON_FAILURE", "false") + event = { + "repository": {"full_name": "example/landing", "default_branch": "main"}, + "workflow_run": { + "id": 123, + "name": "release-main", + "event": "pull_request", + "head_repository": {"full_name": "example/landing"}, + "head_branch": "main", + "conclusion": "failure", + "actor": {"login": "maintainer"}, + }, + } + assert invoke(event, key=None) is None + assert not model[1] + + def test_dynamic_actor_additions_extend_the_configured_base( tmp_path, platform, invoke, model, monkeypatch, dependency_ci ): @@ -1266,6 +1290,7 @@ def test_shared_repository_config_supplies_mode_instructions(tmp_path, monkeypat modes = ensure_config(Settings).modes assert "assess affected user behavior" in modes["gatekeeper"].instructions assert "resolved historical failures" in modes["issuer"].instructions + assert "deployment evidence" in modes["issuer"].instructions assert "preserve" in modes["bumper"].instructions @@ -1327,9 +1352,7 @@ def test_action_defaults_admit_operator_policy_and_keep_explicit_overrides(tmp_p monkeypatch.delenv(name) monkeypatch.setenv("HOME", str(tmp_path)) exported = composite_inputs(monkeypatch) - assert [exported["INPUT_" + name.upper().replace("-", "_")] for name in POLICY_INPUTS] == [""] * len( - POLICY_INPUTS - ) + assert [exported["INPUT_" + name.upper().replace("-", "_")] for name in POLICY_INPUTS] == [""] * len(POLICY_INPUTS) config = tmp_path / ".landing" / "config.yml" config.parent.mkdir() From 69cf4d8e45d0811d6cfd5ee24fbebbe3f1a447d1 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 18:02:05 +0800 Subject: [PATCH 10/15] docs(config): document shared workflow policy and actor additions --- .github/landing.yml | 7 +++++-- .github/workflows/landing-duty.yml | 3 ++- .github/workflows/main.yml | 13 +++++++++---- tests/test_github.py | 3 ++- 4 files changed, 18 insertions(+), 8 deletions(-) diff --git a/.github/landing.yml b/.github/landing.yml index d2d9836..be3bce8 100644 --- a/.github/landing.yml +++ b/.github/landing.yml @@ -1,6 +1,7 @@ # Shared operator policy for the Main and Landing duty workflows. -# Both workflows set LANDING_CONFIG to this file; the bundled Action declares these inputs empty, -# so a non-empty workflow value (${{ vars.* }}) still overrides an entry here. +# 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. @@ -25,6 +26,8 @@ modes: assess affected user behavior. issuer: instructions: | + Native checks are independent of Landing feedback; ignore the Landing feedback job itself when + assessing whether native checks completed. 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. diff --git a/.github/workflows/landing-duty.yml b/.github/workflows/landing-duty.yml index 81d082c..596b2f0 100644 --- a/.github/workflows/landing-duty.yml +++ b/.github/workflows/landing-duty.yml @@ -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' || @@ -121,7 +123,6 @@ jobs: 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: Carry out the delegated dependency maintenance. - name: Collect browser evidence if: always() run: | diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 76a3bd1..71bac6c 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -161,12 +161,17 @@ jobs: # 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" - if git show "$POLICY_REVISION:.github/landing.yml" > "$RUNNER_TEMP/policy/landing.yml" 2>/dev/null; then - echo "LANDING_CONFIG=$RUNNER_TEMP/policy/landing.yml" >> "$GITHUB_ENV" - else - echo "::warning::No operator policy at $POLICY_REVISION; Landing defaults apply." + 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 diff --git a/tests/test_github.py b/tests/test_github.py index 7081259..7f2f055 100644 --- a/tests/test_github.py +++ b/tests/test_github.py @@ -1265,9 +1265,10 @@ def test_shared_repository_config_sets_workflow_policy(tmp_path, monkeypatch): monkeypatch.delenv(name) monkeypatch.setenv("HOME", str(tmp_path)) composite_inputs(monkeypatch) - from bub.configure import load + from bub.configure import ensure_config, load load(SHARED_CONFIG) + assert ensure_config(Settings).model_timeout_seconds == 120 settings = github.GitHubSettings(repository="example/landing") assert settings.bump_on_failure is True assert settings.dependency_update_actors == ["dependabot[bot]", "renovate[bot]"] From 76665b72c1b886e817840551a7c6c0b30fa87079 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 18:03:50 +0800 Subject: [PATCH 11/15] refactor(config): keep each mode instruction set free of duplicated policy --- .github/landing.yml | 2 -- 1 file changed, 2 deletions(-) diff --git a/.github/landing.yml b/.github/landing.yml index be3bce8..4e4361f 100644 --- a/.github/landing.yml +++ b/.github/landing.yml @@ -26,8 +26,6 @@ modes: assess affected user behavior. issuer: instructions: | - Native checks are independent of Landing feedback; ignore the Landing feedback job itself when - assessing whether native checks completed. 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. From c6ff8759d647f07ef738005ac8c40c412bece85a Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Thu, 12 Nov 2026 18:04:37 +0800 Subject: [PATCH 12/15] docs(configuration): describe the policy inputs without a fixed count --- docs/reference/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 5b16627..66b202c 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -137,7 +137,7 @@ check: `dependency_update_actors` sets the allowed update accounts. A non-empty `dependency-update-actors` input or `--dependency-update-actor` option replaces that list; `dependency-update-actor-additions` or `--dependency-update-actor-addition` adds logins to the effective list, so a workflow can union a prepared publishing identity and repository variables with the configured base. Blank additions add nothing. -The bundled Action declares these six inputs empty, so a step that omits a `with:` entry inherits the file and then the default, while a workflow value such as `${{ vars.LANDING_TRUST }}` still wins when set. To maintain static policy in one checked-in file, set `LANDING_CONFIG` once at job level and leave the policy entries out of every Action step: +The bundled Action declares its policy inputs empty, so a step that omits a `with:` entry inherits the file and then the default, while a workflow value such as `${{ vars.LANDING_TRUST }}` still wins when set. To maintain static policy in one checked-in file, set `LANDING_CONFIG` once for the job and leave the policy entries out of every Action step: ```yaml jobs: From 466cd05032a92a2091f61fb9a59e845f97ef293c Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Sat, 14 Nov 2026 01:11:15 +0800 Subject: [PATCH 13/15] docs: rewrite public documentation around adoption behavior --- README.md | 58 ++++++++++++++++++++------------- docs/development.md | 26 ++++----------- docs/get-started.md | 16 ++++----- docs/guides/github.md | 8 +++-- docs/index.md | 25 +++++++++++--- docs/make-it-yours.md | 12 +++---- docs/reference/cli.md | 2 +- docs/reference/configuration.md | 33 ++++++++++++++----- docs/working-with-landing.md | 26 ++++++--------- 9 files changed, 115 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index ae1334f..d2ad5a9 100644 --- a/README.md +++ b/README.md @@ -5,19 +5,24 @@ -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 @@ -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, inputs, and checks, and record the same action lifecycle. [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/). diff --git a/docs/development.md b/docs/development.md index 08d31b9..e4d5e02 100644 --- a/docs/development.md +++ b/docs/development.md @@ -80,7 +80,7 @@ Task instructions and evidence stay in task inputs. GitHub adaptation owns desti ## Run the feedback loop -Main checks candidate PRs, then Landing reviews the affected behavior with those conclusions. Default-branch native failures receive triage; healthy checks skip model feedback. Automatic review and triage use GitHub's `continue-on-error` on the Action step: failures emit a warning and retain their task records without failing native CI. Environment preparation outside the Action remains strict, as do explicit delegations. Maintainers can delegate explanations, fixes, triage, and reviews through explicit comment commands. Release follow-up uses the triggering release's failure or recovery evidence. +The review workflow runs native checks on a candidate pull request, then Landing reviews the affected behavior with those conclusions. Default-branch native failures receive triage; healthy checks skip model feedback. Automatic review and triage use GitHub's `continue-on-error` on the Action step, so a failure emits a warning and keeps its task record without failing native CI. Preparation outside the Action stays strict, as do explicit delegations. Release follow-up uses the triggering release's failure or recovery evidence. The release workflow also deploys documentation from main on push or manual dispatch. Package publication runs only for a published release; documentation-only runs do not trigger issuer follow-up. Pages artifacts use attempt-specific names so deployment retries select one artifact. @@ -91,33 +91,21 @@ Issue or failure -> Delegated work -> Candidate PR -> Native checks +-------------------------------------------------+ ``` -The composite Action is `action.yml`. Main and duty prepare project tools and skills, then call `uses: ./` once with built-in admission. Landing discovers the repository's `.agents` skills and MCP configuration with its default settings. Main groups review work by PR and cancels old candidates; duty uses the default-branch checkout for its prepared environment, admits explicit commands or trusted release events, and queues delegations separately. Admission protects delegated agent work; native workflow policy governs the prepared environment. [GitHub integration](guides/github.md) explains identity, trust, and publication. +The composite Action is `action.yml`. The repository's workflows prepare project tools and skills, then call `uses: ./` once with built-in admission. A review workflow groups its work by pull request and cancels superseded candidates; a separate job handles delegated commands, dependency work, and release follow-up from a default-branch checkout. Admission protects delegated agent work; native workflow policy governs the prepared environment. [GitHub integration](guides/github.md) explains identity, trust, and publication. -Configure this repository's workflows with these GitHub variables and secrets: +Static operator policy for the repository's workflows lives in one checked-in Landing YAML file, which those workflows load through `LANDING_CONFIG`. Model, endpoint, and completion bindings stay in workflow environment; each Action step receives its provider key separately so preparation steps do not inherit it. Policy an Action step omits defers to the file and then to the documented default, and distinct upstream workflow names stay separate per step. -| Setting | Purpose | -| --- | --- | -| Variable `LANDING_MODEL` | Model identifier; unset disables feedback. | -| Variables `LANDING_API_BASE`, `LANDING_COMPLETION_ARGS` | Optional endpoint and completion options. | -| Secret `LANDING_API_KEY` | Provider key. | -| Variable `LANDING_TRUST` | Optional caller policy; unset keeps the Landing YAML value, then `repository`. | -| Secret `LANDING_ADMISSION_TOKEN` | Optional admission credential; organization owner checks need Members read. | -| Secret `LANDING_GITHUB_TOKEN` | Publication token, default workflow token. | -| Variables `LANDING_GIT_NAME`, `LANDING_GIT_EMAIL` | Optional commit identity; set both. Default is the standard Actions bot. | - -For a workflow-token candidate, start Main explicitly using the repository procedure: +With the workflow token, ordinary pushes do not start another workflow run. Start native CI for a candidate explicitly: ```bash gh workflow run main.yml --ref BRANCH -f number=PR_NUMBER -f head=CANDIDATE_SHA ``` -Duty sets its non-secret model, endpoint, completion options, and timeout once at job level. Each Action step receives its provider key separately, so unrelated preparation steps do not inherit it. Policy inputs a step omits defer to Landing YAML and then to the documented defaults; both duty steps pass `trust` from the same variable, and their distinct upstream workflow allow-lists stay separate. Main keeps its environment on its single Action step and omits the `checked-revision` and `run-id` entries the Action already derives from `github.sha` and `github.run_id`. - -Candidate self-checks install Landing from that checkout. A duty task using the default-branch runtime does not reload it when the selected workspace changes. +Candidate self-checks install Landing from that checkout. A task using the default-branch runtime does not reload it when the selected workspace changes. The repository includes a [Playwright MCP example](https://github.com/bubbuild/landing/blob/main/.agents/mcp.json) for demonstration and browser checks during development. -Bundled jobs use a 120-second model request timeout. Main's feedback Action has a 20-minute step timeout inside a 25-minute job, leaving time for warnings and artifact upload. Duty has a 20-minute job timeout. Per-job SQLite artifacts expire after 30 days. Retain lasting findings in issues, project guidance, code, and meaningful regression cases. Update work items when evidence or outcomes change; avoid repeated status reports. +Retain lasting findings in issues, project guidance, code, and meaningful regression cases. Update work items when evidence or outcomes change; avoid repeated status reports. ## Publish a release @@ -129,7 +117,7 @@ After validation and merge, publish a GitHub release with an unprefixed version Check whether the explanation helped, the repair met acceptance, and feedback reached its intended destination. A model's `allow` is not its quality score. A healthy test matrix does not establish recovery from a deployment failure; verify that failure in the relevant environment. -Keep investigation details in artifacts and public feedback useful to the person receiving it. Automated work can proceed within its authorization. Maintainers stay involved in welcoming contributors, understanding concerns, and resolving disagreements, following [Community Over Code](working-with-landing.md#community-over-code). +Keep investigation details in artifacts and public feedback useful to the person receiving it. Automated work can proceed within its authorization. Maintainers stay involved in welcoming contributors, understanding concerns, and resolving disagreements, as [Community Over Code](https://www.apache.org/theapacheway/) describes. ## Verify container recovery diff --git a/docs/get-started.md b/docs/get-started.md index 2d72bcc..4316af8 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -1,8 +1,6 @@ # Your first PR review -Add Landing to an existing GitHub Actions workflow and verify that it publishes review feedback on a PR. Start with a same-repository branch whose author has write access. Fork PRs keep their native checks without receiving model or publication credentials. - -You need a model API key, a repository where you can configure Actions, and a working native check command. The example uses a Python project with uv; replace its setup and check steps with your project's existing ones. Prepare a trusted workflow source before granting it credentials. +Add Landing to an existing GitHub Actions workflow and verify that it publishes review feedback on a pull request. You need a model API key, a repository where you can configure Actions, and a working native check command. The example uses a Python project with uv; replace its setup and check steps with your project's own. Configure the workflow on a trusted branch before giving it credentials. ## Configure the model @@ -56,16 +54,16 @@ jobs: run: echo "::warning::Landing feedback failed. Inspect the Action logs." ``` -Ubuntu's runner provides gh; prepare [a supported version](guides/github.md) with your normal setup action on other runners. The example publishes as `github-actions[bot]`. Keep existing required checks independent; `continue-on-error` makes this automatic review advisory and the next step warns when it fails. Omit that property when a delegated task must fail the job. For owner-restricted execution, use a protected workflow source and the [GitHub trust controls](guides/github.md#choose-who-can-delegate). +Ubuntu's runner provides gh; prepare [a supported version](guides/github.md) with your usual setup action elsewhere. The example publishes as `github-actions[bot]`. Keep your required checks independent of this job: `continue-on-error` makes the automatic review advisory, and the following step turns a failure into a warning. Omit that property when a delegated task must fail the job. For owner-only execution, use a protected workflow source and the [GitHub trust controls](guides/github.md#choose-who-can-delegate). + +Start with a same-repository branch whose author has write access. A pull request from a fork runs the native checks and skips this step, because it receives no model or publication credentials. ## Open a PR and read the result -Put the workflow on your trusted branch, then open a same-repository PR with a small change. When the native checks pass, Landing reads the candidate and publishes an advisory status comment, updating the same comment on later candidates. New findings appear at the relevant code locations through native GitHub `COMMENT` reviews. A clean status can say `No blocking findings.` without adding code comments. +Open a same-repository pull request with a small change. When the native checks pass, Landing reads the candidate and publishes one advisory status comment, updating that comment on later candidates; new findings appear at the relevant lines through native GitHub `COMMENT` reviews. A clean result can say `No blocking findings.` without adding code comments. -Check the workflow and PR together. `status: completed` means the task finished and its required publication was verified; `decision` records `allow`, `block`, or `inconclusive`. Your team reviews the findings and independent checks to decide what to accept. Review guidance asks the agent to leave the candidate unchanged. +Read the workflow and the pull request together. `status: completed` means the task finished and its required publication was verified; `decision` records `allow`, `block`, or `inconclusive`. Review guidance asks the agent to leave the candidate unchanged, and your team decides what to accept using the findings and independent checks. -Unauthorized or unrelated events return `status: skipped` without invoking the model. Fork PRs run the native checks and skip the Landing step. Execution or required publication failure still gives the Action a failed outcome; this workflow reports it as a warning and continues. A successful workflow does not prove that Landing delivered feedback. If you see no status comment, start with the workflow logs and [Troubleshooting](guides/troubleshooting.md). +An unrelated or unauthorized event returns `status: skipped` without starting a task. Execution or required publication failure gives the Action a failed outcome, which this workflow reports as a warning. A successful workflow does not prove that feedback was delivered; if no status comment appears, start with the workflow logs and [Troubleshooting](guides/troubleshooting.md). Continue with [CI integration](guides/ci.md) for scope and concurrency, or [GitHub integration](guides/github.md#wire-commands-and-follow-ups) to delegate `/landing fix` and `/landing explain` from comments. - -For the same ongoing review and delegated-fix loop Landing uses, ask your agent to read [the repository's workflows](https://github.com/bubbuild/landing/tree/main/.github/workflows) and [development guide](development.md), then adapt that setup to your project. diff --git a/docs/guides/github.md b/docs/guides/github.md index 6dd0add..dae1ebc 100644 --- a/docs/guides/github.md +++ b/docs/guides/github.md @@ -68,15 +68,17 @@ Manual Action calls can select `command: bump`; local event calls can use `githu Opt in with `bump-on-failure: true` and an `upstream-workflow` name that runs independent candidate checks. Listen for `workflow_run: completed`; only a `failure` conclusion from a `pull_request` run or a candidate branch `workflow_dispatch` qualifies. The current PR author must match `dependency-update-actors`, which defaults to `dependabot[bot]` and `renovate[bot]`. Prepare isolated candidate tools and [Dependabot credentials](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-on-actions). Leave automatic help disabled to require an explicit `/landing bump` delegation. +Admission stays per workflow: `upstream-workflow` names the one workflow_run source you trust for a step, so a release listener and a failed-candidate listener use separate values. Do not widen one to cover both. + Automatic help requires one open same-repository PR whose head matches the failed run. Ineligible or ambiguous candidates skip; API errors fail the invocation. With the default delivery key, repeated notifications skip when the publishing account already left a marked reply for that candidate. The agent rechecks the current head and CI results before editing. New updates produce an authorized draft and independent CI. Compatibility repair waits for current candidate CI failure. Existing PRs receive authorized repairs on their original branch and retain their draft status; missing write access does not justify a replacement PR. Added commits can affect a bot's [automatic maintenance](https://docs.github.com/en/code-security/how-tos/secure-your-supply-chain/manage-your-dependency-security/manage-dependabot-prs). A new head receives a new assessment; if automatic repair leaves the same failure unresolved, the agent replies with the blocker instead of repeating speculative edits. -Landing's duty workflow invokes the same bump task every Monday at 02:23 UTC or on manual dispatch. It covers open Dependabot alerts and Python dependencies using uv under project version policy, preserving pinning style when versions change. New candidates use `deps/landing-*` draft PRs; existing candidates are reused. Automatic help allows Dependabot, Renovate and the prepared publisher's `deps/landing-*` PRs. The static base lives in the duty workflow's `.github/landing.yml`; `LANDING_DEPENDENCY_UPDATE_ACTORS` and the prepared publishing identity add logins to it instead of replacing it. Set `LANDING_BUMP_ON_FAILURE=false` to disable it. +A scheduled or dispatched bump task reuses this path: it covers open Dependabot alerts and project dependencies under the instructions you supply, and reuses an existing candidate instead of opening a duplicate. Put the allowed update accounts in Landing YAML once, then pass `dependency-update-actor-additions` for identities that only the run knows, such as the publishing account discovered from the authenticated `gh`. Additions extend the configured list; a non-empty `dependency-update-actors` input replaces it. See [Configuration](../reference/configuration.md#github-workflows-and-runner). ### Handle security alerts and unresolved blockers -GitHub exposes `dependabot_alert` as a [webhook event](https://docs.github.com/en/webhooks/webhook-events-and-payloads#dependabot_alert), not a native Actions trigger. Real-time delivery requires a prepared receiver that verifies GitHub's signature and forwards the repository's alert number through [repository dispatch](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch). Landing's duty workflow accepts this payload; it does not deploy a receiver or configure its subscription. +GitHub exposes `dependabot_alert` as a [webhook event](https://docs.github.com/en/webhooks/webhook-events-and-payloads#dependabot_alert), not a native Actions trigger. Real-time delivery requires a prepared receiver that verifies GitHub's signature and forwards the repository's alert number through [repository dispatch](https://docs.github.com/en/actions/reference/workflows-and-actions/events-that-trigger-workflows#repository_dispatch). ```json { @@ -89,7 +91,7 @@ The current GitHub alert state determines the work: open selects bump; fixed or When authorized, the agent reuses or creates an issue for confirmed exposure or blockers such as no patched version, policy conflicts or unresolved compatibility failures. It records the alert or candidate, dependency path, blocker and acceptance criteria. Routine PRs need no extra issue; unchanged evidence needs no issue update. Dismissal alone does not prove repair. -Listeners must exist on the default branch to receive events. Landing's [duty workflow](https://github.com/bubbuild/landing/blob/main/.github/workflows/landing-duty.yml) is a project example, not a requirement for using the Action. +Listeners must exist on the default branch to receive events. Landing's own workflows are an example you may adapt; the Action does not deploy a receiver or configure an alert subscription for you. ## Choose who can delegate diff --git a/docs/index.md b/docs/index.md index b2723e4..0e49e9d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,12 +7,27 @@ title: Landing Landing -Landing helps your team act on engineering problems: explain a failure, make it actionable, delegate a fix, or review a candidate. It works with the tools and checks you already use. +Landing delegates engineering work to a language model using the tools, checks, and identity you prepared: explain a failure, make a problem actionable, repair a demonstrated defect, review a candidate, or update a dependency. -Start with [your first PR review](get-started.md) to use Landing in GitHub Actions, or [run a local task](guides/local.md) from the CLI. Both paths use the same commands and action records. Use the CLI in other CI systems or connect callers to a shared HTTP service. +You choose the model endpoint, execution environment, project instructions, and acceptance checks. Landing admits the work, runs the selected mode, verifies publication, and records the result in SQLite. The documented paths need no hosted Landing account. -You control the model, execution environment, instructions, and tools. Landing is open source, and the documented paths require no hosted Landing account. Read [Make Landing work for you](make-it-yours.md) to adapt it to your team. +## Start -[Working with Landing](working-with-landing.md) describes the method: use relevant engineering context, verify the outcome, and retain feedback. Keep participating in the conversations and relationships that sustain your project. Community Over Code. +- [Your first PR review](get-started.md) adds the Action to a GitHub workflow and verifies that it publishes feedback. +- [Use Landing locally](guides/local.md) runs a task from the CLI against your own checkout. -Use the guides to complete a task and the reference to look up exact commands, settings, and API contracts. [Develop and dogfood](development.md) describes Landing's own development process. +Both use the same modes, inputs, checks, and action records. Use the CLI in another CI system, or [run the server](guides/server.md) when several callers share one prepared environment. + +## Find the right page + +| Goal | Page | +| --- | --- | +| Choose the model, skills, tools, and runner policy | [Configuration](reference/configuration.md) | +| Look up a command, exit code, or Action input | [CLI reference](reference/cli.md) | +| Submit work over HTTP | [HTTP reference](reference/http.md) | +| Wire repository events, comments, and trust | [GitHub integration](guides/github.md) | +| Prepare project guidance and skills | [Make Landing work for you](make-it-yours.md) | +| Understand how context and verification make results reliable | [Working with Landing](working-with-landing.md) | +| Diagnose a failure | [Troubleshooting](guides/troubleshooting.md) | + +[Develop and dogfood](development.md) describes how Landing itself is built and tested. diff --git a/docs/make-it-yours.md b/docs/make-it-yours.md index a059a61..44fa311 100644 --- a/docs/make-it-yours.md +++ b/docs/make-it-yours.md @@ -1,19 +1,17 @@ # Make Landing work for you -You choose the model, environment, instructions, tools, and acceptance checks. Start with the built-in commands and adapt the parts your team needs. CLI, CI, and HTTP calls share the same action contract. +You choose the model endpoint, execution environment, instructions, tools, and acceptance checks. The built-in commands work as shipped; adapt the parts your team needs. CLI, CI, and HTTP calls share the same action contract. ## Choose the model and environment -Configure the model where work executes: +Configure the model where work executes; [Configuration](reference/configuration.md#model) lists the settings, endpoints, and precedence: ```bash export LANDING_MODEL="openai:gpt-4.1" export LANDING_API_KEY="your-provider-api-key" ``` -You can save settings in `~/.landing/config.yml`; see [Configuration](reference/configuration.md) for endpoints and precedence. Model requests go to the selected provider, whose data handling applies. - -Prepare checkouts, language runtimes, dependencies, credentials, and baseline data using your existing setup process. A remote client uses the server's prepared environment. Landing does not install project tools or skills for you. +Model requests go to the selected provider, whose data handling applies. Prepare checkouts, language runtimes, dependencies, credentials, and baseline data with your existing setup process. A remote caller uses the server's prepared environment; Landing does not install project tools or skills for you. ## Provide project guidance @@ -25,7 +23,7 @@ Landing reads the selected workspace's root `AGENTS.md`. Its guidance asks the a Use python acceptance.py to verify CLI behavior. Compare benchmarks with the same workload and environment. When investigating a deployed failure, record the deployed revision and the relevant logs. ``` -Instructions guide the agent; they do not grant permissions or enforce an operating-system boundary. +Instructions guide the agent; they grant no permissions and enforce no boundary. ## Prepare skills @@ -60,4 +58,4 @@ Checks execute in the task workspace. Exit status establishes pass or failure, s Supply focused evidence with `--input`, use the prepared gh CLI for [GitHub](guides/github.md), or translate another platform's events into the [HTTP contract](reference/http.md). Provider signatures belong at that translation boundary. Use a [service](guides/server.md) for shared callers. -Landing's Apache-2.0 source lets you change prompts, runtime behavior, and adapters. Use the CLI, GitHub integration, or [HTTP service](reference/http.md) to delegate work. For an embedded agent, use [Bub's SDK](https://bub.build/docs/build/sdk/). Actions and model history stay in SQLite; workspace files remain separate. Choose retention and [recovery](guides/recovery.md) for both. +Landing's Apache-2.0 source lets you change prompts, runtime behavior, and adapters. Actions and model history stay in SQLite; workspace files remain separate, so choose retention and [recovery](guides/recovery.md) for both. For an embedded agent outside Landing's entry points, use [Bub's SDK](https://bub.build/docs/build/sdk/). diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 8ef8e5b..ed37377 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -109,7 +109,7 @@ The `bubbuild/landing` Action executes work from GitHub workflow events. [Get st | `checks` | Required check commands, one per line; empty means Landing YAML, then none. | | `database` | SQLite path, default `RUNNER_TEMP/landing/landing.sqlite3`. | -These six policy inputs default to empty, and the Action's composite step only forwards the values it receives, so an omitted input defers to Landing YAML and then to the documented default. An explicit non-empty input, including `false`, still wins. Task inputs stay with the invocation. +The policy inputs default to empty, and the Action's composite step only forwards the values it receives, so an omitted input defers to Landing YAML and then to the documented default. An explicit non-empty input, including `false`, still wins. Task inputs stay with the invocation. Outputs are `id`, `status`, `decision`, and `result`. Unrelated or unauthorized events return `status: skipped` without task creation, model use, delegated tools or checks, or publication. Permission lookup errors fail the Action. Execution or required publication failure also fails the step; gate recommendations remain advisory. Automatic PR and candidate dispatch reviews update one status comment instead of requiring a new overview review per execution. Explicit review commands retain their required reply. Automatic unchanged issuer follow-up can finish without a public update. See [GitHub integration](../guides/github.md) for trust and publication. diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 66b202c..168b3ee 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -55,16 +55,16 @@ modes: allowed_skills: [landing-issuer, issue-triage] fixer: allowed_tools: [spill.read, fs.read, fs.write, fs.edit, bash, skill] - allowed_skills: [landing-fixer, friendly-python, piglet] + allowed_skills: [landing-fixer, team-style] gatekeeper: instructions: | Review supported user-visible behavior. - Use $landing-review for project-specific standards. - allowed_skills: [landing-gatekeeper, landing-review] + Use $review-standards for project-specific rules. + allowed_skills: [landing-gatekeeper, review-standards] excluded_tools: [fs.write, fs.edit] explainer: allowed_tools: [spill.read, fs.read, skill] - allowed_skills: [landing-explainer, documentation-writer] + allowed_skills: [landing-explainer] ``` `instructions` adds guidance without replacing the selected method or granting capabilities. Keep project conventions in `AGENTS.md`, reusable methods in skills, and evidence in task inputs. These additions stay literal rather than being evaluated as templates. @@ -125,14 +125,14 @@ Landing YAML may also set operator policy for the GitHub runner: `command_prefix ```yaml command_prefix: "@team-bot" trust: repository -upstream_workflow: [release-main] +upstream_workflow: [ci] bump_on_failure: true dependency_update_actors: - dependabot[bot] - renovate[bot] check: - - uv run ty check - - uv run pre-commit run --all-files + - make acceptance + - make lint ``` `dependency_update_actors` sets the allowed update accounts. A non-empty `dependency-update-actors` input or `--dependency-update-actor` option replaces that list; `dependency-update-actor-additions` or `--dependency-update-actor-addition` adds logins to the effective list, so a workflow can union a prepared publishing identity and repository variables with the configured base. Blank additions add nothing. @@ -154,7 +154,24 @@ jobs: command: review ``` -The checkout supplies the configuration file. In privileged workflows, load operator policy from a trusted revision, not a candidate-controlled file. Landing's feedback job checks out the candidate, so it copies `.github/landing.yml` from the PR base revision into the runner temp directory and points `LANDING_CONFIG` there; the duty job checks out the default branch and reads the checked-in file directly. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`. +The checkout supplies the configuration file. In a privileged workflow, load operator policy from a trusted revision instead of the candidate-controlled checkout. A job that checks out a pull request candidate can copy `.github/landing.yml` from the base revision into `RUNNER_TEMP` and point `LANDING_CONFIG` there: + +```yaml + - name: Prepare operator policy from the trusted revision + env: + POLICY_REVISION: ${{ github.event.pull_request.base.sha || github.sha }} + run: | + mkdir -p "$RUNNER_TEMP/policy" + policy="$RUNNER_TEMP/policy/landing.yml" + git show "$POLICY_REVISION:.github/landing.yml" > "$policy" + echo "LANDING_CONFIG=$policy" >> "$GITHUB_ENV" +``` + +This keeps the file outside the checkout, so candidate files cannot supply it. If the base revision may predate the file, fall back to no `LANDING_CONFIG` and let the documented defaults apply rather than reading the checkout. + +A job that checks out the default branch can read the checked-in file directly. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`. + +A `workflow_run` listener admits one named upstream workflow per step. Give a release listener and a failed-candidate listener their own `upstream-workflow` values rather than combining them. Commit attribution uses Git configuration or `GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `GIT_COMMITTER_NAME`, and `GIT_COMMITTER_EMAIL`. Selecting a publication token alone does not change commit attribution. See [GitHub integration](../guides/github.md) for identity and trust, and [Action inputs](cli.md#github-action) for invocation. diff --git a/docs/working-with-landing.md b/docs/working-with-landing.md index 10d8918..8250e3f 100644 --- a/docs/working-with-landing.md +++ b/docs/working-with-landing.md @@ -1,12 +1,12 @@ # Working with Landing -Landing can investigate failures, prepare issues, make changes, run checks, and publish reviews within the authority you give it. Reliable results depend on the engineering context your team maintains and the evidence you use to accept work. +Landing can investigate a failure, prepare an issue, make a change, run checks, and publish a review within the authority you give it. Results depend on the engineering context your team maintains and the evidence you use to accept the work. ## Connect the engineering context -Give Landing relevant documentation and work items to establish intended behavior and acceptance criteria. Infrastructure describes where the work runs. Tests, benchmarks, and observability establish what it does. Make these available through workspace files, focused snapshots, or tools in the prepared environment. +Give Landing the material that establishes intended behavior and acceptance criteria: documentation, work items, infrastructure, tests, benchmarks, and observability. Expose it through workspace files, focused task inputs, or tools in the prepared environment. -Start with the material needed for the question. Let the agent fetch a specific log or discussion when it needs more evidence. Connecting the engineering system does not require loading every document or issue into every task. +Load only what the question needs and let the agent fetch a specific log or discussion when it does. Preparing the system does not mean loading every document into every task. ```mermaid flowchart TB @@ -32,30 +32,24 @@ flowchart TB Learning --> Evidence ``` -Native checks and operational signals reach maintainers directly. Landing helps them act on the same evidence. Each command works independently; the diagram does not require every task to pass through all four actions. +Landing helps maintainers act on evidence they already receive; it does not replace native checks or operational signals. Each command works independently. ## Delegate a concrete task -Use `explain` for a question, `triage` to make a problem actionable, `fix` for a repair, `review` to evaluate a candidate, and `bump` to update dependencies. State the unresolved condition, expected outcome, relevant constraints, and evidence that would settle it. +Use `explain` for a question, `triage` to make a problem actionable, `fix` for a repair, `review` to evaluate a candidate, and `bump` to update dependencies. State the unresolved condition, the expected outcome, the constraints that matter, and the evidence that would settle it. ```text Fix the documented timeout behavior. Reproduce the failure, preserve the public CLI contract, and use the existing acceptance check. Report the observed result and any remaining uncertainty. ``` -Reuse an existing issue when it describes the same problem. Automatic follow-up updates it only when evidence, conditions, or verified progress change. A new run ID alone does not justify another status comment. Explicit questions still receive a reply. +Reuse the issue that already describes a problem. Automatic follow-up updates it only when evidence, conditions, or verified progress change; a new run alone does not justify another comment. Explicit questions still get a reply. ## Verify the outcome -Reuse independent checks that cover the candidate and its execution environment. Identify the checked revision when it affects the conclusion; a PR head, CI merge checkout, and deployed commit can differ. Use source inspection or a focused counterexample for an unresolved question. +Reuse independent checks that cover the candidate and its environment, and name the revision when it affects the conclusion: a pull request head, a CI merge checkout, and a deployed commit can differ. Resolve an unresolved question with source inspection or the smallest counterexample. -Keep the outcome clear: task completion, a model recommendation, a published reply, and actual recovery establish different things. An `allow` recommendation does not replace acceptance evidence. Review findings should explain a supported trigger and consequence at the useful repair location, with a short verdict when the details are inline. +Keep distinct claims distinct. Task completion, a model recommendation, a published reply, and actual recovery establish different things, and an `allow` recommendation does not replace acceptance evidence. A review finding should state a supported trigger and its consequence at the place someone would repair it. -Retain useful findings and mistaken assumptions in the relevant work item. Improve project guidance, tools, code, or checks where the problem belongs. Behavior tests cover the experience users see; regression tests cover actual mistakes likely to recur. See [Develop and dogfood](development.md) for Landing's own feedback loop. +Record useful findings and mistaken assumptions in the work item. Improve project guidance, tools, code, or checks where the problem belongs. Behavior tests cover the experience users see; regression tests cover mistakes likely to recur. -## Community Over Code - -A healthy community sustains a project as its code changes. [The Apache Way](https://www.apache.org/theapacheway/) describes this as Community Over Code. - -Use the time saved by automation to listen to users, welcome contributions, and work through disagreements. Tools can help prepare a reply; personal thanks, empathy, and commitments need your attention. Stay involved when someone needs encouragement, clarification, or a conversation about the project's direction. - -Authorized engineering tasks can run automatically, including investigation and publication. Maintain the relationships behind that work yourself. Judge the experience by whether people can make progress and remain willing to participate, as well as whether a candidate passes its checks. +Automation can handle investigation and publication within its authorization. Keep the human part — welcoming contributors, understanding concerns, resolving disagreement — with maintainers. From b31c6224a7386c2cbee46658ffac7fae5a935813 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Sat, 14 Nov 2026 02:20:05 +0800 Subject: [PATCH 14/15] docs: make the trusted policy example correct for a shallow checkout --- README.md | 2 +- docs/reference/configuration.md | 23 +++++++++++++++++++---- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d2ad5a9..52cc997 100644 --- a/README.md +++ b/README.md @@ -46,7 +46,7 @@ The example follows `main`; pin a release tag or reviewed commit to keep the run | [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. | -All three accept the same modes, instructions, inputs, and checks, and record the same action lifecycle. [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`. +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`. ## Configure and adapt diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index 168b3ee..e2ed8da 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -154,20 +154,35 @@ jobs: command: review ``` -The checkout supplies the configuration file. In a privileged workflow, load operator policy from a trusted revision instead of the candidate-controlled checkout. A job that checks out a pull request candidate can copy `.github/landing.yml` from the base revision into `RUNNER_TEMP` and point `LANDING_CONFIG` there: +The checkout supplies the configuration file. In a privileged workflow, load operator policy from a trusted revision instead of the candidate-controlled checkout. A job that checks out a pull request candidate can read `.github/landing.yml` from the base commit into `RUNNER_TEMP` and point `LANDING_CONFIG` there: ```yaml +jobs: + feedback: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + with: + fetch-depth: 0 # the base commit object must exist for the lookup below + persist-credentials: false - name: Prepare operator policy from the trusted revision env: POLICY_REVISION: ${{ github.event.pull_request.base.sha || github.sha }} run: | mkdir -p "$RUNNER_TEMP/policy" policy="$RUNNER_TEMP/policy/landing.yml" - git show "$POLICY_REVISION:.github/landing.yml" > "$policy" - echo "LANDING_CONFIG=$policy" >> "$GITHUB_ENV" + if git show "$POLICY_REVISION:.github/landing.yml" > "$policy" 2>/dev/null && [ -s "$policy" ]; then + echo "LANDING_CONFIG=$policy" >> "$GITHUB_ENV" + else + rm -f "$policy" + echo "::warning::No operator policy at the base revision; Landing defaults apply." + fi + - uses: bubbuild/landing@main + with: + command: review ``` -This keeps the file outside the checkout, so candidate files cannot supply it. If the base revision may predate the file, fall back to no `LANDING_CONFIG` and let the documented defaults apply rather than reading the checkout. +`fetch-depth: 0` matters because a shallow pull request checkout normally lacks the base commit, so the lookup fails. The `if` keeps the runner's `bash -eo pipefail` shell from aborting on a miss, deletes the empty file, and leaves `LANDING_CONFIG` unset, so Landing applies its documented defaults instead of reading an empty file from the checkout. This also covers a base revision that predates the file. A job that checks out the default branch can read the checked-in file directly. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`. From 1ace89e4dc924d1581eaab03e61f1bfbc33a2780 Mon Sep 17 00:00:00 2001 From: Chojan Shang Date: Sat, 14 Nov 2026 03:24:56 +0800 Subject: [PATCH 15/15] docs(configuration): require the trusted policy export to be the only config source --- docs/reference/configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index e2ed8da..05bf5d6 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -182,7 +182,7 @@ jobs: command: review ``` -`fetch-depth: 0` matters because a shallow pull request checkout normally lacks the base commit, so the lookup fails. The `if` keeps the runner's `bash -eo pipefail` shell from aborting on a miss, deletes the empty file, and leaves `LANDING_CONFIG` unset, so Landing applies its documented defaults instead of reading an empty file from the checkout. This also covers a base revision that predates the file. +`fetch-depth: 0` matters because a shallow pull request checkout normally lacks the base commit, so the lookup fails. The `if` keeps the runner's `bash -eo pipefail` shell from aborting and, on a miss, deletes the empty file and skips the export; a base revision that predates the file takes the same path. Use this pattern instead of the job-level `LANDING_CONFIG` above, and keep any job- or step-level `LANDING_CONFIG` out of this job: the export here must be its only source. Skipping the export cannot clear a value the job already carries, so an inherited job-level `LANDING_CONFIG: .github/landing.yml` would keep pointing into the candidate checkout and Landing would read candidate-supplied policy. With no inherited value, a miss leaves the setting absent and Landing applies its documented defaults. A job that checks out the default branch can read the checked-in file directly. Keep provider credentials in the Action step environment rather than widening their scope to unrelated job steps. Values that vary per event or step, such as the delegated command, instruction, number, head, delivery key, or a `${{ vars.* }}` override, stay in `with:`. A non-empty workflow value wins over the file, including an explicit `false`.