Persist installer settings via `apm config` for self-update

[sergio-sisternes-epam]

Summary

PR #660 introduces env vars (APM_INSTALL_DIR, GITHUB_URL, APM_REPO, VERSION) to configure install.sh for air-gapped and GHE environments. These work well for the bootstrap install, but once APM is installed, apm update has no way to remember those settings.

Users who installed to a custom directory or from a GHE mirror would need to re-export env vars every time they run apm update, which is error-prone and defeats the purpose of a self-update command.

Proposed solution

Add persistent config keys via apm config:

Config key	Description
install-dir	Custom binary install directory (default: /usr/local/bin)
mirror-url	GHE or artifactory base URL (default: https://github.com)
mirror-repo	Repository override (default: microsoft/apm)

The flow would be:

1. First install: env vars (only option -- no apm binary yet)
2. Post-install: apm config set mirror-url https://gh.corp.com
3. Self-update: apm update reads config; env vars override if set (CI/unattended)

Acceptance criteria

• apm update reads install-dir, mirror-url, mirror-repo from config
• Env vars override config values when set (for CI/unattended use)
• apm config set mirror-url <url> persists across sessions
• Documentation updated for the new config keys

Related

• feat: make install.sh configurable for air-gapped environments #660 -- introduces the env var configurability for install.sh

[github-actions]

Triage decision

needs-design

Proposed labels

theme/portability
area/cli
area/distribution
type/feature
status/needs-design
status/triaged

Milestone

null

Suggested next action

Post a design comment addressing: config file location, key schema, env-var precedence order (env > config > default), and the mirror-url file permission / trust model.

Suggested issue comment

Thanks for the follow-up to #668 -- the user-visible problem is real: re-exporting env vars on every `apm update` defeats the purpose of a self-update command, and your proposed config key surface (`apm config install-dir`, `apm config mirror-url`) matches the npm/pip mental model well.

The direction is sound, but a few design questions need answers before code lands safely:

1. **Config file location**: where does APM store persistent config? (XDG_CONFIG_HOME? a dotfile? per-user vs per-project?)
2. **Precedence**: env var > config file > built-in default -- is this the agreed order? How is it surfaced in `apm config get`?
3. **Key schema**: `install-dir`, `mirror-url`, `mirror-repo` -- are these flat keys or namespaced under an `[update]` or `[installer]` section?
4. **Security**: `mirror-url`, if writable by a broad process, permanently redirects binary downloads. What is the file permission model and trust scope (per-user vs per-machine)?

Please add a design comment here (or link a short doc) addressing these points. Once the design is agreed we can move straight to implementation.

Per-lens notes (collapsed)

DevX UX Expert -- User-Need Reviewer

The pain point is concrete and the proposed API (apm config install-dir) matches the npm/pip config mental model well. However, APM's config storage model is not fully defined: the design must clarify where config is stored, what the format is, and how it interacts with env vars before a consistent UX can be delivered. The precedence question (env > config > default) is especially important for GHE users who sometimes use both.

Supply Chain Security Expert -- Risk-Surface Reviewer

Persisting mirror-url creates a more durable attack surface than env vars: if the config file is writable by a malicious process, binary download redirection becomes persistent across reboots and shell sessions. The file permission model and trust scope (per-user vs per-machine config) must be addressed in the design. No theme/security label added here because this is a design-phase concern, not a confirmed vulnerability in the current implementation.

OSS Growth Hacker -- Contributor-Tone Reviewer

Not activated -- sergio-sisternes-epam is a COLLABORATOR with known prior contributions; tone tuning is not needed.

Python Architect -- Architecture Reviewer

Activated. The apm config command exists but the persistence backend and schema for installer-related keys are not designed. Questions: config file format (TOML? YAML? INI?), location (XDG-compliant?), how apm update reads it (lazy import? global singleton? environment injection?), and precedence semantics. These are cross-cutting: config affects CLI, installer, update, and potentially policy. Recommend status/needs-design until these are settled.

Doc Writer -- Documentation Reviewer

Not activated -- a needs-design issue does not yet produce a doc page. Once the design is settled and the feature is accepted, the apm config reference page will need updating.

APM CEO -- Triage Arbiter

Feature direction is correct (mirrors standard package manager config behavior), but the config backend design is underspecified. Pushing to needs-design to ensure the config file location, format, precedence, and mirror-url trust model are agreed before contributors start implementing. No milestone until design is complete.

{
  "decision": "needs-design",
  "decision_detail": "Config file location, key schema, env-var precedence order, and mirror-url permission/trust model must be specified before implementation.",
  "theme": "theme/portability",
  "areas": ["area/cli", "area/distribution"],
  "type": "type/feature",
  "status": "status/needs-design",
  "priority": null,
  "preserved_labels": [],
  "milestone": null,
  "next_action": "Post a design comment addressing config file location, key schema, precedence (env > config > default), and mirror-url permission model.",
  "comment_markdown": "The direction is sound, but config file location, key schema, env-var precedence, and mirror-url trust model need to be agreed before implementation."
}

---

Triage status: agentic proposal pending human ratification.
Silence is approval. Maintainers can:

• Override any label or milestone above by editing it directly --
  human edits are authoritative and will not be reverted on
  subsequent runs.
• Re-trigger triage by applying the status/needs-triage label, or
  by removing status/triaged to enroll the issue in the next
  daily sweep.

Posted by the Triage Panel workflow. See .apm/skills/apm-triage-panel for the panel skill.

Generated by Triage Panel · ● 3.3M · ◷