Skip to content
This repository was archived by the owner on Apr 22, 2026. It is now read-only.

Commit 5db0de7

Browse files
christian-anderssonchristian-andersson
committed
feat!: initial release
1 parent b772e61 commit 5db0de7

14 files changed

Lines changed: 1750 additions & 0 deletions

File tree

‎.github/workflows/docker-publish.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Release and Publish
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
8+
env:
9+
REGISTRY: ghcr.io
10+
IMAGE_NAME: ${{ github.repository }}
11+
12+
jobs:
13+
release:
14+
runs-on: ubuntu-latest
15+
permissions:
16+
contents: write
17+
packages: write
18+
19+
outputs:
20+
new_tag: ${{ steps.tag.outputs.new_tag }}
21+
changelog: ${{ steps.tag.outputs.changelog }}
22+
23+
steps:
24+
- name: Checkout repository
25+
uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1
26+
with:
27+
fetch-depth: 0
28+
29+
- name: Bump version and push tag
30+
id: tag
31+
uses: mathieudutour/github-tag-action@a22cf08638b34d5badda920f9daf6e72c477b07b # v6.2
32+
with:
33+
github_token: ${{ secrets.GITHUB_TOKEN }}
34+
default_bump: patch
35+
release_branches: main
36+
37+
- name: Create GitHub Release
38+
uses: softprops/action-gh-release@a06a81a03ee405af7f2048a818ed3f03bbf83c7b # v2.5.0
39+
with:
40+
tag_name: ${{ steps.tag.outputs.new_tag }}
41+
name: Release ${{ steps.tag.outputs.new_tag }}
42+
body: ${{ steps.tag.outputs.changelog }}
43+
generate_release_notes: true
44+
45+
- name: Log in to Container Registry
46+
uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
47+
with:
48+
registry: ${{ env.REGISTRY }}
49+
username: ${{ github.actor }}
50+
password: ${{ secrets.GITHUB_TOKEN }}
51+
52+
- name: Extract metadata (tags, labels)
53+
id: meta
54+
uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5.10.0
55+
with:
56+
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
57+
tags: |
58+
type=raw,value=latest,enable={{is_default_branch}}
59+
type=raw,value=${{ steps.tag.outputs.new_tag }}
60+
labels: |
61+
org.opencontainers.image.description=MCP server for GitHub Actions - lookup actions and get SHA-pinned references
62+
org.opencontainers.image.licenses=MIT
63+
64+
- name: Build and push Docker image
65+
uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
66+
with:
67+
context: .
68+
push: true
69+
tags: ${{ steps.meta.outputs.tags }}
70+
labels: ${{ steps.meta.outputs.labels }}

‎.gitignore‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# Environment
2+
.env
3+
.env.*
4+
5+
# IDE
6+
.idea
7+
.vscode
8+
*.swp
9+
*.swo
10+
11+
# Build artifacts
12+
github-actions-mcp
13+
14+
# OS
15+
.DS_Store
16+
Thumbs.db
17+
.claude/settings.local.json

‎.npmrc‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
registry=https://registry.npmjs.org/

‎Dockerfile‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
FROM denoland/deno:2.6.1
2+
3+
WORKDIR /app
4+
5+
# Copy all source files
6+
COPY deno.json deno.lock ./
7+
COPY main.ts ./
8+
COPY src/ ./src/
9+
10+
# Cache dependencies
11+
RUN deno cache main.ts
12+
13+
# Run as non-root user (deno user is provided by the base image)
14+
USER deno
15+
16+
# The MCP server uses stdio transport
17+
CMD ["deno", "run", "--allow-net", "--allow-env", "main.ts"]

‎README.md‎

