Skip to content

Commit 7644639

Browse files
christosgkorosclaude
christosgkoros
and
claude
authored
chore: rework contribution policy to issue-first, with CI enforcement (#188)
CONTRIBUTING.md invited pull requests we can never merge. Its "Safe to edit (PRs welcome directly)" list named paths the sync overwrites -- every entry on it except the generated tool files. PR #138's hand-written unit tests were rewritten three commits after merge. Two mechanical traps compounded it: fork CI could not go green (test.yml passed a secret that is empty for forks, and direct.test.ts spawned the real server with no guard), and the documented `pnpm build && pnpm test && pnpm lint` chain hung because `pnpm test` is bare vitest in watch mode. Reframe the guide around issues as the primary contribution path, keep docs and repository tooling genuinely mergeable, and enforce the boundary in CI. Docs - Rewrite CONTRIBUTING.md: state once that tool definitions and the server implementation are synced from Postman's internal source of truth, then spend the document on what contributors can do. Replace the wrong "safe to edit" list with an open-vs-synced table. Correct the test commands, tell people not to run `pnpm build` (it recompiles the committed dist/), and add the missing --learn flag. - Extract SECURITY.md and CODE_OF_CONDUCT.md to root files so GitHub surfaces them; add SUPPORT.md to route usage questions away from the bug tracker. - Add a Contributing section to README.md, which never linked CONTRIBUTING.md. Enforcement - .github/synced-paths.json as the single source of truth, so the docs and the workflow cannot drift. - synced-paths-guard.yml comments once on fork PRs touching synced paths, applies a `synced-path` label, and retracts both if the PR is split. Uses pull_request_target with no checkout of PR-head code and reads its config from the base commit; actions/github-script only, no third-party actions. Advisory, not blocking. - Issue forms for bug reports, tool requests, and docs, each with a Proposed solution field so design proposals keep flowing in. Blank issues disabled. - A PR template that asks about synced paths up front. CI and tooling - Split test.yml into a fork-safe `unit` job (lint, typecheck, unit tests, no secrets) and an `integration` job gated on same-repo PRs and pushes. Add permissions: contents: read and --frozen-lockfile. - Add test:ci, test:unit, and typecheck scripts. - Guard direct.test.ts on POSTMAN_API_KEY. describe.skipIf alone was not enough: the suite imports PostmanAPIClient, which imports src/env.ts, which calls process.exit(1) at module load -- before skipIf can skip anything. Make that one import lazy so the guard works. `vitest run` now passes with no key (2 passed, 2 skipped). This file is synced, so the same change needs to land upstream to survive; test.yml is what keeps fork CI green regardless. - Untrack .idea/workspace.xml, which exposed a maintainer's local path, and extend .gitignore to cover editor and local agent config. Refs PSTAPI-1647 Co-authored-by: Claude <noreply@anthropic.com>
1 parent b361515 commit 7644639

17 files changed

Lines changed: 927 additions & 226 deletions

‎.github/ISSUE_TEMPLATE/bug_report.yml‎

Lines changed: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
name: Bug report — tool or server behavior
2+
description: A tool returns the wrong result, a schema or description is wrong, or the server misbehaves.
3+
labels: ["bug", "needs-triage"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for reporting this. Bug reports with a clean reproduction are the single
9+
most useful contribution to this project — they're how tool fixes actually get
10+
made.
11+
12+
There's an optional **Proposed solution** field at the bottom. If you already
13+
know what the fix should be, please use it.
14+
15+
⚠️ **Never paste a Postman API key, token, or private collection contents into a
16+
public issue.** Redact anything sensitive, and rotate keys that may have been
17+
exposed.
18+
19+
- type: dropdown
20+
id: server
21+
attributes:
22+
label: Which server are you using?
23+
options:
24+
- Local (npx / STDIO)
25+
- Local (Docker)
26+
- Local (.mcpb bundle)
27+
- Remote (mcp.postman.com)
28+
- Not sure
29+
validations:
30+
required: true
31+
32+
- type: input
33+
id: version
34+
attributes:
35+
label: Version
36+
description: For the local server, the version you installed. For the remote server, enter "remote".
37+
placeholder: 2.11.2
38+
validations:
39+
required: true
40+
41+
- type: dropdown
42+
id: toolset
43+
attributes:
44+
label: Toolset
45+
description: Which toolset flag did you start the server with?
46+
options:
47+
- minimal (default)
48+
- code
49+
- full
50+
- learn
51+
- Not sure
52+
validations:
53+
required: true
54+
55+
- type: input
56+
id: client
57+
attributes:
58+
label: MCP client or host
59+
placeholder: Claude Code 2.x, Claude Desktop, Cursor, VS Code Copilot, Windsurf, Gemini CLI…
60+
validations:
61+
required: true
62+
63+
- type: input
64+
id: tool
65+
attributes:
66+
label: Tool name
67+
description: If the problem is with one specific tool.
68+
placeholder: createCollection
69+
validations:
70+
required: false
71+
72+
- type: dropdown
73+
id: region
74+
attributes:
75+
label: Region
76+
options:
77+
- us (default)
78+
- eu
79+
validations:
80+
required: false
81+
82+
- type: textarea
83+
id: what-happened
84+
attributes:
85+
label: What happened?
86+
validations:
87+
required: true
88+
89+
- type: textarea
90+
id: expected
91+
attributes:
92+
label: What did you expect to happen?
93+
validations:
94+
required: true
95+
96+
- type: textarea
97+
id: repro
98+
attributes:
99+
label: Steps to reproduce
100+
description: |
101+
Include the prompt you gave your agent as well as the tool arguments, if you have
102+
them — MCP behavior often depends on how the tool was invoked.
103+
placeholder: |
104+
1. Started the server with `--full`
105+
2. Asked the agent: "..."
106+
3. It called `createCollection` with { ... }
107+
4. Got ...
108+
validations:
109+
required: true
110+
111+
- type: textarea
112+
id: output
113+
attributes:
114+
label: Request, response, or error output
115+
description: Redact keys, tokens, IDs, and anything private.
116+
render: text
117+
validations:
118+
required: false
119+
120+
- type: textarea
121+
id: proposed-solution
122+
attributes:
123+
label: Proposed solution
124+
description: |
125+
Already know what the fix should be? Describe it here — a schema change, a
126+
corrected description, a code snippet, whatever you have. The server
127+
implementation is synced from Postman's internal source of truth, so an issue is
128+
the place where a proposed fix can actually be acted on. We credit contributions
129+
that ship.
130+
validations:
131+
required: false
132+
133+
- type: input
134+
id: environment
135+
attributes:
136+
label: OS and Node version
137+
placeholder: macOS 15.1, Node 20.11.0
138+
validations:
139+
required: false
140+
141+
- type: checkboxes
142+
id: checks
143+
attributes:
144+
label: Before you submit
145+
options:
146+
- label: I searched the existing issues and this isn't a duplicate.
147+
required: true
148+
- label: This is not a security vulnerability (those go through [SECURITY.md](https://github.com/postmanlabs/postman-mcp-server/blob/main/SECURITY.md)).
149+
required: true
150+
- label: I haven't included any API keys, tokens, or private data.
151+
required: true

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
blank_issues_enabled: false
2+
contact_links:
3+
- name: Question about using the Postman MCP Server
4+
url: https://community.postman.com/
5+
about: Ask the Postman Community — the fastest way to get help with setup, MCP clients, and workflows.
6+
- name: Postman MCP Server documentation
7+
url: https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/overview/
8+
about: Installation guides, client configuration, and tool reference.
9+
- name: Postman account, billing, or platform support
10+
url: https://support.postman.com/
11+
about: For your Postman account or the Postman API itself, rather than this server.
12+
- name: Report a security vulnerability
13+
url: https://github.com/postmanlabs/postman-mcp-server/security/advisories/new
14+
about: Please don't open a public issue for security reports. See SECURITY.md.

‎.github/ISSUE_TEMPLATE/docs_issue.yml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
name: Documentation issue
2+
description: Something in the docs is wrong, unclear, or missing.
3+
labels: ["documentation", "needs-triage"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Documentation in this repository **accepts pull requests directly** — if you
9+
already know the fix, feel free to skip this form and
10+
[open a PR](https://github.com/postmanlabs/postman-mcp-server/compare) instead.
11+
12+
Otherwise, tell us what's wrong and we'll sort it out.
13+
14+
- type: dropdown
15+
id: where
16+
attributes:
17+
label: Where is the problem?
18+
options:
19+
- README.md
20+
- CONTRIBUTING.md
21+
- DOCKER.md
22+
- SECURITY.md / SUPPORT.md / CODE_OF_CONDUCT.md
23+
- Issue or PR templates
24+
- Tool descriptions (shown to the agent)
25+
- learning.postman.com
26+
- Other
27+
validations:
28+
required: true
29+
30+
- type: input
31+
id: location
32+
attributes:
33+
label: Page, file, or URL
34+
placeholder: README.md — "Quick start" section
35+
validations:
36+
required: false
37+
38+
- type: textarea
39+
id: problem
40+
attributes:
41+
label: What's wrong or missing?
42+
validations:
43+
required: true
44+
45+
- type: textarea
46+
id: suggestion
47+
attributes:
48+
label: Suggested wording
49+
description: Optional, but it's the fastest route to a fix.
50+
validations:
51+
required: false
52+
53+
- type: checkboxes
54+
id: offer
55+
attributes:
56+
label: Would you like to fix it?
57+
options:
58+
- label: I'd like to open a pull request for this.
59+
required: false

‎.github/ISSUE_TEMPLATE/tool_request.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Feature or tool request
2+
description: Request a new tool, or a change to an existing tool's schema, parameters, or description.
3+
labels: ["enhancement", "needs-triage"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Tool definitions are synced from Postman's internal source of truth, so this issue
9+
is exactly the right place for this — it's how new and changed tools get proposed.
10+
11+
The more precise your proposal, the more likely it lands close to verbatim. We
12+
credit contributions that ship.
13+
14+
- type: dropdown
15+
id: kind
16+
attributes:
17+
label: What kind of change?
18+
options:
19+
- New tool
20+
- Change to an existing tool's schema or parameters
21+
- Change to a tool's description
22+
- Toolset composition (minimal / code / full / learn)
23+
- Server behavior or CLI flag
24+
- Other
25+
validations:
26+
required: true
27+
28+
- type: input
29+
id: tools
30+
attributes:
31+
label: Tool(s) affected
32+
placeholder: getCollection, createCollection
33+
validations:
34+
required: false
35+
36+
- type: textarea
37+
id: problem
38+
attributes:
39+
label: Problem or use case
40+
description: What are you trying to do with your agent, and what's in the way?
41+
validations:
42+
required: true
43+
44+
- type: textarea
45+
id: proposal
46+
attributes:
47+
label: Proposed behavior
48+
description: |
49+
Be specific: exact parameter names, enum values, which fields are required or
50+
optional, and the description text you'd want. Precise proposals often land
51+
as written.
52+
validations:
53+
required: true
54+
55+
- type: textarea
56+
id: proposed-solution
57+
attributes:
58+
label: Proposed solution
59+
description: |
60+
If you've already worked out the implementation — a schema shape, a code snippet,
61+
a description rewrite — put it here. An issue is where a proposed change can
62+
actually be acted on.
63+
validations:
64+
required: false
65+
66+
- type: textarea
67+
id: alternatives
68+
attributes:
69+
label: Alternatives or workarounds you've tried
70+
validations:
71+
required: false
72+
73+
- type: input
74+
id: client
75+
attributes:
76+
label: MCP client or host
77+
placeholder: Claude Code, Cursor, VS Code Copilot…
78+
validations:
79+
required: false
80+
81+
- type: checkboxes
82+
id: checks
83+
attributes:
84+
label: Before you submit
85+
options:
86+
- label: I searched the existing issues and this isn't a duplicate.
87+
required: true
88+
- label: This is not a security vulnerability (those go through [SECURITY.md](https://github.com/postmanlabs/postman-mcp-server/blob/main/SECURITY.md)).
89+
required: true

‎.github/PULL_REQUEST_TEMPLATE.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
<!-- Thanks for contributing! Documentation and repository tooling PRs are merged directly. -->
2+
3+
## What does this change?
4+
5+
<!-- One or two sentences. Link the issue: Closes #123 -->
6+
7+
## Type of change
8+
9+
- [ ] Documentation (README, CONTRIBUTING, DOCKER, SECURITY, issue/PR templates)
10+
- [ ] Repository tooling (workflows, Dockerfile, lint/format config, manifests)
11+
- [ ] Release plumbing
12+
- [ ] Other (please explain)
13+
14+
## Synced-path check
15+
16+
Files under `src/` and `dist/` are synced from Postman's internal source of truth, so
17+
changes to them can't be merged here — they would be overwritten on the next sync. The
18+
authoritative list is [`.github/synced-paths.json`](./.github/synced-paths.json).
19+
20+
- [ ] This PR does **not** change anything under `src/` or `dist/`.
21+
22+
If it does, please open an issue instead — that's where those changes get made, and we
23+
credit contributions that ship:
24+
[Bug report](../../issues/new?template=bug_report.yml) ·
25+
[Tool request](../../issues/new?template=tool_request.yml)
26+
27+
## Checklist
28+
29+
- [ ] One focused change
30+
- [ ] Branched off the latest `main`, no conflicts
31+
- [ ] Conventional Commits title (`fix:`, `feat:`, `docs:`, `chore:`, …)
32+
- [ ] `pnpm lint`, `pnpm typecheck`, and `pnpm test:unit` pass locally
33+
- [ ] No `dist/` files in the diff — don't run `pnpm build` for a contribution, it
34+
recompiles the committed `dist/` and creates a large unrelated diff

‎.github/synced-paths.json‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"$comment": "Authoritative list of paths synced from Postman's internal source of truth. Changes to these paths can't be merged in this repository. Referenced by CONTRIBUTING.md and .github/workflows/synced-paths-guard.yml. Entries ending in '/' match a whole directory tree; other entries match an exact path.",
3+
"synced": [
4+
"src/",
5+
"dist/",
6+
"vitest.config.ts"
7+
],
8+
"exceptions": [],
9+
"policyUrl": "https://github.com/postmanlabs/postman-mcp-server/blob/main/CONTRIBUTING.md#how-this-repo-works"
10+
}

0 commit comments

Comments
 (0)