Use Landing with GitHub¶

Prepare a trusted checkout, authenticated gh 2.48 or later in PATH, project dependencies, model configuration, and skills. Landing supplies event admission, repository context, and publication verification; the agent uses your prepared tools to investigate and publish. Start with your first PR review.

Use the official GitHub CLI packages or your usual setup action. Landing requires gh api --paginate --slurp; older versions are unsupported. The container installs gh from the official package repository. Optional attachment uploads require gh 2.99 or later and an upload-capable identity.

Choose the publishing identity¶

Gh credentials determine who publishes. Landing verifies that required reviews and replies come from that account. Git's author and committer settings determine commit attribution. Prepare both before delegating a write. The /landing prefix and delivery markers identify commands and deliveries, not accounts.

With the workflow token, GitHub publishes as github-actions[bot]. For another account, pass its token or prepared gh login and use its actual Git identity. For an organization, use an organization-owned GitHub App or authorized machine account; organizations cannot act as users. The official App-token Action shows token and bot identity setup.

Use existing Git configuration or the standard GIT_AUTHOR_* and GIT_COMMITTER_* variables. Run gh auth setup-git when authorizing pushes. Landing preserves caller-provided identity and does not change authentication. See Configuration for runner credentials.

Follow repository conventions¶

Root and scoped AGENTS.md files and prepared skills supply project procedures. Include branch conventions, acceptance checks, and instructions for starting candidate CI. Prepare an isolated checkout for fixes and dependency updates.

When creating an authorized issue or PR, the agent reads the applicable template from GitHub's standard locations. It fills sections with actual evidence and leaves unverified checkboxes unchecked. YAML issue-form labels become Markdown headings; gh does not submit the interactive form. Templates are fetched when needed.

Invoke locally¶

Use the ordinary CLI with your prepared gh login and repository context:

landing --github-repository example/team-project triage "Investigate the evidence and make the problem actionable." --input report.txt

In Actions, Landing supplies the trigger, target, and relevant revisions. The agent fetches specific discussions, templates, diffs, or logs through gh; complete histories and issue lists are not injected. Use the Action's instruction input for task scope and relevant new evidence.

Publish native results¶

Automatic PR and candidate workflow_dispatch reviews maintain one status comment per PR and publishing account. Each completed assessment updates that comment with the candidate, advisory decision, and a short result or links to outstanding findings. A new commit does not require a new overview review. The Action outputs and task records retain each execution's result; the comment shows only the latest published assessment.

New findings use native GitHub Reviews, attached to affected lines where possible. Existing findings stay in their original threads. Follow-ups report changed conclusions, impact or required repairs, confirm fixes, withdraw mistaken claims, or answer questions. A new SHA, moved line or repeated reproduction alone needs no reply. Resolved threads stay settled unless new evidence changes their conclusion. Reviews comment by default; approvals and change requests require explicit authorization.

Explicit PR review commands still require a native review for the requested commit; inline commands require a reply in the original thread. Status updates do not replace those replies.

While admitted work runs, Landing adds an eyes reaction to the triggering PR or command comment. When the work finishes, a rocket replaces it for completed work and a confused reaction for failed work; cancelled or superseded runs only remove it. A delegation for a head that is no longer current is rejected before it starts and leaves existing reactions unchanged. A hard-killed runner cannot clean up, so its eyes reaction stays until the next run on that subject replaces it. Reactions are best effort: a token without reaction permission leaves the work and its publication unaffected.

Explicit delegations require a reply to their selected issue or PR; inline follow-ups reply in the original review thread. Landing verifies that the prepared identity published to the requested destination before reporting completion. Include confirm_reply when restricting tools for inline follow-ups.

Automatic issuer follow-up publishes only useful new evidence, changed conditions, or verified progress. Unchanged conditions complete quietly through no_update, retaining the reason in SQLite. Failed tool execution cannot waive required publication. Explicit questions still require replies.

The same database and delivery key reuse a completed delivery without another model call while its publication receipt remains available. A new delegation needs a new key. A fresh runner can recover an automatic review's decision and result from the matching latest status receipt, but not its execution or validation history. Once a later delivery replaces that receipt, replay of the older local record fails rather than rolling back the status; use a new key for another assessment. Missing or mismatched required publication fails the task.

Status publication is read back and the candidate head is checked before and after delivery. Serialize review jobs per PR with workflow concurrency: GitHub comment writes and head checks are not atomic, and concurrent initial runs can create duplicate status comments. The Action fails for execution or delivery failure, while block and inconclusive remain advisory; ordinary CLI review has stricter exit semantics.

