# Issue Configuration and Templates API Reference

Manage issue templates, contact links, and pin settings for repositories.

---

## Endpoints

### Get Issue Config

```
GET /repos/{owner}/{repo}/issue_config
```

Returns the repository's issue configuration, which controls whether blank issues are allowed and provides optional contact links on the issue creation page.

**Path Parameters:**

| Parameter | Type   | Required | Description        |
|-----------|--------|----------|--------------------|
| owner     | string | yes      | Repository owner   |
| repo      | string | yes      | Repository name    |

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/issue_config" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**IssueConfig Response Object:**

| Field                 | Type               | Description                                              |
|-----------------------|--------------------|----------------------------------------------------------|
| blank_issues_enabled  | boolean            | Whether users can create blank issues (without template) |
| contact_links         | array[ContactLink] | External links shown on the issue creation page          |

**ContactLink fields:**

| Field | Type   | Description                       |
|-------|--------|-----------------------------------|
| name  | string | Link display name                 |
| url   | string | URL to link to                    |
| about | string | Short description of the link     |

**Example response:**

```json
{
  "blank_issues_enabled": true,
  "contact_links": [
    {
      "name": "Support",
      "url": "https://example.com/support",
      "about": "Get help from our support team"
    },
    {
      "name": "Security",
      "url": "https://example.com/security",
      "about": "Report security vulnerabilities"
    }
  ]
}
```

### Validate Issue Config

```
GET /repos/{owner}/{repo}/issue_config/validate
```

Validates the repository's issue configuration file and returns whether it is valid.

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/issue_config/validate" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Validation Response:**

| Field   | Type   | Description                                        |
|---------|--------|----------------------------------------------------|
| valid   | boolean| Whether the config is valid                        |
| message | string | Error details (only present when `valid` is false) |

```json
{"valid": true}
```

```json
{"valid": false, "message": "contact_links[0]: url is required"}
```

### List Issue Templates

```
GET /repos/{owner}/{repo}/issue_templates
```

Returns all issue templates defined in the repository.

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/issue_templates" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**IssueTemplate Response Fields:**

| Field     | Type          | Description                                                 |
|-----------|---------------|-------------------------------------------------------------|
| name      | string        | Template name (displayed to user)                           |
| title     | string        | Default issue title (may contain placeholders)              |
| about     | string        | Short description of this template                          |
| body      | array         | Structured form body (YAML form syntax, if used)            |
| labels    | array[string] | Labels automatically applied when using this template       |
| assignees | array[string] | Users automatically assigned when using this template       |
| ref       | string        | Branch reference for the template (if template is branch-specific) |
| content   | string        | Markdown content/body of the template                       |
| filename  | string        | File path of the template in the repository                 |

**Example response:**

```json
[
  {
    "name": "Bug Report",
    "title": "[Bug]: ",
    "about": "Report a bug in the application",
    "body": null,
    "labels": ["bug", "triage"],
    "assignees": [],
    "ref": "",
    "content": "## Description\n\n## Steps to Reproduce\n\n## Expected Behavior\n\n## Actual Behavior\n",
    "filename": ".forgejo/ISSUE_TEMPLATE/bug_report.md"
  },
  {
    "name": "Feature Request",
    "title": "[Feature]: ",
    "about": "Suggest a new feature",
    "body": null,
    "labels": ["enhancement"],
    "assignees": [],
    "ref": "",
    "content": "## Problem\n\n## Proposed Solution\n\n## Alternatives Considered\n",
    "filename": ".forgejo/ISSUE_TEMPLATE/feature_request.md"
  }
]
```

### Check if New Pins Are Allowed

```
GET /repos/{owner}/{repo}/new_pin_allowed
```

Returns whether new issue and PR pins are allowed for the repository.

```bash
curl -s "${FORGEJO_URL}/api/v1/repos/{owner}/{repo}/new_pin_allowed" \
  -H "Authorization: token ${FORGEJO_PAT}"
```

**Response:**

| Field          | Type    | Description                              |
|----------------|---------|------------------------------------------|
| issues         | boolean | Whether new issue pins are allowed       |
| pull_requests  | boolean | Whether new PR pins are allowed          |

```json
{"issues": true, "pull_requests": true}
```

Pins may be disallowed when:
- The maximum number of pinned issues/PRs has been reached (default max is typically 3)
- Pinning is disabled in the repository or instance settings

---

## Issue Template Directory Structure

Issue templates are defined as files in the repository. Forgejo looks for templates in these directories (in order of priority):

1. `.forgejo/ISSUE_TEMPLATE/`
2. `.github/ISSUE_TEMPLATE/`

Templates can be either **Markdown templates** or **YAML form templates**.

### Markdown Template Example

File: `.forgejo/ISSUE_TEMPLATE/bug_report.md`

```markdown
---
name: "Bug Report"
title: "[Bug]: "
about: "Report a bug in the application"
labels:
  - bug
  - triage
assignees:
  - maintainer1
---

## Description

A clear description of the bug.

## Steps to Reproduce

1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior

What you expected to happen.

## Actual Behavior

What actually happened.

## Environment

- OS: 
- Browser: 
- Version: 
```

### YAML Form Template Example

File: `.forgejo/ISSUE_TEMPLATE/bug_report.yaml`

```yaml
name: "Bug Report"
title: "[Bug]: "
about: "Report a bug in the application"
labels:
  - bug
  - triage
body:
  - type: textarea
    id: description
    attributes:
      label: Description
      description: A clear description of the bug
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: Version
      description: Which version are you running?
    validations:
      required: true
  - type: dropdown
    id: severity
    attributes:
      label: Severity
      options:
        - Low
        - Medium
        - High
        - Critical
```

### Issue Config File

The issue config file controls blank issues and contact links. It is located at:

1. `.forgejo/issue_config.yaml`
2. `.github/ISSUE_TEMPLATE/config.yml`

**Example `config.yml`:**

```yaml
blank_issues_enabled: false
contact_links:
  - name: Support Forum
    url: https://forum.example.com
    about: Ask questions and get help from the community
  - name: Security Issues
    url: https://example.com/security/report
    about: Report security vulnerabilities privately
  - name: Feature Requests
    url: https://feedback.example.com
    about: Vote on and suggest new features
```

When `blank_issues_enabled: false`, users must choose from the available templates or contact links — they cannot create a free-form issue without a template.
