git-auto-comment/README.md

# 🧩 PR Commenter for GitHub & Gitea

A composite Action that posts PR comments from **large output files**, such as Terraform/OpenTofu plans, logs, or diffs — directly to **GitHub** or **Gitea** pull requests.

It’s based on [`tofu-pr-commenter`](https://github.com/alexnorell/tofu-pr-commenter) but extended for **Gitea compatibility**, **multi-line comment templates**, and **general-purpose content handling** (not just diffs).

---

## 🚀 Features

- ✅ Works with **GitHub** and **Gitea** PR APIs
- ✅ Handles **large text outputs** (plans, diffs, logs, etc.)
- ✅ Allows **multiline comment templates** with placeholders
- ✅ Defaults to environment variables from the Action runner (no hardcoded repo info required)
- ✅ Can run on **both GitHub Actions** and **Gitea Actions**

---

## ⚙️ Inputs

| Name | Required | Default | Description |
|------|-----------|----------|-------------|
| `platform` | ❌ | `github` | Platform type (`github` or `gitea`) |
| `token` | ✅ | — | Access token for API requests (`GITHUB_TOKEN` or personal token) |
| `pr_index` | ✅ | — | Pull request number or index |
| `repo_owner` | ❌ | `${{ github.repository_owner }}` | Repository owner |
| `repo_name` | ❌ | `${{ github.repository }}` | Repository name |
| `api_url` | ❌ | `${{ github.api_url }}` | API URL for Gitea (required only for Gitea) |
| `content` | ❌ | — | Large text input — diff, plan, or log content |
| `comment_template` | ❌ | See below | Comment body template supporting `{line}` and `{lines}` placeholders |

### 🧠 Template Variables

| Placeholder | Description |
|--------------|--------------|
| `{line}` | The specific line being commented on (when parsed from diff-style input) |
| `{lines}` | The full set of added lines for that file or section |

---

## 🧩 Default `comment_template`

```yaml
comment_template: |
  Auto-comment:
  ---
  {line}
```

## 💡 Example: GitHub Action Workflow
```yaml
name: Comment Terraform Plan on PR
on:
  pull_request:
    branches:
      - main

jobs:
  plan-comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Run Terraform Plan
        id: plan
        run: |
          terraform plan -no-color > plan.txt
          echo "plan_text<<EOF" >> $GITHUB_OUTPUT
          cat plan.txt >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Comment Plan on GitHub PR
        uses: "https://gitea.example.com/your-org/pr-commenter-action@main"
        with:
          platform: github
          token: ${{ secrets.GITHUB_TOKEN }}
          pr_index: ${{ github.event.pull_request.number }}
          content: ${{ steps.plan.outputs.plan_text }}
          comment_template: |
            🚀 **Terraform Plan Summary**
            ```
            {lines}
            ```
```

## 💡 Example: Gitea Action Workflow
```yaml
name: Comment Plan on PR (Gitea)
on:
  pull_request:
    branches:
      - main

jobs:
  plan-comment:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Run Tofu Plan
        id: tofu
        run: |
          tofu plan -no-color > tofu-plan.txt
          echo "plan_text<<EOF" >> $GITEA_OUTPUT
          cat tofu-plan.txt >> $GITEA_OUTPUT
          echo "EOF" >> $GITEA_OUTPUT

      - name: Post Plan to Gitea PR
        uses: "https://gitea.example.com/your-org/pr-commenter-action@main"
        with:
          platform: gitea
          token: ${{ secrets.GITEA_TOKEN }}
          api_url: "https://gitea.example.com/api/v1"
          pr_index: ${{ gitea.event.pull_request.number }}
          content: ${{ steps.tofu.outputs.plan_text }}
          comment_template: |
            🧠 **OpenTofu Plan Diff**
            ```
            {lines}
            ```
```

## 🪵 Example: Posting Large Log Output
```yaml
- name: Upload build logs to PR
  uses: "https://gitea.example.com/your-org/pr-commenter-action@main"
  with:
    platform: gitea
    token: ${{ secrets.GITEA_TOKEN }}
    api_url: "https://gitea.example.com/api/v1"
    pr_index: 42
    content: ${{ steps.build.outputs.log }}
    comment_template: |
      🧾 **Build Log Summary**
      ```
      {lines}
      ```
```

## 🧰 Local Development

You can test the script locally by exporting the necessary environment variables and running:

```
export PLATFORM=gitea
export TOKEN=<your_token>
export REPO_OWNER=your-org
export REPO_NAME=your-repo
export PR_INDEX=42
export API_URL=https://gitea.example.com/api/v1
export CONTENT="$(cat plan.txt)"
python3 comment_pr.py
```

## ⚠️ Limitations & Tips for Large Files

1. GitHub & Gitea Comment Limits
   - GitHub: max ~65,536 characters per comment.
   - Gitea: may vary depending on server configuration.

2. Chunk Large Content
   - For extremely long plans/logs, split content into smaller chunks and post multiple comments.
   - Example using shell `split`:

```bash
split -l 5000 plan.txt plan_chunk_
for file in plan_chunk_*; do
  CONTENT=$(cat "$file")
  python3 comment_pr.py ...
done
```

3. Diff Parsing
   - If your content is a diff, {line} and {lines} placeholders work.
   - Otherwise, the action will post the entire content under {lines}.

4. Avoid Passing Huge Strings via Env Variables
   - Always prefer writing output to a file and reading it in the script.