git:20260727.7842a1d to git:20260826.575370c

---

id: huawei-cloud-swr-image-governance

name: huawei-cloud-swr-image-governance

description: |

Huawei Cloud SWR (Software Repository for Container) image governance skill using hcloud CLI.

Use this skill when the user wants to: (1) manage SWR namespace permissions - grant/query/modify/revoke, (2) manage repository permissions - grant/query/modify/revoke, (3) manage image retention rules - create/list/update/delete, (4) manage shared download domains - create/list/update/delete, (5) manage image sharing - list shared repos/query feature gates, (6) check SWR agency status and create agency delegation, (7) list repo accessories and references.

Trigger: user mentions "SWR image governance", "SWR 镜像治理", "SWR 权限管理", "SWR retention", "SWR 保留策略", "SWR 共享域名", "SWR 共享镜像", "SWR 委托", "SWR agency", "namespace permissions", "repository permissions", "镜像权限", "保留规则", "共享下载", "镜像分享"

tags: [swr, image-governance, permissions, retention, sharing]

---

# Huawei Cloud SWR Image Governance

## Overview

This skill provides governance capabilities for Huawei Cloud SWR (Software Repository for Container) using the `hcloud` CLI, covering permissions, retention policies, sharing, and agency delegation.

**Architecture**: hcloud CLI → SWR Service API → Permission/Retention/Domain/Share/Agency resources

**Related Skills**:

- `huawei-cloud-swr-image-management` - Image lifecycle management (namespace, repo, tag, auth, quota)

- `huawei-cloud-swr-image-automation` - Image automation ops (sync, triggers, domains)

- `huawei-cloud-swr-enterprise-instance` - Enterprise instance management

**Capabilities**:

- Grant, query, modify, and revoke namespace-level permissions

- Grant, query, modify, and revoke repository-level permissions

- Create and manage image retention rules for automated cleanup

- Create and manage shared download domains for cross-organization access

- List shared repositories and check sharing feature gates

- Check and create agency delegation for SWR operations

- List repository accessories and references

**Typical Use Cases**:

- "Grant edit permission on namespace 'group-dev' to user 'dev-team'"

- "List all users with access to namespace 'group-dev'"

- "Set up a retention rule to keep only the last 10 tags in repository 'nginx'"

- "Create a shared download domain for repository 'my-app'"

- "List all shared repositories"

- "Check if image sharing feature is enabled"

- "Check agency delegation status for SWR"

- "Revoke a user's permission on a repository"

## Workflow

1. **Parse user request** — identify the governance operation (permissions, retention, domains, sharing, agency)

### 参数确认

> **All write operations (Create, Update, Delete) require explicit user confirmation before execution.**

Before executing any write operation, the skill must:

1. Display the exact hcloud command to be executed

2. Show the target resource (namespace, repository, domain, etc.)

3. Show the change to be applied (permission level, retention rule, domain settings)

4. Wait for user confirmation ("yes" / "confirm") before proceeding

5. If user declines, abort the operation and return to step 1

**Write operations requiring confirmation**:

| Operation | Command | Risk Level | Description |

|-----------|---------|------------|-------------|

| Grant namespace permission | `CreateNamespaceAuth` | 🟡 Medium | Grants access to all repos under namespace. **If auth=7, grants full control (create/delete repos, manage permissions)** — warn user accordingly |

| Update namespace permission | `UpdateNamespaceAuth` | 🟡 Medium | Changes access level for namespace. **Permission downgrade may prevent the user from performing existing operations, impacting business workflows** |

| Revoke namespace permission | `DeleteNamespaceAuth` | 🟠 High | Removes all access to namespace. **May cause business interruption — any CI/CD pipelines or services using this namespace will immediately lose access** |

| Grant repo permission | `CreateUserRepositoryAuth` | 🟡 Medium | Grants access to specific repository. **If auth=7, grants full control of this repository** |

| Update repo permission | `UpdateUserRepositoryAuth` | 🟡 Medium | Changes access level for repository. **Permission downgrade may break existing workflows that depend on the current access level** |

| Revoke repo permission | `DeleteUserRepositoryAuth` | 🟠 High | Removes all access to repository. **May cause business interruption — services pulling from this repo will immediately lose access** |

