Install the Orbit skill from orbit-cli and index workloads with a checkout

Thomas Schmidtrequested to merge
duo/update/599968-orbit-local-setup-drop-ff-glab-1-115 into master

What does this MR do and why?

Duo Agent Platform workloads with a checkout now get the Orbit skill from orbit-cli itself and index the checkout before the agent starts, so the agent has a branch-aware knowledge graph. Local Orbit has no Orbit gate. Remote Orbit content only shows up in the skill when remote Orbit is available to the agent. The orbit-cli path is behind duo_developer_orbit, so we can roll it out on GitLab.com and turn it off without a release. With the flag off, workloads behave as on master.

Closes #599968

What changed

  • OrbitSetup (was OrbitLocalSetup) owns all Orbit setup. GlabSetup only sets up glab.
    • With a checkout and duo_developer_orbit on: glab orbit --yes setup duo --yes --skip instructions --no-index writes the full orbit skill (SKILL.md plus references/) that matches the installed binary, then glab orbit --yes index . indexes the checkout. glab orbit installs the binary on first use. If setup fails, the index step is skipped, so a failed download isn't retried.
    • Otherwise: the workload keeps glab's remote Orbit skill (glab skills install --global --force orbit) when foundational_enabled?, as on master. This covers flows without a checkout (coding_environment: none) and the flag being off.
    • The hand-written orbit-local skill and WORKLOAD_NOTE are removed.
  • Remote content: orbit-cli adds the instance's remote skill only when GET /api/v4/orbit/skills/orbit answers. That route returns 404 unless GKG is configured and the user is in an Orbit-enabled namespace, so the local-only skill is the fallback. The route ignores the license, the "Orbit in GitLab Duo" setting and the user's "Other Foundational Agents" setting, so the setup runs with GITLAB_TOKEN= when ::Ai::Orbit::Settings.foundational_enabled? is false. Without a credential, orbit-cli writes the local skill only.
  • Sandbox#environment_variables:
    • ORBIT_DATA_DIR=/tmp/orbit: the index lands somewhere the sandboxed agent can read.
    • ORBIT_TELEMETRY_ENABLED=false: the sandbox blocks orbit-cli's collector, so each call would log a failed send.
  • duo_developer_orbit (gitlab_com_derisk, default off) is kept. It used to gate the old local Orbit setup for Developer, and now it gates the orbit-cli path for every workload with a checkout. A follow-up removes it after the rollout.
  • glab pin: GlabSetup::VERSION goes to 1.124.0, with digests from the v1.124.0 checksums.txt. The pin only applies to images without glab. The two install snippets in doc/user/duo_agent_platform/agents/external_examples.md follow, because seeder_spec.rb compares them with GlabSetup.install_command. The default image ships 1.120.0.

This follows the plan agreed with dgruzd in !259938 (comment 4043850016) and relies on orbit-cli 0.148.0 or later (gitlab-org/orbit/knowledge-graph!2813 (merged)).

References

Screenshots or screen recordings

Not applicable. This is a backend-only change.

How to set up and validate locally

Use a GDK with a runner that can run Duo workloads, and enable the flag for your user: Feature.enable(:duo_developer_orbit, User.find_by_username('root')).

  1. Start a Developer session, for example:

    glab api -X POST ai/duo_workflows/workflows -f project_id=<project> -f workflow_definition=developer/v1 \
  -F start_workflow=true -f environment=web \
  -f goal='Do not change files. Use the orbit skill to run glab orbit sql and list 10 definitions.'

  2. In the job log, expect:

    • glab skills install --global, and no glab skills install --global --force orbit
    • if glab orbit --yes setup duo …; then glab orbit --yes index . …, with GITLAB_TOKEN= before glab when remote Orbit is unavailable to you
    • Downloading orbit-cli-linux-… and Installed to: /root/.config/glab-cli/bin/orbit
    • "database_path": "/tmp/orbit/local/revisions/…"
    • [AgentSkillsResolver] SKILL.md loaded from for both glab/SKILL.md and orbit/SKILL.md
    • the agent running glab orbit sql … and getting rows back

  3. With remote Orbit available, the setup command has no GITLAB_TOKEN=, and orbit/SKILL.md has a +gql version with the remote references/.

  4. Disable the flag and start the session again: the log matches master (glab skills install --global --force orbit when remote Orbit is available) and has no glab orbit commands.

