canonical: https://jentic.com/apis/gogs.io/gogs

# Gogs API

Jentic publishes the only available OpenAPI specification for Gogs API, keeping it validated and agent-ready. Gogs is a self-hosted, lightweight Git service written in Go that follows the GitHub REST API v3 conventions. Its API exposes repositories, branches, commits, contents, issues, releases, webhooks, collaborators, deploy keys, organisations, users, miscellaneous helpers, and administration endpoints. It is the standard interface for self-hosting teams that want a familiar GitHub-style integration surface without depending on a third-party SaaS.

## For AI agents

Manage self-hosted Git repositories on Gogs: create issues, push releases, configure webhooks, and manage collaborators. Mirrors GitHub-style endpoints for easy adoption.

## Scope

Does not handle CI/CD execution, package registries, or runtime monitoring - use for self-hosted Git source-control operations on Gogs only.

## Capabilities

- Search repositories or list user, organisation, and team repositories
- Create, read, and migrate repositories including their branches and contents
- Open, list, and comment on issues against a repository
- Manage releases, tags, and webhooks for a repository
- Add or remove collaborators and deploy keys on a repository
- Run administration tasks such as user provisioning when authenticated as an admin

## Use cases

### Self-Hosted Issue Tracking Automation

Engineering teams that run Gogs internally automate issue triage by calling `/repos/{owner}/{repo}/issues` to read open issues and POST to the same path to create new ones. This pattern mirrors the GitHub Issues API, so existing scripts and bots port over with minimal changes.

Example prompt: Open an issue on repo 'platform/infra' titled 'Investigate intermittent CI timeout' with the agent's debug log attached as a comment.

### Repository Migration

When teams move from GitHub or another Git host to Gogs, `/repos/migrate` accepts a clone URL and credentials and pulls the full repository - including history - into Gogs. Pair it with `/repos/{owner}/{repo}/hooks` to recreate webhooks on the new host.

Example prompt: Migrate the repository at https://github.com/example/widgets into the Gogs organisation 'platform' and recreate the GitHub webhooks.

### Release Automation

CI integrations create releases on Gogs by calling `/repos/{owner}/{repo}/releases` when a tag pipeline completes. Combined with `/repos/{owner}/{repo}/branches` and `/repos/{owner}/{repo}/commits/{sha}`, the integration can record the exact commit and branch each release was cut from.

Example prompt: Create a release v1.4.0 on repo 'platform/widgets' with notes assembled from the commits since the last release.

### AI Agent Source Control

An AI coding agent uses Jentic to interact with a Gogs server: it lists repositories, opens issues for newly detected bugs, and writes back fix commits via the contents endpoints. Basic auth credentials and personal access tokens stay in your Jentic One instance.

Example prompt: Search Jentic for 'create gogs issue', load the schema, and open a 'flaky test' issue on every repo where the nightly CI failed.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/repos/search` | Search repositories |
| GET | `/repos/{owner}/{repo}` | Get a repository |
| POST | `/repos/migrate` | Migrate an external repository into Gogs |
| GET | `/repos/{owner}/{repo}/issues` | List issues on a repository |
| POST | `/repos/{owner}/{repo}/issues` | Create an issue on a repository |
| GET | `/repos/{owner}/{repo}/branches` | List branches |
| GET | `/repos/{owner}/{repo}/releases` | List releases |
| GET | `/repos/{owner}/{repo}/hooks` | List webhooks for a repository |

## Key resources

- **Repositories** — Search, create, migrate, and inspect repositories
- **Issues** — Open, list, and comment on issues
- **Releases** — Create and read releases for a repository
- **Webhooks** — Configure outbound webhooks per repository
- **Collaborators and Deploy Keys** — Manage repo-level access for users and machines
- **Users** — Look up user profiles and their repositories
- **Organizations** — List and inspect organisations and their repos
- **Administration** — Admin-only endpoints for user provisioning
- **Miscellaneous** — Server health, markdown rendering, and helper endpoints

## Why Jentic

- **Setup:** Wiring Gogs by hand means pointing at your own self-hosted host, choosing between basic auth and a personal access token in the Authorization header, and mapping the repository, issue, and hook endpoints yourself. Through Jentic you install once, import Gogs from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** Gogs puts the owner and repository in the URL path (`/repos/{owner}/{repo}/...`), so a rule can pin your agent to one repository: it can read and file issues, list branches, and read releases for that repo and nothing else. You choose the operations it may call, so ones like migrating a repository are not included unless you add them.
- **Credential handling:** Your Gogs token or basic-auth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a gogs issue' or 'search repositories', and Jentic returns the matching Gogs operation with its input schema so the agent calls the right endpoint without browsing the source-tree Markdown.

## Related APIs

- **GitHub REST API** — GitHub is the SaaS Git host whose API conventions Gogs mirrors closely.
- **GitLab API** — GitLab provides Git plus integrated CI/CD and project management in one platform.
- **GoCD API** — GoCD pulls source from Gogs as a material and runs the resulting deploy pipelines.

## FAQ

### Why is there no official OpenAPI spec for Gogs API?

Gogs documents its endpoints in source-tree Markdown files but does not ship a maintained OpenAPI specification. Jentic generates and maintains this spec so AI agents and developers can call Gogs API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the Gogs API use?

Gogs supports two schemes: HTTP basic authentication with username and password, and personal access tokens passed via the Authorization header. Through Jentic, both are stored encrypted in the vault and injected at execution time so the agent never sees the raw secret.

### Can I create an issue with the Gogs API?

Yes. POST `/repos/{owner}/{repo}/issues` opens a new issue and POST `/repos/{owner}/{repo}/issues/{index}/comments` adds a comment. The shape mirrors the GitHub Issues API so existing tooling ports across with little change.

### What are the rate limits for the Gogs API?

Gogs is self-hosted and the OpenAPI spec does not declare a numeric rate limit. The practical limit depends on the deployed server's capacity; back off on HTTP 429 responses if your administrator has fronted the server with a rate-limiting proxy.

### How do I migrate a repository to Gogs through Jentic?

Run a Jentic search for 'migrate repo to gogs', load the schema for POST `/repos/migrate`, and execute it with the source clone URL and target organisation. Install with pip install jentic and chain search, load, and execute.

### Does the Gogs API support webhooks?

Yes. `/repos/{owner}/{repo}/hooks` lists configured webhooks and POST to the same path adds a new one. `/repos/{owner}/{repo}/hooks/{id}` updates or removes a specific webhook so CI integrations can keep their delivery URLs current.

### Can I limit what my agent is allowed to do with the Gogs API?

Yes. Because Jentic One is self-hosted by you, your own rules decide which Gogs operations and credentials the agent may use. Gogs puts the owner and repository in the URL path, such as `/repos/{owner}/{repo}/issues`, so you can pin the agent to a single repository where it reads and files issues, lists branches, and reads releases and nothing more. Sensitive operations like POST `/repos/migrate` are excluded unless you explicitly add them, and your Gogs token or basic-auth credential is injected at execution time rather than exposed to the agent.