Git Repository Configuration

https://app.example.com is an example address. Replace it with the actual address of your environment, retaining the route path and query parameters.

1. Configuration Goal

Create Git Repository Connections in the Admin Console to provide reusable Git sources for Skills, Works, and Connectors in Resource Hub.

The Git Repositories page maintains only repository connections, default branches, authentication methods, credentials, and Access Scope. It does not maintain resource drafts, resource versions, file merges, or Explore publication strategies.

2. Configuration Entry

Configuration entry: System → Git repositories

app.example.com is an example domain. During actual operation, replace it with the AOS Work access domain for the customer environment. Keep the route path /admin/settings/git-repositories unchanged.

The page provides the following operations and information:

• Add repository: Add a repository connection;
• Search Git repositories: Search repository connections;
• List fields: Name, Repository URL, Default branch, Auth, and Access scope;
• More actions on the right of each record: continue to use the edit, test, unbind, or delete actions provided by the current environment.

3. Pre-configuration Checklist

Before starting, confirm:

1. The current administrator has Admin Console access and Git repository management permission;
2. The repository name, repository URL, and readable default branch are confirmed;
3. The repository serves exactly one resource type: Skill, Work, or Connector;
4. Credentials matching the repository's authentication method are ready. For a publicly readable repository, use the no-auth option provided by the page;
5. The target repository branch contains the corresponding .workbench Manifest and resource directory structure;
6. SSH private keys, Tokens, and other authentication secrets are not recorded in ordinary documents, chat records, or resource files.

4. Repository Connection Fields

After clicking Add repository, the page opens the Add repository dialog:

Test connection verifies whether the repository URL, branch, authentication method, and credentials can be accessed. Save repository saves the connection configuration. Do not put credentials in Repository name, URL parameters, or resource files.

5. Add a Git Repository Connection

1. Open System → Git repositories.
2. Click Add repository.
3. Fill in Repository name.
4. Fill in Default branch and confirm that the branch exists remotely.
5. Fill in Repository URL.
6. Select Auth type.
7. Select an Access scope matching the target resource type: Skill, Work, or Connector.
8. Enter Credential secret according to the authentication method. Handle a public repository without authentication as required by the page.
9. Click Test connection and confirm that the test succeeds.
10. Click Save repository.

A successful connection test only means that the Git repository and credentials are accessible. It does not replace subsequent Resource Manifest and resource-directory structure checks.

6. Access Scope and Resource Types

Access scope defines the binding boundary between a repository connection and the Resource Hub resource type:

Resource Hub displays only repository connections whose scope exactly matches the selected Resource Type and whose connection test succeeded. A repository with Skill scope cannot create a Work, and a repository with Connector scope cannot create a Skill.

7. Resource Manifest and Directory Structure

7.1 General Manifest Requirements

The target branch must contain the Manifest corresponding to the Access scope. The Manifest must satisfy all of the following:

• The file exists and contains valid JSON;
• The corresponding skills, works, or connectors field in the JSON is an array;
• Every array item is an object containing non-empty string values for key, name, and path;
• key values within one Manifest must not be duplicated case-insensitively; for example, GitHub and github are duplicates;
• path must exactly equal the resource root directory plus key: skills/<key>, works/<key>, or connectors/<key>;
• Paths use / as the separator, must not be absolute, and must not contain a path segment whose value is ..;
• path must point to a directory in the target commit.

Example structure:

.workbench/
  skills.json
skills/
  code-review/
    SKILL.md

7.2 Skill

The Skill Manifest item path must be skills/<key>, and the root of the corresponding resource directory must contain SKILL.md.

skills/
  <key>/
    SKILL.md

When a version is later published in Resource Hub, the root SKILL.md must be a non-empty text file with parseable YAML frontmatter. The Skill description may be empty, but the frontmatter must not be missing or damaged.

7.3 Work

The Work Manifest item path must be works/<key>. The resource root must not contain SKILL.md and must contain at least one first-level member definition:

works/
  <key>/
    <member>/
      SKILL.md

