Skip to content

Commit fb5b6f3

Browse files
aduminucaduminuc
authored
chore: fix readme (#3)
* fix license badge URL Signed-off-by: Alessandro Duminuco <aduminuc@cisco.com> * fix: typos and nits Signed-off-by: Alessandro Duminuco <aduminuc@cisco.com> * docs: fix dirctl docs in README Signed-off-by: Alessandro Duminuco <aduminuc@cisco.com> --------- Signed-off-by: Alessandro Duminuco <aduminuc@cisco.com>
1 parent b489d39 commit fb5b6f3

1 file changed

Lines changed: 28 additions & 94 deletions

File tree

‎README.md‎

Lines changed: 28 additions & 94 deletions
Original file line numberDiff line numberDiff line change
@@ -2,24 +2,20 @@
22

33
![GitHub Release (latest by date)](https://img.shields.io/github/v/release/outshift-open/agntcy-dir-push-action)
44
[![Tests](https://github.com/outshift-open/agntcy-dir-push-action/actions/workflows/test-signing-and-pushing.yml/badge.svg?branch=main)](https://github.com/outshift-open/agntcy-dir-push-action/actions/workflows/test-signing-and-pushing.yml)
5-
[![License](https://img.shields.io/github/license/outshift-open/open-ui-kit)](LICENSE.md)
5+
[![License](https://img.shields.io/github/license/outshift-open/agntcy-dir-push-action)](LICENSE.md)
66

7-
Push records to your [Agent Directory](https://agent-directory.outshift.com) using the [dirctl CLI](https://github.com/agntcy/dir).
7+
Push [OASF](https://github.com/agntcy/oasf) records to the [Hosted Outshift Agent Directory](https://agent-directory.outshift.com) using the [dirctl CLI](https://github.com/agntcy/dir).
88

99
## How It Works
1010

11-
The action prepares the `dirctl` CLI for your runner's environment and **processes your record file**, applying any specified overrides for organization, name, or version. It then smartly **handles the record's signature** before **pushing the final version** to your specified Agent Directory.
11+
This GitHub Action streamlines the process of publishing your AI agents to the Agent Directory. Features:
1212

13-
14-
## Features
15-
16-
- **Downloads** the correct `dirctl` binary for your runner's OS and architecture.
17-
- **Pushes** records that are already signed.
18-
- **Signs** unsigned records on-the-fly using a provided Cosign key.
19-
- Re-signs an already signed record with a new key
20-
- Dynamically **overrides** `organization_name`, `record_name`, and `record_version` at runtime.
21-
- Uses GitHub **secrets** for API keys and signing credentials
22-
- Automatically provides GitHub action **artifacts** for easy troubleshooting.
13+
* **Environment Setup**: Automatically downloads and configures the correct `dirctl` CLI binary for your runner's operating system and architecture
14+
* **Record Processing**: Reads your agent record file and applies any runtime overrides you've specified (organization name, record name, or version)
15+
* **Smart Signing**: Intelligently handles record signatures - whether your record is already signed, needs signing with your provided Cosign key, or requires re-signing with a new key
16+
* **Secure Publishing**: Pushes the final, processed record to Agent Directory using authenticated API credentials
17+
* **Secret Handling** Uses GitHub secrets for API keys and signing credentials.
18+
* **Troubleshooting** Automatically provides GitHub action artifacts for easy troubleshooting.
2319

2420
## Supported Platforms
2521

@@ -37,7 +33,7 @@ You'll need **API Key credentials** for your Agent Directory instance. Follow th
3733
dirctl hub login
3834
```
3935

40-
2. **Create an API key for your organization:**
36+
1. **Create an API key for your organization:**
4137
```bash
4238
dirctl hub apikey create --role ROLE_ORG_ADMIN --org-name your_org_name
4339
```
@@ -49,24 +45,13 @@ You'll need **API Key credentials** for your Agent Directory instance. Follow th
4945
- `ROLE_VIEWER` - Read-only access
5046

5147

52-
> **Important**: The `name` field in your directory record file must always be in the format `"my-org/my-record"`. The organization part (`my-org`) must match the `--org-name` used to create the API key. If they differ, use the `organization_name` input to override it.
53-
54-
3. **Extract the credentials:**
55-
56-
The command will output your `client_id`:
48+
The command will output both client id and secret:
5749
```
58-
API Key created successfully:
59-
{
60-
"client_id": "abcd1234-56ef-78gh-90ij-klmnopqrstuv@ak.example.io",
61-
"role_name": "ROLE_ORG_ADMIN"
62-
}
50+
DIRCTL_CLIENT_ID=3603e7f1-6903-44ec-868e-b78fab3cf43f@ak.eticloud.io
51+
DIRCTL_CLIENT_SECRET=*********************************************
6352
```
6453

65-
The `secret` (base64 encoded) can be found in your session file:
66-
- Location: `~/.dirctl/session.json`
67-
- Path: `[hub_sessions][your-directory-url][api_key_access][secret]`
68-
69-
4. **Add them as GitHub secrets in your repository:**
54+
1. **Add them as GitHub secrets in your repository:**
7055

7156
Create secrets with any names you prefer, for example:
7257
- `AGENT_DIRECTORY_CLIENT_ID`
@@ -89,13 +74,16 @@ your-private-key-content-here
8974
-----END ENCRYPTED SIGSTORE PRIVATE KEY-----
9075
```
9176

92-
>**Note:** You can sign the record with `dirctl` **locally** by exectuting:\
77+
>**Note:** You can sign the record with `dirctl` **locally** by executing:\
9378
> `cat your-record.json | dirctl hub sign --stdin --key cosign.key > signed-record.json`
9479
9580
### Directory Record File
9681

9782
Your directory record JSON file **must be present in your repository**. You can place it anywhere in your repository structure (e.g., `./records/my-record.json`).
9883

84+
> **Important**: The `name` field in your directory record file must always be in the format `"my-org/my-record"`. The organization part (`my-org`) must match the `--org-name` used to create the API key. If they differ, use the `organization_name` input to override it.
85+
86+
9987
## Override Behavior
10088

10189
The action supports overriding specific fields in your **record file** by providing the following inputs to the GitHub action:
@@ -116,7 +104,7 @@ Override Example:
116104

117105
## Usage Examples
118106

119-
**Runner Compatibility:** This action works on any GitHub Actions runner. The examples below use `ubuntu-latest`, but you can use `macos-latest`, `apline-latest`, or any other runner. The action automatically downloads the appropriate dirctl binary.
107+
**Runner Compatibility:** This action works on any GitHub Actions runner. The examples below use `ubuntu-latest`, but you can use `macos-latest`, `alpine-latest`, or any other runner. The action automatically downloads the appropriate dirctl binary.
120108

121109
### Basic Usage (Pre-signed Record)
122110

@@ -129,7 +117,7 @@ jobs:
129117
steps:
130118
- uses: actions/checkout@v4
131119
- name: Push Directory Record
132-
uses: your-org/agent-directory-actions@v1
120+
uses: outshift-open/agntcy-dir-push-action@v1
133121
with:
134122
dirctl_client_id: ${{ secrets.AGENT_DIRECTORY_CLIENT_ID }}
135123
dirctl_secret: ${{ secrets.AGENT_DIRECTORY_SECRET }}
@@ -147,7 +135,7 @@ jobs:
147135
steps:
148136
- uses: actions/checkout@v4
149137
- name: Push Signed Directory Record
150-
uses: your-org/agent-directory-actions@v1
138+
uses: outshift-open/agntcy-dir-push-action@v1
151139
with:
152140
dirctl_client_id: ${{ secrets.MY_CLIENT_ID }}
153141
dirctl_secret: ${{ secrets.MY_SECRET }}
@@ -167,7 +155,7 @@ jobs:
167155
steps:
168156
- uses: actions/checkout@v4
169157
- name: Push Record with Custom Values
170-
uses: your-org/agent-directory-actions@v1
158+
uses: outshift-open/agntcy-dir-push-action@v1
171159
with:
172160
dirctl_client_id: ${{ secrets.DIRECTORY_CLIENT }}
173161
dirctl_secret: ${{ secrets.DIRECTORY_SECRET }}
@@ -189,7 +177,7 @@ jobs:
189177
steps:
190178
- uses: actions/checkout@v4
191179
- name: Push to Custom Directory
192-
uses: your-org/agent-directory-actions@v1
180+
uses: outshift-open/agntcy-dir-push-action@v1
193181
with:
194182
directory_endpoint: "https://my-custom-directory.example.com"
195183
dirctl_client_id: ${{ secrets.CUSTOM_DIRECTORY_CLIENT_ID }}
@@ -210,62 +198,8 @@ jobs:
210198
| `record_version` | Override the version in the record file | No | - |
211199
| `cosign_private_key` | Cosign private key content for signing | No | - |
212200
| `cosign_private_key_password` | Password for encrypted cosign private key | No | - |
213-
| `dirctl_version` | Version of dirctl to download and use | No | `v0.2.12` |
214-
215-
## Directory Record File Format
216-
217-
Your directory record file should be a JSON file stored in your repository following this structure:
218-
219-
```json
220-
{
221-
"name": "organization/record-name",
222-
"version": "1.0.0",
223-
"description": "Description of your AI agent",
224-
"schema_version": "0.7.0",
225-
"skills": [
226-
{
227-
"class_uid": 10201
228-
}
229-
],
230-
"locators": [
231-
{
232-
"type": "package-source-code",
233-
"url": "https://github.com/example/my-record"
234-
}
235-
]
236-
}
237-
```
201+
| `dirctl_version` | Version of dirctl to download and use | No | `v0.3.0` |
238202

239-
### With Existing Signature (Example)
240-
241-
If your record is already signed, include the signature block:
242-
243-
```json
244-
{
245-
"name": "organization/record-name",
246-
"version": "1.0.0",
247-
"description": "Description of your AI agent",
248-
"schema_version": "0.7.0",
249-
"skills": [
250-
{
251-
"class_uid": 10201
252-
}
253-
],
254-
"locators": [
255-
{
256-
"type": "package-source-code",
257-
"url": "https://github.com/example/my-record"
258-
}
259-
],
260-
"signature": {
261-
"algorithm": "SHA2_256",
262-
"signature": "abcdef123456789example0123456789abcdef123456789example0123456789abcd",
263-
"content_type": "application/vnd.dev.sigstore.bundle.v0.3+json",
264-
"content_bundle": "CoNtEnTbUnDlE...",
265-
"signed_at": "2025-01-02T03:04:05Z"
266-
}
267-
}
268-
```
269203

270204
## Error Handling
271205

@@ -317,7 +251,7 @@ If you receive an error during push, it might be due to organization mismatch:
317251
1. **Override the organization** in your workflow:
318252
```yaml
319253
- name: Push Directory Record
320-
uses: your-org/agent-directory-actions@v1
254+
uses: outshift-open/agntcy-dir-push-action@v1
321255
with:
322256
dirctl_client_id: ${{ secrets.AGENT_DIRECTORY_CLIENT_ID }}
323257
dirctl_secret: ${{ secrets.AGENT_DIRECTORY_SECRET }}
@@ -347,7 +281,7 @@ If you receive a `unique constraint` error, it means you are trying to push a re
347281
1. **Update** the record **version** either by modifying the `version` field in your **record file** before pushing, or by **overriding it dynamically** in your **workflow**:
348282
```yaml
349283
- name: Push record with updated version
350-
uses: your-org/agent-directory-actions@v1
284+
uses: outshift-open/agntcy-dir-push-action@v1
351285
with:
352286
dirctl_client_id: ${{ secrets.AGENT_DIRECTORY_CLIENT_ID }}
353287
dirctl_secret: ${{ secrets.AGENT_DIRECTORY_SECRET }}
@@ -358,7 +292,7 @@ If you receive a `unique constraint` error, it means you are trying to push a re
358292
2. **Change** the record **name** either in the record **file** or dynamically with the `record_name` **input**:
359293
```yaml
360294
- name: Push record with updated name
361-
uses: your-org/agent-directory-actions@v1
295+
uses: outshift-open/agntcy-dir-push-action@v1
362296
with:
363297
dirctl_client_id: ${{ secrets.AGENT_DIRECTORY_CLIENT_ID }}
364298
dirctl_secret: ${{ secrets.AGENT_DIRECTORY_SECRET }}
@@ -373,7 +307,7 @@ If you receive a `unique constraint` error, it means you are trying to push a re
373307
- **Pre-signed record pushing** - Validates pushing records that are already signed
374308
- **On-the-fly signing** - Tests signing during the push process
375309
- **Re-signing behavior** - Tests re-signing already signed records
376-
- **Diffenent Organization** - Tests API Key not belonging to the correct organization
310+
- **Different Organization** - Tests API Key not belonging to the correct organization
377311

378312
> **Note:** The test workflow (`.github/workflows/test-signing-and-pushing.yml`) can be triggered manually by providing the `record_version`.
379313

0 commit comments

Comments
 (0)