Add a Custom Field to a GitHub Project

A board full of issues with nowhere to record risk or a target date is a board that stops being useful the moment the sprint gets busy. This guide adds one named custom field to a GitHub Project with gh project field-create and checks that it actually exists afterwards. Allow about five minutes if you already know the project number and have a working GitHub CLI login.

Before you start

• You need: the gh command, access to the target project, and its numeric project number.
• Your token needs the project scope. Check the installed version and authentication without touching project data:

$ gh --version
$ gh auth status

The exact version and account details depend on this machine. If authentication reports the token lacks the project scope, refresh it as GitHub directs, then run gh auth status again. Do not paste a token into a command or an article. No root or sudo access is needed anywhere in this guide.

1. Identify the project

List projects for the owner you intend to change. Replace OWNER with a GitHub login, organisation login or @me:

$ gh project list --owner OWNER

Use the number in the first column, not the project title. A project number is scoped to its owner, so pairing it with the wrong owner can select a different project entirely, or simply fail before anything is created.

Checkpoint: list the existing fields before creating a new one, and search the output for the name you plan to use.

$ gh project field-list PROJECT_NUMBER --owner OWNER

This command is read-only. A field with the same purpose may already exist under a slightly different name, and creating another one will not merge or rename it for you.

2. Create a text, number or date field

Choose one of the data types this command accepts: TEXT, SINGLE_SELECT, DATE or NUMBER. The type is baked into the field definition, so decide it before running the command. Here is a date field on project 12, owned by the current user:

$ gh project field-create 12 --owner "@me" --name "Target date" --data-type "DATE"

For a numeric estimate, change only the name and type:

$ gh project field-create 12 --owner "@me" --name "Estimate" --data-type "NUMBER"

The command prints the created field in its normal output. For machine-readable output, request JSON explicitly:

$ gh project field-create 12 --owner "@me" --name "Estimate" --data-type "NUMBER" --format json

Do not run both examples unless you genuinely want two fields. The second command is another create operation, not an update to the first.

3. Create a single-select field

For a controlled list such as a work queue, supply the options as one comma-separated value:

$ gh project field-create 12 --owner "@me" --name "Risk" --data-type "SINGLE_SELECT" --single-select-options "Low,Medium,High"

Keep the option string quoted so the shell passes it as one argument. This flag only applies to SINGLE_SELECT fields; do not add it to a text, number or date field. If an option itself needs a comma, this interface has no separate escaping mechanism for it, so pick a label without one.

4. Verify the field

List the fields again and check for the name and type:

$ gh project field-list 12 --owner "@me"

For a script or a focused review, use JSON output and a jq filter. The exact response fields can vary with the GitHub API, so inspect the unfiltered JSON first rather than assuming a property name:

$ gh project field-list 12 --owner "@me" --format json

Checkpoint: the field is ready when it appears in this list with the intended type and, for a single-select field, the intended options.

Common traps and recovery

• Missing project number, wrong owner or an inaccessible project normally fails the command without creating a field. Re-run gh project list --owner OWNER, copy the correct number and check the owner spelling.
• Authentication or scope error? That needs an account or token correction, not sudo.
• Wrong name or type? Stop and inspect it with gh project field-list. Creation has no undo flag.
• Deleting instead of fixing: gh project field-delete removes a field, but that is destructive and may remove its values from project items too. Do not delete it until you have confirmed the field ID and accepted that loss; if you only need a different label or value, use the normal project editing workflow instead.

Done means

• You confirmed the owner and project number before running anything.
• You checked the existing field list first, so you are not duplicating a field.
• You picked one supported type: text, single-select, date or number.
• You created the field with the required name and, where relevant, comma-separated options.
• You confirmed it afterwards with gh project field-list.
• You have not deleted or duplicated a field while troubleshooting.