How-to Guides

Task-oriented guides for common Scaffolder operations.

Template Management

How to Create a Template from Scratch

1. Navigate to the Scaffolder templates page
2. Click Create New Template
3. Select Create from Scratch

4. Define your template structure:
   • Add form fields for user inputs
   • Configure actions to execute
   • Set up extensions if needed
5. Save as draft or publish when ready

How to Create a Template from an Existing Template

1. Click Create New Template
2. Select Create from a Premade Template
3. Choose your source:
   • Select via GitHub repository
   • Choose the repository containing your template
   • Set visibility (public/private)
   • Click Initialize
4. The template will load in the editor for customization

How to Edit a Published Template

1. Navigate to your templates list

2. Find the template you want to edit
3. Click Edit on the template

4. Make your changes in the editor
5. Save your changes:
   • Save: Update the template
   • Download: Export template locally
   • Publish: Update the published version

How to Add Form Fields

Form fields collect input from users when they run your template.

1. Open your template in the editor
2. Navigate to the form fields configuration section

3. Click Append to add a new field

4. Configure the field:

   • Set field name and type
   • Add label and description
   • Configure validation rules
   • Set default values (optional)

5. Save your changes

How to Add Actions to a Template

Actions define what happens when the template executes.

1. In the template editor, navigate to the actions section
2. Click to add a new action
3. Select an action type:
   • catalog:register: Register entities in the catalog
   • github:create: Create GitHub repositories
   • fetch:template: Fetch template content
   • And more...
4. Configure action parameters
5. Save the action configuration

How to Configure Extensions

Extensions provide custom filters, functions, and values for your templates.

1. Navigate to the extensions section in the editor
2. Add extensions as needed:
   • Filters: Transform data (e.g., lowercase, uppercase)
   • Functions: Custom logic for complex operations
   • Values: Reusable values across your template
3. Reference extensions in your template configuration
4. Save your changes

Template Testing

How to Use Dry Run

Dry run allows you to test templates without creating actual resources.

1. In the template editor, click Dry Run

2. Fill in the form with test values:
   • Organization selection
   • Repository name
   • Any required fields

3. Click Dry Run to simulate execution
4. Review the output:
   • Check what repository would be created
   • Verify expected resources
   • Confirm configuration is correct

5. If issues are found, return to editor and make adjustments

How to Review Dry Run Results

After running a dry run:

1. Check the preview section for expected outputs
2. Verify repository details:
   • Organization
   • Repository name
   • Visibility settings
3. Review any catalog entities that would be created
4. Confirm all parameters are correctly applied

Template Execution

How to Run a Published Template

1. Navigate to the templates list
2. Click Run on your desired template
3. Fill in the required information:
   • Select organization from dropdown
   • Enter repository name
   • Provide description
   • Complete any additional fields
4. Click Review to verify your inputs
5. Click Submit to execute the template

How to Monitor Template Execution

When a template is running:

1. View Logs: Real-time execution logs appear automatically

2. Check Progress: Monitor each step as it executes

3. Review Output: Once complete, check the output section for:

   • Created repositories
   • Registered catalog entities
   • Any generated artifacts

4. Access Resources: Click links to view created resources

How to Handle Execution Errors

If template execution fails:

1. Review the error message in the logs
2. Common issues:
   • Missing permissions (verify write access to target repository)
   • Invalid configuration
   • Network or API errors
3. Check the Show Logs option for detailed error information
4. Fix the issue and retry execution

Troubleshooting

Template Won't Save

Issue: Error when trying to save template changes

Solutions:

• Check that all required fields are filled in
• Verify JSON/YAML syntax is valid
• Ensure you have permission to edit the template
• Try downloading the template and checking for errors locally

GitHub Integration Error

Issue: Error message when creating template via GitHub

Solutions:

• Verify GitHub authentication is valid
• Check that the repository exists and you have access
• Confirm the repository URL is correct
• Re-authenticate with GitHub if necessary

Dry Run Not Working as Expected

Issue: Dry run results don't match expectations

Solutions:

• Review form field configurations
• Check action parameters are correctly set
• Verify extensions are properly configured
• Test with different input values

Template Missing After Publishing

Issue: Published template doesn't appear in templates list

Solutions:

• Refresh the page
• Check that publish completed successfully
• Verify template catalog configuration
• Ensure template has proper metadata (name, description)

Tips to Ensure Success

1. Verify Permissions: Ensure your user has write access to the repository where you're creating components
2. Check Template Structure: Make sure your template doesn't contain conflicting catalog-info.yaml files
3. Test First: Always use dry run before publishing templates to production
4. Use Clear Names: Give templates descriptive names and descriptions
5. Document Requirements: Clearly document any prerequisites or permissions needed