Skip to main content

Documentation Index

Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Technical reference documentation and frequently asked questions.

​
Template Structure

A Portal Scaffolder template consists of three main sections:
Template structure overview

​
Form Fields (Input)

Form fields define what information users provide when running a template.
Form fields example
Common field types:
  • Text input
  • Dropdown/select
  • Checkbox
  • Radio buttons
  • Text area
  • Number input
Field properties:
  • name: Unique identifier for the field
  • type: Field input type
  • title: Display label
  • description: Help text for users
  • default: Default value (optional)
  • required: Whether field is mandatory
  • validation: Validation rules

​
Actions (Execution Steps)

Actions define the operations performed when the template runs.
Actions configuration
Common actions:
  • catalog:register: Register entities in the Software Catalog
  • github:create: Create a new GitHub repository
  • fetch:template: Fetch and process template files
  • publish:github: Publish files to a GitHub repository
  • Custom actions: Organization-specific actions
Action configuration:
  • id: Unique identifier for the action
  • name: Display name
  • action: Action type to execute
  • input: Parameters for the action

​
Extensions

Extensions enhance template functionality with custom logic.
Extensions configuration
Extension types:
  • Filters: Transform data (e.g., lowercase, uppercase, parseJson)
  • Functions: Custom functions for complex operations
  • Values: Reusable values and constants

​
Template Modes

​
Draft Mode

  • Templates in draft mode are only visible to the creator
  • Can be edited freely without affecting users
  • Not discoverable in the main templates list
  • Ideal for development and testing

​
Published Mode

  • Templates are discoverable by all users
  • Can be run by anyone with appropriate permissions
  • Still editable (changes apply to next execution)
  • Recommended to test thoroughly before publishing

​
Dry Run Feature

Dry run mode simulates template execution without creating actual resources. What it does:
  • Validates template configuration
  • Processes user inputs
  • Shows what resources would be created
  • Displays expected output
What it doesn’t do:
  • Create actual repositories
  • Register catalog entities
  • Make any permanent changes
  • Execute external API calls
When to use dry run:
  • Testing new templates
  • Validating configuration changes
  • Training users on template usage
  • Debugging template issues

​
Execution Logs

When running a template, logs provide real-time feedback:
  • Info logs: General progress updates
  • Debug logs: Detailed execution information
  • Warning logs: Non-critical issues
  • Error logs: Failures and problems
Execution logs
Accessing logs:
  • Automatically displayed during execution
  • Click Show Logs to view detailed output
  • Logs persist after execution completes
In progress view with logs

​
Repository Visibility

When creating repositories through templates:
  • Public: Visible to everyone
  • Private: Only visible to organization members
  • Internal: Visible to enterprise organization (if applicable)
Visibility is typically set via form field or template configuration.

​
Frequently Asked Questions

​
General Questions

Q: What’s the difference between the Portal Scaffolder and the legacy Scaffolder? A: The Portal Scaffolder provides a complete in-Portal experience for creating, editing, and managing templates without leaving the UI. The underlying Backstage Scaffolder model remains the same, but all lifecycle operations are now available directly in Portal. Q: Can I import existing Backstage templates? A: Yes, you can create a template from a premade template by selecting a GitHub repository that contains an existing Backstage template. Q: Do I need to know YAML to create templates? A: No, the Portal Scaffolder provides a visual editor for creating and configuring templates. However, understanding YAML can be helpful for advanced customization. Q: Can I export my templates? A: Yes, use the Download button in the template editor to export your template locally.

​
Permissions and Access

Q: Who can create templates? A: Platform engineers and admins with appropriate permissions can create and publish templates. Check with your organization’s Portal administrator for specific role requirements. Q: Who can run templates? A: All Portal users can run published templates. However, execution may require specific permissions (e.g., write access to target repositories). Q: Why am I getting a permissions error? A: Common causes:
  • You don’t have write access to the target repository
  • GitHub authentication has expired
  • Organization policies restrict repository creation
  • Check with your administrator for required permissions

​
Template Creation

Q: How do I test my template before publishing? A: Use the Dry Run feature to simulate execution without creating actual resources. This validates your configuration and shows expected outputs. Q: Can I edit a published template? A: Yes, published templates can be edited. Changes will apply to future executions but won’t affect previously created resources. Q: What happens if my template has errors? A: Templates are validated when saved. If errors exist, you’ll receive error messages indicating what needs to be fixed. Templates with errors cannot be published. Q: Can I have multiple versions of a template? A: Currently, templates are updated in place. Consider using descriptive names (e.g., “My Template v2”) if you need to maintain multiple versions.

​
Template Execution

Q: How long does template execution take? A: Execution time varies based on template complexity and actions performed. Simple templates (creating a repository) typically complete in under a minute. Complex templates with multiple actions may take longer. Q: Can I cancel a running template? A: Cancellation support depends on your Portal configuration. Some actions may not be cancellable once started. Q: What should I do if execution fails? A:
  1. Check the execution logs for error details
  2. Verify you have necessary permissions
  3. Confirm all required inputs were provided correctly
  4. Try running again if it was a temporary issue
  5. Contact support if the problem persists
Q: Will failed executions create partial resources? A: It depends on where the failure occurred. Some actions may have completed before the failure. Check your repositories and catalog for any partial resources.

​
Template Configuration

Q: Can I use variables in my templates? A: Yes, form field values can be referenced in actions using template syntax (e.g., ${{ parameters.repoName }}). Q: What actions are available? A: Available actions depend on your Portal configuration. Common actions include GitHub operations, catalog registration, and file manipulation. Check your Portal’s action documentation for a complete list. Q: Can I add custom actions? A: Custom actions can be added by platform administrators. Contact your Portal admin if you need custom functionality. Q: How do I validate user input? A: Use field validation rules in form field configuration to enforce patterns, required fields, and value constraints.

​
Best Practices

Q: What makes a good template? A: Good templates:
  • Have clear, descriptive names
  • Include helpful descriptions and field labels
  • Use validation to prevent errors
  • Are tested thoroughly with dry run
  • Document any prerequisites or requirements
Q: Should I create one large template or multiple small ones? A: Generally, create focused templates for specific use cases. This makes templates easier to maintain and understand. Users can run multiple templates if needed. Q: How often should I update templates? A: Update templates when:
  • Requirements change
  • New features are available
  • Users report issues or request improvements
  • Best practices evolve
Q: How do I make templates user-friendly? A:
  • Use clear, descriptive labels
  • Provide helpful field descriptions
  • Set sensible defaults
  • Use validation to guide users
  • Test with actual users before publishing

​
Troubleshooting

Q: Template won’t load in editor A: Try:
  • Refreshing the page
  • Checking browser console for errors
  • Verifying the template repository is accessible
  • Contacting support if the issue persists
Q: GitHub integration showing errors A: Verify:
  • GitHub authentication is valid
  • Repository URL is correct
  • You have access to the repository
  • Re-authenticate with GitHub if needed
Q: Dry run results look wrong A: Check:
  • Form field configurations are correct
  • Action parameters are properly set
  • Extensions are configured correctly
  • Try with different input values to isolate the issue
Content coming soon