Creating a Team

Learn how to create a Team in Harness IDP using the visual editor, YAML, Git import, or the Entity API.

You can create a Team from the Harness IDP user interface, from YAML, by importing an existing definition from Git, or through the Entity API. All four methods produce the same entity.

---

Before you begin

Prerequisite	Details
Permissions	You need Create/Edit permission on the Teams resource at the scope where you want to create the Team. Go to Team access control for details.
Scope	Decide whether the Team belongs at the Account, Organization, or Project scope. Go to Scopes to review what each scope means.
Parent team	If this Team is a sub-team, the parent Team must already exist at the same scope or at a parent scope.

---

Create a Team from the user interface

There are two entry points.

• Go to Teams in the IDP sidebar and click + Create.

• Go to Catalog, click + Create, and select Team under For Platform Engineers.

Create menu with the Team option

Step 1: Fill in the basic details

Create Team form

Field	Required	Description
Name	Yes	The display name of the Team, for example Payments Platform. The identifier is generated from the name and can be edited using the pencil icon.
Type	Yes	A classification for the Team, for example team or squad. Select an existing type or enter a new one.
Parent Team	No	The Team that this Team reports into. Leave this empty for a top-level Team.
Leader	No	The person who leads the Team. Setting this creates a hasLeader relation from the Team to the user, visible in the Catalog graph. In YAML, this maps to spec.leaders.
Members	No	The users who belong to the Team. A Team can be created with no members and populated later.
Team email address	No	A shared contact address for the Team, for example [e-mail].
Description	No	A short explanation of what the Team is responsible for.
Tags	No	Labels used for filtering and discovery in the Catalog.

Step 2: Define the scope

Under Define Scope, choose where the Team lives.

Scope	Behavior
Account	The Team is created at the account level and is accessible by all organizations and projects by default.
Organization	The Team is created at the organization level and is accessible by all projects in that organization by default.
Project	The Team is created at the project level and is accessible only by users added to that project. Select the project from the Select a Project list.

HOW THE PARENT TEAM LIST IS BUILT

The Parent Team list is scope-aware. A Team can take sub-teams from its own scope or from any child scope. For example, a Team at the Organization scope can have sub-teams that live in different projects inside that organization. It cannot take a sub-team from a parent scope.

Step 3: Choose where to store the Team

Under Where to store the Team?, select one of the following.

• Inline: The Team definition is stored in Harness and is managed entirely through the user interface or the API. This is the default.

• Remote: The Team definition is stored in your Git repository. Select a Git connector, repository, branch, and YAML path. Go to Git Experience Journey to learn more.

If you already have a Team definition in Git, click Import from Git at the top of the page instead of filling in the form.

Step 4: Review the YAML and create the Team

Click Review YAML to see the generated definition. The visual view and the YAML view stay in sync, so a change in one is reflected in the other.

Review YAML step of the Create Team flow

Check the YAML Validation panel, then click Create Team.

Ensure your identifier follows the identifier naming rules. An invalid identifier causes the entity registration to fail.

---

Create a Team using YAML

You can write the definition yourself instead of using the form. Switch to the YAML view using the toggle at the top of the Create Team page, or use the Entity API with kind set to Group.

apiVersion: harness.io/v1
kind: Group
type: team
identifier: payments_platform
name: Payments Platform
spec:
  members:
    - user:account/[e-mail]
    - user:account/[e-mail]
  leaders:
    - user:account/[e-mail]
  parent: group:account/platform_engineering
  profile:
    email: [e-mail]
metadata:
  description: Owns the payment gateway, settlement services, and their APIs.
  tags:
    - payments
    - platform

Field reference

Field	Description
apiVersion	Always harness.io/v1.
kind	Always Group. This is the entity kind that backs a Team.
type	A classification for the Team, for example team, squad, or department.
identifier	The unique reference for the Team.
name	The display name shown in the Catalog.
spec.members	The users who belong to the Team, referenced as user:account/<email>.
spec.leaders	The Team leader, referenced as user:account/<email>.
spec.parent	A reference to the parent Team, which creates the hierarchy.
spec.profile.email	The shared contact address for the Team.
metadata	Description, tags, and any additional key-value pairs you want to carry on the Team.

If you are bringing entity definitions across from Backstage, keep kind: Group in your YAML. Harness IDP accepts it without modification.

You do not need to declare child teams. When you set spec.parent on a Team, Harness IDP generates the reverse relations automatically, so both childOf and parentOf are visible in the Catalog graph.

---

Add more information to a Team

Beyond the fields above, a Team can carry any metadata that is useful to your organization, such as a region, a focus area, or an on-call rotation. You can add these directly under metadata in the YAML, or push them from an external system. Go to Team metrics and scorecards to learn how.

---

Next steps

• Manage Teams and assign ownership

• Configure Team access control