Turn a GitHub Project into a Reusable Template with gh

You will finish with an organisation-owned GitHub Project marked as a template, plus a checked command to remove that status again. This guide uses GitHub CLI gh 2.87.3, the version installed on the reference machine. The command talks to GitHub and changes remote project metadata. It does not create a copy of the project or alter its fields and items.

Allow about ten minutes. You need gh, a signed-in GitHub account, access to the target organisation, and the project number. No root access is required. The relevant token scope is project.

1. Check the account and scope

Start by confirming which account gh will use:

$ gh auth status

Look for the active account and its token scopes. The installed account may authenticate successfully while still lacking the scope needed to change a Project. If project is absent, request it explicitly:

$ gh auth refresh -s project

This may open a browser or ask you to complete a device flow. It changes the local CLI token, not the Project. Checkpoint: run gh auth status again and confirm that project is listed before continuing.

2. Identify the organisation and project number

The positional number identifies the Project. The --owner value identifies its organisation, and the command's help describes this as the organisation owner login. Do not substitute a repository name or a Project title.

List the organisation's Projects to find the number:

$ gh project list --owner "EXAMPLE_ORG"

Replace EXAMPLE_ORG with the organisation login and record the number shown for the intended Project. If you need a closer look before making the change, view that Project:

$ gh project view PROJECT_NUMBER --owner "EXAMPLE_ORG"

Use a numeric value such as 7, not the visible title. This matters when an organisation has similarly named Projects. A project list or view is read-only; it is a useful checkpoint before the state-changing command.

3. Mark the Project as a template

When the owner and number are confirmed, run:

$ gh project mark-template 7 --owner "EXAMPLE_ORG"

The command marks Project 7 as a template. GitHub can then present it as a starting point for creating Projects with the same structure. The exact success text is not part of the command's interface, so treat exit status 0 as the reliable shell-level success signal:

$ gh project mark-template 7 --owner "EXAMPLE_ORG"
$ printf 'exit status: %s\n' "$?"
exit status: 0

Do not add sudo. This is an authenticated API operation, not a local filesystem operation. If the command fails, read the error before retrying: a wrong owner, wrong number, insufficient organisation access, missing project scope, or a GitHub API error needs a different fix.

4. Choose output only when automation needs it

By default, keep the command simple and use its exit status. The command also accepts --format json, --jq, and --template. The latter two are formatting filters for JSON output, not alternative ways to select the Project.

For a script that needs machine-readable output, request JSON and filter it:

$ gh project mark-template 7 --owner "EXAMPLE_ORG" --format json --jq '.number'

Only use a field that the command returns on the installed CLI and API host. If a filter gives no value, rerun without --jq to inspect the JSON rather than treating an empty result as proof that the operation failed.

5. Undo the change

Marking a Project as a template is reversible. If you selected the wrong Project, or no longer want new Projects based on it, remove the template status with the same owner and number:

$ gh project mark-template 7 --owner "EXAMPLE_ORG" --undo
$ printf 'exit status: %s\n' "$?"
exit status: 0

--undo unmarks the Project. It does not delete the Project, remove its items, or restore another Project created from it. Confirm the target carefully before running either form: using the wrong number changes a different Project, and the command has no dry-run flag.

Common failure points

• Permission denied or unauthorised: check gh auth status, refresh the project scope, and confirm that the account can administer Projects for the named organisation.
• Project not found: repeat gh project list --owner "EXAMPLE_ORG". A Project number is scoped by its owner, so the same number under another owner is a different target.
• Unexpected output: remove --jq or --template. Those flags are for formatting JSON, and the command documents --format json as the output mode they use.
• Repeated command: stop and check the result before retrying. A successful mark is a state change even if a wrapper or terminal hides its output.