---
metadata:
  - name: generator
    content: Diplodoc Platform v5.66.0
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/issue-custom-fields.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/issue-custom-fields.md
  - href: https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/issue-custom-fields.md
    type: text/markdown
    title: Markdown version
  - href: https://sourcecraft.dev/portal/docs/en/llms.txt?revision=r21973087
    rel: describedby
title: Setting up custom fields for issues in SourceCraft
description: How to set up custom fields for issues at the repository and organization levels in SourceCraft using the `.sourcecraft/issues.yaml` file.
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt?revision=r21973087


# Setting up custom fields for issues in SourceCraft

With custom fields, you can add additional parameters to [issues](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#issues), i.e., a scheduled start date, estimated effort, or work stage. The field configuration is stored in the `.sourcecraft/issues.yaml` file in the default branch.

You can set up custom fields for issues in an [individual repository](#configure-repository) and/or [all repositories](#configure-organization) of the organization.

Custom fields are displayed as a single list on the full issue page. The fields are listed in the same order as in the configuration.

## Configuration of .sourcecraft/issues.yaml {#spec}

Here is the basic structure of `.sourcecraft/issues.yaml`:

```yaml
issues:
  custom_fields:
    - slug: <field text ID>
      type: <string, number, datetime, date, user, or value from issues.custom_types.slug>
      title: <field name in SourceCraft UI>
      description: <field text description>
      default: <default field value or value from issues.custom_types.values.slug>
      visibility: public
    ...
  custom_types:
    - slug: <text ID of custom field type>
      kind: enum
      title: <custom type name>
      description: <type text description>
      values:
        - slug: <option text ID>
          title: <option name in SourceCraft UI>
          description: <option text description>
        ...
    ...
```

Where:
* `issues`: Root block of the specification. The following nested items are allowed:
  * `custom_fields`: List of custom issue fields.
    * `slug`: Field text ID.

      {% note warning %}

      The `slug` value must not match the [system field ID](https://sourcecraft.dev/portal/docs/en/api-ref/Issues/GetIssue.md#body) of the issue.

      {% endnote %}

    * `type`: Custom field type. The possible values are:
      * `string`: String.
      * `number`: [Double-precision floating-point number](https://en.wikipedia.org/wiki/Double-precision_floating-point_format).
      * `datetime` or `date`: Date and time in [RFC 3339](https://www.rfc-editor.org/rfc/rfc3339) format. The two options are equivalent. We recommend using `datetime`.
      * `user`: SourceCraft user [ID](https://sourcecraft.dev/portal/docs/en/api-ref/User/GetProfile.md#body).
      * A value from the `issues.custom_types.slug` section for a choice of one of the preset options.
    * `title`: Field name in the SourceCraft UI.
    * `description`: Field text description displayed in ![image](../../_assets/console-icons/circle-question.svg).
    * `default`: Default field value. For a field with preset options, set this to `issues.custom_types.values.slug`.
    * `visibility`: Field visibility. The only supported value is `public`, i.e., the field value is visible to users who have access to the issue.
  * `custom_types`: List of custom field types.
    * `slug`: Text ID of custom field type.
    * `kind`: Kind of custom field type. The only supported value is `enum`, which stands for a choice from several preset options.
    * `title`: Type name.
    * `description`: Type text description.
    * `values`: List of possible options.
      * `slug`: Option text ID.
      * `title`: Option name in the SourceCraft UI.
      * `description`: Option text description.

## Setting up custom fields for issues in a repository {#configure-repository}

You can create the [.sourcecraft/issues.yaml](#spec) file in the [SourceCraft UI](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/add-file-repo.md#create) or on a local machine. When creating a file in the UI, add the configuration according to the example below and save your changes to the default branch.

To configure custom fields for issues locally:

1. [Clone the repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/repo-clone.md).
1. Create the [.sourcecraft/issues.yaml](#spec) file with a custom issue field configuration.

    {% cut "Configuration example" %}

    ```yaml
    issues:
      custom_fields:
        - slug: planned_start_date
          type: datetime
          title: Planned start date
          description: Planned start date for works on the issue
          default: null
          visibility: public
        - slug: effort
          type: effort
          title: Effort
          description: Estimated effort represented as garment size (XS to XXL)
          default: m
          visibility: public
        - slug: testing_status
          type: testing_status
          title: Testing status
          description: Testing progress status for this issue
          default: not_tested
          visibility: public
        - slug: stage
          type: stage
          title: Issue stage
          description: Current issue lifecycle stage
          default: discovery
          visibility: public
      custom_types:
        - slug: effort
          kind: enum
          title: Effort
          description: Estimated effort represented as garment size
          values:
            - slug: xs
              title: XS
              description: Extra small issue
            - slug: s
              title: S
              description: Small issue
            - slug: m
              title: M
              description: Medium issue
            - slug: l
              title: L
              description: Large issue
            - slug: xl
              title: XL
              description: Extra large issue
            - slug: xxl
              title: XXL
              description: Issue you might want to break down into smaller ones
        - slug: testing_status
          kind: enum
          title: Testing status
          description: Testing progress status
          values:
            - slug: not_tested
              title: Not tested
              description: Testing not started yet
            - slug: testing
              title: Testing
              description: Testing in progress
            - slug: needs_changes
              title: Needs fixes
              description: Problems were discovered
            - slug: done
              title: Done
              description: Testing successfully completed
        - slug: stage
          kind: enum
          title: Issue stage
          description: Current issue lifecycle stage
          values:
            - slug: discovery
              title: Discovery
              description: The issue is at the discovery stage
            - slug: development
              title: Development
              description: The issue is at the development stage
            - slug: review
              title: Review
              description: The issue is at the review stage
            - slug: prestable
              title: Stabilizing
              description: The issue is mostly stabilized
            - slug: internal_prod
              title: Internal production
              description: The issue is in internal production
            - slug: external_prod
              title: External production
              description: The issue is in external production
    ```

    {% endcut %}

1. Add the file to the Git index, commit, and push the changes to the default branch:

    ```bash
    git add .sourcecraft/issues.yaml
    git commit -m "Add custom issue fields"
    git push origin <default_branch>
    ```

1. [Create](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/issue-create.md) or open an issue on a separate page and make sure the issue form displays your custom fields.

{% note warning %}

If the configuration contains errors, custom fields are not displayed when creating or editing an issue. The already created issues will retain the custom parameters you set previously. The custom fields will become available again once the configuration is fixed.

If you remove a field from the configuration, it will stop being displayed, including among the parameters of previously created issues. However, the field values are retained and will start being displayed again if you later add a field with the same `slug` as before to the configuration.

{% endnote %}

## Configuring fields at the organization level {#configure-organization}

To use common custom fields across all repositories of the organization, [create a dedicated `.sourcecraft` repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/org-config.md#create-repo) and add the `.sourcecraft/issues.yaml` file to its default branch. You can create the file in the SourceCraft UI or locally, same as [for a single repository](#configure-repository). The file structure is the same as that used for a single repository.

<!-- source: en/_includes/sourcecraft/custom-issue-fields-org-repo-configuration.md -->
The repository configuration takes precedence over the organization configuration. If an object with an identical `slug` exists in both configurations, the repository settings apply. The `enum` value lists from the repository configuration completely replace the organization lists.

On the issue page, organization fields are displayed first, followed by repository fields. The order within each group matches the order defined in the relevant `.sourcecraft/issues.yaml` file.
<!-- endsource: en/_includes/sourcecraft/custom-issue-fields-org-repo-configuration.md -->

#### Useful links {#see-also}

* [Setting up an organization's access policy in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/org-policies.md)
* [Creating an issue in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/issue-create.md)
* [Working with issues in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/issue-work.md)
* [Setting up repository configurations as code](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/configuration-edit.md)
* [Configuring organization settings as code in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/org-config.md)