| Create retention rule | `CreateRetention` | 🟠 High | Creates automated cleanup policy. **When the rule executes, tags not matching retention conditions are automatically deleted and data is unrecoverable** |

| Update retention rule | `UpdateRetention` | 🟠 High | Modifies cleanup policy. **Changing conditions may cause previously retained tags to be deleted — data is unrecoverable** |

| Delete retention rule | `DeleteRetention` | 🟡 Medium | Removes automated cleanup policy. Existing tags are preserved, but no future cleanup will occur |

| Create shared domain | `CreateRepoDomains` | 🟡 Medium | Shares images with another account via cross-organization access |

| Update shared domain | `UpdateRepoDomains` | 🟡 Medium | Changes sharing settings (e.g., expiration, permissions) |

| Delete shared domain | `DeleteRepoDomains` | 🟠 High | Revokes cross-account access. **Users in the target organization will immediately lose the ability to pull images via this domain** |

| Create agency | `CreateAgency` | 🟠 High | Creates SWR delegation. **Grants SWR permission to access other services (OBS, CCE) on your behalf — confirm the delegation scope before proceeding** |

## Prerequisites

### 1. hcloud CLI Requirements (MANDATORY)

- hcloud CLI installed (version >= 7.2.2)

- Run `hcloud version` to verify installation

- First-time usage: `printf "y\n" | hcloud version` to accept privacy statement

### 2. Credential Configuration

hcloud CLI supports two credential modes via environment variables, automatically detected at runtime:

**Mode A — Long-term AK/SK** (permanent access):

```bash

export HUAWEI_CLOUD_AK=<your-ak>

export HUAWEI_CLOUD_SK=<your-sk>

export HUAWEI_CLOUD_REGION=cn-north-4

```

**Mode B — Temporary AK/SK + SecurityToken** (recommended for temporary or delegated access):

```bash

export HUAWEI_CLOUD_AK=<your-temp-ak>

export HUAWEI_CLOUD_SK=<your-temp-sk>

export HUAWEI_CLOUD_SECURITY_TOKEN=<your-security-token>

export HUAWEI_CLOUD_REGION=cn-north-4

```

> When `HUAWEI_CLOUD_SECURITY_TOKEN` is present, hcloud CLI automatically uses temporary credential authentication. When only AK/SK are set, it uses long-term credential authentication.

- **Security Rules**:

- 🚫 Never expose AK/SK/SecurityToken values in code, conversation, or commands

- 🚫 Never use `echo $HUAWEI_CLOUD_AK` or `echo $HUAWEI_CLOUD_SK` to check credentials

- ✅ Use environment variables: `HUAWEI_CLOUD_AK`, `HUAWEI_CLOUD_SK`, `HUAWEI_CLOUD_REGION`, `HUAWEI_CLOUD_SECURITY_TOKEN`

- ✅ Prefer IAM users over root account for cloud operations

- ✅ Enable MFA for sensitive operations

**⚠️ Important Security Notes**:

- Never commit credentials to version control

- Use IAM users with minimal required permissions

- Enable MFA for sensitive operations

- Rotate AK/SK regularly

### 3. IAM Permission Requirements

| API Action | Permission | Purpose |

| -------------------------------- | ----------------- | -------------------------------------- |

| `swr:namespace:auth:create` | Create NS auth | Grant namespace permissions |

| `swr:namespace:auth:get` | Get NS auth | Query namespace permissions |

| `swr:namespace:auth:update` | Update NS auth | Modify namespace permissions |

| `swr:namespace:auth:delete` | Delete NS auth | Revoke namespace permissions |

| `swr:repository:auth:create` | Create repo auth | Grant repository permissions |

| `swr:repository:auth:get` | Get repo auth | Query repository permissions |

| `swr:repository:auth:update` | Update repo auth | Modify repository permissions |

| `swr:repository:auth:delete` | Delete repo auth | Revoke repository permissions |

| `swr:retention:create` | Create retention | Create retention rules |

| `swr:retention:list` | List retention | List retention rules |

| `swr:retention:get` | Get retention | View retention rule details |

| `swr:retention:update` | Update retention | Modify retention rules |

| `swr:retention:delete` | Delete retention | Remove retention rules |

| `swr:domain:create` | Create domain | Create shared download domains |

| `swr:domain:list` | List domains | List shared download domains |

| `swr:domain:get` | Get domain | View domain details |

