This guide takes 7 minutes to complete, and aims to demonstrate the potential of a developer portal for you and your developers.
The goal of this guide
In this guide we will model a repository from your Git provider in Port, using your real data.
After completing it, you will get a sense of how your organization's daily routine could look like:
- Developers will be able to see all the services in the organization and their relevant metadata.
- Developers will be able to follow the organization's standards for production readiness.
- R&D managers will be able to get a bird's eye view of the organization's production readiness.
- Platform engineers will be able to customize Port to curate the developer's and R&D manager's experience.
1. Sign-up to Port
Head over to app.getport.io and create an account.
2. Create your first blueprint!
Blueprints are one of Port's basic building blocks, used to represent any data source in your infrastructure.
We will now create a
Service blueprint to model a Git repository on Github/Bitbucket.
- Go to your Builder, click on the
Addbutton in the top right corner, then choose
Click on the
Edit JSONbutton in the top right corner. Here you can define a blueprint and its properties using JSON.
Replace the example content with the following definition, then click
Blueprint JSON (click to expand)
"title": "Repository URL",
Congratulations, you have successfully modeled a basic Git repository 🥳
You can now see the blueprint in your
Now let's connect our blueprint to a data source and fill it with real data!
3. Ingest data into your repository
- To export and sync data from Github or BitBucket, Port provides a simple application. Choose your preferred provider and install the app:
Make sure to install the app in the entire organization (and not in a single repository). This way Port will automatically create entities for all repositories.
Once installed, you will see new data sources in the
Data Sources tab of the builder page, waiting to be used (may take a few seconds to appear):
- Finally, we need to map the desired information from our Git provider's API to the properties of the blueprint we created in Port. For this guide, we will provide you with mapping so you do not need to do anything yourself. If you want to dive further into this, see Port's Git integrations.
Data sources tab, click on the exporter you installed. In the
Mapping tab paste the following snippet (choose your Git provider), then click
Save & Resync:
Github blueprint mapping (click to expand)
- kind: repository
BitBucket blueprint mapping (click to expand)
- kind: repository
Gitlab blueprint mapping (click to expand)
- kind: project
identifier: .path_with_namespace | gsub(" "; "")
language: .__languages | to_entries | max_by(.value) | .key
Now head back to your
Catalog, and go to the
Services page. We can see that Port has created entities for us representing our repositories, filled with real data: 🥳
Clicking on a service name in the table will take us to its entity page:
As you can see, Port has pulled the repository's name, url and language, and its readme file is displayed in a new
README tab in the entity page.
4. Set standards using scorecards
In this step we will see how to set metrics for our resources.
Let's add a scorecard to the
- Head over to the
Builderpage and double-click on the blueprint. Choose the
Scorecardstab, then click on
- Replace the contents with the following JSON and click
Scorecard JSON (click to expand)
"title": "Production Readiness",
"title": "Has readme",
What we have just done is add a "Bronze" level metric that ensures all
Services have a readme file.
Going back to the entity we created in our
Catalog, we can see that its
Scorecards tab displays our new metric. Since our repository has a readme file, we pass with flying colors:
What more can you achieve with scorecards?
- Evaluate the maturity & producton readiness of your services.
- Enforce the standards that matter to you (e.g. ensure each service has an on-call defined).
- Track DORA metrics.
- Define thresholds (gold/silver/bronze) and prioritize metrics & KPIs.
5. Customize views and dashboards
Port is designed to be very flexible when it comes to data visualization and presentation.
Let's create a simple new view for our service (and future services):
- Head back to the
Servicespage in your
Catalog. Click on
Group byand choose
Production Readinessfrom the dropdown:
This table is now grouped by the scorecard we created in the previous step.
Say you really like this view, and want your developers to see the
Services table in this format. Notice that the
Save this view button is now enabled?
- Click on
Save this view, then click on
Save as a new page:
Choose a name and icon, and click on
Services page is now created in your
Catalog. You can further customize views and create pages in any way that suits you.
Create a dashboard
Dashboards allow you to visualize data that interests you and your developers.
Let's create a simple pie chart showing the language distribution in our services:
- Go to the
Hometab of your Port app.
- In the top-right corner, click on
- Fill the form out like this, then click
You will now see a pie chart with the number of services and their language distribution in the
Home tab of your Port app:
This is just an example, in a real-life environment with many different resources you can visualize more complex data based on any property in any of your blueprints.
Hopefully you now have a basic grasp of what you can do with Port, but this is just the tip of the iceberg. With Port's full suite of features, you can create a truly powerful, personalized developer portal.
- Self-service actions guide (~7 minutes)
Increase your developers' productivity and independence by creating powerful actions for them to use.