docs: replace instance-specific values with placeholders in forgejo.md
Replace hardcoded bot_id "48" and bot_email "claude@wxs.ro" with generic placeholders in Quick Start and setup examples so readers don't copy instance-specific values. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Vlad MocanuandClaude Opus 4.6 committed
1 parent
b4a6c34853
commit
07e0384538
1 file changed
+95
-10
+95
-10
@@ -7,19 +7,16 @@ This action supports [Forgejo](https://forgejo.org/) (and Forgejo Actions) as an
|
||||
- **Forgejo instance** with [Forgejo Actions](https://forgejo.org/docs/latest/user/actions/) enabled
|
||||
- **Forgejo runner** registered and operational (e.g., a `grunt` or `ubuntu-latest` runner)
|
||||
- **Anthropic API key** or **Claude Code OAuth token** for Claude API access
|
||||
- **Forgejo token** with repo access (automatically available as `github.token` in workflows, or use a dedicated token)
|
||||
- **Forgejo token** with repo access (automatically available as `github.token` in workflows, or use a [dedicated bot user](#dedicated-bot-user-recommended))
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Add Secrets
|
||||
|
||||
In your Forgejo repository, go to **Settings > Actions > Secrets** and add:
|
||||
Add secrets at the **organization level** (Settings > Actions > Secrets) so all repos can share them:
|
||||
|
||||
- `ANTHROPIC_API_KEY` — Your Anthropic API key (starting with `sk-ant-`)
|
||||
|
||||
If you need a dedicated token for Claude's GitHub operations (recommended for tag mode):
|
||||
|
||||
- `FORGEJO_CLAUDE_TOKEN` — A Forgejo personal access token with `repo` scope
|
||||
- `CLAUDE_BOT_TOKEN` — API token for the dedicated bot user (see [Dedicated Bot User](#dedicated-bot-user-recommended) below)
|
||||
|
||||
### 2. Create Workflow
|
||||
|
||||
@@ -45,7 +42,10 @@ jobs:
|
||||
with:
|
||||
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
platform: "forgejo"
|
||||
github_token: ${{ secrets.FORGEJO_CLAUDE_TOKEN }}
|
||||
github_token: ${{ secrets.CLAUDE_BOT_TOKEN }}
|
||||
bot_id: "YOUR_BOT_ID" # Replace with your bot's Forgejo user ID (see step 5 below)
|
||||
bot_name: "claude-bot"
|
||||
bot_email: "claude@yourdomain.com" # Must match the bot user's registered email
|
||||
```
|
||||
|
||||
### 3. Agent Mode (Automation)
|
||||
@@ -70,7 +70,10 @@ jobs:
|
||||
prompt: ${{ github.event.inputs.task }}
|
||||
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
platform: "forgejo"
|
||||
github_token: ${{ secrets.FORGEJO_CLAUDE_TOKEN }}
|
||||
github_token: ${{ secrets.CLAUDE_BOT_TOKEN }}
|
||||
bot_id: "YOUR_BOT_ID" # Replace with your bot's Forgejo user ID
|
||||
bot_name: "claude-bot"
|
||||
bot_email: "claude@yourdomain.com"
|
||||
```
|
||||
|
||||
## Platform Detection
|
||||
@@ -90,11 +93,11 @@ The action detects the platform using a three-tier strategy:
|
||||
### Authentication
|
||||
|
||||
| Aspect | GitHub | Forgejo |
|
||||
| ------------------------ | ------------------------------- | --------------------------------------- |
|
||||
| ------------------------ | ------------------------------- | ------------------------------------------------------------- |
|
||||
| **Default auth** | GitHub App OIDC token exchange | Direct `GITHUB_TOKEN` / `FORGEJO_TOKEN` |
|
||||
| **Token setup** | Automatic via Claude GitHub App | Manual — provide `github_token` input |
|
||||
| **App token revocation** | Automatic cleanup step | Skipped (no app token) |
|
||||
| **Bot identity** | `claude[bot]` (ID: 41898282) | Token owner's identity |
|
||||
| **Bot identity** | `claude[bot]` (ID: 41898282) | Dedicated bot user via `bot_id`/`bot_name`/`bot_email` inputs |
|
||||
|
||||
On Forgejo, there is no OIDC token exchange with Anthropic. The action uses the workflow token (`github.token`) or a user-provided `github_token` directly.
|
||||
|
||||
@@ -131,6 +134,88 @@ platform:
|
||||
|
||||
All other inputs work identically on both platforms. See the [Usage Guide](./usage.md) for the full list.
|
||||
|
||||
## Dedicated Bot User (Recommended)
|
||||
|
||||
On GitHub, Claude gets its own identity via the GitHub App (`claude[bot]`). On Forgejo, there's no such mechanism — by default the action runs under whatever token you provide, meaning commits and comments appear as the human user.
|
||||
|
||||
Creating a dedicated bot user solves this:
|
||||
|
||||
- **Clear attribution**: Commits and comments show as `claude-bot`, not your personal account
|
||||
- **Least privilege**: The bot token has only the permissions Claude needs
|
||||
- **Audit trail**: Easy to distinguish human actions from bot actions in repo history
|
||||
- **Security**: If the action is compromised, only the bot's scoped token is exposed
|
||||
|
||||
### Setup Steps
|
||||
|
||||
#### 1. Create the bot user
|
||||
|
||||
Go to **Site Administration > User Accounts > Create User Account** or use the admin API:
|
||||
|
||||
- **Username**: `claude-bot`
|
||||
- **Email**: e.g., `claude@yourdomain.com`
|
||||
- **Password**: any strong password (you'll use API tokens, not password login)
|
||||
- **Uncheck** "Require user to change password"
|
||||
- Leave "Admin" **unchecked**
|
||||
- Optionally set a display name and avatar to distinguish from human users
|
||||
|
||||
#### 2. Add to organizations via teams
|
||||
|
||||
For each organization where Claude should operate:
|
||||
|
||||
1. Go to **Org Settings > Teams > New Team**
|
||||
2. Create a team named `Claude` with:
|
||||
- **Permission**: `Write`
|
||||
- **Access**: All Repositories (so new repos are automatically covered)
|
||||
3. Add `claude-bot` to the team's **Members**
|
||||
|
||||
#### 3. Generate a scoped API token
|
||||
|
||||
Log in as `claude-bot`, go to **Settings > Applications**, and create a token:
|
||||
|
||||
- **Token Name**: `claude-code-action`
|
||||
- **Scopes**:
|
||||
- `repo` — read/write (issues, PRs, comments, branches, commits)
|
||||
- `user:read` — needed for API identity
|
||||
- Leave `admin`, `organization`, `package` **unchecked**
|
||||
|
||||
#### 4. Store the token as an org-level secret
|
||||
|
||||
Add the token as `CLAUDE_BOT_TOKEN` at the **organization level** (Settings > Actions > Secrets) with visibility set to "All repositories". This way all repos in the org share the same secret.
|
||||
|
||||
#### 5. Get the bot user's ID
|
||||
|
||||
You'll need the Forgejo user ID for the `bot_id` input:
|
||||
|
||||
```bash
|
||||
curl -s "https://your-forgejo-instance/api/v1/users/claude-bot" | jq '.id'
|
||||
```
|
||||
|
||||
#### 6. Configure the workflow
|
||||
|
||||
```yaml
|
||||
- uses: https://git.wxs.ro/actions/claude-code-action@v1
|
||||
with:
|
||||
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
|
||||
platform: "forgejo"
|
||||
github_token: ${{ secrets.CLAUDE_BOT_TOKEN }}
|
||||
bot_id: "YOUR_BOT_ID" # Replace with the ID from step 5
|
||||
bot_name: "claude-bot"
|
||||
bot_email: "claude@yourdomain.com" # Must match the bot user's registered email
|
||||
```
|
||||
|
||||
The `bot_email` input overrides the default noreply email format. When it matches the bot user's registered email in Forgejo, commits will be linked to the bot's profile in the UI.
|
||||
|
||||
### Token Rotation
|
||||
|
||||
Forgejo API tokens can expire. Plan for rotation:
|
||||
|
||||
1. **Set a calendar reminder** for before the token expires
|
||||
2. **Generate a new token** by logging in as `claude-bot` (same scopes as above)
|
||||
3. **Update the org secret** `CLAUDE_BOT_TOKEN` with the new token value
|
||||
4. **No code changes needed** — the workflow reads the secret at runtime
|
||||
|
||||
Alternatively, generate a token without an expiration date (if your Forgejo instance allows it).
|
||||
|
||||
## Included CI Workflows
|
||||
|
||||
This fork includes four Forgejo-native workflows in `.forgejo/workflows/`:
|
||||
|
||||
Reference in new issue
Block a user