Only a file whose relative path is exactly <member>/SKILL.md counts as a first-level member. group/<member>/SKILL.md does not count. At publication time, every member definition must contain parseable YAML frontmatter and a non-empty description. After trimming leading and trailing whitespace, a member name must be non-empty and no longer than 100 characters; it cannot be . or .., contain / or a backslash, or contain ASCII control characters. Member names must be exactly unique within a Work.

7.4 Connector

The Connector Manifest item path must be connectors/<key>. The resource root must not contain SKILL.md and must contain at least one first-level member definition:

connectors/
  <key>/
    <member>/
      SKILL.md

The root-level README.md, ordinary files, and references/ inside member directories may exist. If a root-level SKILL.md and member-level Skills both exist, Connector structure validation fails. At publication time, every member definition must contain parseable YAML frontmatter and a non-empty description. Member names follow the same safety rules as Work member names and must be exactly unique within a Connector.

8. Create and Sync Resources from Git

After the Git repository connection is complete, use it in Resource Hub as follows:

1. Click New Resource and first select a Resource Type: Skill, Work, or Connector.
2. Select Import from Git.
3. Select a Git Repository Connection whose type matches the resource type and whose connection test succeeded.
4. The system reads the default branch and displays the repository, Commit, and file preview.
5. Fill in Resource Name, Description, and Draft Name.
6. Confirm to create the resource and its first Named Draft.

When Git Sync is later executed in Resource Hub, the system reads the latest available Commit on the default branch and always creates a new Named Draft. It does not overwrite existing drafts or published Immutable Versions. The Git Repositories page does not handle file merges or conflicts.

9. Git Resource Snapshot Validation

After the resource-list preview passes, the first import or confirmed resource snapshot read performs these additional checks:

• During the first import, the Commit actually read must match the Commit confirmed during preview. If the remote commit changes, preview again;
• The resource key and normalized path must still match the current Manifest item. key matching is case-sensitive;
• A resource whose Manifest item was deleted or renamed is not silently imported from its old path;
• The resource contains at least one file;
• The file count does not exceed 1000;
• No individual file exceeds 100 MiB;
• The total size of all files in one resource does not exceed 500 MiB;
• Files no larger than 1,000,000 bytes that are valid UTF-8 and contain no NUL byte can be read as text; other files are preserved as binary content.

10. Common Validation Problems

A successful Git fetch does not mean that Resource validation succeeds. A repository may be accessible while still being invalid as a Resource Hub source because its Manifest, paths, or resource directory does not meet the requirements.

11. Permissions and Auditing

When Access Scope is added or changed, credentials are replaced, a connection is tested again, a resource binding is removed, or a repository connection is deleted, the system records the operator, time, changes, and result. Resource modules can use repository connections but cannot read Git credentials in plaintext. Credentials continue to be displayed as masked values or status.

12. Post-save Verification

1. Return to the Git repositories list and search for the saved Repository name.
2. Verify Repository URL, Default branch, Auth, and Access scope.
3. Confirm that credentials are displayed only as masked values or status, never in plaintext.
4. In Resource Hub, create a resource of the corresponding type and confirm that the resource selector displays only connections with matching Access scope and a successful connection test.
5. Run one Import from Git preview using the target branch and confirm that the Commit, Manifest, and resource list can all be read.
6. If the repository is referenced by a resource, check the reference count before changing Access scope or deleting it. Do not perform an operation that would create an invalid binding while a valid binding exists.

13. Completion Criteria

• The Git Repository Connection is saved and the list shows the correct name, URL, default branch, authentication status, and access scope;
• Test connection succeeded;
• Access scope is one of Skill, Work, or Connector and matches the subsequent Resource Type;
• The target branch contains a valid Manifest and resource directory meeting the type-specific requirements;
• Resource Hub can complete a resource preview or first import through the connection;
• The first-import Commit matches the preview Commit, and file count and size are within limits;
• Credentials are stored securely and displayed in masked form, and have not been written to ordinary documents or resource content;
• Published resource versions are not modified in place by later Git synchronization.