Build a scalable internal developer portal with Backstage and CircleCI

The power of IDPs

Internal developer portals (IDPs) have become essential tools in platform engineering, helping standardize developer workflows and reduce friction by providing self-service access to tools, APIs, and infrastructure.

During my time on a platform team, I experienced firsthand the transformative power of IDPs. Our team implemented custom solutions that significantly reduced load on developers, allowing them to focus on writing code rather than navigating complex infrastructure. That experience reinforced a key lesson: a great developer experience relies on minimizing friction and complexity. IDPs like Backstage, Cortex, and Port do exactly that.

Effective IDPs rely on CI/CD to automate the software delivery pipeline and provide developers with self-service capabilities. When you connect CircleCI with your Backstage IDP, you create a powerful developer experience where teams can independently build, test, and deploy without waiting for operations support. This tutorial guides you through linking these systems to reduce manual work and enforce quality standards, all while maintaining the consistency that platform teams need to effectively support multiple engineering teams.

IDP benefits for platform teams

Well-designed IDPs create a foundation for standardized, automated software delivery across your organization. When integrated properly, these systems offer several key advantages:

Standardization & reduced manual work: IDPs enforce consistent project setup across teams and automate repetitive workflows—from repository configuration to pipeline creation—letting developers focus on building applications rather than fighting with tooling.

Enhanced control with Developer Freedom: Platform teams gain visibility into service health and can enforce security policies while developers work within operational guardrails. This balance allows developers to move quickly without sacrificing compliance.

Simplified Onboarding: New developers can push code to production on day one through pre-configured templates and self-service documentation, eliminating lengthy learning periods for company-specific tooling.

Platform engineering toolkit: CircleCI & Backstage

CircleCI and Backstage complement each other perfectly for platform engineers. CircleCI provides robust CI/CD capabilities that handle complex workflows and deliver pipeline insights, while Backstage serves as the central hub for all developer resources.

When connected, these tools create a powerful developer ecosystem where platform teams can use Backstage’s Service Templates to create new projects with CircleCI pipelines pre-configured and ready to execute.

Step by step guide: Building an IDP

Let’s walk through how platform teams can configure Backstage to automate repository creation, CircleCI setup, and pipeline execution when developers need to create new projects.

Before You Begin

This tutorial assumes you have:

• A Backstage instance already configured
• A CircleCI account
• A GitHub, GitLab, or Bitbucket project set up in CircleCI
• Basic knowledge of both Backstage and CircleCI

Step 1: Configure application repository templates (Platform team)

The first step is to configure application repository templates that will provide a baseline for the development teams creating applications across your organization.

The baseline applications will also be accompanied by a standardized CircleCI configuration. For the purpose of this tutorial, we will assume the platform team wants the CircleCI configuration to live alongside the application code, but it is also possible to manage your pipeline configurations from a centralized repo.

Let’s take a look at what the tree structure looks like for the frontend and backend applications inside the application template repository.

With the above structure, the platform team has provided a baseline for various programming languages across backend and frontend applications in their organization.

On top of that, CI/CD configuration will also be provided in the form of a CircleCI config file (.circleci/config.yml). Here’s a look at the complete template for the Node frontend project.

Step 2: Set up a Backstage template catalog (Platform team)

The next step in this process involves creating a template catalog and importing it into Backstage. This catalog allows developers to choose from your predefined repository templates when they need to create new projects.

By taking this approach, you can ensure your team is always using standardized application templates, preconfigured with optimized CI/CD pipelines. which significantly reduce manual configuration and onboarding time.

The template catalog will be stored in a version control system. Our example is titled backstage-software-catalog. Here’s what a basic template catalog looks like:

Take a look at our template for configuring a node-frontend application and setting it up on CircleCI. You’ll notice it has 3 key steps:

1. Fetch

The fetch step is responsible for retrieving a pre-configured Node.js frontend template from a specified GitHub repository. Using the fetch:plain action, this step downloads the necessary files from a template located at the provided GitHub URL. In this case, it pulls the template for a Node.js service from the frontend-templates/node directory in the repository.

2. Publish

Once the template is fetched, the publish step takes over to upload the template to a new GitHub repository. This is achieved using the publish:github action, which takes the template files from the workspace and pushes them to the newly created repository, defined by the repoUrl and repoName parameters. It also automatically sets the default branch to main and provides a description for the repository.

