Fixes?

README.md

@@ -250,7 +250,8 @@ pre_tag   = ""               # Set by `stamp preview enter`; leave blank for nor
 |----------|---------|
 | `STAMP_REPO` | Repository slug `owner/repo` — required for `publish`, `comment`, and `release-pr` |
 | `GITHUB_TOKEN` | GitHub token for releases and PR comments — automatically provided by the GitHub Actions runner; no manual setup needed |
-| `GITEA_TOKEN` | Gitea access token — **must be created manually** (Gitea Actions does not inject one automatically); create a token in your Gitea account settings and store it as a repository secret |
+| `GITEA_TOKEN` | Auto-injected by Gitea Actions — has limited scopes and **cannot create PRs or post comments**; do not use this for stamp |
+| `STAMP_GITEA_TOKEN` | PAT you create manually with `repository` (read/write) and `issue` (read/write) scopes; used by stamp for all Gitea API calls. Store it as a repository secret. The name `GITEA_TOKEN` is reserved by Gitea Actions, which is why a different name is required. |
 | `GITEA_BASE_URL` | Gitea instance URL (e.g. `https://gitea.example.com`) — also enables Gitea mode |
 
 ## CI Integration
@@ -305,7 +306,7 @@ jobs:
       - name: Comment on PR
         run: stamp comment --pr=${{ gitea.event.pull_request.number }}
         env:
-          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          STAMP_GITEA_TOKEN: ${{ secrets.STAMP_GITEA_TOKEN }}
           GITEA_BASE_URL:    ${{ gitea.server_url }}
           STAMP_REPO:        ${{ gitea.repository }}
 ```
@@ -377,6 +378,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ secrets.STAMP_GITEA_TOKEN }}
 
       - name: Configure git
         run: |
@@ -389,7 +391,7 @@ jobs:
       - name: Create or update release PR
         run: stamp release-pr --base=main
         env:
-          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          STAMP_GITEA_TOKEN: ${{ secrets.STAMP_GITEA_TOKEN }}
           GITEA_BASE_URL:    ${{ gitea.server_url }}
           STAMP_REPO:        ${{ gitea.repository }}
 ```
@@ -446,6 +448,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ secrets.STAMP_GITEA_TOKEN }}
 
       - name: Configure git
         run: |
@@ -458,7 +461,7 @@ jobs:
       - name: Publish releases
         run: stamp publish
         env:
-          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          STAMP_GITEA_TOKEN: ${{ secrets.STAMP_GITEA_TOKEN }}
           GITEA_BASE_URL:    ${{ gitea.server_url }}
           STAMP_REPO:        ${{ gitea.repository }}
 ```

docs/workflow.md

@@ -256,6 +256,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ secrets.STAMP_GITEA_TOKEN }}
 
       - name: Configure git
         run: |
@@ -268,7 +269,7 @@ jobs:
       - name: Create or update release PR
         run: stamp release-pr --base=main
         env:
-          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          STAMP_GITEA_TOKEN: ${{ secrets.STAMP_GITEA_TOKEN }}
           GITEA_BASE_URL:    ${{ gitea.server_url }}
           STAMP_REPO:        ${{ gitea.repository }}
 ```
@@ -290,6 +291,7 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
+          token: ${{ secrets.STAMP_GITEA_TOKEN }}
 
       - name: Configure git
         run: |
@@ -302,12 +304,12 @@ jobs:
       - name: Publish releases
         run: stamp publish
         env:
-          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          STAMP_GITEA_TOKEN: ${{ secrets.STAMP_GITEA_TOKEN }}
           GITEA_BASE_URL:    ${{ gitea.server_url }}
           STAMP_REPO:        ${{ gitea.repository }}
 ```
 
-> **Note on `GITEA_TOKEN`:** Gitea Actions does not automatically inject a token the way GitHub Actions does. You must create a personal access token (or a bot account token) in your Gitea account settings with repository read/write permissions, then store it as a repository secret named `GITEA_TOKEN`.
+> **Note on `STAMP_GITEA_TOKEN`:** Gitea Actions auto-injects a `GITEA_TOKEN` for each run, but that token has limited scopes and cannot create PRs or post comments. Because `GITEA_TOKEN` is a reserved name you cannot override it with a secret of the same name. Instead, create a PAT in your Gitea account settings with **`repository` (read/write)** and **`issue` (read/write)** scopes, then store it as a repository secret named `STAMP_GITEA_TOKEN`. stamp reads `STAMP_GITEA_TOKEN` first and falls back to `GITEA_TOKEN`.
 
 ---
 
@@ -366,7 +368,7 @@ jobs:
       - name: Comment on PR
         run: stamp comment --pr=${{ gitea.event.pull_request.number }}
         env:
-          GITEA_TOKEN:    ${{ secrets.GITEA_TOKEN }}
+          STAMP_GITEA_TOKEN: ${{ secrets.STAMP_GITEA_TOKEN }}
           GITEA_BASE_URL:    ${{ gitea.server_url }}
           STAMP_REPO:        ${{ gitea.repository }}
 ```
