Skip to content

Commit fea4486

Browse files
shizhMSFTshizhMSFT
authored
docs: update release related docs (#28)
Signed-off-by: Shiwei Zhang <shizh@microsoft.com>
1 parent 1767c31 commit fea4486

2 files changed

Lines changed: 133 additions & 60 deletions

File tree

‎README.md‎

Lines changed: 112 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -1,60 +1,112 @@
1-
# ORAS MCP Server
2-
3-
## Usage
4-
5-
Configure the ORAS MCP Server to run inside [VS Code agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) for registry-aware chats.
6-
7-
The server is implemented with the [`oras-go`](https://github.com/oras-project/oras-go) library and does not depend on the [`oras`](https://github.com/oras-project/oras) CLI.
8-
9-
### Setup with Docker
10-
11-
It is easier to use docker to run the ORAS MCP Server.
12-
13-
#### Setup for VS Code
14-
15-
Add the following code to `.vscode/mcp.json`:
16-
17-
```json
18-
{
19-
"servers": {
20-
"oras-mcp-server": {
21-
"type": "stdio",
22-
"command": "docker",
23-
"args": [
24-
"run",
25-
"--rm",
26-
"-i",
27-
"ghcr.io/oras-project/oras-mcp:main",
28-
"serve"
29-
]
30-
}
31-
}
32-
}
33-
```
34-
35-
### Authentication
36-
37-
If you need to access private registries through the server, log in ahead of time using either the ORAS CLI or Docker:
38-
39-
- `oras login <registry>`
40-
- `docker login <registry>`
41-
42-
The server will reuse the credentials from your local credential store when available.
43-
44-
## Example Chats
45-
46-
Q: What platform does the image ghcr.io/oras-project/oras support?
47-
48-
A: The image `ghcr.io/oras-project/oras` supports the following platforms:
49-
50-
1. **Linux (amd64)**
51-
2. **Linux (arm64)**
52-
3. **Linux (arm, variant v7)**
53-
4. **Linux (s390x)**
54-
5. **Linux (ppc64le)**
55-
56-
Let me know if you need further details!
57-
58-
Q: What's the latest Azure Linux 3.0 image in MCR? Does it have a signature? What's the type of it?
59-
60-
A: The latest Azure Linux 3.0 image in the Microsoft Container Registry (MCR) is tagged as `3.0.20250402`. It has a signature, and the type of the signature is `application/vnd.cncf.notary.signature`.
1+
# ORAS MCP Server
2+
3+
## Usage
4+
5+
Configure the ORAS MCP Server to run inside [VS Code agent mode](https://code.visualstudio.com/docs/copilot/chat/chat-agent-mode) for registry-aware chats.
6+
7+
The server is implemented with the [`oras-go`](https://github.com/oras-project/oras-go) library and does not depend on the [`oras`](https://github.com/oras-project/oras) CLI.
8+
9+
### Setup with Docker
10+
11+
It is easier to use docker to run the ORAS MCP Server.
12+
13+
#### Setup for VS Code
14+
15+
Add the following code to `.vscode/mcp.json`:
16+
17+
```json
18+
{
19+
"servers": {
20+
"oras-mcp-server": {
21+
"type": "stdio",
22+
"command": "docker",
23+
"args": [
24+
"run",
25+
"--rm",
26+
"-i",
27+
"ghcr.io/oras-project/oras-mcp:main",
28+
"serve"
29+
]
30+
}
31+
}
32+
}
33+
```
34+
35+
##### Mount Docker credentials (Linux only)
36+
37+
Linux users can share `docker login` credentials by mounting the config file:
38+
39+
```json
40+
{
41+
"servers": {
42+
"oras-mcp-server": {
43+
"type": "stdio",
44+
"command": "docker",
45+
"args": [
46+
"run",
47+
"--rm",
48+
"-i",
49+
"-v",
50+
"${env:HOME}/.docker/config.json:/root/.docker/config.json:ro",
51+
"ghcr.io/oras-project/oras-mcp:main",
52+
"serve"
53+
]
54+
}
55+
}
56+
}
57+
```
58+
59+
Adjust the path if you keep credentials under `${env:DOCKER_CONFIG}`. The container understands only inline `auths` entries; helper-based configs (`credsStore`, `credHelpers`) won't work. On macOS/Windows, install the [released binary](#setup-from-released-binaries) instead.
60+
61+
### Setup from Released Binaries
62+
63+
1. Visit the [GitHub releases page](https://github.com/oras-project/oras-mcp/releases) and download the archive that matches your operating system and CPU architecture (`oras-mcp_<version>_<os>_<arch>.tar.gz` for Linux or macOS, `oras-mcp_<version>_windows_<arch>.zip` for Windows).
64+
2. Extract the archive; the folder contains a single executable named `oras-mcp` (or `oras-mcp.exe` on Windows) and a copy of the project license.
65+
3. Move the binary to a directory on your `PATH` (for example, `/usr/local/bin` on Linux/macOS or `%LOCALAPPDATA%\Programs\oras-mcp` on Windows) or reference it directly from its extracted location.
66+
4. Run `oras-mcp serve --help` (or `oras-mcp.exe serve --help`) to confirm the binary works on your system.
67+
5. To integrate with VS Code agent mode, update `.vscode/mcp.json` to point at the extracted binary:
68+
69+
```json
70+
{
71+
"servers": {
72+
"oras-mcp-server": {
73+
"type": "stdio",
74+
"command": "/absolute/path/to/oras-mcp",
75+
"args": [
76+
"serve"
77+
]
78+
}
79+
}
80+
}
81+
```
82+
83+
On Windows, set `"command": "C:/path/to/oras-mcp.exe"`.
84+
85+
### Authentication
86+
87+
`oras-mcp` reads credentials from the same stores used by the ORAS and Docker CLIs, but you need to expose those stores to the server process:
88+
89+
- **Released binary** – Run `oras login <registry>` or `docker login <registry>` on the host machine; the binary will pick up the cached credentials automatically.
90+
- **Docker container** – On Linux you can mount your Docker config as shown in the [credential section](#mount-docker-credentials-linux-only); ensure the file contains inline `auths` entries. Docker Desktop (macOS/Windows) depends on keychain helpers, so use the released binary there.
91+
92+
## Example Chats
93+
94+
Q: What platform does the image ghcr.io/oras-project/oras support?
95+
96+
A: The image `ghcr.io/oras-project/oras` supports the following platforms:
97+
98+
1. **Linux (amd64)**
99+
2. **Linux (arm64)**
100+
3. **Linux (arm, variant v7)**
101+
4. **Linux (s390x)**
102+
5. **Linux (ppc64le)**
103+
104+
Let me know if you need further details!
105+
106+
Q: What's the latest Azure Linux 3.0 image in MCR? Does it have a signature? What's the type of it?
107+
108+
A: The latest Azure Linux 3.0 image in the Microsoft Container Registry (MCR) is tagged as `3.0.20250402`. It has a signature, and the type of the signature is `application/vnd.cncf.notary.signature`.
109+
110+
## Release Process
111+
112+
Maintainers can find the full release steps in the [release checklist](./RELEASE_CHECKLIST.md).

‎RELEASE_CHECKLIST.md‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Release Checklist
2+
3+
## Overview
4+
5+
This document is for maintainers and describes the checklist to publish an `oras-mcp` release through the GitHub release page. After releasing, an updated multi-architecture container image will be pushed to `ghcr.io/oras-project/oras-mcp`.
6+
7+
## Release Process
8+
9+
1. Determine a [SemVer2](https://semver.org/)-valid version prefixed with `v` (for example, `v1.0.0` or `v1.1.0-rc.1`).
10+
2. Update `internal/version/version.go` with the new version and open a pull request that serves as the release vote. The commit in that PR is the one that will be tagged.
11+
3. Collect approvals and make sure CI for the PR is green. Once the vote passes, keep a note of the exact commit SHA that was reviewed.
12+
4. Merge the pull request using **Create a merge commit** so the voted commit stays intact in the target branch.
13+
5. In a clean working tree, check out the voted commit (not the merge commit) and create the release tag, then push it:
14+
- `git tag vX.Y.Z <commit-sha>`
15+
- `git push origin vX.Y.Z`
16+
6. (Optional) Cut off a `release-<major>.<minor>` branch on the tagged commit, but only when you are shipping a new minor version.
17+
7. Watch the `release-github.yml` and `release-ghcr.yml` workflows triggered by the new tag and wait for them to succeed.
18+
8. Validate the published image on GHCR by pulling and running a quick smoke test such as `docker run --rm ghcr.io/oras-project/oras-mcp:vX.Y.Z serve --help`.
19+
9. Polish the release notes (either in the PR description or a shared doc) and copy them into the GitHub release draft for `vX.Y.Z`.
20+
10. Publish the GitHub release once the notes are ready and validation is complete.
21+
11. Announce the release in the [#oras](https://cloud-native.slack.com/archives/CJ1KHJM5Z) Slack channel and close out any tracking items.

0 commit comments

Comments
 (0)