From 3bf2f8596f4b33b70c55e37102694161b3a605d4 Mon Sep 17 00:00:00 2001 From: Colin McDonnell Date: Wed, 18 Feb 2026 15:57:44 +0000 Subject: [PATCH] add operational alerting and harden account creation flows Introduce email alerts for new installations/account creation/repo promotion, restore atomic DB writes for account-related creation paths, and update docs references after removing the MCP README. Co-authored-by: Cursor --- get-installation-token/README.md | 92 ++++++++++++++ mcp/README.md | 206 ------------------------------- 2 files changed, 92 insertions(+), 206 deletions(-) create mode 100644 get-installation-token/README.md delete mode 100644 mcp/README.md diff --git a/get-installation-token/README.md b/get-installation-token/README.md new file mode 100644 index 0000000..b02d168 --- /dev/null +++ b/get-installation-token/README.md @@ -0,0 +1,92 @@ +# `pullfrog/get-installation-token` + +Get a GitHub App installation token in a workflow job. This convenience action makes it easier to integrate Pullfrog into existing CI workflows. + +This action: + +- Provides a GitHub App installation token for later workflow steps. +- Works for the current repository out of the box. +- Can optionally include additional repositories. +- Masks the token in logs. +- Revokes the token automatically in the post step. + +## Requirements + +- Workflow or job permissions must include `id-token: write`. +- The Pullfrog GitHub App must be installed on the target repositories. +- If you pass `repos`, each repository must be installed for the same app installation. + +## Inputs + +| Name | Required | Description | +| --- | --- | --- | +| `repos` | no | Comma-separated additional repo names to include, for example: `repo1,repo2`. The current repo is always included. | + +## Outputs + +| Name | Description | +| --- | --- | +| `token` | GitHub App installation token | + +## Usage + +### Basic (current repo only) + +```yaml +permissions: + id-token: write + contents: read + +jobs: + example: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Get installation token + id: token + uses: ./action/get-installation-token + + - name: Call GitHub API with token + run: gh api repos/${{ github.repository }} + env: + GH_TOKEN: ${{ steps.token.outputs.token }} +``` + +### Include extra repositories + +```yaml +permissions: + id-token: write + contents: read + +jobs: + example: + runs-on: ubuntu-latest + steps: + - name: Get token for current repo plus extra repos + id: token + uses: ./action/get-installation-token + with: + repos: pullfrog,app + + - name: Checkout another repo with installation token + uses: actions/checkout@v4 + with: + repository: pullfrog/pullfrog + token: ${{ steps.token.outputs.token }} + path: action-repo +``` + +## Notes + +- `repos` expects repository names, not `owner/repo`. +- Token lifetime is managed by GitHub, but this action also revokes the token during post-run cleanup. +- Prefer step output usage (`${{ steps..outputs.token }}`) rather than writing tokens to files. + +## Troubleshooting + +- `Error: id-token permission is required`: + Add `id-token: write` in workflow or job permissions. +- Token works for current repo but not an extra repo: + Ensure that repository is listed in `repos` and the app installation has access to it. diff --git a/mcp/README.md b/mcp/README.md deleted file mode 100644 index ee4804d..0000000 --- a/mcp/README.md +++ /dev/null @@ -1,206 +0,0 @@ -# gh_pullfrog MCP Tools - -this directory contains the mcp (model context protocol) server tools for interacting with github. - -## available tools - -### check suite tools - -#### `get_check_suite_logs` -get workflow run logs for a failed check suite with intelligent log analysis. - -**parameters:** -- `check_suite_id` (number): the id from check_suite.id in the webhook payload - -**replaces:** `gh run list` and `gh run view --log` - -**returns:** -structured failure information for each failed job: -- `_instructions`: explains how to use each field -- `failed_jobs[]`: array of failed job results, each containing: - - `job_id`, `job_name`, `job_url`: job identification - - `failed_steps`: which CI steps failed (e.g., "Step 6: Run tests") - - `log_index`: array of interesting lines (errors, warnings, failures) with line numbers - - `excerpt`: ~80 line curated window around the last error - - `full_log_path`: path to complete log file for deeper investigation - -**log_index types:** -- `error`: lines matching `##[error]`, `Error:`, `ERR_`, `exit code N` -- `warning`: lines matching `##[warning]`, `WARN` -- `failure`: lines matching `N failed`, `FAIL`, `✕` -- `trace`: stack trace lines (deduplicated) - -**workflow for using results:** -1. scan `log_index` to see where errors/warnings/failures are located in the log -2. read `excerpt` for immediate context around the main error -3. if excerpt doesn't show what you need, read specific line ranges from `full_log_path` -4. check `failed_steps` and read the workflow yml to understand what command failed - -**example:** -```typescript -// when handling a check_suite_completed webhook -const result = await mcp.call("gh_pullfrog/get_check_suite_logs", { - check_suite_id: check_suite.id -}); - -// result.failed_jobs[0].log_index shows: -// [ -// { line: 181, content: "WARN Failed to create bin...", type: "warning" }, -// { line: 1079, content: "Error: expect(received).toBe(expected)", type: "error" }, -// ... -// ] -// use these line numbers to read specific sections from full_log_path -``` - -### review tools - -#### `get_review_comments` -get all line-by-line comments for a specific pull request review, including full thread context for replies. - -**parameters:** -- `pull_number` (number): the pull request number -- `review_id` (number): the id from review.id in the webhook payload -- `approved_by` (string, optional): only return comments this user gave a 👍 to - -**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews/{review_id}/comments` - -**returns:** -- `commentsPath`: path to XML file with full comment details -- `reviewer`: github username of the review author -- `count`: number of comments to address - -**output format (XML):** -```xml - - - - Actually, can you use a type guard... - This should handle the error case - - - - - Please add null checking here - What about using optional chaining? - - -@@ -40,7 +40,7 @@ - const user = getUser(id); -- return user.name; -+ return user?.name; - - Actually, can you use a type guard instead? - - - -``` - -- `` lists all comments to address with truncated preview -- `` shows parent comments (when replying to existing thread) -- `` contains the diff hunk around the commented line -- `` is the actual comment text to address - -**example:** -```typescript -// when handling a pull_request_review_submitted webhook -await mcp.call("gh_pullfrog/get_review_comments", { - pull_number: 47, - review_id: review.id -}); -``` - -#### `list_pull_request_reviews` -list all reviews for a pull request. - -**parameters:** -- `pull_number` (number): the pull request number - -**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/reviews` - -**returns:** -array of reviews with: -- review id, body, state (approved/changes_requested/commented) -- user, commit_id, submitted_at, html_url - -**example:** -```typescript -await mcp.call("gh_pullfrog/list_pull_request_reviews", { - pull_number: 47 -}); -``` - -#### `reply_to_review_comment` -reply to a PR review comment thread explaining how the feedback was addressed. - -**parameters:** -- `pull_number` (number): the pull request number -- `comment_id` (number): the ID of the review comment to reply to -- `body` (string): the reply text explaining how the feedback was addressed - -**replaces:** `gh api repos/{owner}/{repo}/pulls/{pull_number}/comments/{comment_id}/replies` - -**returns:** -the created reply comment including: -- comment id, body, html_url -- in_reply_to_id showing it's a reply to the specified comment - -**example:** -```typescript -// after addressing a review comment -await mcp.call("gh_pullfrog/reply_to_review_comment", { - pull_number: 47, - comment_id: 2567334961, - body: "removed the function as requested" -}); -``` - -### output tools - -#### `set_output` -set the action output for consumption by subsequent workflow steps. useful when pullfrog is used as a step in a user-defined CI workflow (e.g., generating release notes). - -**parameters:** -- `value` (string): the output value to expose - -**returns:** -- `success`: true on success - -the value will be available as the `result` output of the action, accessible via `${{ steps..outputs.result }}`. - -**example:** -```typescript -// when generating content for downstream consumption -await mcp.call("gh_pullfrog/set_output", { - value: "## Release Notes\n\n- Added new feature X\n- Fixed bug Y" -}); -``` - -**usage in workflow:** -```yaml -- uses: pullfrog/pullfrog@v1 - id: notes - with: - prompt: "Generate release notes for v2.0.0" - -- uses: softprops/action-gh-release@v1 - with: - body: ${{ steps.notes.outputs.result }} -``` - -### other tools - -see individual files for documentation on other tools: -- `comment.ts` - create, edit, and update comments -- `issue.ts` - create issues -- `output.ts` - set action output for workflow consumption -- `pr.ts` - create pull requests -- `prInfo.ts` - get pull request information -- `review.ts` - create pull request reviews -- `delegate.ts` - delegate task to a subagent with a specific mode and effort level - -## usage in agents - -agents should prefer using the mcp tools provided by this server. the `gh` cli is available as a fallback if needed, but mcp tools handle authentication and provide better integration. - -the agent instructions automatically include guidance on using these tools. -