docs: add private packages guide and enhance authentication page#314
Open
docs: add private packages guide and enhance authentication page#314
Conversation
Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
Copilot created this pull request from a session on behalf of
danielmeppiel
March 15, 2026 08:47
View session
Collaborator
|
@copilot this is not satisfactory - the Authentication page itself should speak about the case of an object reference to gitURL and how git credential helpers work there. Also, the guide seems to repeat a lot of stuff from the Authentication page. rethink the structure as a world class technical writer for developer tooling without bloating the docs. |
…slim down private packages guide Co-authored-by: danielmeppiel <51440732+danielmeppiel@users.noreply.github.com>
Contributor
Author
Restructured in 9f6840e. Two changes:
|
Copilot
AI
changed the title
docs: add private packages guide
docs: add private packages guide and enhance authentication page
Mar 15, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
Documentation update to close gaps around how APM authenticates to private git repositories and to provide a dedicated, workflow-focused guide for private packages.
Changes:
- Added a new “Private Packages” guide describing the end-to-end workflow (create → install → share → CI).
- Restructured the Authentication page to explain APM’s auth paths (token injection vs git credential helpers/SSH) and object-style
git:references. - Updated the docs sidebar to include the new guide.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.
| File | Description |
|---|---|
| docs/src/content/docs/guides/private-packages.md | New workflow guide for creating and consuming private APM packages. |
| docs/src/content/docs/getting-started/authentication.md | Reorganized and expanded authentication documentation, including git: object references and setup scenarios. |
| docs/astro.config.mjs | Adds “Private Packages” to the Guides sidebar section. |
| | Host | Token variable | How it's used | | ||
| |------|---------------|---------------| | ||
| | GitHub / GitHub Enterprise | `GITHUB_APM_PAT` | Injected into the HTTPS URL as `x-access-token` | | ||
| | Azure DevOps | `ADO_APM_PAT` | Injected into the HTTPS URL as the password | |
| - **Type**: Personal Access Token with Copilot access | ||
| - **Fallback**: Falls back to `GITHUB_TOKEN` if not set | ||
| - **Scope**: Runtime features (see [Agent Workflows](../../guides/agent-workflows/)) | ||
| - **Fallback**: `GITHUB_TOKEN` |
Comment on lines
41
to
+48
| ```bash | ||
| export GITHUB_APM_PAT=ghp_finegrained_token_here | ||
| ``` | ||
|
|
||
| - **Purpose**: Access to private APM modules on GitHub/GitHub Enterprise | ||
| - **Type**: Fine-grained Personal Access Token (org or user-scoped) | ||
| - **Permissions**: Repository read access to repositories you want to install from | ||
| - **Scope**: Private repositories on GitHub and GitHub Enterprise | ||
| - **Type**: [Fine-grained PAT](https://github.com/settings/personal-access-tokens/new) (org or user-scoped) | ||
| - **Permissions**: Repository read access | ||
| - **Fallback**: `GITHUB_TOKEN` (e.g., in GitHub Actions) |
| ```yaml | ||
| dependencies: | ||
| apm: | ||
| - your-org/my-private-package@v1.0.0 |
| Set the appropriate token (see [Authentication](../../getting-started/authentication/)), then install like any public package: | ||
|
|
||
| ```bash | ||
| export GITHUB_APM_PAT=ghp_your_token |
Comment on lines
+13
to
+16
| | Host | Token variable | How it's used | | ||
| |------|---------------|---------------| | ||
| | GitHub / GitHub Enterprise | `GITHUB_APM_PAT` | Injected into the HTTPS URL as `x-access-token` | | ||
| | Azure DevOps | `ADO_APM_PAT` | Injected into the HTTPS URL as the password | |
Comment on lines
+15
to
+19
| | GitHub / GitHub Enterprise | `GITHUB_APM_PAT` | Injected into the HTTPS URL as `x-access-token` | | ||
| | Azure DevOps | `ADO_APM_PAT` | Injected into the HTTPS URL as the password | | ||
| | Any other git host | — | Delegated to **git credential helpers** or SSH keys | | ||
|
|
||
| When APM has a token for the host, it injects it directly and disables interactive prompts. When no token is available (public repos or generic hosts), APM relaxes the git environment so your existing credential helpers — `gh auth`, macOS Keychain, Windows Credential Manager, `git-credential-store`, etc. — can provide credentials transparently. |
Comment on lines
166
to
178
| ## Azure DevOps Support | ||
|
|
||
| APM supports Azure DevOps Services (cloud) and Azure DevOps Server (self-hosted). There is no `ADO_HOST` equivalent — Azure DevOps always requires FQDN syntax. | ||
| APM supports Azure DevOps Services (cloud) and Azure DevOps Server (self-hosted). There is no `ADO_HOST` equivalent — always use FQDN syntax. | ||
|
|
||
| ### URL Format | ||
|
|
||
| Azure DevOps uses 3 segments vs GitHub's 2: | ||
| - **GitHub**: `owner/repo` | ||
| - **Azure DevOps**: `org/project/repo` | ||
| Azure DevOps uses 3 path segments vs GitHub's 2: | ||
|
|
||
| ```bash | ||
| # Both formats work (the _git segment is optional): | ||
| apm install dev.azure.com/myorg/myproject/myrepo | ||
| apm install dev.azure.com/myorg/myproject/_git/myrepo | ||
|
|
||
| # With git reference | ||
| apm install dev.azure.com/myorg/myproject/myrepo#main | ||
|
|
||
| # Legacy visualstudio.com URLs | ||
| apm install mycompany.visualstudio.com/myorg/myproject/myrepo | ||
|
|
||
| # Self-hosted Azure DevOps Server | ||
| apm install ado.company.internal/myorg/myproject/myrepo | ||
|
|
||
| # Virtual packages (individual files) | ||
| apm install dev.azure.com/myorg/myproject/myrepo/prompts/code-review.prompt.md | ||
| apm install dev.azure.com/myorg/myproject/_git/myrepo # _git is optional | ||
| apm install dev.azure.com/myorg/myproject/myrepo#main # with ref | ||
| apm install mycompany.visualstudio.com/org/project/repo # legacy URL | ||
| apm install ado.internal/myorg/myproject/myrepo # self-hosted | ||
| ``` |
Comment on lines
+113
to
+114
| > - team/internal-package # → GITHUB_HOST | ||
| > - github.com/public/open-source-package # → github.com |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
APM already supports private packages via git credentials, but the documentation had gaps: the Authentication page didn't explain how git credential helpers and
git:object references work, and there was no dedicated guide for the private packages workflow.This PR enhances the Authentication page to be the single source of truth for how APM authenticates, and adds a focused private packages guide that covers the workflow without duplicating auth details.
Authentication page (
docs/src/content/docs/getting-started/authentication.md) — restructured with:git:object references and how authentication applies to themPrivate packages guide (
docs/src/content/docs/guides/private-packages.md) — a concise workflow page (~70 lines) covering create → install → share → CI → org-wide, linking to Authentication for all auth details with no duplication.Sidebar (
docs/astro.config.mjs) — inserted "Private Packages" between Pack & Distribute and Org-Wide Packages.Type of change
Testing
📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.