docs: add air-gapped apiops setup walkthroughs for GitHub Actions and Azure DevOps by Copilot · Pull Request #77 · Azure/apiops-cli

Copilot · 2026-05-19T22:39:30Z

Added operator-focused walkthroughs for running apiops in restricted networks where CI agents/runners cannot reach npm at runtime. The docs now explicitly cover local package bootstrapping and pipeline behavior for both GitHub Actions and Azure DevOps.

New walkthroughs (docs/walkthrough/)
- air-gapped-github-actions.md
- air-gapped-azure-devops.md
- Each guide covers:
  - preparing and transferring a local apiops tarball
  - generating and committing package-lock.json
  - offline dependency strategy (npm ci --offline) and cache/feed options
  - self-hosted runner/agent prerequisites
  - provider-specific pipeline/workflow adjustments for air-gapped execution
Behavior alignment with current init semantics
- Documentation now reflects that apiops init --cli-package <path> stages the tarball and writes a local file: dependency in package.json.
- Clarifies that generated CI definitions use npm ci, which consumes the local package via package.json/lockfile resolution.
Docs navigation update
- Updated docs/README.md:
  - added Walkthroughs to Quick Links
  - added docs/walkthrough/ to the documentation tree for discoverability

apiops init \
  --ci github-actions \
  --cli-package ./peterhauge-apiops-cli-<version>.tgz \
  --environments dev,prod \
  --non-interactive

…Azure DevOps Add step-by-step guides under docs/walkthrough/ covering: - Tarball preparation with --cli-package flag - Lock file strategy for offline npm ci - Self-hosted runner/agent configuration - Workflow/pipeline modifications for offline operation - Upgrade procedures and troubleshooting Update docs/README.md navigation with new walkthrough section. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: EMaher <9244742+EMaher@users.noreply.github.com>

- Merged inbox/docwriter-airgapped-walkthroughs.md into decisions.md - Established walkthrough pattern for complex multi-step deployment scenarios - Covers GitHub Actions and Azure DevOps air-gapped deployments - Pattern: docs/walkthrough/ (scenario-based), docs/ci-cd/ (reference), docs/guides/ (feature-oriented) - Deleted merged inbox file Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: EMaher <9244742+EMaher@users.noreply.github.com>

Agent-Logs-Url: https://github.com/Azure/apiops-cli/sessions/55ca6c66-0c45-4eec-9647-95bcedd33b90 Co-authored-by: EMaher <9244742+EMaher@users.noreply.github.com>

EMaher · 2026-05-19T22:57:09Z

+
+| Requirement | Details |
+|-------------|---------|
+| **Connected workstation** | A machine with internet access to download packages |


The whole point is an air gapped environment. Isn't there a way to have a local intranet npm registry?

Updated in a4f5edb. The walkthrough now uses a local intranet npm registry (Azure Artifacts feed) as the primary/default pattern, with tarball + offline cache as fallback only.

EMaher · 2026-05-19T22:57:23Z

+|-------------|---------|
+| **Connected workstation** | A machine with internet access to download packages |
+| **Node.js 22.x** | Installed on both the workstation and the agent |
+| **npm 10+** | Comes with Node.js 22 |


remove this line if it comes with prerequisite

Done in a4f5edb. I removed the separate npm prerequisite line and folded it into the Node.js prerequisite.

EMaher · 2026-05-19T22:57:39Z

+| **Connected workstation** | A machine with internet access to download packages |
+| **Node.js 22.x** | Installed on both the workstation and the agent |
+| **npm 10+** | Comes with Node.js 22 |
+| **Self-hosted Azure Pipelines agent** | Registered in your agent pool, running in the air-gapped network |


Add link to official documentation.

Added in a4f5edb. I linked official Microsoft docs for self-hosted agents and Azure Artifacts npm feed setup.

EMaher · 2026-05-19T22:59:24Z

+| **Node.js 22.x** | Installed on both the workstation and the agent |
+| **npm 10+** | Comes with Node.js 22 |
+| **Self-hosted Azure Pipelines agent** | Registered in your agent pool, running in the air-gapped network |
+| **Azure connectivity from agent** | The agent must reach your APIM instance's ARM endpoint (network-level, not npm) |


Is there a document about on premises installs or sovereign clouds?

Yes—added in a4f5edb. There is now a dedicated “Sovereign Clouds and On-Premises” section linking Azure DevOps Server install docs and national cloud endpoint guidance.

EMaher · 2026-05-19T22:59:38Z

