mirror of
https://github.com/docker/docs.git
synced 2026-06-19 07:35:16 +00:00
Agent redirect skill and small admin > company reorg (#24856)
This PR captures a small chunk of work intended to test a new agent skill for handling redirect aliases, link references, and link anchors.
This commit is contained in:
Alexa Kristensen
@@ -0,0 +1,384 @@
|
||||
---
|
||||
name: migrate-content-ia
|
||||
description: >
|
||||
Handle Hugo docs information-architecture moves: discover old vs new URLs,
|
||||
add front matter aliases (Phase 1), update in-repo links (Phase 2), interactive
|
||||
List 2 resolution and fragment validation (Phase 3; no guessing). Supports
|
||||
PR-scoped mapping plus whole-content sweeps for inbound links to that mapping,
|
||||
or a full-site follow-up. Triggers on: "IA migration", "redirects for moved
|
||||
pages", "fix links after content move", "PR-scoped link/anchor pass",
|
||||
"aliases for old URLs". After branch work, chain the review-changes skill
|
||||
(main...HEAD) before a PR. Agents must run the in-file required procedure
|
||||
and definition of done, not the phases alone in isolation.
|
||||
---
|
||||
|
||||
# Migrate content IA (redirects + links + anchors)
|
||||
|
||||
Use this skill when pages **move or rename** under `content/` and you must
|
||||
preserve old public URLs and/or fix cross-references. Work in **phases**;
|
||||
choose **PR-scoped** vs **full-site** mode per run.
|
||||
|
||||
**Read first:** **CLAUDE.md** / **AGENTS.md** (URL rules, vendored areas, external
|
||||
links, special cases) and **hugo.yaml** (`permalinks`, `refLinksErrorLevel`,
|
||||
`disablePathToLower`). For **prose and link text**, follow **STYLE.md**; for
|
||||
**components, front matter, and link examples**, follow **COMPONENTS.md**.
|
||||
|
||||
**Related skills:** **research** helps map moves and find inbound links; **write**
|
||||
commits minimal edits. Run this skill’s phases after the move is identified (or
|
||||
in parallel with research for large IA work).
|
||||
|
||||
## Agent: required procedure (do not skip)
|
||||
|
||||
**Common mistake (wrong):** use **`git diff main...HEAD` (or the PR’s file
|
||||
list) as the full set of places to fix links** for a migration. That set shows
|
||||
**what *moved***; it is **not** the list of every page that **points *to*** a
|
||||
moved page. Inbound stragglers are often in files the PR **never** touched. You
|
||||
must still **sweep the repo** for every string in the **old path and published-URL set**
|
||||
for this run, not only for “files in the diff.”
|
||||
|
||||
**Definition of done (when the migration is *finished*):** **Both** of the
|
||||
following (unless the user or **AGENTS.md** **explicitly defers** a **List 2**
|
||||
item in **Phase 3**; document the deferral):
|
||||
|
||||
1. **`docker buildx bake validate`** passes for the branch, with no new
|
||||
build/link errors from this work.
|
||||
2. A **sweep of the old path and published-URL set for this run** (see
|
||||
[Sweep commands](#sweep-commands) below) finds **no** remaining
|
||||
migration-relevant **inbound** reference—**including**:
|
||||
- links to an old **source** path (plain `.md` and equivalent `ref` forms),
|
||||
- links that use the old path **and** a `#fragment`,
|
||||
- and, where your mapping includes them, old **published-style** `link:` /
|
||||
`url:` / full-site URL strings,
|
||||
**except** intentional entries to keep: for example `aliases` on the **new**
|
||||
canonical page, or **redirects.yml** *sources* you must not edit per policy.
|
||||
(A hit on a **source** that is only an `alias` line on the new page is
|
||||
**expected**—do not “fix” that away; distinguish alias rows from straggler
|
||||
links in body or nav config.)
|
||||
|
||||
**Chaining (policy):** when this branch’s content work is ready for handoff,
|
||||
**run the [review-changes](../review-changes/SKILL.md) skill** on
|
||||
**`main...HEAD`** (or **`merge-base`…`HEAD`** for a different target branch) so
|
||||
the **whole branch** is re-read for cross-page issues before opening a PR. Do
|
||||
not treat phases 0–3 alone as the final check.
|
||||
|
||||
**Run in order (mandatory for agents):**
|
||||
|
||||
1. **Scope the moves (mapping input):** set the Git range like **review-changes**
|
||||
(for a PR to `main`: `git diff --name-only main...HEAD`; for another target:
|
||||
`BASE=$(git merge-base <target-branch> HEAD)` then
|
||||
`git diff --name-only $BASE...HEAD`, as in **Phase 0.5**). Include
|
||||
renames; build the **old → new** table (source and published) per **Phase
|
||||
0**.
|
||||
2. **Sweep and list:** for every **old** path/URL in that table, run
|
||||
[Sweep commands](#sweep-commands) on the **allowed** trees. Record
|
||||
every hit as **List 1** (no `#`) or **List 2** (old path with `#...`) per
|
||||
**Phase 0.5**.
|
||||
3. **Phased edits:** **Phase 1** (`aliases`), then **Phase 2** (List 1), then
|
||||
**Phase 3** (List 2) with **no guessing**—as in the sections below.
|
||||
4. **Re-sweep** the same old-path set, then run **`docker buildx bake
|
||||
validate`**. The **Definition of done** above is met or you have **explicit
|
||||
defers** for the remainder.
|
||||
5. **review-changes:** run **[review-changes](../review-changes/SKILL.md)**
|
||||
on the branch vs **`main`…`HEAD`** (or the correct base) before a PR.
|
||||
|
||||
### Sweep commands
|
||||
|
||||
Use a **repository** search (e.g. `rg` / your IDE) so **nothing** in the
|
||||
allowed scope is only eyeballed.
|
||||
|
||||
**Trees to include** (at minimum): all of `content/`, plus **`data/`** and
|
||||
**`layouts/`** when a migration can appear in config, `link:`-like fields,
|
||||
shortcodes, or hardcoded path strings. Follow **Vendored / generated** rules in
|
||||
**AGENTS.md**; do not edit disallowed files.
|
||||
|
||||
**What to search for (repeat per row in the old side of the mapping):**
|
||||
|
||||
- **Hugo / source form:** path segments that identify the *old* file, e.g.
|
||||
`manuals/.../old-segment/...` or `../old-segment/.../page.md` as your tree
|
||||
uses; include variants that still appear in the repo.
|
||||
- **Published / site form:** e.g. `/admin/.../old-slug/` in front matter, nav
|
||||
`url:`, or `https://docs.docker.com/...` in allowed files—**match the
|
||||
file’s** established pattern, per **Conventions** below.
|
||||
- **Anchors:** search for the **old path string**; matches that also include
|
||||
`#...` belong on **List 2** for **Phase 3** unless the whole link is
|
||||
a pure path-only case.
|
||||
|
||||
[scripts/scope-pr-files.sh](scripts/scope-pr-files.sh) (if present) prints
|
||||
**`PR_SCOPE_FILES` only**—it does **not** replace this sweep. Use it to build
|
||||
the **old → new** table, **not** to list where inbound links were fixed.
|
||||
|
||||
## Progressive disclosure (optional)
|
||||
|
||||
The procedure below stays in this file. If a run produces a very large
|
||||
**old → new** URL table, store that table in **`reference.md`** in this skill
|
||||
directory and link it from the task summary, so the agent reads the long
|
||||
mapping only when needed.
|
||||
|
||||
## Modes
|
||||
|
||||
- **PR-scoped (typical for a single PR)**
|
||||
- **What the PR “owns” (focus):** use `git diff` / `base...HEAD` to know which
|
||||
pages and renames the branch actually moves (`PR_SCOPE_FILES`). The **old →
|
||||
new** mapping and **List 1 / List 2** for this migration are defined from
|
||||
**that** work, not from unrelated areas.
|
||||
- **Where to look for stale references (sweep):** search broadly—typically all
|
||||
of `content/` (and config, shortcodes, layouts, per Conventions)—for **inbound**
|
||||
links and fields whose **target** is an **old** path or URL in **this** PR’s
|
||||
mapping. Inbound stragglers are often in files the PR never touched; finding
|
||||
them is **in scope** for this migration.
|
||||
- **What to edit:** update **any** file in the allowed trees that contains a
|
||||
**migration-relevant** reference (target ∈ this PR’s old path set) according
|
||||
to the phases below. **Do not** treat `PR_SCOPE_FILES` as a hard limit on
|
||||
*which files you may save* for **inbound** link repairs (unless
|
||||
project policy for a given PR says otherwise; then follow policy and
|
||||
**defer** out-of-PR file fixes).
|
||||
- **Out of scope (defer / ignore in this run):** link and anchor problems that
|
||||
are **not** about this PR’s old→new map—e.g. a different area’s own slug
|
||||
issues, rot unrelated to the remapped path set. *Example:* a PR that only
|
||||
remaps `content/strawberry/...` should not “fix the whole site”; it **should**
|
||||
still fix a link under `mango/…` that **points at** an old `strawberry/…` path
|
||||
in the mapping, and **should not** chase **mango/**-only issues that do
|
||||
not involve those old targets.
|
||||
|
||||
- **Full-site (complete migration after the PR)**
|
||||
- Update stragglers **across the repo** (or all inbound links to moved
|
||||
sections), including config-driven `link:` fields if policy allows.
|
||||
- Still make **minimal** edits; no drive-by rewrites to **unrelated** targets
|
||||
outside the run’s **declared** mapping and lists.
|
||||
|
||||
### No guessing
|
||||
|
||||
- The agent must **not** guess **replacement paths, published URLs, or fragment
|
||||
IDs** (including for consolidated pages, renamed headings, or
|
||||
“semantic” remaps of `#anchor` → new `#…`). If the user has not given an
|
||||
explicit new target, **ask**, **defer**, or **stop** per **AGENTS.md**; never
|
||||
infer, autocomplete, or substitute a plausible fragment from the target page’s
|
||||
heading list. That rule applies in **every** phase, including after validation
|
||||
in Phase 3.
|
||||
|
||||
---
|
||||
|
||||
## Conventions (links, anchors, redirects)
|
||||
|
||||
### Front matter `aliases` (redirects)
|
||||
|
||||
- Per **COMPONENTS.md**, `aliases` are **URLs that redirect to this page**.
|
||||
- Add or **merge** on the **new canonical** page; do not drop unrelated
|
||||
entries. Match local examples: **published-style paths** (leading `/`), and
|
||||
**trailing `/`** when that matches existing pages in the same area.
|
||||
- **No** speculative redirects for URLs that were never published.
|
||||
- **Collision check** before adding: no other page or redirect may already
|
||||
own the same old path.
|
||||
- If the site also uses **`data/redirects.yml`**, only add entries when
|
||||
project policy requires it; avoid duplicating the same old URL in
|
||||
`aliases` **and** `redirects.yml` unless maintainers do.
|
||||
|
||||
### Internal links in Markdown (STYLE.md + COMPONENTS.md)
|
||||
|
||||
- Use **relative paths to source files** (e.g. `../section/page.md`) with
|
||||
**`.md`**, following **COMPONENTS.md** examples, unless the file already
|
||||
uses an established pattern (e.g. some `link:` or nav fields use **published**
|
||||
paths without `manuals` or `.md` — **match the surrounding file**).
|
||||
- Keep **CLAUDE.md** / **AGENTS.md** rules: internal ref targets under
|
||||
`content/manuals/...` often use the full **`/manuals/...`** path; published
|
||||
URLs omit the `manuals` segment—do not confuse the two when fixing links.
|
||||
- **Link text (STYLE.md):** descriptive, ~**5 words**; no “click here” or
|
||||
“learn more”; **no** end punctuation **inside** the link text; **no** bold/italic
|
||||
on link text unless normal in the sentence.
|
||||
- **Headings (STYLE):** **sentence case**; do not rename headings in passing
|
||||
unless the migration requires it (heading changes break fragments).
|
||||
|
||||
### Shortcodes and layouts (links not only in Markdown)
|
||||
|
||||
- **Phase 2–3 scope includes** any **shortcode or layout partial** (under
|
||||
**Modes**, search broadly for inbound links to the migration; **edits** follow
|
||||
the same file-level rules as for Markdown) that emits links: e.g. `ref` /
|
||||
`relref`, `link` fields in shortcode args, or hardcoded
|
||||
`docs.docker.com` / path strings. Grep for old paths, slugs, and fragments
|
||||
under `layouts/shortcodes/` (and `layouts/_default/` if partials build nav).
|
||||
- Match each file’s existing pattern; do not rewrite working shortcode style
|
||||
just to “clean up.”
|
||||
|
||||
### Fragments / anchors (Phase 3)
|
||||
|
||||
- List 1 / List 2: fragment-bearing **cross-references to old paths** are tracked
|
||||
on **List 2** in Phase 0.5; do not bulk-rewrite them in the **List 1** pass
|
||||
(Phase 2). See Phase 0.5 and Phase 2.
|
||||
- **Valid `#fragment` values:** after the user supplies a new fragment, it should
|
||||
match the **target** page’s **generated** heading ID (Hugo slugification; see
|
||||
**CLAUDE.md** / **AGENTS.md**). The agent still **validates** (see Phase 3) and
|
||||
must **not** “pick” a different id from the page to replace a bad answer—**No
|
||||
guessing**.
|
||||
- Same-page: `[Text](#section-id)`.
|
||||
- Cross-page: when user-provided, `#fragment` must still be checked against the
|
||||
**target** file. Validate fragments in shortcodes the same way as in body
|
||||
Markdown.
|
||||
|
||||
### External URLs (**AGENTS.md**)
|
||||
|
||||
- Do not commit **guessed** replacement URLs. If a URL cannot be verified,
|
||||
treat as blocked or drop the fragment per AGENTS guidance. See also **No
|
||||
guessing** above; internal and external link targets are treated the same for
|
||||
inference: **none** without user input or a verified source.
|
||||
|
||||
### Special cases (**AGENTS.md**)
|
||||
|
||||
- **Engine API version** pages: respect coordinated **`/latest/` `aliases`**
|
||||
rules—never leave two version files both owning `/latest/`.
|
||||
- **Vendored / generated** trees: read-only; see CLAUDE.md. Do not “fix” links
|
||||
there if policy forbids.
|
||||
|
||||
---
|
||||
|
||||
## Phase 0 — Discovery (read-only; may use whole repo)
|
||||
|
||||
1. Read **hugo.yaml** (permalinks, `refLinksErrorLevel`, `disablePathToLower`).
|
||||
2. From the branch (diff, renames), build a **mapping table**:
|
||||
- old source path → new source path
|
||||
- old published URL → new published URL (from permalink rules)
|
||||
3. **Case:** with `disablePathToLower: true`, filesystem path **case** appears in
|
||||
URLs—**directory and link casing must match** (e.g. `setup` vs `Setup`).
|
||||
4. When planning **inbound link** fixes, treat old-path references as two
|
||||
categories: **no fragment** vs **with `#fragment`**. That split feeds
|
||||
**List 1** and **List 2** in Phase 0.5 and drives Phase 2 ordering (see
|
||||
there).
|
||||
|
||||
---
|
||||
|
||||
## Phase 0.5 — PR-scoped evaluation (required before edits in PR mode)
|
||||
|
||||
1. **Set `PR_SCOPE_FILES` (Git scope for PR mode)**
|
||||
- When the PR **targets `main`**, use the same triple-dot form as
|
||||
**review-changes**:
|
||||
`git diff --name-only main...HEAD`
|
||||
- For a **different target branch** or a custom base, use the merge base:
|
||||
`BASE=$(git merge-base <target-branch> HEAD)`
|
||||
then:
|
||||
`git diff --name-only "$BASE"...HEAD`
|
||||
- Those paths define **what moved** in the branch; they are the primary input
|
||||
to the **old → new** path/URL table. They are **not** a hard cap on *where
|
||||
to search* for **inbound** links (see **Modes**): sweeps for links **to** old
|
||||
paths usually cover all of `content/` (and other trees per Conventions).
|
||||
- If project policy **limits edits** to the diff for a given PR, follow that
|
||||
and **defer** link fixes in files outside the diff; note the exception in
|
||||
the task if the user relaxes that policy.
|
||||
|
||||
2. Build checklists (see **Modes** for sweep vs area-of-work):
|
||||
- path/URL mapping this run must honor (old source path → new; old published
|
||||
→ new, from the **PR’s** moves in PR-scoped mode, or the **declared** full
|
||||
migration in full-site mode)
|
||||
- **List 1 — old path, no fragment:** every **inbound** reference, found on
|
||||
the **sweep** surface, to a moved **old** path that does **not** include a
|
||||
`#...` fragment (e.g. `…/banana.md` in the repo’s link style for that
|
||||
file).
|
||||
- **List 2 — old path with fragment:** every **inbound** reference, found on
|
||||
the same sweep, to a moved **old** path that **includes** a `#...` fragment
|
||||
(e.g. `…/banana.md#anchor` or the published-style equivalent in context). The
|
||||
**same** old path string may appear on **both** List 1 and List 2 for
|
||||
different links; duplication across the two lists is OK.
|
||||
- **Matching rules:** when recording List 1 / List 2, use **one** consistent
|
||||
path representation for comparison (e.g. relative `../path/banana.md` vs
|
||||
root-anchored) **per the conventions in this doc** and the **surrounding
|
||||
file’s** established pattern. Agents compare and skip List 2 links in the
|
||||
List 1 pass using the **same** representation rules.
|
||||
3. **Out of scope** for the lists: only include references whose **old** target
|
||||
is in this run’s **mapping**. Do not build List 1/2 for unrelated **mango/**
|
||||
(or other) problems unless those links also target an **old** path that this
|
||||
migration renames. Defer those issues separately (see **Modes**).
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 — `aliases` (old published URLs)
|
||||
|
||||
1. On each **new** canonical page, add or merge **`aliases`** for every **real**
|
||||
former public URL.
|
||||
2. Do not strip existing unrelated aliases.
|
||||
3. **PR-scoped:** add aliases only where the canonical file is in scope or the
|
||||
project requires it; otherwise list missing alias targets for follow-up.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 — In-repo link reference updates
|
||||
|
||||
1. **List 1 first (path only):** update references that belong to **List 1**
|
||||
(old path, **no** fragment). Replace old source paths or old published URLs
|
||||
with the **new** targets; preserve each file’s link pattern (relative vs
|
||||
root-anchored `.md` paths). **Do not** apply the same bulk path replacement to
|
||||
links that appear in **List 2** (old path **with** `#...`) during this
|
||||
sub-step—**leave** every **List 2** link **unchanged** for now.
|
||||
2. **After List 1 is complete:** **re-scan** the **same** **sweep** surface as
|
||||
in Phase 0.5 (e.g. all of `content/` plus config) or **print** a clear list of
|
||||
all **remaining** **List 2** entries. Those links should still point at the
|
||||
**old** path and **old** fragment until Phase 3.
|
||||
3. **Full-site (extra sweep):** after steps 1–2, still use **AGENTS “Page
|
||||
deletion checklist”**-style thoroughness for **config / front matter**
|
||||
`link:` and similar so nav and grids are not left on old slugs. Apply the
|
||||
**List 1 / List 2** rules there too: path-only old references first; defer
|
||||
fragment-bearing rewrites in line with **List 2** until Phase 3.
|
||||
4. **PR-scoped (which files to change):** apply List 1 and later Phase 3 updates
|
||||
to **every** file the **sweep** finds with a **migration-relevant** reference
|
||||
(inbound to an **old** path in the mapping), including files **not** in
|
||||
`PR_SCOPE_FILES`, per **Modes**. **Log** and **defer** (do not “fix”)
|
||||
unrelated stragglers. If policy forbids out-of-PR file edits, defer per step 1
|
||||
of Phase 0.5.
|
||||
5. Include **shortcodes and layout partials** (see Conventions and **Modes** for
|
||||
sweep vs focus).
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 — List 2: interactive path and fragment resolution
|
||||
|
||||
**Prerequisites:** Phase 2 has updated **List 1**; **List 2** still lists **old
|
||||
path + `#...`** (unchanged) for this migration. See **Modes** for which files
|
||||
may be edited; **No guessing** applies.
|
||||
|
||||
1. **Print List 2** to the user: every remaining **old path** + `#anchor` (in the
|
||||
agreed representation), so nothing is hidden before the loop.
|
||||
2. **For each distinct** `old-path#oldAnchor` (or process in the order the user
|
||||
prefers, one at a time):
|
||||
- Ask: **What is the new path (and fragment, if any) for this content?** The
|
||||
user may give a new source path, published URL, and/or `#newAnchor` per
|
||||
project conventions.
|
||||
- **Validate** the user’s answer: open the **target** page (or resolve the
|
||||
target) and check that `#newAnchor` (if any) **exists** as a real heading
|
||||
/ generated id on that page, per **CLAUDE.md** / **AGENTS.md** (same rules
|
||||
as the rest of the site). **Do not** replace the user’s fragment with a
|
||||
“better” one from the file.
|
||||
- If validation **fails** (unknown target file, or `#newAnchor` not found on
|
||||
the page): **warn** clearly (what failed: path vs missing fragment), then
|
||||
**ask again** for a corrected path and/or fragment. **Repeat** until
|
||||
validation passes or the user **defers** / **drops** the fragment (per
|
||||
**AGENTS.md**). **Never** guess a new fragment to fix the problem.
|
||||
- When validation **passes:** update **all** in-repo references that match
|
||||
that **same** `old-path#oldAnchor` to the user-approved `new-path#newAnchor`
|
||||
(respect each file’s link style; include shortcodes/layouts on the same
|
||||
**sweep** surface as Phase 2).
|
||||
3. **Repeat** from step 1: **re-print** or **re-scan** for **List 2** until it is
|
||||
**empty** or the user defers the remainder.
|
||||
4. **PR-scoped / full-site:** the **loop** is the same. **Edits** follow **Modes**:
|
||||
migration-relevant **inbound** links may live in any file on the sweep; do
|
||||
not expand into **unrelated** link debt from other areas. Defer as in **Modes**
|
||||
and Phase 0.5.
|
||||
|
||||
---
|
||||
|
||||
## Optional: scripts helper
|
||||
|
||||
This skill includes a small **scope helper** so agents do not re-derive Git
|
||||
recipes. See [scripts/scope-pr-files.sh](scripts/scope-pr-files.sh) — it prints
|
||||
paths in PR scope for a given target branch (default `main`).
|
||||
|
||||
---
|
||||
|
||||
## Verification
|
||||
|
||||
```bash
|
||||
docker buildx bake validate
|
||||
```
|
||||
|
||||
Use the **Definition of done** in **Agent: required procedure (do not skip)**
|
||||
as the final bar: **validate** must pass, and the **sweep** must be clean for
|
||||
**plain** and **`#fragment`** old-path references, **or** the remainder must be
|
||||
**explicitly deferred** in **Phase 3** per **AGENTS.md** / the user. Mid-run,
|
||||
**Phase 2** may still leave **List 2** links unchanged **until** Phase 3; that
|
||||
intermediate state is **not** the finished migration.
|
||||
@@ -0,0 +1,22 @@
|
||||
#!/bin/bash
|
||||
# List files changed on the current branch since merge-base with the target
|
||||
# branch — suitable for PR_SCOPE_FILES in PR-scoped migrate-content-ia runs.
|
||||
#
|
||||
# Usage:
|
||||
# ./scope-pr-files.sh [target-branch]
|
||||
# Default target-branch: main
|
||||
#
|
||||
# Example (Bash / Git Bash, from repo root):
|
||||
# bash .agents/skills/migrate-content-ia/scripts/scope-pr-files.sh
|
||||
# Example (other base):
|
||||
# bash .../scope-pr-files.sh upstream/main
|
||||
set -euo pipefail
|
||||
|
||||
target="${1:-main}"
|
||||
|
||||
if ! base=$(git merge-base "$target" HEAD 2>/dev/null); then
|
||||
echo "Error: could not merge-base with '$target'. Fetch remotes or pass a valid branch." >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
git diff --name-only "$base"...HEAD
|
||||
@@ -30,6 +30,6 @@ for Docker.
|
||||
|
||||
To continue optimizing your Docker environment:
|
||||
|
||||
- Review your [organization's usage data](/manuals/admin/organization/insights.md) to track adoption
|
||||
- Review your [organization's usage data](/manuals/admin/insights.md) to track adoption
|
||||
- Monitor [Docker Scout findings](/manuals/scout/explore/analysis.md) for security insights
|
||||
- Explore [additional security features](/manuals/enterprise/security/_index.md) to enhance your configuration
|
||||
|
||||
@@ -17,9 +17,9 @@ params:
|
||||
- title: Roles and permissions
|
||||
url: /security/for-admins/roles-and-permissions/
|
||||
- title: Insights
|
||||
url: /admin/organization/insights/
|
||||
url: /admin/insights/
|
||||
- title: Activity logs
|
||||
url: /admin/organization/activity-logs/
|
||||
url: /admin/activity-logs/
|
||||
---
|
||||
|
||||
Managing roles and permissions is key to securing your Docker environment while enabling easy collaboration and operational efficiency. This guide walks IT administrators through the essentials of user and access management, offering strategies for assigning roles, provisioning users, and using tools like activity logs and Insights to monitor and optimize Docker usage.
|
||||
|
||||
@@ -24,7 +24,7 @@ Activity logs are available for Docker Team or Docker Business plans, with data
|
||||
- Team collaboration review: Logs show which team members pushed updates to a critical repository, ensuring accountability during a development sprint.
|
||||
- Billing adjustments: Track who added or removed subscription seats to maintain budgetary control and compliance.
|
||||
|
||||
For more information, see [Activity logs](/manuals/admin/organization/activity-logs.md).
|
||||
For more information, see [Activity logs](/manuals/admin/activity-logs.md).
|
||||
|
||||
## Insights
|
||||
|
||||
@@ -42,13 +42,13 @@ Insights provide data-driven views of Docker usage to improve team productivity
|
||||
- Build efficiency: Track average build times and success rates to pinpoint bottlenecks in development processes.
|
||||
- Container utilization: Analyze container activity across departments to ensure proper resource distribution and cost efficiency.
|
||||
|
||||
For more information, see [Insights](/manuals/admin/organization/insights.md).
|
||||
For more information, see [Insights](/manuals/admin/insights.md).
|
||||
|
||||
## Next steps
|
||||
|
||||
Now that you've mastered user and access management in Docker, you can:
|
||||
|
||||
- Review your [activity logs](/manuals/admin/organization/activity-logs.md) regularly to maintain security awareness
|
||||
- Check your [Insights dashboard](/manuals/admin/organization/insights.md) to identify opportunities for optimization
|
||||
- Review your [activity logs](/manuals/admin/activity-logs.md) regularly to maintain security awareness
|
||||
- Check your [Insights dashboard](/manuals/admin/insights.md) to identify opportunities for optimization
|
||||
- Explore [advanced security features](/manuals/enterprise/security/_index.md) to further enhance your Docker environment
|
||||
- Share best practices with your team to ensure consistent adoption of security policies
|
||||
|
||||
@@ -54,13 +54,13 @@ The company owner:
|
||||
|
||||
- Can view and manage all organizations within the company
|
||||
- Has full access to company-wide settings and inherits the same permissions as organization owners
|
||||
- Do not occupy a seat
|
||||
- Does not occupy a seat
|
||||
|
||||
Companies are only available for Docker Business subscribers.
|
||||
|
||||
### Organization
|
||||
|
||||
Organization owners have the organization owner administrator role available. They can manage organization settings, users, and access controls, but occupy a [seat](/manuals/admin/faqs/organization-faqs.md#what-is-the-difference-between-user-invitee-seat-and-member).
|
||||
Organization owners have the organization owner administrator role available. They can manage organization settings, users, and access controls, but occupy a [seat](/manuals/admin/organization/organization-faqs.md#what-is-the-difference-between-user-invitee-seat-and-member).
|
||||
|
||||
- An organization contains teams and repositories.
|
||||
- All Docker Team and Business subscribers must have at least one organization.
|
||||
|
||||
+1
@@ -5,6 +5,7 @@ description: Learn how to access and interpret Docker activity logs for organiza
|
||||
keywords: audit log, organization activity, Docker business logs, repository activity, track changes Docker, security logs Docker, filter logs, log Docker events
|
||||
aliases:
|
||||
- /docker-hub/audit-log/
|
||||
- /admin/organization/activity-logs/
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Activity logs" >}}
|
||||
@@ -14,15 +14,15 @@ grid:
|
||||
Learn how to add and manage organizations as well as seats within your
|
||||
company.
|
||||
icon: store
|
||||
link: /admin/company/organizations/
|
||||
link: /admin/company/manage/organizations/
|
||||
- title: Manage company owners
|
||||
description: Find out more about company owners and how to manage them.
|
||||
icon: supervised_user_circle
|
||||
link: /admin/company/owners/
|
||||
link: /admin/company/manage/owners/
|
||||
- title: Manage users
|
||||
description: Explore how to manage users in all organizations.
|
||||
icon: group_add
|
||||
link: /admin/company/users/
|
||||
link: /admin/company/manage/users/
|
||||
- title: Configure single sign-on
|
||||
description: Discover how to configure SSO for your entire company.
|
||||
icon: key
|
||||
|
||||
+3
-2
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: FAQs on companies
|
||||
linkTitle: Company
|
||||
title: Company FAQs
|
||||
linkTitle: FAQs
|
||||
weight: 30
|
||||
description: Company FAQs
|
||||
keywords: Docker, Docker Hub, SSO FAQs, single sign-on, company, administration, company management
|
||||
@@ -8,6 +8,7 @@ tags: [FAQ]
|
||||
aliases:
|
||||
- /docker-hub/company-faqs/
|
||||
- /faq/admin/company-faqs/
|
||||
- /admin/faqs/company-faqs/
|
||||
---
|
||||
|
||||
### Some of my organizations don’t have a Docker Business subscription. Can I still use a parent company?
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
build:
|
||||
render: never
|
||||
title: Manage
|
||||
weight: 20
|
||||
---
|
||||
+9
-7
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Manage company organizations
|
||||
linkTitle: Manage organizations
|
||||
linkTitle: Organizations
|
||||
description: Learn how to manage organizations in a company.
|
||||
keywords: company, multiple organizations, manage organizations, Docker Admin Console, organization settings, add organization, company management
|
||||
aliases:
|
||||
- /admin/company/organizations/
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Company" >}}
|
||||
@@ -12,14 +14,14 @@ Learn to manage the organizations in a company using the Docker Admin Console.
|
||||
## View all organizations
|
||||
|
||||
1. Sign in to the [Docker Home](https://app.docker.com) and choose
|
||||
your company.
|
||||
your company.
|
||||
1. Select **Admin Console**, then **Organizations**.
|
||||
|
||||
The **Organizations** view displays all organizations under your company.
|
||||
|
||||
## Add seats to an organization
|
||||
|
||||
If you have a [self-serve](../../subscription/details.md#self-serve)
|
||||
If you have a [self-serve](../../../subscription/details.md#self-serve)
|
||||
subscription that has no pending subscription changes, you can add seats using
|
||||
Docker Home. For more information about adding seats,
|
||||
see [Manage seats](/manuals/subscription/manage-seats.md#add-seats).
|
||||
@@ -39,10 +41,10 @@ To add an organization to a company, ensure the following:
|
||||
> [!IMPORTANT]
|
||||
>
|
||||
> Once you add an organization to a company, you can't remove it from the
|
||||
company.
|
||||
> company.
|
||||
|
||||
1. Sign in to [Docker Home](https://app.docker.com) and select your company from
|
||||
the top-left account drop-down.
|
||||
the top-left account drop-down.
|
||||
1. Select **Admin Console**, then **Organizations**.
|
||||
1. Select **Add organization**.
|
||||
1. Choose the organization you want to add from the drop-down menu.
|
||||
@@ -51,12 +53,12 @@ the top-left account drop-down.
|
||||
## Manage an organization
|
||||
|
||||
1. Sign in to [Docker Home](https://app.docker.com) and select your company from
|
||||
the top-left account drop-down.
|
||||
the top-left account drop-down.
|
||||
1. Select **Admin Console**, then **Organizations**.
|
||||
1. Select the organization you want to manage.
|
||||
|
||||
For more details about managing an organization, see
|
||||
[Organization administration](../organization/_index.md).
|
||||
[Organization administration](../../organization/_index.md).
|
||||
|
||||
## More resources
|
||||
|
||||
+3
-2
@@ -1,9 +1,10 @@
|
||||
---
|
||||
title: Manage company owners
|
||||
linkTitle: Manage owners
|
||||
linkTitle: Owners
|
||||
description: Learn how to add and remove company owners.
|
||||
keywords: company, owners, add company owner, remove company owner, company manageemnt, company owner permissions
|
||||
keywords: company, owners, add company owner, remove company owner, company management, company owner permissions
|
||||
aliases:
|
||||
- /admin/company/owners/
|
||||
- /docker-hub/company-owner/
|
||||
---
|
||||
|
||||
+4
-2
@@ -1,8 +1,10 @@
|
||||
---
|
||||
title: Manage company members
|
||||
linkTitle: Manage users
|
||||
linkTitle: Users
|
||||
description: Learn how to manage company members in the Docker Admin Console.
|
||||
keywords: company, company members, members, admin, Admin Console, member management, organization management, company management, bulk invite, resend invites
|
||||
aliases:
|
||||
- /admin/company/users/
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Company" >}}
|
||||
@@ -142,4 +144,4 @@ see the [Bulk create invites](https://docs.docker.com/reference/api/hub/latest/#
|
||||
## Manage members on a team
|
||||
|
||||
Use Docker Hub to add a member to a team or remove a member from a team. For
|
||||
more details, see [Manage members](../organization/manage/members.md#manage-members-on-a-team).
|
||||
more details, see [Manage members](../../organization/manage/members.md#manage-members-on-a-team).
|
||||
@@ -1,10 +1,11 @@
|
||||
---
|
||||
title: Create a company
|
||||
title: Create new company
|
||||
linkTitle: Create
|
||||
weight: 10
|
||||
description: Learn how to create a company to centrally manage multiple organizations.
|
||||
keywords: company, hub, organization, company owner, Admin Console, company management, Docker Business, create company, Docker Admin Console
|
||||
aliases:
|
||||
- /docker-hub/new-company/
|
||||
- /docker-hub/new-company/
|
||||
---
|
||||
|
||||
{{< summary-bar feature_name="Company" >}}
|
||||
@@ -24,26 +25,26 @@ Before you begin, you must:
|
||||
To create a new company:
|
||||
|
||||
1. Sign in to [Docker Home](https://app.docker.com/) and select your
|
||||
organization.
|
||||
organization.
|
||||
1. Select **Admin Console**, then **Company management**.
|
||||
1. Select **Create a company**.
|
||||
1. Enter a unique name for your company, then select **Continue**.
|
||||
|
||||
> [!TIP]
|
||||
>
|
||||
> The name for your company can't be the same as an existing user,
|
||||
organization, or company namespace.
|
||||
> [!TIP]
|
||||
>
|
||||
> The name for your company can't be the same as an existing user,
|
||||
> organization, or company namespace.
|
||||
|
||||
1. Review the migration details and then select **Create company**.
|
||||
|
||||
For more information on how you can add organizations to your company,
|
||||
see [Add organizations to a company](./organizations.md#add-organizations-to-a-company).
|
||||
see [Add organizations to a company](./manage/organizations.md#add-organizations-to-a-company).
|
||||
|
||||
## Next steps
|
||||
|
||||
- [Manage organizations](./organizations.md)
|
||||
- [Manage company members](./users.md)
|
||||
- [Manage company owners](./owners.md)
|
||||
- [Manage organizations](./manage/organizations.md)
|
||||
- [Manage company members](./manage/users.md)
|
||||
- [Manage company owners](./manage/owners.md)
|
||||
|
||||
## More resources
|
||||
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
---
|
||||
build:
|
||||
render: never
|
||||
linkTitle: FAQs
|
||||
title: Account and admin FAQs
|
||||
weight: 30
|
||||
---
|
||||
@@ -16,7 +16,7 @@ grid:
|
||||
- title: Activity logs
|
||||
description: Learn how to audit the activities of your members.
|
||||
icon: text_snippet
|
||||
link: /admin/organization/activity-logs/
|
||||
link: /admin/activity-logs/
|
||||
- title: Image Access Management
|
||||
description: Control which types of images your developers can pull.
|
||||
icon: photo_library
|
||||
|
||||
@@ -140,7 +140,7 @@ reference](/manuals/enterprise/security/hardened-desktop/settings-management/set
|
||||
|
||||
To view usage for Docker products:
|
||||
|
||||
- Docker Desktop: View the **Insights** page in [Docker Home](https://app.docker.com/). For more details, see [Insights](../insights.md).
|
||||
- Docker Desktop: View the **Insights** page in [Docker Home](https://app.docker.com/). For more details, see [Insights](../../insights.md).
|
||||
- Docker Hub: View the [**Usage** page](https://hub.docker.com/usage) in Docker Hub.
|
||||
- Docker Build Cloud: View the **Build minutes** page in [Docker Build Cloud](http://app.docker.com/build).
|
||||
- Docker Scout: View the [**Repository settings** page](https://scout.docker.com/settings/repos) in Docker Scout.
|
||||
|
||||
+4
-3
@@ -1,13 +1,14 @@
|
||||
---
|
||||
title: Organization FAQs
|
||||
linkTitle: FAQs
|
||||
weight: 60
|
||||
description: Organization FAQs
|
||||
linkTitle: Organization
|
||||
weight: 20
|
||||
keywords: Docker, Docker Hub, SSO FAQs, single sign-on, organizations, administration, Admin Console, members, organization management, manage orgs
|
||||
title: FAQs on organizations
|
||||
tags: [FAQ]
|
||||
aliases:
|
||||
- /docker-hub/organization-faqs/
|
||||
- /faq/admin/organization-faqs/
|
||||
- /admin/faqs/organization-faqs/
|
||||
---
|
||||
|
||||
### How can I see how many active users are in my organization?
|
||||
@@ -191,7 +191,7 @@ Docker introduces the Advanced Image Management dashboard that enables you to vi
|
||||
|
||||
Docker introduces Audit logs, a new feature that allows team owners to view a list of activities that occur at organization and repository levels. This feature begins tracking the activities from the release date, that is, **from 25 January 2021**.
|
||||
|
||||
For more information about this feature and for instructions on how to use it, see [Activity logs](../admin/organization/activity-logs.md).
|
||||
For more information about this feature and for instructions on how to use it, see [Activity logs](../admin/activity-logs.md).
|
||||
|
||||
## 2020-11-10
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@ Attribution is based on the following:
|
||||
- Single organization membership:
|
||||
- If the owner of the verified domain is a company and the user is part of
|
||||
only one organization within that
|
||||
[company](../../admin/faqs/company-faqs.md#what-features-are-supported-at-the-company-level),
|
||||
[company](../../admin/company/company-faqs.md),
|
||||
the pull is attributed to that specific organization.
|
||||
- If the user is part of only one organization, the pull is attributed to
|
||||
that specific organization.
|
||||
|
||||
@@ -86,7 +86,7 @@ This page provides details on new features, enhancements, known issues, and bug
|
||||
|
||||
### New
|
||||
|
||||
- Administrators can now view [organization Insights](/manuals/admin/organization/insights.md).
|
||||
- Administrators can now view [organization Insights](/manuals/admin/insights.md).
|
||||
|
||||
## 2024-07-17
|
||||
|
||||
|
||||
@@ -117,7 +117,7 @@ tags:
|
||||
description: |
|
||||
The Audit Logs API endpoints allow you to query audit log events across a namespace.
|
||||
|
||||
For more information, see [Audit Logs](https://docs.docker.com/admin/organization/activity-logs/).
|
||||
For more information, see [Audit Logs](https://docs.docker.com/admin/activity-logs/).
|
||||
- name: org-settings
|
||||
x-displayName: Org Settings
|
||||
description: |
|
||||
@@ -1533,7 +1533,7 @@ paths:
|
||||
- `last_seen_at`
|
||||
- `last_desktop_version`
|
||||
|
||||
To make visible, please see [View Insights for organization users](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
|
||||
To make visible, please see [View Insights for organization users](https://docs.docker.com/admin/insights/#view-insights-for-organization-users).
|
||||
|
||||
<span class="oat"></span>
|
||||
tags:
|
||||
@@ -3639,20 +3639,20 @@ components:
|
||||
format: date-time
|
||||
description: |
|
||||
Last time the user logged in. To access this field, you must have insights visible for your organization. See
|
||||
[Insights](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
|
||||
[Insights](https://docs.docker.com/admin/insights/#view-insights-for-organization-users).
|
||||
example: "2021-01-05T21:06:53.506400Z"
|
||||
last_seen_at:
|
||||
type: string
|
||||
format: date-time
|
||||
description: |
|
||||
Last time the user was seen. To access this field, you must have insights visible for your organization. See
|
||||
[Insights](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
|
||||
[Insights](https://docs.docker.com/admin/insights/#view-insights-for-organization-users).
|
||||
example: "2021-01-05T21:06:53.506400Z"
|
||||
last_desktop_version:
|
||||
type: string
|
||||
description: |
|
||||
Last desktop version the user used. To access this field, you must have insights visible for your organization. See
|
||||
[Insights](https://docs.docker.com/admin/organization/insights/#view-insights-for-organization-users).
|
||||
[Insights](https://docs.docker.com/admin/insights/#view-insights-for-organization-users).
|
||||
example: 4.29.0
|
||||
|
||||
org_member_paginated:
|
||||
|
||||
Reference in New Issue
Block a user