| `swr:domain:update` | Update domain | Modify domain settings |

| `swr:domain:delete` | Delete domain | Remove shared download domains |

| `swr:share:list` | List shared repos | List shared repositories |

| `swr:share:get` | Get shared repo | View shared repository details |

| `swr:share:feature:get` | Get share feature | Check sharing feature gates |

| `swr:global:feature:get` | Get global feature| Check global feature gates |

| `swr:agency:check` | Check agency | Check agency delegation status |

| `swr:agency:create` | Create agency | Create agency delegation |

| `swr:accessory:list` | List accessories | List repository accessories |

| `swr:reference:list` | List references | List repository references |

See [IAM Permission Policies](references/iam-policies.md) for complete policy JSON.

**Permission Failure Handling**:

1. When any command fails due to permission errors, read `references/iam-policies.md`

2. Display the required permission list and policy JSON to the user

3. Guide the user to create a custom policy in the IAM console and grant authorization

4. Pause execution and wait for user confirmation that permissions have been granted

## KooCLI Command Format Standard

All commands follow the standard hcloud KooCLI format:

```bash

hcloud SWR <Operation> --param1=value1 --param2=value2 --cli-region=<region>

```

**Key conventions**:

- Service name: `SWR` (uppercase, matches KooCLI Services listing)

- Operation name: PascalCase (e.g., `ShowNamespaceAuth`, `CreateRetention`, `ListRepoDomains`)

- Region parameter: `--cli-region=<value>` (default: `cn-north-4`, or `HUAWEI_CLOUD_REGION` env var)

- Output format: `--cli-output=json` (for agent processing)

- JMESPath filtering: `--cli-query="<expression>"` (to reduce output)

- Array-style parameters: `--1.auth=7 --1.user_id=xxx` (index starts from 1, not 0)

- Nested object parameters: `--rules.1.template=tag_rule --rules.1.params='{"num":"10"}'`

**Example — read operation**:

```bash

hcloud SWR ShowNamespaceAuth --namespace=pancake --cli-region=cn-north-4 --cli-output=json

```

**Example — write operation (requires user confirmation)**:

```bash

# Step 1: Display command and parameters for user confirmation

# Step 2: After user confirms, execute:

hcloud SWR CreateNamespaceAuth --namespace=pancake --1.auth=7 --1.user_id=<user-id> --1.user_name=<user-name> --cli-region=cn-north-4

```

## Core Commands

### 1. Namespace Permissions

See [Task: Namespace Permissions](references/task-namespace-permissions.md) for detailed workflows.

```bash

# Show namespace permissions (who has access and their auth levels)

hcloud SWR ShowNamespaceAuth --namespace=pancake --cli-region=cn-north-4

# Grant namespace permission to a user

hcloud SWR CreateNamespaceAuth --namespace=pancake --1.auth=7 --1.user_id=05949eb5350010e21f85c017722182de --1.user_name=hwstaff_p00506267 --cli-region=cn-north-4

# Update namespace permission for a user

hcloud SWR UpdateNamespaceAuth --namespace=pancake --1.auth=3 --1.user_id=05949eb5350010e21f85c017722182de --1.user_name=hwstaff_p00506267 --cli-region=cn-north-4

```

**Auth Values**: `7` = manage (full control), `3` = edit (push/pull), `1` = read (pull only)

### 2. Repository Permissions

See [Task: Repository Permissions](references/task-repository-permissions.md) for detailed workflows.

```bash

# Show repository permissions

hcloud SWR ShowUserRepositoryAuth --namespace=pancake --repository=openclaw-sandbox --cli-region=cn-north-4

# Grant repository permission to a user

hcloud SWR CreateUserRepositoryAuth --namespace=pancake --repository=openclaw-sandbox --1.auth=7 --1.user_id=05949eb5350010e21f85c017722182de --1.user_name=hwstaff_p00506267 --cli-region=cn-north-4

# Update repository permission for a user

hcloud SWR UpdateUserRepositoryAuth --namespace=pancake --repository=openclaw-sandbox --1.auth=3 --1.user_id=05949eb5350010e21f85c017722182de --1.user_name=hwstaff_p00506267 --cli-region=cn-north-4

```

**Auth Values**: Same as namespace permissions: `7` = manage, `3` = edit, `1` = read

