Setting up custom fields for issues in SourceCraft

With custom fields, you can add additional parameters to 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 and/or all repositories 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

Here is the basic structure of .sourcecraft/issues.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.

        Warning

        The slug value must not match the system field ID of the issue.

      • type: Custom field type. The possible values are:

        • string: String.
        • number: Double-precision floating-point number.
        • datetime or date: Date and time in RFC 3339 format. The two options are equivalent. We recommend using datetime.
        • user: SourceCraft user ID.
        • 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 .

      • 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

You can create the .sourcecraft/issues.yaml file in the SourceCraft UI 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.

  2. Create the .sourcecraft/issues.yaml file with a custom issue field configuration.

    Configuration example
    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

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

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

  4. Create or open an issue on a separate page and make sure the issue form displays your custom fields.

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.

Configuring fields at the organization level

To use common custom fields across all repositories of the organization, create a dedicated .sourcecraft repository 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. The file structure is the same as that used for a single repository.

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.

Useful links

Previous
Searching, filtering, and sorting issues
Next
Working with a milestone