Points for reviewers

  • Slow failure when gitlab.com egress is silently dropped. The E2E in https://gitlab.com/gitlab-org/orbit/agents/-/work_items/76 measured 192 s per glab orbit call (12 s when the connection is refused or there's no network). The index is now skipped when setup fails, so a run pays this once, not twice. duo_developer_orbit is the off switch during the rollout. Self-managed only gets the orbit-cli path once the flag is removed, so whether to cap the setup with timeout is a decision for the removal MR.
  • Re-indexing inside the SRT sandbox fails (found by the E2E). After a branch switch, glab orbit index . exits with failed to walk repository files: … Permission denied, because SRT masks dotfiles in the checkout and the indexer stops at the first unreadable entry. Querying the index built before the agent starts works. The workload checks out the agent's branch before setup, so this only matters when the agent switches branches itself. The fix belongs in orbit-cli: skip unreadable entries.
  • glab's wrapper skill for flows without a checkout on images without glab. From glab 1.123, glab skills install orbit installs a wrapper skill (cli!4054 (merged)) that needs orbit-cli, which those workloads don't install. The E2E confirmed the wrapper can't load there. Workloads with a checkout don't use glab's skill while the flag is on, and the default image (1.120.0) isn't affected yet.
  • Token sent to gitlab.com by the bare binary (dgruzd). The workload sets GITLAB_TOKEN and passes it into the sandbox, but sets no GITLAB_URL. If the agent runs orbit directly instead of glab orbit, orbit-cli falls back to https://gitlab.com and sends the instance's token there. Both my test and the E2E reproduced this. Setup in this MR always goes through glab orbit. Possible fixes: set GITLAB_URL in the workload, or have orbit-cli not fall back to gitlab.com for an environment token.
  • glab warning inside the sandbox. Each glab orbit call there prints Failed to save binary metadata: … read-only file system, because SaveBinaryInfo in glab (still the same in v1.124.0) rewrites its config even when nothing changed. The command still succeeds. This MR doesn't make ~/.config/glab-cli writable.
  • Local-only skill wording (dgruzd). The embedded skill says "hosted GitLab data (use the orbit skill)", but in local-only mode it is the orbit skill.
  • Changelog. The orbit-cli path is behind a default-off flag, so the squash commit should carry no Changelog trailer. The entry belongs in the flag removal MR.
What was verified and what was not

Verified:

  • RSpec, run locally: orbit_setup_spec, glab_setup_spec, sandbox_spec, start_workflow_service_spec, the start params resolver spec, the developer definition spec and seeder_spec (331 examples, 0 failures). RuboCop and the pre-commit and pre-push hooks pass.
  • orbit_setup_spec runs the generated command against a stub glab: it indexes after a successful setup and skips the index when setup fails.
  • Mutation check: hardcoding checkout: true in the service fails 3 examples, including the real-class check that workloads without a checkout get no glab orbit command.
  • Docker, linux arm64, default image, with the generated commands (flag forced on, remote Orbit off): with network, the orbit-cli skill was written local-only, the index landed under /tmp/orbit, and the run took 6 s. With --network none, the run printed one Warning: Orbit setup failed line, skipped the index and took 12 s.
  • Earlier commits on this MR, with the same orbit-cli commands:
    • Docker: an image without glab installed 1.124.0 and passed the checksum check.
    • Docker, workload-shaped glab config with a gitlab.com token: the plain command wrote the combined skill (0.33.14+gql, 9 files), and with GITLAB_TOKEN= it wrote the local-only skill (0.24.0, 4 files).
    • GDK, Developer flow in the SRT sandbox: the Duo CLI loaded both skills, and the agent ran glab orbit sql and got rows back.
    • The amd64 E2E in https://gitlab.com/gitlab-org/orbit/agents/-/work_items/76 confirmed the install, the local-only skill and the index location.

Not verified:

  • The combined skill with the workload OAuth token against an instance that serves remote skills.
  • A full session at this commit, and in a flow other than Developer.
  • The nono sandbox.
  • CI: the pipeline for this push hasn't finished.

MR acceptance checklist

Evaluate this MR against the MR acceptance checklist. It helps you analyze changes to reduce risks in quality, performance, reliability, security, and maintainability.

Edited by Thomas Schmidt

Merge request reports