### 3. Agency Delegation

```bash

# Check if agency delegation is enabled

hcloud SWR CheckAgency --cli-region=cn-north-4

# Create agency delegation for SWR

hcloud SWR CreateAgency --cli-region=cn-north-4

```

**Use Cases**:

- Agency delegation allows SWR to access other services (OBS, CCE) on your behalf

- Required for features like image sync to OBS and CCE trigger deployments

- `CheckAgency` returns whether agency is already configured; `CreateAgency` sets up the delegation

### 4. Retention Rules

See [Task: Retention Management](references/task-retention-management.md) for detailed workflows.

```bash

# List retention rules for a repository

hcloud SWR ListRetentions --namespace=pancake --repository=openclaw-sandbox --cli-region=cn-north-4

# Create a retention rule (keep last 10 tags)

hcloud SWR CreateRetention --namespace=pancake --repository=openclaw-sandbox --algorithm=or --rules.1.template=tag_rule --rules.1.params='{"num":"10"}' --rules.1.tag_selectors.1.kind=label --rules.1.tag_selectors.1.pattern=latest --cli-region=cn-north-4

# Create a retention rule (keep tags from last 30 days)

hcloud SWR CreateRetention --namespace=pancake --repository=openclaw-sandbox --algorithm=or --rules.1.template=date_rule --rules.1.params='{"days":"30"}' --rules.1.tag_selectors.1.kind=label --rules.1.tag_selectors.1.pattern=latest --cli-region=cn-north-4

# Show retention rule details

hcloud SWR ShowRetention --namespace=pancake --repository=openclaw-sandbox --retention_id=<id> --cli-region=cn-north-4

# Update a retention rule

hcloud SWR UpdateRetention --namespace=pancake --repository=openclaw-sandbox --retention_id=<id> --algorithm=or --rules.1.template=tag_rule --rules.1.params='{"num":"5"}' --rules.1.tag_selectors.1.kind=label --rules.1.tag_selectors.1.pattern=latest --cli-region=cn-north-4

# Delete a retention rule

hcloud SWR DeleteRetention --namespace=pancake --repository=openclaw-sandbox --retention_id=<id> --cli-region=cn-north-4

# List retention execution histories

hcloud SWR ListRetentionHistories --namespace=pancake --repository=openclaw-sandbox --retention_id=<id> --cli-region=cn-north-4

```

**Retention Rule Templates**:

- `tag_rule`: Keep a specified number of the most recent tags (`params.num`)

- `date_rule`: Keep tags created within a specified number of days (`params.days`)

**Tag Selector Kinds**:

- `label`: Exact tag name match (e.g., `latest`, `v1.0`)

- `regexp`: Regex pattern match (e.g., `v\d+\.\d+\.\d+`)

**Algorithm**: `or` means rules are combined with OR logic (a tag is retained if it matches ANY rule)

### 5. Shared Download Domains

See [Task: Shared Domains](references/task-shared-domains.md) for detailed workflows.

```bash

# List shared download domains for a repository

hcloud SWR ListRepoDomains --namespace=pancake --repository=openclaw-sandbox --cli-region=cn-north-4

# Create a shared download domain

# --access_domain: Huawei Cloud IAM domain name (tenant name/account name) of the target account to share with

# --deadline: Expiration time in UTC format; use "forever" for permanent access

# --permit: Permission type; currently only "read" is supported

hcloud SWR CreateRepoDomains --namespace=pancake --repository=openclaw-sandbox --access_domain=<iam-domain-name> --deadline=forever --permit=read --cli-region=cn-north-4

# Show shared domain details

hcloud SWR ShowAccessDomain --namespace=pancake --repository=openclaw-sandbox --access_domain=<iam-domain-name> --cli-region=cn-north-4

# Update a shared download domain

hcloud SWR UpdateRepoDomains --namespace=pancake --repository=openclaw-sandbox --access_domain=<iam-domain-name> --deadline=forever --permit=read --cli-region=cn-north-4

# Delete a shared download domain

hcloud SWR DeleteRepoDomains --namespace=pancake --repository=openclaw-sandbox --access_domain=<iam-domain-name> --cli-region=cn-north-4

```

**Shared Domain Parameters**:

- `--access_domain`: The Huawei Cloud IAM domain name (shared tenant name) of the account you want to share the image with. This is the target account's domain name, not a custom domain identifier.

