> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/internal-developer-portal/3.0/troubleshooting-and-resources/adoption-guide/adoption-playbook.md).
# Harness IDP Adoption Playbook
**A step-by-step implementation guide for adopting Harness Internal Developer Portal at scale.**
Harness Internal Developer Portal (IDP) is a unified home for developers to create, manage, and explore software. It enables teams to:
* Quickly create software components aligned with organizational best practices.
* Manage existing components with developer-centric views that consolidate service health, deployments, alerts, and documentation.
* Discover internal tools, APIs, and services for enhanced collaboration.
* Measure and enforce maturity standards using Scorecards for Service, DevOps, and Security best practices.
The goal of this playbook is to provide actionable guidance, helping engineering leaders and platform teams achieve a successful IDP rollout.
### Top 10 IDP use cases
These are the 10 standard use cases for Harness Internal Developer Portal:
| # | Use Case | Description |
| -- | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| 1 | **Service Ownership Tracking** | Establish clear accountability by associating services with designated owners, enhancing transparency and reducing ambiguity. |
| 2 | **Workflow Automation** | Minimize repetitive tasks by automating processes, eliminating the reliance on "TicketOps." |
| 3 | **Self-Service Application Onboarding** | Streamline the onboarding process for new applications, reducing delays and errors. |
| 4 | **DevOps Workflow Automation** | Enable self-service provisioning for repositories and CI/CD pipelines, empowering developers to work autonomously. |
| 5 | **Self-Service Infrastructure Provisioning** | Offer on-demand infrastructure creation capabilities, reducing bottlenecks. |
| 6 | **Enhanced Discoverability** | Centralize and improve access to internal tools, APIs, and technical documentation. |
| 7 | **Docs-as-Code** | Promote collaboration and knowledge-sharing through code-driven documentation processes. |
| 8 | **Service Maturity Enforcement** | Monitor and enhance service quality with Scorecards evaluating DevOps, security, and service maturity. |
| 9 | **Migration Tracking** | Gain real-time insights into software migrations across the organization’s catalog, ensuring alignment with strategic goals. |
| 10 | **Developer Onboarding** | Equip new hires with easy access to essential resources, accelerating their ramp-up time. |
Since IDPs have traditionally been built from scratch, few other use cases can address their needs. However, they are often harder to implement and adopt.
### Adoption mindsets
When it comes to adopting an Internal Developer Portal (IDP), organizations generally approach it with one of the two mindsets: the **Platform-First Mindset** or the **Developer-First Mindset**. While both have their merits, our research shows that a Developer-First Mindset leads to significantly higher adoption success.
#### Platform-First mindset
This mindset is driven by the platform engineering team’s desire to standardize and optimize the organization’s developer platform. It often stems from recognizing gaps in existing systems, such as:
* A lack of robust catalogs for service discovery.
* The absence of comprehensive scorecards to measure service or DevOps maturity.
* Poor visibility into CI/CD processes and other observability dashboards.
While these goals are valid and can improve overall efficiency, a Platform-First Mindset risks overlooking the immediate, tangible needs of developers. If the primary focus is on building a portal as part of a broader platform strategy without addressing everyday developer pain points, the adoption may struggle. Projects with this mindset often face challenges such as:
* Limited early engagement from developers due to perceived misalignment with their pain points.
* Feedback loops that highlight a lack of practical utility, resulting in stalled adoption efforts.
* Risk of project abandonment if initial traction and developer buy-in are insufficient.
#### Developer-First mindset ✅
A Developer-First Mindset, on the other hand, focuses on solving the real, day-to-day challenges that developers face. This mindset emphasizes:
* Simplifying application and developer onboarding.
* Reducing friction by automating repetitive tasks.
* Making standards and best practices easily accessible and actionable.
Organizations with this mindset prioritize developer utility and aim to address common pain points, such as overwhelming and fragmented tools and inefficiencies that delay developers’ ability to ship code.
By putting developers at the center, this approach fosters higher engagement and more enthusiastic adoption.
#### Recommendation
To achieve maximum success with IDP adoption, you should strive for a Developer-First Mindset. Focusing on developer utility ensures that the portal delivers tangible value to the end users (Developers), making it an indispensable part of their daily workflow. By addressing developer pain points first, you can build trust and momentum, leading to broader adoption and long-term viability.
### Developer daily utility
Developer Daily Utility is the most critical metric for IDP adoption. It reflects the portal's integration into developers’ daily workflows. Without frequent engagement, even a configured Catalog with Plugins, Scorecards, and Workflows will not sustain adoption.
Ensure IDP addresses daily needs of your developers like quick access to services, real-time insights, and simplified workflows. It should also seamlessly connect with existing tools like IDEs and CI/CD pipelines.
Harness tracks "Monthly Active Users" (MAU) as an indicator of engagement. You can find all IDP Adoption details in the built-in dashboard. We highly recommend setting up weekly alerts to this dashboard so that you can keep track of adoption in your inbox.
[Check out IDP Adoption Dashboard](/internal-developer-portal/troubleshooting-and-resources/adoption-guide/how-to-track-adoption.md)
### Adoption flywheel
There are five main phases of a successful rollout of an Internal Developer Portal
1. Research: Understand Why and What
2. Setup: Establish Stakeholders and Metrics
3. Prioritize: Find top problems and early users
4. Deliver: Implementation
5. Assess: Collect feedback and adjust plan
#### 1. Research
The research phase identifies why your organization needs IDP and what it should provide. Evaluate the current development environment. Identify inefficiencies, visibility gaps, and workflow bottlenecks. Focus on high-impact problems that justify adopting IDP. Ensure they align with developer priorities. Avoid adoption driven only by trends or competitor activities.
Pitfalls to avoid:
* Do not look out for an IDP just because you see others in the industry doing so. Identify your own unique challenges in improving developer experience and evaluate if that is one of the top IDP use-cases as defined above.
* After identifying DevEx problems, understand their frequency and return on investment (ROI). If a problem occurs once a quarter or once a year, IDP might not be the answer. A frequent problem can become a daily utility.
#### 2. Setup
This phase has two main goals
1. Identify owners and stakeholders
2. Identify success criteria and KPIs
**Owners and stakeholders**
Usually the Internal Developer Portal initiative is owned by the Head of Developer Experience or the Head of Platform Engineering. If these organizations do not exist, then it falls back to the DevOps team. Sometimes, IDPs are also owned by SREs.
You should have one to two platform engineers who understand the product. They should have Software Development Lifecycle experience in your organization. Go to [Get started with Harness IDP](/internal-developer-portal/3.0/new-to-idp/get-started.md) to understand Harness Platform, Catalog, Scorecards, and Workflows.
You should also have a platform product manager. Their main responsibility is collecting developer feedback, creating a roadmap, and promoting launched solutions. If you do not have one, an engineering manager or director can assume this part-time responsibility. Ensure someone creates the feedback loop with developers and stakeholders. This should not be the platform engineers implementing IDP.
After you identify the central team that owns IDP, work with stakeholders such as:
* DevOps (CI/CD)
* Infrastructure
* Engineering Architects
* Application security
Share responsibilities with stakeholders from these teams. Invite them to provide Workflows, create Scorecards, and set IDP standards. Otherwise, tool fragmentation can affect your IDP rollout.
**Success criteria and KPIs**
Measure and track developer experience key performance indicators (KPIs) that align with your IDP initiative. Monthly Active Users, onboarding speed, and developer satisfaction are examples. Use business-aligned metrics where available. You can also start with DORA metrics. Run a biannual survey where developers score productivity from `0` to `100`. Consider [Harness Software Engineering Intelligence](https://www.harness.io/products/software-engineering-insights) to measure developer effectiveness.
#### 3. Prioritize
Start small by focusing on a few teams and avoid overpromising features to thousands of developers. You need to identify your early users and understand their top DevEx problems. This product strategy is well explained in [Crossing the Chasm curve](https://en.wikipedia.org/wiki/Crossing_the_Chasm#/media/File:Technology-Adoption-Lifecycle.png) by Geoffrey Moore.
For example, start with two teams of 10 developers, for a total of 20 people. They might have a common problem that requires significant manual time. They can provide early feedback. For example, debugging a customer issue might require a Jira ticket, access, infrastructure provisioning, and other tasks. The process can take several hours each week. Automate the process while retaining approval gates for platform engineers.
Another use case is helping developers manage Jira tickets and pull requests. One portal can show their tickets, created pull requests, and pull requests requiring review.
The most common use case is letting developers find owned software and relevant dashboards in one place.
Your early users will care about the problems you solve. Offer solutions that fit their daily workflows.
#### 4. Deliver
Most work takes place in this phase. Use Harness IDP features such as the Catalog, Self Service Workflows, Plugins, Scorecards, and IDP Pipelines. Integrate with existing tools and provide an easy-to-use experience.
If the work involves configuring the Catalog, ask the team’s technical leads for owned software details. Do not automate too much. Provide repeatable self-service patterns.
This approach is similar to how anyone builds features for their customers. Their experience should be your top priority.
#### 5. Assess
After you have a solution, return to the teams that identified the problems. Have them use the product. This establishes trust. Use their feedback to bring implemented use cases to other teams.
Celebrate this early success with other teams and your stakeholders. Build excitement in what you are building and the problems you are solving.
And this kicks off your adoption flywheel. You will continue to expand to more teams and solve more Developer Experience problems.
### Timeline and rollout strategy
An iterative approach to IDP adoption ensures continuous improvement and avoids the pitfalls of overcommitment. A suggested timeline includes:
* **First 3 Months**: Engage 25% of target users, focusing on core use cases and quick wins.
* **3–6 Months**: Expand adoption to 50% by incorporating additional use cases and addressing early feedback.
* **6–9 Months**: Achieve 75% adoption through iterative refinements and team-wide rollouts.
* **Beyond 9 Months**: Stabilize utilization at 70–75% across the organization’s developer base.
IDP adoption works best in cycles with expanding teams and use cases. Do not implement all use cases in three to six months before releasing to developers. Longer implementation delays developer feedback and can negatively affect IDP adoption.
A much more successful approach is to find early adopters and important use-cases. Then release early and release often.
### Visibility-first vs automation-first
IDP adopters commonly follow one of two archetypes:
* **Visibility-first**: They focus a lot on showing things to users, enhancing discoverability by centralizing documentation, tools, and APIs. As well as creating Scorecards. These are all the “Explore” use-cases.
* **Automation-first**: They focus a lot on simplifying processes by automating workflows and repetitive tasks. These are all the “Create” and “Manage” use-cases.
Automation-first adopters often succeed because they can solve individual use cases progressively. However, these use cases might not drive repeated use. For example, a developer might not create infrastructure every day.
Maintain a balance between visibility and automation approaches.
### Golden path to adoption
Use these steps to onboard IDP. Do not skip steps unless they are marked optional.
1. **Core Harness Platform Setup**
1. SSO, Users and User Groups, RBAC, Hierarchy, Secret Manager, Delegate, etc.
* *Docs and Tutorials for Reference:* [Platform access control](/harness-ai/use-harness-platform/platform-access-control.md), [RBAC in IDP](/internal-developer-portal/3.0/admin-and-customization/rbac/rbac.md), [Delegates](/harness-ai/use-harness-platform/delegates.md), [Secrets Management](/harness-ai/use-harness-platform/secrets/secrets-management.md)
2. **Setup Git Integrations**
* *Docs and Tutorials for Reference:* [Setup Git Integration](/internal-developer-portal/3.0/new-to-idp/get-started.md)
3. **Your first Self Service Workflow**
1. Remove TicketOps, focus on quick automation use-cases. Ask your Platform Teams - what is the most common type of JIRA ticket they receive
* *Docs and Tutorials for Reference:* [Getting Started with Workflows](https://github.com/iKettles/harness-gitbook/tree/main/3k-internal-developer-portal/new-to-idp/get-started/step-3-workflows.md), [Self Service Workflows Overview](/internal-developer-portal/3.0/use-idp/self-service-workflows/overview.md)
4. **Your first Service Onboarding Workflow**
1. Standardize how a new Backend or Frontend application gets created with CI/CD pipelines and infrastructure included
* *Docs and Tutorials for Reference:* [Create a service onboarding pipeline](/internal-developer-portal/3.0/use-idp/self-service-workflows/workflows-tutorials/java-onboarding-pipeline.md)
5. **Your first Catalog Components**
1. Onboard Applications, Services, APIs or Libraries owned by your first users/teams
* *Docs and Tutorials for Reference:* [Register a Software Component in Catalog](/internal-developer-portal/3.0/use-idp/software-catalog/manage-catalog.md)
6. **First TechDocs**
1. Enable TechDocs for one of those applications where documentation is available in markdown.
2. You can also choose to onboard central documentation such as engineering handbooks if you have those written in Markdown (docs-like-code approach)
* *Docs and Tutorials for Reference:* [Enable documentation for your Component](/internal-developer-portal/3.0/use-idp/software-catalog/integrate-tools/techdocs/enable-docs.md)
7. **First few Catalog Plugins**
1. Look at the IDP Plugins Marketplace and enable up to 5 plugins which are the most commonly used tools in your organization.
* *Docs and Tutorials for Reference:* [List of curated plugins supported in the Internal Developer Portal](/internal-developer-portal/3.0/use-idp/plugins/available-plugins.md)
8. **Your First Scorecard**
1. Create a “Catalog Readiness” Scorecard which can help you ensure that the Catalog entries are fully updated and all annotations required by the Plugins are set
* *Docs and Tutorials for Reference:* [Getting Started with Scorecards](/internal-developer-portal/3.0/use-idp/scorecards/create-scorecards/create-scorecard.md)
9. **Invite your early users ✉️**
1. Send invites to 10-20 users that you have identified as early adopters. Collect feedback
10. **Setup Metadata Ingestion**
1. Use Catalog Ingestion API to auto-fill some of the details that your early users don’t want to provide manually
* *Docs and Tutorials for Reference:* [Catalog Ingestion API](/internal-developer-portal/3.0/use-idp/software-catalog/integrate-tools/catalog-ingestion-api.md)
11. **Your first Custom Plugin (Optional)**
1. Create a small widget on the Catalog to show some application metadata which is hard to find today for your developers
* *Docs and Tutorials for Reference:* [Overview of custom plugins](/internal-developer-portal/3.0/use-idp/plugins/custom-plugins/overview.md)
12. **Setup Weekly IDP Adoption Dashboard Updates**
1. Ensure you are subscribed to receive weekly adoption reports from IDP.
* *Docs and Tutorials for Reference:* [Adoption Dashboard](/internal-developer-portal/3.0/admin-and-customization/platform-dashboards/custom-dashboards.md)
After completing these steps, onboard more teams, solve new use cases, onboard their Catalog Components, and build more Workflows.
### Miscellaneous adoption tips and tricks
* Create an internal Slack/Teams channel called **#harness-idp-adoption**. Announce new features and ask users to share feedback (both good and bad).
* Use one portal. Avoid fragmenting developer IDP use cases.
* Onboarding is not the same as Adoption. Onboarding refers to one or more Platform Engineers setting up the tool with Authentication, Authorization and other configuration. Adoption refers to active usage by Developers. Onboarding is a prerequisite to Adoption.
#### Central vs distributed catalog definition YAML files
Catalog completeness is key to a successful Internal Developer Portal (IDP). Choose the right approach for managing `catalog-info.yaml` files. The following centralized and distributed strategies both work with Harness IDP.
Start with all IDP YAML files in one Git repository. After onboarding, move to a distributed model where team leads manage their Catalog YAML files.
**Centralized catalog management**
In this approach, all catalog definition YAML files are stored in a single centralized repository. You can manage all YAML files without waiting for pull request approvals from dozens of teams.
Most IDP functionalities such as Scorecards and plugins use an annotation under `metadata` to reference the source code, ensuring documentation, scorecard evaluations, and dependency analysis works seamlessly, even when the YAML file is not colocated with the service. This is made possible by using the `backstage.io/source-location` annotation, which links the catalog entry in the central repository to the actual source repository of the components.
Here is an example annotation:
```yaml
## Example catalog-info.yaml
...
annotations:
backstage.io/source-location: url:https://github.com/org/service-repo
...
```
**Implementation Details:**
1. Repository Setup:
Create a dedicated repository named idp-catalog or similar, containing all `catalog-info.yaml` files. Structure the repository with directories representing teams or projects. For example:
```bash
/catalog/
team-a/
service-a/catalog-info.yaml
service-b/catalog-info.yaml
team-b/
service-c/catalog-info.yaml
```
**Distributed catalog management**
Catalog definition YAML files are stored within each component's own repository, allowing teams to manage their own catalog entries. By colocating the `catalog-info.yaml` file with the service's code, the `backstage.io/source-location` annotation becomes redundant for most operations because the source code and metadata are already in the same repository. If necessary, the `backstage.io/source-location` annotation can be made to point to additional repositories or locations related to the service.
**Implementation Details:**
1. Repository Setup: Each service repository should include the `catalog-info.yaml` file at the root of the repository.
```bash
/service-repo/
catalog-info.yaml
docs/
src/
```
**Harness IDP tools for catalog population**
1. **Automation Script for Bulk Onboarding:**
Harness provides a [Python script](/internal-developer-portal/3.0/use-idp/software-catalog/tutorials/migrate-catalog-scripts/catalog-scripts.md) that automates the generation and registration of `catalog-info.yaml` files across multiple repositories. This script is particularly useful for organizations aiming to onboard many services simultaneously.
**Key Features of the Script:**
* *Automated YAML Generation:* Scans your repositories to generate catalog-info.yaml files automatically.
* *Batch Registration:* Registers multiple services into the catalog in a single operation.
* *Customization:* Allows filtering repositories using regex patterns to target specific services.
2. Harness IDP’s [**Create Catalog**](/internal-developer-portal/3.0/use-idp/self-service-workflows/create-workflow/harness-pipeline.md#4-create-catalog), [**Direct Push**](/internal-developer-portal/3.0/use-idp/self-service-workflows/create-workflow/harness-pipeline.md#5-direct-push), and [**Register Catalog**](/internal-developer-portal/3.0/use-idp/self-service-workflows/create-workflow/harness-pipeline.md#6-register-catalog) steps let teams onboard services into the catalog through workflows.
### Resources and support
* [Harness IDP Documentation](/internal-developer-portal/3.0/readme.md)
* [Getting Started](/internal-developer-portal/3.0/new-to-idp/get-started.md)
* Ask a Question or Report a Bug using [Harness Support](https://www.harness.io/support)
* Submit feature requests using [Harness Ideas Portal](https://ideas.harness.io)
* [IDP Roadmap](https://developer.harness.io/roadmap#idp)
* Keep up with [Release Notes](/release-notes/internal-developer-portal.md) for new feature announcements
This playbook supports sustainable IDP adoption and long-term value. You can download the content as a PDF and reuse it internally to discuss Harness IDP.