Lines changed: 249 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,249 @@
1+
# MCP GitHub Actions
2+
3+
A Deno-based MCP (Model Context Protocol) service that helps you securely reference GitHub Actions by providing:
4+
5+
- Latest version lookup for any GitHub Action
6+
- Commit SHA retrieval for specific version tags
7+
- Immutability status checking for releases
8+
- Ready-to-use SHA-pinned references
9+
10+
## Why Use This?
11+
12+
GitHub Actions referenced by tag (e.g., `actions/checkout@v4`) can be vulnerable to supply chain attacks if the tag is moved to point to malicious code. This MCP service helps you:
13+
14+
1. **Find the commit SHA** for any action version
15+
2. **Check if a release is immutable** (protected from modification)
16+
3. **Get secure references** in the format `owner/repo@sha # version`
17+
18+
## Installation
19+
20+
### Prerequisites
21+
22+
- [Deno](https://deno.land/) 2.x or later
23+
24+
### Setup with Claude Desktop
25+
26+
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
27+
28+
```json
29+
{
30+
"mcpServers": {
31+
"github-actions": {
32+
"command": "deno",
33+
"args": [
34+
"run",
35+
"--allow-net",
36+
"--allow-env",
37+
"/path/to/mcp-github-actions/main.ts"
38+
],
39+
"env": {
40+
"GITHUB_TOKEN": "your-github-token-optional"
41+
}
42+
}
43+
}
44+
}
45+
```
46+
47+
### Setup with Claude Code CLI
48+
49+
```bash
50+
claude mcp add github-actions -- deno run --allow-net --allow-env /path/to/mcp-github-actions/main.ts
51+
```
52+
53+
### Setup with Docker
54+
55+
The service is available as a Docker image using stdio transport.
56+
57+
**Pull the image:**
58+
59+
```bash
60+
docker pull ghcr.io/tripletex/mcp-github-action:latest
61+
```
62+
63+
**Run directly:**
64+
65+
```bash
66+
docker run --rm -i -e GITHUB_TOKEN ghcr.io/tripletex/mcp-github-action:latest
67+
```
68+
69+
**Claude Desktop configuration:**
70+
71+
```json
72+
{
73+
"mcpServers": {
74+
"github-actions": {
75+
"command": "docker",
76+
"args": [
77+
"run",
78+
"--rm",
79+
"-i",
80+
"-e", "GITHUB_TOKEN",
81+
"ghcr.io/tripletex/mcp-github-action:latest"
82+
],
83+
"env": {
84+
"GITHUB_TOKEN": "your-github-token-optional"
85+
}
86+
}
87+
}
88+
}
89+
```
90+
91+
**MCP Gateway configuration:**
92+
93+
```yaml
94+
mcp_services:
95+
- name: "github-actions"
96+
alias: "github-actions"
97+
type: "stdio"
98+
command:
99+
- docker
100+
- run
101+
- --rm
102+
- -i
103+
- -e
104+
- GITHUB_TOKEN
105+
- ghcr.io/tripletex/mcp-github-action:latest
106+
timeout: 30
107+
```
108+
109+
## Usage
110+
111+
Once configured, ask Claude to look up GitHub Actions:
112+
113+
**Example prompts:**
114+
115+
- "Look up the latest version of actions/checkout"
116+
- "Get the secure reference for actions/setup-node@v4"
117+
- "Check if actions/cache@v4.2.0 is immutable"
118+
- "List all versions of actions/upload-artifact"
119+
120+
## Tool: `lookup_action`
121+
122+
### Parameters
123+
124+
| Parameter | Type | Required | Description |
125+
|-----------|------|----------|-------------|
126+
| `action` | string | Yes | Action reference (e.g., `actions/checkout` or `actions/checkout@v4`) |
127+
| `include_all_versions` | boolean | No | List all available versions (default: false) |
128+
129+
### Example Output
130+
131+
```
132+
Action: actions/checkout
133+
134+
Latest Version: v4.2.2
135+
Commit SHA: 11bd71901bbe5b1630ceea73d27597364c9af683
136+
Immutable: Yes
137+
Published: 2024-10-23T14:05:06Z
138+
139+
Recommended Usage (SHA-pinned):
140+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
141+
142+
Security Notes:
143+
- This release is immutable - the tag and assets are protected from modification.
144+
- SHA-pinned references prevent supply chain attacks by ensuring you always use the exact same code.
145+
```
146+
147+
## Authentication
148+
149+
### Without Token (Default)
150+
151+
- Works for public repositories only
152+
- Rate limit: 60 requests/hour
153+
154+
### With Token (Recommended)
155+
156+
Set the `GITHUB_TOKEN` environment variable:
157+
158+
- Works for **private repositories**
159+
- Rate limit: 5,000 requests/hour
160+
- Required for organization private actions
161+
162+
### Multi-Organization Support
163+
164+
For accessing private repositories across multiple organizations, configure org-specific tokens:
165+
166+
```bash
167+
# Org-specific tokens (format: GITHUB_TOKEN_<ORG_NAME>)
168+
# Hyphens in org names become underscores, all uppercase
169+
GITHUB_TOKEN_MY_ORG=ghp_xxx... # For My-Org
170+
GITHUB_TOKEN_OTHER_ORG=ghp_yyy... # For Other-Org
171+
GITHUB_TOKEN=ghp_zzz... # Fallback for public repos
172+
```
173+
174+
**Token resolution order:**
175+
1. Org-specific token (`GITHUB_TOKEN_<ORG>`)
176+
2. Fallback token (`GITHUB_TOKEN`)
177+
3. Unauthenticated (public repos only)
178+
179+
**Supported token types and required permissions:**
180+
181+
| Token Type | Required Permissions | Notes |
182+
|------------|---------------------|-------|
183+
| Fine-grained PAT | `Contents: Read` + `Metadata: Read` | Recommended - scoped to specific repos/orgs |
184+
| Classic PAT | `repo` scope | Broader access - use only if fine-grained isn't suitable |
185+
| GitHub App | `Contents: Read` | Recommended for organizations |
186+
187+
> **Note:** For private repositories, the token must have read access to repository contents. Without proper permissions, you'll receive a 404 error when looking up private actions.
188+
189+
**Example Claude Desktop config with multi-org:**
190+
191+
```json
192+
{
193+
"mcpServers": {
194+
"github-actions": {
195+
"command": "deno",
196+
"args": [
197+
"run",
198+
"--allow-net",
199+
"--allow-env",
200+
"/path/to/mcp-github-actions/main.ts"
201+
],
202+
"env": {
203+
"GITHUB_TOKEN_MY_ORG": "ghs_xxx...",
204+
"GITHUB_TOKEN_OTHER_ORG": "ghs_yyy...",
205+
"GITHUB_TOKEN": "ghp_zzz..."
206+
}
207+
}
208+
}
209+
}
210+
```
211+
212+
## Development
213+
214+
```bash
215+
# Run the server
216+
deno task start
217+
218+
# Run with watch mode (auto-reload)
219+
deno task dev
220+
221+
# Type check
222+
deno task check
223+
224+
# Lint
225+
deno task lint
226+
227+
# Format
228+
deno task fmt
229+
230+
# Compile to binary
231+
deno task compile
232+
```
233+
234+
## Security Best Practices
235+
236+
1. **Always use SHA-pinned references** in production workflows
237+
2. **Check immutability status** - immutable releases cannot be modified
238+
3. **Add version comments** for maintainability: `@sha # v4.2.0`
239+
4. **Use Dependabot/Renovate** to keep SHA references updated
240+
241+
## References
242+
243+
- [GitHub Immutable Releases](https://docs.github.com/en/code-security/supply-chain-security/understanding-your-software-supply-chain/immutable-releases)
244+
- [Pinning GitHub Actions for Security](https://www.stepsecurity.io/blog/pinning-github-actions-for-enhanced-security-a-complete-guide)
245+
- [Model Context Protocol](https://modelcontextprotocol.io/)
246+
247+
## License
248+
249+
MIT

‎deno.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "@mcp/github-actions",
3+
"version": "1.0.0",
4+
"exports": "./main.ts",
5+
"tasks": {
6+
"start": "deno run --allow-net --allow-env main.ts",
7+
"dev": "deno run --watch --allow-net --allow-env main.ts",
8+
"compile": "deno compile --allow-net --allow-env -o github-actions-mcp main.ts",
9+
"check": "deno check main.ts",
10+
"lint": "deno lint",
11+
"fmt": "deno fmt"
12+
},
13+
"imports": {
14+
"@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk@1.25.1",
15+
"zod": "npm:zod@3.25.76"
16+
},
17+
"compilerOptions": {
18+
"strict": true
19+
}
20+
}

0 commit comments

Comments
 (0)