- `--deadline`: Expiration time in UTC format (e.g., `2025-12-31T23:59:59Z`). Use `forever` for permanent access.

- `--permit`: Permission type. Currently only `read` (download/pull) is supported.

- `--description` (optional): Human-readable description of the shared domain.

### 6. Image Sharing

See [Task: Image Sharing](references/task-image-sharing.md) for detailed workflows.

```bash

# List shared repositories I have shared (self) or received (thirdparty)

# --center is REQUIRED: "self" = repos I shared to others, "thirdparty" = repos shared to me

hcloud SWR ListSharedReposDetails --center=self --cli-region=cn-north-4

# List shared repository details (--shared_by is REQUIRED: self|thirdparty)

hcloud SWR ListSharedRepoDetails --shared_by=self --cli-region=cn-north-4

# Check sharing feature gates

hcloud SWR ShowShareFeatureGates --cli-region=cn-north-4

# Check global feature gates

hcloud SWR ListGlobalFeatureGates --cli-region=cn-north-4

```

### 7. Repository Accessories & References

```bash

# List repository accessories

hcloud SWR ListRepoAccessories --namespace=pancake --repository=openclaw-sandbox --cli-region=cn-north-4

# List repository references

hcloud SWR ListReferences --namespace=pancake --repository=openclaw-sandbox --cli-region=cn-north-4

```

## Parameter Reference

### Common Parameters

| Parameter | Required/Optional | Description | Default |

| --------------- | ----------------- | ----------------------------- | ------------------------------------ |

| `--cli-region` | Required | Huawei Cloud region ID | Config value or `HUAWEI_CLOUD_REGION` |

| `--namespace` | Context-dependent | SWR namespace (organization) | N/A |

| `--repository` | Context-dependent | Image repository name | N/A |

### Permission Parameters

| Parameter | Required | Description | Constraints |

| --------------- | -------- | ---------------------- | ---------------------------------------------- |

| `--namespace` | Yes | Namespace name | Must exist |

| `--repository` | Yes | Repository name (repo-level only) | Must exist |

| `--[N].auth` | Yes | Permission level | 7=manage, 3=edit, 1=read |

| `--[N].user_id` | Yes | IAM user ID | Hex string (e.g., `05949eb5350010e21f85c017722182de`) |

| `--[N].user_name` | Yes | IAM user name | IAM user display name |

**⚠️ Array Index Format**: `[N]` starts from 1 (not 0). For granting permission to a single user, use `--1.auth=7 --1.user_id=xxx --1.user_name=xxx`. For multiple users, use `--1.auth=7 --1.user_id=xxx --1.user_name=xxx --2.auth=3 --2.user_id=yyy --2.user_name=yyy`.

### Retention Parameters

| Parameter | Required | Description | Constraints |

| ----------------------------- | -------- | ------------------------ | -------------------------------------------- |

| `--namespace` | Yes | Namespace name | Must exist |

| `--repository` | Yes | Repository name | Must exist |

| `--retention_id` | Yes | Retention rule ID (for show/update/delete) | Numeric ID |

| `--algorithm` | Yes | Rule combination logic | Fixed value `or` |

| `--rules.[N].template` | Yes | Rule template type | `date_rule` or `tag_rule` |

| `--rules.[N].params` | Yes | Rule parameters | `days` for date_rule, `num` for tag_rule |

| `--rules.[N].tag_selectors.[N].kind` | Yes | Selector kind | `label` or `regexp` |

| `--rules.[N].tag_selectors.[N].pattern` | Yes | Selector pattern | Tag name or regex |

### Domain Parameters

| Parameter | Required | Description | Constraints |

| ----------------- | -------- | ------------------------------------ | ---------------------------------------------- |

| `--namespace` | Yes | Namespace name | Must exist |

| `--repository` | Yes | Repository name | Must exist |

| `--access_domain` | Yes | Huawei Cloud IAM domain name (shared tenant name) | Target account's domain name, not a custom identifier |

| `--deadline` | Yes (create/update) | Expiration time | UTC format (e.g., `2025-12-31T23:59:59Z`) or `forever` |

| `--permit` | Yes (create/update) | Permission type | `read` (only supported value) |

| `--description` | No | Domain description | Default: empty string |

