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

# Pagure API

Pagure is a lightweight Git-centered forge providing a REST API for managing Git repositories, issues, pull requests, tags, branches, users, groups, and projects. The API covers project creation and configuration, issue tracking with metadata and custom fields, pull request lifecycle (create, comment, merge, flag), release management via Git tags, user and group administration, webhook configuration, and repository settings including branch protection and notifications. Authentication uses API tokens obtained from Pagure user settings.

## For AI agents

Manage Pagure Git repositories, issues, pull requests, users, groups, webhooks, and project settings through a lightweight forge API.

## Scope

Does not host Git repositories, run CI/CD pipelines, or provide artifact storage - use for forge management (issues, PRs, users, webhooks) via API only. Git operations happen via Git protocol, not REST API.

## Capabilities

- Create and configure Git projects with public/private visibility and namespace organization
- Manage issues with custom fields, tags, milestones, assignees, and status transitions
- Create, update, comment on, flag, and merge pull requests across forks and branches
- List and manage repository branches, tags, and commits
- Configure webhooks for project events like push, pull request, and issue updates
- Manage users, groups, and access control for projects
- Query project and user activity, stars, forks, and watchers
- Administer project settings including branch protection, notifications, and close-on-merge behavior

## Use cases

### Automated Issue Creation from External Systems

Integrate Pagure issue tracking with external monitoring, ticketing, or CI/CD systems by creating issues programmatically. POST `/project/{namespace}/{repo}/new_issue` accepts title, description, assignee, tags, milestone, and custom fields. This supports workflows like creating Pagure issues from GitHub Actions, incident response systems, or customer support platforms.

Example prompt: POST /{namespace}/{repo}/new_issue with title, issue_content, assignee, tags, milestone, and private flag.

### Pull Request Review and Merge Workflow

Automate pull request workflows by querying open PRs, posting review comments, applying flags (CI status, linter results), and merging when criteria are met. GET `/project/{namespace}/{repo}/pull-requests` lists PRs, POST `/project/{namespace}/{repo}/pull-request/{id}/comment` adds review feedback, and POST `/project/{namespace}/{repo}/pull-request/{id}/merge` completes the merge. This supports code review bots and automated merge policies.

Example prompt: GET /{namespace}/{repo}/pull-requests?status=Open, then POST /{namespace}/{repo}/pull-request/{id}/merge when flags and reviews pass.

### Repository Release Management

Manage Git tags and releases via the API by listing tags, creating new tags, and querying commits. GET `/project/{namespace}/{repo}/git/tags` returns all tags, and combined with commit endpoints, enables automated changelog generation, version bumping, and release note publishing. This supports CI/CD pipelines that tag releases based on semantic versioning rules.

Example prompt: GET /{namespace}/{repo}/git/tags to list versions, then use commit endpoints to generate changelog.

### Project and User Activity Monitoring

Track project activity, user contributions, and repository statistics by querying users, projects, stars, forks, and watchers. GET /projects lists all projects with filters, GET `/user/{username}/activity` shows user contributions, and GET `/project/{namespace}/{repo}/stargazers` lists who starred a project. This supports analytics dashboards, contributor recognition, and community health metrics.

Example prompt: GET `/user/{username}/activity`?date={YYYY-MM-DD} for contributions, GET /projects?fork=false&short=true for project list.

### AI Agent for Forge Operations

Let an AI agent manage Pagure forge tasks like creating issues from user reports, triaging PRs, tagging releases, adding collaborators to projects, and configuring webhooks. Through Jentic, the agent searches by intent (e.g., 'create a pagure issue'), loads the schema, and executes with the API token injected securely.

Example prompt: Use Jentic search 'create pagure issue' to find POST /{namespace}/{repo}/new_issue, load schema, execute with title and issue_content.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/{namespace}/{repo}/new_issue` | Create a new issue |
| GET | `/{namespace}/{repo}/issues` | List issues with filters |
| GET | `/{namespace}/{repo}/pull-requests` | List pull requests |
| POST | `/{namespace}/{repo}/pull-request/{id}/merge` | Merge a pull request |
| GET | `/projects` | List projects with filters |
| GET | `/user/{username}/activity` | Get user activity |
| POST | `/{namespace}/{repo}/webhook/add` | Add a webhook |

## Key resources

- **Projects** — Git repositories with namespace, name, visibility, and settings for issues, PRs, and wikis
- **Issues** — Bug and task tracking with custom fields, tags, milestones, assignees, and status
- **Pull Requests** — Code review and merge workflow with comments, flags (CI, linting), and merge controls
- **Users and Groups** — User accounts, group membership, and access control for projects
- **Git Objects** — Branches, tags, commits, and repository content
- **Webhooks** — Event-driven HTTP callbacks for project activity

## Why Jentic

- **Setup:** Wiring Pagure by hand means handling its API-token auth in the Authorization header against pagure.io/api/0, shaping issue and pull-request requests, and building your own retry and error handling. Through Jentic you install once, import the Pagure API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Pagure puts the namespace and repo in the URL path (/{namespace}/{repo}/new_issue), so a rule can pin your agent to one repository: it can open issues and read that repo and nothing else. You choose the operations it may call, so merging a pull request or adding a webhook is not included unless you add them.
- **Credential handling:** Your Pagure token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a Pagure issue' or 'merge a pull request', and Jentic returns the matching Pagure operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **GitHub API** — GitHub is a larger, feature-rich Git forge with extensive integrations, while Pagure is a lightweight, self-hostable alternative focused on simplicity.
- **GitLab API** — GitLab provides a full DevOps platform with CI/CD built-in, while Pagure is a simpler Git forge focused on repositories, issues, and PRs.

## FAQ

### What authentication does the Pagure API use?

The Pagure API uses API key authentication via the Authorization header with format 'token <your-api-token>'. Tokens are obtained from Pagure user settings. Through Jentic, tokens are stored encrypted and injected at execution time.

### Can I manage pull requests programmatically with the Pagure API?

Yes. The API supports listing PRs, creating PRs from branches, commenting, applying flags (CI status), and merging. This enables automated code review and merge workflows.

### Does the Pagure API support issue tracking?

Yes. The API provides full CRUD for issues including custom fields, tags, milestones, assignees, status updates, and comments. This supports integration with external ticketing and monitoring systems.

### How do I configure webhooks through the Pagure API?

Use POST /{namespace}/{repo}/webhook/add with the target URL and event types (push, pull request, issue). Webhooks enable real-time integration with CI/CD, chat, and notification systems.

### Is the Pagure API free?

Pagure is open-source software (GPL-2.0) and the public instance at pagure.io is free to use for open-source projects. Self-hosted Pagure instances can be deployed with the same API surface.

### Can I list all projects on a Pagure instance?

Yes. GET /projects returns a list of projects with optional filters for forks, short format, username, namespace, tags, and pattern matching. Pagination is supported via page and per_page parameters.

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

Yes. Jentic One runs on your own infrastructure, and your rules decide which Pagure operations and which stored token the agent may use. Because Pagure puts the namespace and repo in the URL path, such as /{namespace}/{repo}/new_issue, you can pin the agent to a single repository and grant only the calls you want, for example opening issues and reading that repo while leaving out merging a pull request or adding a webhook. The agent can invoke only the operations you approve.