3. Set Up CircleCI

The Set Up CircleCI step integrates the newly created GitHub repository with CircleCI for CI/CD. This step utilizes a custom shell command that triggers an API call to CircleCI, specifically using the CircleCI API to “follow” the newly created GitHub repository. This action automates the process of connecting repositories to CircleCI, eliminating the need for manual setup and configuration of each project’s CI/CD pipeline.

Step 3: Register a template on Backstage (Platform team)

Assuming your Backstage instance is configured, the next step involves adding the templates you created in step 2 to your Backstage catalog. On the homepage of your company catalog, click create.

Next, click register existing component. In the below screenshot I’ve added a few different example templates to Backstage.

To register an existing component, or template in our case, you must provide the URL to the source code repo containing the backstage template configured in step 2.

After you click register, enter the URL and click analyse. Review the entity you are about to add to the catalog before clicking import. If the import was successful, you should see a window similar to the screenshot below.

If you navigate to the template catalog, you should see your newly added template.

From here, you can dive deeper to see the source code and the relationships that each template has.

Step 4: Launch a template (Developer)

Now that you’ve set up a template catalog and registered your first template in Backstage, the next step is to put on your developer hat and launch the template. This will:

• Create a repository on GitHub
• Set up the project on CircleCI
• Run the first pipeline with the config.yml file provided in the repository template

You can launch the template by clicking launch template in the template view shown in the screenshot above, but most developers will start from the homepage. Under My Company Catalog, click create:

Then choose the template that you created in the previous step. In our case, that is the Node.js Template Frontend

Next, you will need to populate the parameters in the template. In my case, I used the following values:

Parameter	Value	Description
Name	The Field Engineering Frontend Node Application	Unique name of the component
Owner	stone-monkeys	The organization, user or project that this repo will belong to
Repository	fe-frontend-node-app	The name of the repository
CCI Token	**************	CircleCI API Token

Note: The CircleCI API Token can be provided in two ways:

1. Manually entered by developers during template execution (useful for testing or one-off deployments)
2. Pre-configured as part of the Backstage application setup (recommended for production environments to avoid repeated token entry and improve security)

Once all that information is filled out, quickly review the project that you are about to create.

After successful execution of your template, you should see a window similar to the following.

You should also see that the repository has been created in GitHub.

Now for the exciting part: navigate to CircleCI, and you should see that the project was set up and configured, and the first pipeline run with the provided CircleCI config.

This integration between Backstage and CircleCI eliminates bottlenecks in the development workflow, allowing developers to focus on writing code rather than configuration. For platform teams, it provides the control needed to maintain quality and compliance while giving developers the self-service capabilities they need to move quickly. The result is faster delivery cycles and a more productive engineering organization.

Extra: Abstract the CircleCI configuration away from developers

If you want to go one step further and completely abstract the need for your developers to interact with CI/CD configuration, that is now possible on CircleCI. The good news is that it is also very easy to do once you have stepped through the above process.

All you need to do is:

1. Remove the .circleci folder from your application template repository in step 1.
2. Reregister the template (step 3) so that it uses the latest application template

You should now notice that a repository was created without any CircleCI config.

The project will be created and set up on CircleCI, but no pipeline will be executed as there is no configuration in the project repo.

To set up the pipeline using config from a different repository, you will want to create a simple multi-repo project. You can follow along with our blog post and video tutorial to learn the benefits of this setup and how you can configure it via the Github App.

Conclusion: Empowering devs by enabling platform engineers

The key to a best in class software organization that outperforms its competition is reducing developer time to value. By combining CircleCI with an IDP such as Backstage, platform engineering teams can create a frictionless developer experience that enforces best practices and accelerates delivery.

With standardized templates, automated repo creation and preconfigured CI/CD pipelines, organizations can build a developer first culture where innovation thrives - ensuring teams move fast while staying within the guardrails. The result? Happier developers, faster time to market, and a more resilient engineering ecosystem, all powered by CircleCI’s scalable CI/CD platform.

Ready to propel your organization forward with a modern developer platform? Sign up for a free CircleCI account or reach out to our team for a personalized demo.