> ## 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.
# Scaffolder Reference
> Technical reference for Scaffolder template structure including form field types, action steps, field properties, and validation rules.
Technical reference documentation and frequently asked questions.
## Template Structure
A Portal Scaffolder template consists of three main sections:
### Form Fields (Input)
Form fields define what information users provide when running a template.
**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.
**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.
**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
**Accessing logs**:
* Automatically displayed during execution
* Click **Show Logs** to view detailed output
* Logs persist after execution completes
## 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*