Use GitHub conversation references such as #42 or owner/repo#42, and link commits with short, unambiguous hashes. Other destinations need explicit links. Full identities remain in API calls and verification.

Wire commands and follow-ups¶

Listen for issue_comment and pull_request_review_comment; the Action reads the native event file. An admitted caller delegates with the first nonblank line:

/landing triage Track the recurring release failure with acceptance criteria.
/landing fix Fix this issue and preserve its user-visible behavior.
/landing review Review the candidate against independent checks.
/landing explain Explain the failed job and the next useful check.
/landing bump Update example-lib to 1.2.3 in the root project, following update policy and keeping the lockfile consistent.

The prefix is configurable and can use your actual bot mention. Every delegation, including a thread follow-up, requires an explicit command. Ordinary status replies and Landing's marked output do not trigger work. Authorized machine accounts can delegate; a bot name or installation ID grants no authority by itself.

Manual Action calls can select command: bump; local event calls can use github event --command bump. Supply dependency targets and project or bot configuration through ordinary instructions or inputs. Required checks run after edits, and explicit delegations require a verified conversation or thread reply. Local dependency updates covers work without CI.

Help dependency updates after CI fails¶

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. Leave automatic help disabled to require an explicit /landing bump delegation.

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. 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.

Handle security alerts and unresolved blockers¶

GitHub exposes dependabot_alert as a webhook event, 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. Landing's duty workflow accepts this payload; it does not deploy a receiver or configure its subscription.

{
  "event_type": "dependabot_alert",
  "client_payload": {"alert_number": 7}
}

The current GitHub alert state determines the work: open selects bump; fixed or dismissed reconciles tracked work without a new upgrade. Alert lookup errors fail the invocation. The executing identity needs Dependabot alerts read access, such as vulnerability-alerts: read for the workflow token.

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 is a project example, not a requirement for using the Action.

Choose who can delegate¶

trust: repository admits effective repository writers and administrators. trust: owner admits the current personal owner by user ID, or an active organization owner with native membership role: admin. It does not admit every repository administrator. Native repository permission and organization membership APIs are authoritative; Landing keeps no member list or permission cache.

Comments check their author, not the PR author or author_association. Repository policy reuses GitHub's authorization for native Actions dispatch, schedules, push, release, and validated workflow_run sources, including authorized Apps. These entries do not query a bot's user-level repository permission. Other events check the sender; owner policy always checks identity and also checks the rerunning user on reruns. Local invocation without an event uses the executing user's credentials.

Admission authorizes delegated model use, tools, checks, and publication. Known unauthorized callers skip without starting a task or publishing a refusal. Organization-owner checks first skip callers without repository admin access, then query membership. Unreadable membership, including an ambiguous 404, fails closed; other permission lookup errors also fail the invocation. Owner checks need a credential with repository Metadata/Contents read and organization Members read. Set GH_ADMISSION_TOKEN when admission uses a different credential from publication.

Action targets and events must match the workflow repository. workflow_run additionally needs an allowed upstream-workflow name, matching source repository, and a default-branch push, manual dispatch, or release as its source event. The opted-in dependency help path also admits failed PR or candidate dispatch runs under the candidate and account rules above. Success alone does not authorize execution. An event file must come from a trusted caller; an external webhook receiver verifies the original signature before translation.

Use protected default-branch or pinned workflow code for policy and setup. Owner-restricted credential jobs also need GitHub environment branch restrictions, required reviewers, and branch governance such as CODEOWNERS. Repository administrators can edit settings, so owner trust alone does not isolate secrets from them. CI integration shows native environment controls. The workflow prepares the project and calls the Action once; admission governs Landing's work and does not protect earlier steps or make candidate code trusted. Job permissions constrain GITHUB_TOKEN, not separately supplied PATs or App tokens.

Finish and cancel work¶

A fixer validates its repair, publishes the candidate, starts required native CI, and replies with the result and pending-check links. It waits only when the delegation requires CI results before replying, and never waits for its own feedback job. With GitHub's workflow token, ordinary pushes do not start another workflow; use an authorized explicit dispatch following repository procedures.

CI concurrency cancels old candidates at workflow arrival. The runner also rejects stale heads, checks the current head before each model tool batch, and verifies the candidate recorded in the published status comment or explicit review. Stale or unverifiable heads stop new tools; this is not an atomic publication lock, and an in-flight write may finish. Existing reviews remain. Explicit comment work uses a separate queue.

Runner termination requests normal stream cancellation and shell cleanup. Hard termination can leave interrupted work for recovery. Use !cancelled() for agent jobs and reserve always() for cleanup. See Troubleshooting for partial work and Develop and dogfood for Landing's workflow wiring.