Add issue fields documentation for limited public preview (#59982)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: labudis

content/issues/planning-and-tracking-with-projects/understanding-fields/about-issue-fields.md

@@ -0,0 +1,62 @@
+---
+title: About issue fields in projects
+shortTitle: About issue fields
+intro: 'Learn how to use organization-level issue fields in your projects to track structured metadata like priority, effort, and dates.'
+versions:
+  feature: issue-fields
+type: tutorial
+topics:
+  - Projects
+  - Issues
+---
+
+{% data reusables.issues.issue-fields-public-preview-note %}
+
+Issue fields are organization-level fields that provide consistent, typed metadata across all repositories. Unlike project custom fields, issue fields are defined once at the organization level and are available on every issue and in every project across the organization. For more information on creating and managing issue fields, see [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization).
+
+> [!NOTE]
+> Issue fields are currently only supported in private projects. Issue fields are not available in public projects.
+
+## Adding an issue field to a project
+
+To display issue field values in a project:
+
+1. Open a project and select a view using the table layout.
+1. Click {% octicon "plus" aria-label="Add field" %} in the table header.
+1. Click **Add field**.
+1. Select one or more issue fields from the list of available fields in the organization.
+1. Click **Add**.
+
+The issue field appears as a column in the table view.
+
+## Removing an issue field from a project
+
+To remove an issue field from a project:
+
+1. Click {% octicon "kebab-horizontal" aria-label="open field options" %} in the top right corner of the project page.
+1. Click **Settings**.
+1. In the left sidebar, select the issue field you want to remove.
+1. Click **Remove field**.
+
+Removing an issue field from a project does not delete the field or its values from the organization. The field can be re-added at any time.
+
+## Editing issue field values in a project
+
+You can edit issue field values directly in the project table view without opening the issue. Click on a cell in the issue field column to set or change the value. Changes are synced back to the issue automatically.
+
+## Grouping, filtering, and sorting
+
+You can group, filter, and sort project views by issue field values, just like any other project field. This works in both table and board layouts.
+
+You can also use issue fields to group by column on the board layout.
+
+## Charts and insights
+
+Issue fields are available as data sources in project charts. You can create charts that group or segment by issue field values to visualize trends across your organization.
+
+## Limits
+
+Projects support up to 50 fields in total. Issue fields and system fields count toward this limit. If a project is already at the field limit, you need to remove existing fields before issue fields can be added.
+
+> [!NOTE]
+> Issue fields only apply to issues owned by the same organization. If a project contains pull requests, draft issues, or issues from another organization, issue field columns show empty cells for those items.

content/issues/planning-and-tracking-with-projects/understanding-fields/index.md

@@ -9,6 +9,7 @@ children:
   - /about-date-fields
   - /about-single-select-fields
   - /about-iteration-fields
+  - /about-issue-fields
   - /about-parent-issue-and-sub-issue-progress-fields
   - /about-pull-request-fields
   - /about-the-issue-type-field

content/issues/tracking-your-work-with-issues/using-issues/adding-and-managing-issue-fields.md

@@ -0,0 +1,88 @@
+---
+title: Adding and managing issue fields
+intro: 'You can set, edit, and clear issue field values on individual issues to capture structured metadata for your team.'
+versions:
+  feature: issue-fields
+type: how_to
+topics:
+  - Project management
+shortTitle: 'Using issue fields'
+permissions: 'People with triage access or greater to a repository can set and edit issue field values.'
+---
+
+{% data reusables.issues.issue-fields-public-preview-note %}
+
+Issue fields appear in the right-hand sidebar of issues, alongside system fields like assignees, labels, and type. You can set values when creating or editing an issue. When you select an issue type while creating an issue, any fields pinned to that type automatically appear in the sidebar.
+
+## Setting a field value
+
+1. Navigate to the issue you want to update.
+1. In the right sidebar, if the field you want is not already visible, click **Add field**.
+1. From the dropdown, select the field you want to add.
+1. Set the value:
+   * For **single-select** fields, choose an option from the dropdown.
+   * For **text** fields, type your value. URLs are automatically detected and displayed as links.
+   * For **number** fields, enter a numeric value.
+   * For **date** fields, use the date picker to select a date, or type the date directly.
+1. Changes are saved automatically.
+
+## Editing a field value
+
+1. Navigate to the issue.
+1. In the right sidebar, click on the field value you want to change.
+1. Select a new value or type a new entry.
+1. Changes are saved automatically.
+
+## Clearing a field value
+
+1. Navigate to the issue.
+1. In the right sidebar, click on the field value.
+1. Clear the value:
+   * For **single-select** fields, click the currently selected option to deselect it.
+   * For **text** and **number** fields, delete all text in the input.
+   * For **date** fields, click the clear button in the date picker.
+1. After clearing, the field is removed from the sidebar. It can be re-added using the **Add field** button.
+
+## Pinned fields
+
+If your organization administrator has pinned fields to specific issue types, those fields automatically appear in the sidebar and the issue creation modal when you create or view an issue of that type. You do not need to manually add pinned fields.
+
+## Viewing field changes in the timeline
+
+When a field value is changed, the update is recorded in the issue timeline. The timeline entry shows:
+* Which field was changed
+* The new value that was set
+* Who made the change
+* When the change was made
+
+Timeline events for fields set to "Organization only" visibility are hidden from users who are not organization members or collaborators.
+
+## Field visibility
+
+Organization administrators can set each field's visibility to "Organization only" or "Public". This affects what you see:
+
+* If a field is set to **Organization only**, it is only visible to organization members and repository collaborators with at least read access. If you are not a member or collaborator, the field does not appear in the issue sidebar, timeline, or search suggestions.
+* If a field is set to **Public**, it is visible to anyone viewing the issue.
+
+For more information about configuring visibility, see [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization#setting-field-visibility).
+
+## Using issue fields in projects
+
+Issue fields can be added as columns in project views, where you can edit values, group, filter, sort, and build charts. For more information, see [AUTOTITLE](/issues/planning-and-tracking-with-projects/understanding-fields/about-issue-fields).
+
+## Searching by field values
+
+You can filter and search for issues based on field values on both the issues dashboard and your repository's issues page. In the search bar, type `field.` followed by the field name and value. For example:
+
+* `field.priority:high` to find issues with priority set to "high"
+* `field."target date":>=2026-03-01` to find issues with a target date on or after March 1, 2026
+* `field.priority:high,medium` to find issues with priority set to "high" or "medium"
+
+For more information, see [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests).
+
+## Using issue fields with the API
+
+Issue fields have full REST and GraphQL API support. You can automate field management, set values programmatically, and integrate with external tools.
+
+- **Managing fields**: Create, update, and delete organization-level fields. See the [Organization issue fields REST API](/rest/orgs/issue-fields).
+- **Using fields**: Get, set, and clear field values on individual issues. See the [Issue field values REST API](/rest/issues/issue-field-values).

content/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests.md

@@ -144,6 +144,22 @@ If your organization uses issue types, you can filter issues for a particular ty
 
 {% endif %}
 
+{% ifversion issue-fields %}
+
+## Filtering by issue fields
+
+If your organization uses issue fields, you can filter issues by field values. Type `field.` followed by the field name and value in your filter. Field names with spaces should be enclosed in quotes.
+
+Examples:
+* `field.priority:high` -- find issues with priority set to "high"
+* `field."target date":>=2026-03-01` -- find issues with a target date on or after March 1, 2026
+* `field.story-points:>5` -- find issues with a number field value greater than 5
+* `field.priority:high,medium` -- find issues with priority set to "high" or "medium"
+
+For more information about managing issue fields, see [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization).
+
+{% endif %}
+
 ## Filtering pull requests by review status
 
 You can use filters to list pull requests by review status and to find pull requests that you've reviewed or other people have asked you to review.
@@ -222,7 +238,8 @@ For issues, you can also use search to:
 
 * Filter for issues that are linked to a pull request by a closing reference: `linked:pr`
 * Filter issues by the reason they were closed: `is:closed reason:completed` or `is:closed reason:"not planned"`
-{% ifversion issue-types %}* Filter for issues with a particular type: `is:open type:"Bug"`{% endif %}{% ifversion issues-advanced-search %}
+{% ifversion issue-types %}* Filter for issues with a particular type: `is:open type:"Bug"`{% endif %}{% ifversion issue-fields %}
+* Filter for issues by field value: `is:open field.priority:high`{% endif %}{% ifversion issues-advanced-search %}
 * Filter for issues that have metadata: `has:label`
 * Filter for issues that are missing metadata: `no:project`
 * Filter for issues from repositories [**owned**](/search-github/searching-on-github/searching-issues-and-pull-requests#search-within-a-users-or-organizations-repositories) by a certain user or organization, limited to up to 16 `user` and `org` qualifiers with no limit on `repo` qualifiers: `state:open is:issue org:github OR user:octocat`{% endif %}

content/issues/tracking-your-work-with-issues/using-issues/index.md

@@ -18,4 +18,6 @@ children:
   - /linking-a-pull-request-to-an-issue
   - /about-slash-commands
   - /managing-issue-types-in-an-organization
+  - /managing-issue-fields-in-your-organization
+  - /adding-and-managing-issue-fields
 ---

content/issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-your-organization.md

@@ -0,0 +1,134 @@
+---
+title: Managing issue fields in your organization
+intro: 'You can create and manage custom issue fields to collect structured metadata across all issues in your organization.'
+redirect_from:
+  - /issues/tracking-your-work-with-issues/using-issues/managing-issue-fields-in-an-organization
+versions:
+  feature: issue-fields
+type: overview
+topics:
+  - Project management
+shortTitle: 'Managing issue fields'
+permissions: 'Organization owners can create and manage issue fields.'
+---
+
+{% data reusables.issues.issue-fields-public-preview-note %}
+
+Issue fields let you add structured metadata to issues across your organization. Instead of relying on labels or free-text workarounds, you can create fields like priority, effort, impact, or any custom category your team needs. Fields are defined at the organization level and apply across all repositories in your organization.
+
+## About issue field types
+
+You can create up to 25 issue fields per organization. The following field types are available:
+
+* **Single-select**: choose one option from a predefined list. Options can have names, descriptions, and colors.
+* **Text**: capture free-form text. URLs are automatically detected and displayed as clickable links.
+* **Number**: accept numeric input, including decimals.
+* **Date**: provide a date picker for selecting dates.
+
+## Default fields
+
+When issue fields are enabled for your organization, four default fields are created automatically:
+
+* **Priority** (single-select): Urgent, High, Medium, Low
+* **Effort** (single-select): High, Medium, Low
+* **Start date** (date)
+* **Target date** (date)
+
+These default fields are fully customizable. You can edit their names, descriptions, and options, or delete them if they don't fit your workflow.
+
+## Creating an issue field
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Planning" section of the sidebar, click **Issue fields**.
+1. Click **New field**.
+1. Under "Field name", type the name of your new field.
+1. Optionally, under "Description", type a description to help others understand the purpose of the field.
+1. Under "Field type", select the type of field you want to create.
+1. If you selected **Single-select**, add options for the field:
+   * Click **Add option** and type the option name.
+   * Optionally, to set a color for an option, click {% octicon "kebab-horizontal" aria-label="open option menu" %} next to the option, click **Edit option**, choose a color, and click **Save**.
+   * Repeat to add more options.
+1. Under "Field Visibility", choose one of the following:
+   * **Permissions**: choose who can see the field and its value. Options are **Organization only** (default) or **Public**. This setting only applies to issues in public repositories.
+   * **Pin to types**: click {% octicon "pencil" aria-label="edit pinning" %} to choose which issue types show this field in the issue viewer and creator. Select one or more issue types, or "Issues without a type". Fields that are not pinned and have no value will stay hidden in the issue viewer and creator.
+1. Click **Create**.
+
+## Editing an issue field
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Planning" section of the sidebar, click **Issue fields**.
+1. To the right of the field you want to edit, click {% octicon "kebab-horizontal" aria-label="open field options" %}.
+1. Click **Edit** and make your changes.
+1. Click **Save field**.
+
+## Deleting an issue field
+
+When you delete an issue field, all values set on issues for that field are permanently removed.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Planning" section of the sidebar, click **Issue fields**.
+1. To the right of the field you want to delete, click {% octicon "kebab-horizontal" aria-label="open field options" %}.
+1. Click **Delete** and confirm the deletion.
+
+## Reordering issue fields
+
+The order of pinned fields is managed per issue type. The field order determines how fields appear in the issue sidebar and the issue creation modal.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Planning" section of the sidebar, click **Issue types**.
+1. Click the issue type you want to reorder fields for.
+1. Under "Pinned issue fields", drag fields to reorder them.
+1. Click **Save**.
+
+## Pinning fields to issue types
+
+You can associate issue fields with specific issue types so that only the most relevant fields appear when creating or viewing issues of that type. For example, you can pin "Severity" to bugs and "Impact" to features.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Planning" section of the sidebar, click **Issue fields**.
+1. Click the field you want to pin.
+1. Under "Pin to types", click {% octicon "pencil" aria-label="edit pinning" %} and select the issue types this field should appear on.
+1. Click **Save field**.
+
+Pinned fields automatically appear in the issue sidebar based on the selected issue type. To pin fields to issues that have no type, select the "Issues without a type" option.
+
+> [!NOTE]
+> Fields must be pinned to at least one issue type, or to "Issues without a type", to appear in the issue sidebar. Fields that are not pinned to any type are only accessible via the **Add field** button or in projects.
+
+## Setting field visibility
+
+For organizations with public repositories, you can control whether each issue field is visible to everyone or only to organization members and collaborators.
+
+{% data reusables.profile.access_org %}
+{% data reusables.profile.org_settings %}
+1. In the "Planning" section of the sidebar, click **Issue fields**.
+1. To the right of the field, click {% octicon "kebab-horizontal" aria-label="open field options" %}.
+1. Click **Edit**.
+1. Under "Field Visibility", choose one of the following:
+   * **Organization only**: the field is visible only to organization members and repository collaborators with at least read access.
+   * **Public**: the field is visible to anyone viewing the issue.
+1. Click **Save**.
+
+By default, all new and existing fields are set to "Organization only". Visibility settings are enforced across the web UI, API, issue timeline events, and search suggestions.
+
+## Issue fields and projects
+
+Issue fields are available in any project across your organization. For details on adding, removing, and editing issue fields in projects, see [AUTOTITLE](/issues/tracking-your-work-with-issues/using-issues/adding-and-managing-issue-fields#using-issue-fields-in-projects).
+
+### Field limits in projects
+
+Projects support up to 50 fields in total, and issue fields and system fields count toward this limit. If a project is already at the field limit, you need to remove existing fields before issue fields can be added.
+
+## Limits
+
+| Resource | Limit |
+|----------|-------|
+| Issue fields per organization | 25 |
+| Options per single-select field | 50 |
+| Pinned fields per issue type | 10 |
+| Total fields in a project (including issue fields and system fields) | 50 |

data/features/issue-fields.yml

@@ -0,0 +1,4 @@
+# Reference: github/releases#7336
+versions:
+  fpt: '*'
+  ghec: '*'

data/reusables/issues/issue-fields-public-preview-note.md

@@ -0,0 +1,2 @@
+> [!NOTE]
+> Issue fields are currently in {% data variables.release-phases.public_preview %} and subject to change. To share feedback, see the [community discussion](https://github.com/orgs/community/discussions/189141).