# Forgejo (Gitea Fork) MCP

> Forgejo (Gitea Fork) MCP connects your self-hosted Git instances to any AI agent. It lets you manage repository access, check version compatibility across multiple environments, and trigger CI/CD workflows—all from a single conversation. Need an API token or running a deployment test? This is where you do it.

## Overview
- **Category:** loved-by-devs
- **Price:** Free
- **Tags:** git-repository, self-hosted, version-control, ci-cd, token-management, automation

## Description

Connect your Forgejo or Gitea self-hosted Git instance to any AI agent to handle complex DevOps tasks naturally. Instead of logging into multiple dashboards, checking version numbers across different tabs, and manually generating access tokens, you just ask your agent. You can check detailed version compatibility between Forgejo and Gitea APIs, generate new Personal Access Tokens with specific read/write scopes, or kick off a full CI/CD build by dispatching workflows directly from the chat. The Vinkius catalog makes this connection simple; once connected to any compatible client, you get access to all these Git management functions. It’s about keeping your entire development process in one conversation.

## Tools

### create_token
Generates a new personal access token for a specified user with defined permissions.

### dispatch_workflow
Triggers a manual workflow run within Forgejo Actions.

### get_forgejo_version
Retrieves detailed version information for the connected Forgejo instance.

### get_gitea_version
Gets the Gitea-compatible version data from your self-hosted Git service.

## Prompt Examples

**Prompt:** 
```
Check the Forgejo and Gitea-compatible versions of my instance.
```

**Response:** 
```
I've checked your instance. It is running Forgejo version 7.0.1 and is compatible with Gitea API version 1.21.0.
```

**Prompt:** 
```
Generate a new API token named 'CI-Runner' with read:repository scope for user 'admin'.
```

**Response:** 
```
I have successfully created the token 'CI-Runner' for user 'admin'. The token is: [TOKEN_VALUE]. Please save it securely.
```

**Prompt:** 
```
Trigger the 'deploy.yaml' workflow in the 'main-app' repository owned by 'dev-team'.
```

**Response:** 
```
The workflow 'deploy.yaml' has been successfully dispatched for dev-team/main-app. You can monitor the progress in your Forgejo Actions dashboard.
```

## Capabilities

### Audit self-hosted version compatibility
You can retrieve detailed version numbers for both Forgejo and Gitea, confirming API compatibility across your infrastructure.

### Generate new access tokens
The agent generates Personal Access Tokens (PATs) using your basic credentials, allowing you to grant specific read or write scopes instantly.

### Trigger CI/CD pipelines manually
You can execute manual workflow dispatches for Forgejo Actions directly from the chat interface to start builds or deployments.

## Use Cases

### Audit versioning across environments
A sysadmin needs to know if their staging environment's Forgejo instance is compatible with the new Gitea API standard. They ask the agent, and it executes `get_forgejo_version` and `get_gitea_version`, immediately confirming compatibility before they write a single line of code.

### On-demand credential generation
A developer is building a script that needs read access to the main repo but shouldn't have write permissions. Instead of asking an admin, they use `create_token` to generate a dedicated PAT with only the 'read:repository' scope.

### Testing deployment readiness
A team lead needs to ensure the latest code pushes correctly by triggering a full build. They instruct their agent to run `dispatch_workflow` for the `release.yaml`, confirming the pipeline starts without any manual clicks.

### Troubleshooting environment issues
A junior developer reports that one service is failing mysteriously. The senior engineer asks the agent to verify the overall health by running version checks, quickly diagnosing if the problem is due to API incompatibility between the two Git systems.

## Benefits

- Version checks are instant. Instead of manually navigating the UI to check compatibility, you ask your agent to run `get_forgejo_version` and `get_gitea_version` for a full audit.
- Token management is fast. Need an API key for a local script? Use `create_token` to generate a new Personal Access Token instantly without leaving the chat window.
- CI/CD automation happens on command. You can trigger builds or deployments by calling `dispatch_workflow`, eliminating the need to click through multiple pipeline dashboards.
- Reduce context switching. All your core DevOps tasks—from checking versions to running pipelines—are centralized and managed via a single conversation with your agent.
- Deep visibility into self-hosted systems. You can verify instance health and configuration using this MCP, giving you immediate answers without having to log in repeatedly.

## How It Works

The bottom line is you manage complex repository and deployment tasks without ever leaving your chat interface.

1. Subscribe to this MCP, providing your specific Forgejo Instance URL and necessary credentials (Token or Username/Password).
2. Your AI agent connects to the instance via the Vinkius framework, authenticating access to your repositories.
3. You simply ask your agent to perform a task—like checking versions or triggering a workflow—and it handles the rest.

## Frequently Asked Questions

**How do I check the version compatibility using Forgejo (Gitea Fork) MCP?**
You need to use `get_forgejo_version` for your Forgejo data and then call `get_gitea_version` to get the corresponding Gitea-compatible API data. This tells you if they talk to each other.

**Can I trigger a workflow manually with Forgejo (Gitea Fork) MCP?**
Yes, you use `dispatch_workflow`. You just tell the agent which YAML file and repository needs the build, and it sends the manual dispatch command for you.

**Does create_token require specific permissions?**
Yes, the AI agent uses your basic credentials to generate tokens. Make sure the account connected has the necessary admin rights to issue new Personal Access Tokens (PATs).

**Is this MCP only for Forgejo instances?**
No, it's designed for both Forgejo and Gitea-compatible self-hosted Git services. You'll need to provide the correct instance URL when setting up your connection.

**What if my workflow fails? Can I check the version using Forgejo (Gitea Fork) MCP?**
While this MCP doesn't monitor live build logs, it can help diagnose potential causes by running `get_forgejo_version` or `get_gitea_version`. Version mismatch is often the root cause.