From 2e7b7de2c2932c466e7153de4321395dc3791dfb Mon Sep 17 00:00:00 2001 From: Fabio Wakim Trentini Date: Fri, 12 Jun 2026 14:41:37 -0300 Subject: [PATCH 1/2] docs(ci): add canonical Iris PR workflow with contents:read MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Consuming repos copied an iris.yml whose permissions block only granted pull-requests:write. Declaring any permission sets unlisted ones to none, so actions/checkout failed on private repos with "Repository not found". Establish a canonical, correct source so future repos start right: - .github/actions/iris-pr/example-workflow.yml — copyable workflow with both contents:read and pull-requests:write - .github/actions/iris-pr/README.md — action usage, the permissions gotcha, and inputs - README.md — link the template from the PR Analysis section Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/actions/iris-pr/README.md | 70 ++++++++++++++++++++ .github/actions/iris-pr/example-workflow.yml | 25 +++++++ README.md | 13 ++++ 3 files changed, 108 insertions(+) create mode 100644 .github/actions/iris-pr/README.md create mode 100644 .github/actions/iris-pr/example-workflow.yml diff --git a/.github/actions/iris-pr/README.md b/.github/actions/iris-pr/README.md new file mode 100644 index 0000000..d64228c --- /dev/null +++ b/.github/actions/iris-pr/README.md @@ -0,0 +1,70 @@ +# Iris PR Insights — GitHub Action + +Analyze a pull request with Iris and post AI-aware engineering insights as a PR +comment, automatically, on every PR. + +## Setup + +Copy this workflow into the consuming repository as +`.github/workflows/iris.yml`: + +```yaml +name: Iris PR Insights + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + iris-pr: + name: Iris PR Analysis + runs-on: ubuntu-latest + permissions: + contents: read # required: actions/checkout reads the repo + pull-requests: write # required: post the insights comment + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # full history → churn / cascade context + + - uses: RocketBus/clickbus-iris/.github/actions/iris-pr@main +``` + +## Important: the `permissions` block + +The moment you declare a `permissions:` block, **every permission you do not +list is set to `none`** — not the default `read`. Iris needs both: + +- `contents: read` — without it, `actions/checkout` cannot read the repo. On a + **private** repo this surfaces as a confusing `remote: Repository not found` + / `fatal: repository '...' not found` (GitHub returns 404, not 403, to a + token that lacks access). This is the most common setup failure. +- `pull-requests: write` — without it, the final `gh pr comment` step fails. + +If you omit the `permissions:` block entirely, the workflow inherits the +repository's default token permissions, which may or may not include +`pull-requests: write`. Declaring both explicitly is the reliable setup. + +## Inputs + +| Input | Default | Description | +|---|---|---| +| `pr-number` | event context | PR number (auto-detected from the `pull_request` event) | +| `churn-days` | `14` | Churn context window in days | +| `python-version` | `3.11` | Python version to install | + +Example with overrides: + +```yaml + - uses: RocketBus/clickbus-iris/.github/actions/iris-pr@main + with: + churn-days: '30' + python-version: '3.12' +``` + +## Notes + +- `fetch-depth: 0` gives Iris full history for churn and cascade context. With a + shallow clone the action degrades gracefully and runs with `--no-context`. +- `@main` always runs the latest action. Pin to a tag or commit SHA if you need + reproducible behavior across runs. diff --git a/.github/actions/iris-pr/example-workflow.yml b/.github/actions/iris-pr/example-workflow.yml new file mode 100644 index 0000000..76e21e8 --- /dev/null +++ b/.github/actions/iris-pr/example-workflow.yml @@ -0,0 +1,25 @@ +# Canonical Iris PR Insights workflow. +# Copy this file into a consuming repo as: .github/workflows/iris.yml +# +# Both permissions are required: +# contents: read -> actions/checkout (private repos 404 without it) +# pull-requests: write -> posting the insights comment +name: Iris PR Insights + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + iris-pr: + name: Iris PR Analysis + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: RocketBus/clickbus-iris/.github/actions/iris-pr@main diff --git a/README.md b/README.md index fb392b6..fbeea6c 100644 --- a/README.md +++ b/README.md @@ -118,6 +118,19 @@ Generates concise markdown insights for code review: Requires `gh` CLI installed and authenticated. +### GitHub Actions (automatic PR comments) + +To post Iris insights on every PR automatically, copy +[`.github/actions/iris-pr/example-workflow.yml`](.github/actions/iris-pr/example-workflow.yml) +into the consuming repo as `.github/workflows/iris.yml`. See the +[action README](.github/actions/iris-pr/README.md) for inputs and setup notes. + +> The workflow **must** grant `contents: read` (for checkout) and +> `pull-requests: write` (to comment). Declaring a `permissions:` block sets +> every unlisted permission to `none`, so on private repos a missing +> `contents: read` shows up as a misleading `Repository not found` during +> checkout. + ### Options | Flag | Default | Description | From 0c3c686358fe6515796b2ca95b2a6288ba8ed9d1 Mon Sep 17 00:00:00 2001 From: Fabio Wakim Trentini Date: Fri, 12 Jun 2026 14:45:08 -0300 Subject: [PATCH 2/2] fix(ci): install Iris from repo source, not public PyPI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The action ran `pip install iris`, which pulls an unrelated public-PyPI package named "iris" (no `iris` console script) — every run failed with `iris: command not found` (exit 127). Iris is not published to public PyPI; install it from the action's own repo checkout, whose root holds pyproject.toml. $GITHUB_ACTION_PATH/../../.. resolves to that root, so the installed code always matches the action ref. Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/actions/iris-pr/action.yml | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/.github/actions/iris-pr/action.yml b/.github/actions/iris-pr/action.yml index 5d9f7d5..536e49b 100644 --- a/.github/actions/iris-pr/action.yml +++ b/.github/actions/iris-pr/action.yml @@ -21,7 +21,12 @@ runs: with: python-version: ${{ inputs.python-version }} - - run: pip install iris + # Install Iris from this action's own repo checkout (the repo root holds + # pyproject.toml). Iris is not published to public PyPI — `pip install iris` + # would pull an unrelated package and leave `iris` unavailable. + # $GITHUB_ACTION_PATH = .../.github/actions/iris-pr, so ../../.. is the repo root. + - name: Install Iris + run: pip install "$GITHUB_ACTION_PATH/../../.." shell: bash - name: Run Iris PR analysis