+| **npm 10+** | Comes with Node.js 22 |
+| **Self-hosted Azure Pipelines agent** | Registered in your agent pool, running in the air-gapped network |
+| **Azure connectivity from agent** | The agent must reach your APIM instance's ARM endpoint (network-level, not npm) |
+| **Transfer mechanism** | USB drive, Azure Artifacts upstream feed, or approved file share for moving packages into the restricted zone |


Remove this.

Done in a4f5edb. I removed that transfer-mechanism prerequisite line.

EMaher · 2026-05-19T23:00:04Z

+
+---
+
+## Step 1 — Prepare the Tarball (Connected Workstation)


Update this to talk about using local npm registry.

Updated in a4f5edb. Step 1 now explicitly covers configuring a local npm registry first (Azure Artifacts feed) and uses tarball flow only as fallback.

EMaher · 2026-05-19T23:05:55Z

+
+Copy the entire npm cache directory (or the `_cacache` subfolder) to your transfer media.
+
+> **Alternative — Azure Artifacts upstream feed:** If your air-gapped network has an Azure Artifacts feed with an upstream source configured (accessible during a controlled sync window), you can use it as a local npm registry instead of transferring the cache manually. Configure `.npmrc` to point to the feed.


Assume this is the default path.

Handled in a4f5edb. The local registry path is now assumed as default flow; the Azure Artifacts section was moved into the main steps and the tarball flow is fallback.

EMaher · 2026-05-19T23:08:17Z

+
+### `pipelines/run-extractor.yaml`
+
+```yaml


I'm worried about this getting out of date with the default pipelines.

Addressed in a4f5edb. I removed large copied YAML blocks and replaced them with minimal durable edits that reference the generated default pipeline files to reduce drift risk.

- Make local npm registry (Azure Artifacts) the primary approach - Demote tarball flow to fallback section - Remove redundant npm and transfer mechanism prerequisites - Add official Microsoft docs links (agents, feeds, on-prem, sovereign clouds) - Replace brittle embedded YAML with edit guidance referencing generated files - Add sovereign clouds and on-premises section Closes #44 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: EMaher <9244742+EMaher@users.noreply.github.com>

petehauge · 2026-05-21T19:41:35Z

+
+Commit `package-lock.json` to the repository. The command `npm ci --offline` requires it.
+
+Then transfer the npm cache to the agent:


in my testing - this wasn't needed... The npm command (as long as it was already available on the runner) would just use the tgz file and install it to the cache... I would think that the npmcacache.tar.gz would be needed only if there are other npm packages?

Copilot AI and others added 4 commits May 19, 2026 22:32

chore: record squad orchestration logs for air-gapped walkthrough task

30b5808

Agent-Logs-Url: https://github.com/Azure/apiops-cli/sessions/55ca6c66-0c45-4eec-9647-95bcedd33b90 Co-authored-by: EMaher <9244742+EMaher@users.noreply.github.com>

chore: remove accidental temp commit message file

af26aaf

Agent-Logs-Url: https://github.com/Azure/apiops-cli/sessions/55ca6c66-0c45-4eec-9647-95bcedd33b90 Co-authored-by: EMaher <9244742+EMaher@users.noreply.github.com>

Copilot AI assigned Copilot and EMaher May 19, 2026

Copilot created this pull request from a session on behalf of EMaher May 19, 2026 22:39 View session

EMaher requested changes May 19, 2026

View reviewed changes

Copilot started work on behalf of EMaher May 19, 2026 23:09 View session

Copilot finished work on behalf of EMaher May 19, 2026 23:15

Copilot AI requested a review from EMaher May 19, 2026 23:15

EMaher added 3 commits May 21, 2026 12:08

updating articles for air-gapped environments

0829109

reverting changes to squad

46935bd

modifying doc tree

c8937cc

EMaher marked this pull request as ready for review May 21, 2026 19:27

EMaher approved these changes May 21, 2026

View reviewed changes

EMaher requested a review from petehauge May 21, 2026 19:29

petehauge approved these changes May 21, 2026

View reviewed changes


		---

		## Step 1 — Prepare the Tarball (Connected Workstation)


		Copy the entire npm cache directory (or the `_cacache` subfolder) to your transfer media.

		> Alternative — Azure Artifacts upstream feed: If your air-gapped network has an Azure Artifacts feed with an upstream source configured (accessible during a controlled sync window), you can use it as a local npm registry instead of transferring the cache manually. Configure `.npmrc` to point to the feed.


		Commit `package-lock.json` to the repository. The command `npm ci --offline` requires it.

		Then transfer the npm cache to the agent:


		### `pipelines/run-extractor.yaml`

		```yaml

Conversation

Copilot AI commented May 19, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI May 19, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants