Skip to main content

Scaffolder Reference

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