@@ -479,5 +481,6 @@ Tag format: `<name>@v<version>` for monorepos (e.g. `my-app@v1.3.0`), or `v<vers
 |----------|---------|
 | `STAMP_REPO` | Repository slug `owner/repo` — required for `publish`, `comment`, and `release-pr` |
 | `GITHUB_TOKEN` | GitHub token — automatically injected by GitHub Actions; no setup needed |
-| `GITEA_TOKEN` | Gitea access token — must be created manually and stored as a secret |
+| `GITEA_TOKEN` | Auto-injected by Gitea Actions with limited scopes — **do not use this for stamp** |
+| `STAMP_GITEA_TOKEN` | PAT you create manually with `repository` (read/write) and `issue` (read/write) scopes. The name `GITEA_TOKEN` is reserved by Gitea Actions, so a different name is required. |
 | `GITEA_BASE_URL` | Gitea instance URL (e.g. `https://gitea.example.com`) — presence of this variable also activates Gitea mode |

internal/gitea/gitea.go

@@ -8,6 +8,17 @@ import (
 	giteaSDK "code.gitea.io/sdk/gitea"
 )
 
+// isPRsDisabledError returns true when the Gitea server rejects a PR operation
+// because the Pull Requests unit is disabled on the repository.
+func isPRsDisabledError(err error) bool {
+	if err == nil {
+		return false
+	}
+	msg := err.Error()
+	return strings.Contains(msg, "Can't read pulls") ||
+		strings.Contains(msg, "UnitTypeCode")
+}
+
 const prMarker = "<!-- stamp-release-pr -->"
 
 // Client wraps the Gitea API.
@@ -19,12 +30,18 @@ type Client struct {
 
 const commentMarker = "<!-- stamp-pr-comment -->"
 
-// NewClient creates a Gitea client from GITEA_TOKEN and GITEA_BASE_URL environment variables.
+// NewClient creates a Gitea client from GITEA_BASE_URL and a token environment variable.
+// The token is read from STAMP_GITEA_TOKEN first, falling back to GITEA_TOKEN.
+// STAMP_GITEA_TOKEN should be used in CI to avoid the reserved GITEA_TOKEN name that
+// Gitea Actions injects automatically (with limited scopes).
 // The repoSlug must be in "owner/repo" format.
 func NewClient(repoSlug string) (*Client, error) {
-	token := os.Getenv("GITEA_TOKEN")
+	token := os.Getenv("STAMP_GITEA_TOKEN")
 	if token == "" {
-		return nil, fmt.Errorf("GITEA_TOKEN environment variable is not set")
+		token = os.Getenv("GITEA_TOKEN")
+	}
+	if token == "" {
+		return nil, fmt.Errorf("neither STAMP_GITEA_TOKEN nor GITEA_TOKEN environment variable is set")
 	}
 	baseURL := os.Getenv("GITEA_BASE_URL")
 	if baseURL == "" {
@@ -87,6 +104,12 @@ func (c *Client) UpsertPR(head, base, title, body string) (int64, string, error)
 		State: giteaSDK.StateOpen,
 	})
 	if err != nil {
+		if isPRsDisabledError(err) {
+			return 0, "", fmt.Errorf(
+				"pull requests are disabled on %s/%s — enable them under Settings → General → Features → Pull Requests",
+				c.owner, c.repo,
+			)
+		}
 		return 0, "", fmt.Errorf("listing pull requests: %w", err)
 	}
 
@@ -116,6 +139,12 @@ func (c *Client) UpsertPR(head, base, title, body string) (int64, string, error)
 		Body:  markedBody,
 	})
 	if err != nil {
+		if isPRsDisabledError(err) {
+			return 0, "", fmt.Errorf(
+				"pull requests are disabled on %s/%s — enable them under Settings → General → Features → Pull Requests",
+				c.owner, c.repo,
+			)
+		}
 		return 0, "", fmt.Errorf("creating pull request: %w", err)
 	}
 	return pr.Index, pr.HTMLURL, nil