Replacing Port self-service actions with Backstage Software Templates
Backstage Software Templates and scaffolder actions cover most of the request-and-provision flows that a platform team currently runs as Port self-service actions, such as creating a repository, provisioning an environment or scaffolding a service from a standard skeleton. Approvals, long-running jobs and some third-party integrations are the parts that need custom work: they typically require a custom scaffolder action, a backend plugin or an external runner such as a CI pipeline that the template triggers and reports back to. Port's actions are a feature of a SaaS product, so the logic runs on Port's side. A Backstage template is code your team owns, versioned in Git and executed in your own infrastructure. The rest of the Port suite, including its catalog integrations and scorecards, does not have to move at the same time, and you can decide per capability whether to keep it, replace it or retire it.
Start by inventorying every action in your Port portal: the trigger, the inputs, the systems it writes to, the people who must approve it and the typical run time. Sort them into three groups: actions a stock scaffolder action can perform, actions that need a custom action or plugin, and actions better handled by a pipeline that the template calls. Confirm the approval model with your security and change management owners before you build, because Backstage does not ship a generic approval workflow that matches every Port setup. Check which scaffolder actions and plugins your target Backstage release includes by reading the release notes for the version you plan to adopt, and confirm how the portal's service account authenticates to each downstream system. Treat the first template as a pilot, and record its audit trail, since that evidence is what your compliance team will ask to see.
Which Backstage option fits which action type
Port's self-service actions cover several kinds of request, and each kind maps to a different Backstage mechanism. The cards below separate what Software Templates handle out of the box from what needs custom code, external runners or an approval layer you design yourself. Use them to sort your current action list before estimating build effort.
Software Templates with built-in actions
Software Templates are Backstage's built-in way to scaffold new components, repositories and catalog entries from a form. They run scaffolder steps that create files, publish to a Git host and register the result in the Software Catalog. This fits requests that create a new service or repository from a standard skeleton. Check which built-in steps match your Git host and CI system, since the steps you need may depend on plugins you still have to install and maintain.
Custom scaffolder actions for internal APIs
When a request must call an internal API, such as provisioning a database account or reserving a DNS name, you write a custom scaffolder action in TypeScript and register it in the backend. This keeps the call inside the template so the developer never leaves the portal. The trade-off is ownership: your platform team maintains the action through every Backstage upgrade, and it needs its own tests, credentials handling and error reporting. Ask who will own each action before you write it.
Plugins that surface run status
A template that starts a job tells the developer only that the job began unless a plugin shows the outcome. Status views in the portal, such as CI build state linked from the catalog entity, let developers follow a request without asking the platform team. Plugin availability differs by CI system and version, so confirm the plugin exists for your tooling and that it is maintained against your Backstage release line before you commit to it.
External CI or workflow runners
Many actions are better run by an existing pipeline than inside the Backstage backend, especially long jobs, jobs that need privileged runners, or jobs your CI team already owns. A template can trigger a pipeline in your CI system and pass the parameters as inputs. The cost is a second system to monitor, with its own credentials, retries and logs. Confirm that your CI system can accept an external trigger with scoped credentials, and that failures return to the portal.
Custom approval flows
Port's self-service actions can require sign-off, and Backstage does not ship an equivalent approval workflow. You can build one from Backstage permissions to restrict who can run a template, or connect an external approval system that holds the request until a named approver responds. Each option needs a decision on who approves, how approval is recorded for audit, and what happens when an approver is unavailable. Test the full path with an illustrative change request before going live.
Infrastructure requests with external state
Requests that create cloud resources, such as a bucket or a cluster namespace, need a system of record for the state they produce. A template can write the request to infrastructure as code and let a pipeline apply it, which keeps Backstage out of cloud credentials. The trade-off is that the portal shows the request while the pipeline holds the truth, so you need a link back to the applied state. Confirm who can change the code path and how drift is detected.
How approvals and backend runners work in a self-hosted portal
Approvals, long-running provisioning and secret handling are not a single switch in Backstage. A Software Template runs as a sequence of steps in the scaffolder backend, and each step is an action that either does work inside the portal or calls out to another system. That means the approval model is a design decision you make, not a setting you turn on. The first decision is where the approval lives: inside the portal with custom code, in an existing ticketing or change system, or in the pipeline that does the provisioning. Pick one before you write the first template, because the other two choices depend on it.
Approving inside the portal means building the gate yourself, typically as a custom action or a plugin that holds a request until an authorized person signs off. This gives the tightest experience for developers but puts approval logic, audit records and escalation rules in code your platform team owns. Delegating to a ticketing or change system keeps the approval record where auditors already look, at the cost of an integration and a slower loop for developers. Running provisioning in CI or an infrastructure runner, with the portal only triggering the job, moves long-running work and credentials out of the scaffolder process. Confirm how your chosen runner reports status back to the template run before you rely on it for anything that takes longer than a request.
Access control for every one of these paths depends on who the portal thinks the requester is. The Backstage authentication documentation recommends configuring sign-in resolvers so that every identity provider resolves to the same user, and not offering guest access in production. If a developer can sign in through two providers that map to two identities, permission checks on templates and actions can be inconsistent. Confirm the scaffolder and permission APIs against the Backstage release you plan to run, since both change across releases, and test an approval path end to end in a non-production instance before any team depends on it.
What needs custom plugins and what does not
Many self-service actions are a sequence of standard operations: create a repository from a skeleton, write catalog files, open a pull request, and register the new component in the software catalog. Backstage Software Templates express these as a template with parameters and steps that run in the scaffolder. Because the scaffolder ships with built-in actions for common work, these flows need templates and skeleton content, not new plugins. The work is mostly authoring and review of YAML and skeleton files.
- Template parameters: Form fields that replace Port's action inputs map to the
parameterssection of a template, with schema validation for each field. - Repository and catalog steps: Built-in actions cover publishing to supported Git hosts and registering the result, so teams can reuse them across templates.
- Skeleton content: Files such as
catalog-info.yamland pipeline definitions are rendered from skeletons, which keeps each new service consistent. - Effort drivers: The number of distinct templates and how many shared skeletons they reuse. Fewer templates with shared skeletons means less maintenance.
Before you migrate, list each Port action and check whether its steps exist as built-in scaffolder actions in your Backstage version, and confirm the exact action names against the current documentation.
Some actions call systems the scaffolder does not know, such as an internal cloud account service, a ticketing API, or a cost allocation system. In Backstage, you implement these as custom scaffolder actions, which are code packaged in a backend module, or as a plugin that exposes the needed API to templates. Each internal system adds an integration to build, test, secure and upgrade, so the cost grows with the number of systems rather than the number of actions.
- Custom scaffolder actions: One action per internal call, with typed inputs and outputs, is the usual pattern for a single system.
- Credentials handling: Service credentials for each internal API should come from your secrets store, not from template files, and should be scoped to the action.
- Shared actions: Several templates calling the same internal API should reuse one action so the integration is maintained once.
- Effort drivers: How many internal systems are involved, how stable their APIs are, and whether they have test environments that the portal can use.
Ask your internal platform owners which APIs each action calls and whether those APIs offer service accounts and non-production endpoints.
Actions that require sign-off, or that must record state across several systems, need more than a template run. A template run is a single execution of steps, so approval gates, waiting for a human decision, and tracking a request across days typically need an external workflow or a custom plugin with its own state. Port's approval and action run history features have no direct one-to-one equivalent in a default Backstage setup, so confirm which features your team needs before designing the replacement.
- Approval rules: Decide who approves which request types, whether approvals depend on values in the request, and how emergency changes are handled.
- Run state and history: Long-running requests need a record of each step, its inputs and its result, stored in a database that survives restarts.
- Audit requirements: Auditors may ask who requested, who approved, and what changed. Design the log fields and retention period with your compliance team before building.
- Effort drivers: The number of approval paths, whether approvers work in another tool, and how many systems hold state for one request.
Confirm your approval and audit requirements in writing first, then decide whether a Backstage plugin, an external workflow engine or a ticketing integration best fits them.
Splitting the Port action inventory into these three groups gives a practical basis for a fixed scope. Start by listing every action, its trigger, the systems it touches, and its approval rule. Actions that fall in the first group can usually move early. Actions in the other two groups need design decisions and owners before build work starts, because those decisions drive most of the effort.
- Inventory: Export the action definitions from Port and record the systems and approvers each one uses.
- Classification: Tag each action as built-in, internal API or approval-driven.
- Prioritization: Move high-volume, low-risk actions first to prove the pattern.
- Ownership: Name an owner for each internal API integration and each approval path.
- Operations: Custom plugins need upgrades as Backstage releases, so plan ongoing maintenance.
For a quote, ask the implementation partner to base the scope on this classification and to state which actions are excluded and why.
Questions buyers ask before replacing Port actions
How much effort does a template-per-action migration from Port take?
Effort depends mainly on how many self-service actions Port runs today, how many distinct backends they call, and how much of each action's logic lives in Port's own workflow setup rather than in code you control. Each action usually becomes a Backstage Software Template with a set of parameters, a sequence of scaffolder steps, and a call into the systems it provisions. Actions that call one existing pipeline are quick to port. Actions that combine several approvals, cloud accounts and custom validation need custom scaffolder actions or plugins. Ask any vendor for an inventory of actions, their inputs, their targets and their approval rules before agreeing on a fixed scope, since that inventory is what drives the quote.
Can our own platform team do this migration without outside help?
Yes, if the team already knows TypeScript or Node.js, runs CI and infrastructure as code, and has an owner for the developer portal. Backstage is a framework, so the team writes templates, scaffolder actions and plugins in code and maintains them. Teams with no prior Backstage experience usually spend early effort learning the catalog model and plugin structure before they can migrate anything. Many organizations split the work: internal engineers own the catalog and business logic, while an outside implementation partner handles architecture, hardening and cutover. DeployOpen plans, implements and supports self-hosted platforms like this under a written, fixed scope, so you can choose either path.
What costs come with running Backstage instead of Port?
Port's subscription is a recurring vendor fee. Backstage has no license fee, since Backstage is Apache-2.0 licensed and the CNCF project has no paid edition. The costs shift to people and infrastructure. One-time costs include design, template and plugin development, and migration. Recurring costs include infrastructure for the Backstage backend and its PostgreSQL database, CI for the portal's own code, plugin maintenance, and upgrades. Backstage's versioning policy describes a main release line shipped monthly and a next release line shipped weekly, so budget for regular upgrade work. Ask any quote to separate build, run and upgrade effort, and to state who is paid for each.
How does approval work for self-service actions in Backstage?
Backstage does not provide a built-in approval workflow for Software Templates, so approvals are implemented through the surrounding tools. Common patterns include requiring a pull request review on a generated repository, routing requests through an existing ticketing or change system via a scaffolder action, or gating the final pipeline run behind a protected environment in your CI system. Access to each template should be restricted through the permission system in your deployment, and you should confirm which permission and RBAC options your chosen plugins support. Document the approval path for each action before migrating it, because approvals are the part buyers most often underestimate.
Can Backstage run in an isolated, air-gapped network?
Yes, Backstage is open source and can be deployed in a network with no internet access, provided you mirror its dependencies. You need a container registry, a package mirror for npm packages, and internal copies of any templates, documentation builds and external data sources. Authentication must point at an identity provider you run inside the network. Plan for offline dependency updates, since the release cadence means you will regularly fetch new versions into the isolated environment. Confirm each plugin's external calls before you rely on it offline, because some plugins fetch data from SaaS endpoints by default.
What must our team supply before the migration starts?
Backstage depends on systems you already run, so the inputs are largely a checklist. You need an identity provider for sign-in, such as one of the built-in providers in the authentication documentation, and sign-in resolvers that map every provider to the same identity. You need Git hosting for templates and catalog files, a CI system that runs the scaffolded pipelines, and APIs or credentials for each infrastructure target such as cloud accounts, Kubernetes clusters or ticketing tools. You also need a PostgreSQL database and a place to host the portal. Confirm the owners and access model for each of these before scoping, since missing inputs are a common cause of delay.
How do we request a fixed-scope quote for this migration?
Send a written inventory of your Port self-service actions, including each action's inputs, target systems, approval rules and current owner, along with your identity provider, Git and CI systems, and the environments where Backstage must run. Include whether the deployment must work offline and which compliance evidence you need to produce. DeployOpen agrees scope, deliverables and timelines in writing before work starts, and most engagements are fixed-scope. DeployOpen does not publish a price list, so a quote follows from that written scope. Ask for the quote to list one-time build work, run and upgrade effort, and the items your team owns.
Migrating Port actions to Software Templates in phases
This sequence moves each Port self-service action to a Backstage Software Template in controlled stages, so requests keep working for developers while approvals, audit trails and backend runners are verified before Port actions are switched off.
Inventory every Port action and its backend
A platform engineer exports the list of self-service actions from the Port configuration and records, for each one, the request inputs, the team that owns it and the system that does the work, such as a Terraform run, a CI pipeline, a ticket queue or a script on a server. Use the export steps in your Port workspace and confirm the current definitions with the Port admin who maintains them. The step is done when every action has a row in a shared sheet with its owner and backing system.
Classify each action by how it runs
Sort the inventory into three groups: actions Port runs itself with built-in behavior, custom actions that call your own webhook or service, and actions that depend on an external runner such as a CI system or an automation server. Each group implies a different Backstage path. Built-in behavior usually needs a scaffolder action or an existing plugin, custom calls need a custom action or plugin, and external runners need a defined trigger and status feedback. The step is done when each action carries one of the three labels and the team has agreed on the list.
Build templates for the simplest requests first
The platform team starts with the actions that have few inputs and a single backend, such as creating a repository from an approved skeleton or provisioning a standard test namespace. Each becomes a Software Template with a
template.yamlfile, a parameter form and scaffolder steps that call the same backend Port used. Test each template in a non-production Backstage instance and compare the output with what Port produced for the same inputs. The step is done when a sample request in staging produces the same resources and records as the Port action.Add approvals and audit logging
Before any template reaches developers, the security and platform owners define who may run each action, which requests need a second approver and where the run history is stored. Backstage Software Templates do not provide a single approval workflow out of the box, so confirm with your identity team how group membership is passed through sign-in resolvers and which approval mechanism your organization will use, such as a pull request gate or an external workflow tool. Check that each run is recorded with the requester, inputs and result. The step is done when a test run by a user outside the approver group is blocked and the audit record for a successful run can be retrieved.
Move templates to the backend runners
Where an action depended on an external runner, connect the template to that runner through the scaffolder or a custom plugin and confirm that Backstage can start the job and read its status. Decide whether to keep the runner as it is or move its logic into the scaffolder, based on how often it changes and who maintains it. Confirm credentials are held in your secrets store and not in template files. The step is done when each external-runner template completes end to end in staging and reports success or failure back to the requester.
Run Port and Backstage side by side
Publish the Backstage templates to a limited group of teams while Port keeps serving everyone else. Compare request volumes, failure rates and support tickets for both paths over an agreed period, and collect feedback from the teams using each. Keep a rollback route to Port for each action until the new path has proven stable. The step is done when the platform owner signs off that the Backstage path handles the agreed request types without manual fixes.
Retire Port actions and keep the evidence
Disable each Port action once its Backstage template is accepted, starting with the simplest group. Remove the action definitions from Port only after the audit records and runner logs are confirmed to be kept in your own systems. Store the inventory, approval rules and test results with the migration record so auditors or security reviewers can trace each action to its replacement. Confirm with your Port contract owner which data and licensing obligations continue after the subscription changes. The step is done when every action in the inventory is marked retired with a link to its template and evidence.
Cost components when replacing Port actions with Backstage
The license line disappears, but the cost of replacing Port's self-service actions with Backstage Software Templates moves into components you pay for directly. Backstage itself is Apache-2.0 licensed and has no paid edition from the project, so the recurring cost is the infrastructure, the people who build and maintain the portal, and any third-party services you choose to connect. Expect four groups: a one-time build of templates and custom scaffolder actions, the design of approvals, the infrastructure for the portal and its PostgreSQL database, and recurring plugin maintenance and upgrades. Platform team time spans all four and is usually the largest line.
The one-time build cost grows with the number of actions Port performs today. Each action that only calls a REST API and creates a repository or ticket is a small template job. Actions that need a custom backend runner, a new plugin, or an integration with an internal system take longer and need owners who can support them later. Approval design is a separate cost because Backstage does not give you Port's approval flow out of the box; you decide whether approvals live in your Git provider's review process, a ticketing system, or a custom step, and each choice has its own build and audit effort. Ask for a written scope that lists each action, the system it touches, who approves it, and whether it needs a new plugin.
Recurring costs follow the upgrade cadence. The Backstage versioning policy describes a monthly main release line and a weekly next line, and high and critical vulnerabilities are backported to releases from the last six months where feasible, so plan staff time for regular upgrades and for patching custom plugins that depend on Backstage internals. Infrastructure is driven by how many users sign in, how many catalog entities you sync, and whether you run a highly available PostgreSQL service. Confirm with your team the Node.js versions your chosen Backstage release supports, because that affects your build pipeline. Ask any implementation partner to price upgrades and plugin maintenance separately from the initial build so you can compare them with Port's subscription.
How DeployOpen scopes and delivers a Port actions replacement
A Port actions replacement is a set of connected pieces: the portal, its Software Templates, the approval path and the backend that runs each action. DeployOpen agrees the scope of each piece in writing before work starts, so the client knows what is built, hardened, tested and handed over.
Written scope before any work
Engagements are fixed-scope. Before work starts, the scope, deliverables and timeline are agreed in writing, including which Port actions are in and which are retired. Ask for the inventory of existing self-service actions, the systems each one touches and the acceptance criteria for each template. A written scope is the basis for a quote, so vague scope is the main cause of cost surprises.
Self-hosted Backstage implementation
DeployOpen plans and installs the Backstage portal inside the client's own cloud accounts, data centers or isolated networks. This covers the catalog, the database layout, the identity provider integration and the Git and registry connections that templates need. Confirm early which Node.js and Backstage versions the client will standardize on, and who owns upgrades after handover.
Custom template and action work
Port's self-service actions usually map to Software Templates and scaffolder actions, but some need custom actions or plugins, for example a call to a ticketing system or a cloud API that no existing action covers. DeployOpen builds and tests these custom pieces and documents their inputs, outputs and permissions. Ask which actions are standard and which are bespoke, because bespoke work drives most of the build effort.
Approvals and access hardening
Actions that create environments or change production need approval paths, sign-in resolvers that map each identity provider to one user, and no guest access in production. DeployOpen configures these controls and checks that a developer cannot run an action beyond their group's rights. Confirm which approvers exist for each action class before the build starts.
Security testing of portal and actions
DeployOpen tests the portal, its APIs and the actions it can trigger, including attempts to escalate privileges through template parameters and to reach backend credentials. Findings are reported with reproduction steps and fixes are retested. Ask whether testing covers the scaffolder's downstream systems as well as the portal, since those systems are where a template's effect lands.
Documentation, handover and retainers
DeployOpen documents the templates, runbooks, configuration and access model so the client's platform team can maintain them. Ongoing upgrades, support and continuous testing are available as retainers after handover. DeployOpen prepares evidence for compliance assessments but does not issue audit reports or certifications, so ask which independent auditor the client will use.