## Output Format

See [Output Format](references/output-format.md) for detailed response format examples (NamespaceAuth, RepositoryAuth, RepoDomains, CheckAgency, ShareFeatureGates, GlobalFeatureGates, Retentions, RepoAccessories, ListSharedReposDetails).

**Key Format Notes**:

- `auth`: Permission value (7=manage, 3=edit, 1=read)

- `self_auth` vs `others_auths`: Check both when auditing permissions

- `ListRepoDomains`: Uses `created/updated` (NOT `created_at/updated_at`)

- `ListRetentions`: Returns flat array (empty `[]` when no rules)

- `ListRepoAccessories`: Uses `total` + `accessories` (null when empty)

## Verification

See [Verification Method](references/verification-method.md) for step-by-step verification.

## Best Practices

1. **Least Privilege**: Grant the minimum auth level needed — `1` (read) for pull-only, `3` (edit) for push/pull, `7` (manage) for full control

2. **Namespace vs Repository Permissions**: Namespace permissions apply to ALL repositories under it; repository permissions are granular per-repo

3. **Retention Rules**: Use `tag_rule` (keep N most recent) for most cases; `date_rule` (keep tags within N days) for time-based cleanup

4. **Retention Tag Selectors**: Use `label` kind with `latest` pattern to protect important tags from retention cleanup

5. **Shared Domains**: Use `deadline=forever` for stable internal sharing; set specific deadlines for temporary cross-team access

6. **Agency Delegation**: Check agency status before configuring image sync or CCE triggers — these require agency to be enabled

7. **Audit Permissions Regularly**: Use `ShowNamespaceAuth` and `ShowUserRepositoryAuth` to periodically review who has access

## Reference Documents

| Document | Description |

| ------------------------------------------------------ | ---------------------------------------- |

| [SWR Governance API Guide](references/swr-governance-api-guide.md) | hcloud SWR governance API reference |

| [Output Format](references/output-format.md) | Response format examples (verified) |

| [IAM Permission Policies](references/iam-policies.md) | Required permissions and policy JSON |

| [Verification Method](references/verification-method.md) | Step-by-step verification |

| [Common Pitfalls](references/common-pitfalls.md) | Troubleshooting guides |

| [Task: Namespace Permissions](references/task-namespace-permissions.md) | Namespace permission workflows |

| [Task: Repository Permissions](references/task-repository-permissions.md) | Repository permission workflows |

| [Task: Retention Management](references/task-retention-management.md) | Retention rule workflows |

| [Task: Shared Domains](references/task-shared-domains.md) | Shared domain workflows |

| [Task: Image Sharing](references/task-image-sharing.md) | Image sharing workflows |

| [CLI Installation Guide](references/cli-installation-guide.md) | KooCLI installation and configuration |

| [Acceptance Criteria](references/acceptance-criteria.md) | Correct/error pattern comparison |

## Notes

- **Permission changes are immediate** — no delay between granting and availability

- **Revoke with caution** — removing manage auth (7) prevents the user from administering the namespace/repository

- **Retention rules execute automatically** — tags matching the rule conditions will be deleted during execution

- **AK/SK must never be hardcoded** — credentials should only be obtained via environment variables

- **hcloud CLI is the only supported method** — all operations use `hcloud SWR <Operation>` format

- **ListRepoDomains timestamps use `created/updated`** — NOT `created_at/updated_at`

## Common Pitfalls

See [Common Pitfalls & Solutions](references/common-pitfalls.md) for detailed troubleshooting guides.

**Quick Reference**:

| Pitfall | Symptom | Quick Fix |

| --------------------------- | ------------------------------- | -------------------------------------------- |

| Array-style params | Permission grant fails | Use `--1.auth=7 --1.user_id=xxx` (index from 1, not 0) |

| Auth value wrong | User has unexpected access | 7=manage, 3=edit, 1=read (not 1/2/3) |

| self_auth vs others_auths | Missing user in audit | Check both `self_auth` and `others_auths` |

| Domain timestamp fields | Parsing `created_at` fails | Use `created`/`updated` (not `created_at`) |

| Retention rule format | CreateRetention fails | Nested array params: `--rules.1.tag_selectors.1.kind` |

| Agency not configured | Image sync/CCE trigger fails | Run `CheckAgency` then `CreateAgency` |