Alauda DevOps Pipelines Docs
  • English

    • Writing Pipelines for Tekton Hub

    TOC

    OverviewHub-Specific MetadataRequired Labels for HubRequired Annotations for HubHub Task ReferencesCatalog Task Reference for HubHub Categories and TagsStandard Pipeline CategoriesEffective Pipeline TaggingHub Parameter StandardsHub-Specific Parameter RequirementsHub Pipeline TemplateHub Best PracticesTask Composition for HubWorkspace Management for HubPipeline Reusability for HubHub Testing RequirementsRequired Pipeline Test FilesHub Pipeline Validation ChecklistSecurity for Hub PipelinesHub Security RequirementsDocumentation RequirementsHub Pipeline Documentation StandardsHub Publishing Checklist✅ Hub Compliance✅ Quality Standards

    Overview

    This guide covers the specific requirements and best practices for creating Pipelines that work with Tekton Hub catalogs. It focuses on Hub-specific metadata, validation, and composition standards.

    Hub-Specific Metadata

    Required Labels for Hub

    metadata:
  name: my-custom-pipeline
  labels:
    app.kubernetes.io/version: "0.1"  # Must match catalog version directory

    Required Annotations for Hub

    metadata:
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"    # Minimum Tekton version
    tekton.dev/categories: "Integration & Delivery"  # Hub category
    tekton.dev/tags: "ci,build,test,deploy"     # Hub search tags
    tekton.dev/displayName: "CI/CD Pipeline"    # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Supported platforms

    Hub Task References

    Catalog Task Reference for Hub

    spec:
  tasks:
  - name: git-clone
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"  # Hub catalog name
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: git-clone  # Task name from Hub
      - name: version
        value: "0.9"      # Task version
    params:
    - name: url
      value: $(params.repo-url)
    workspaces:
    - name: output
      workspace: source-code

    Hub Categories and Tags

    Standard Pipeline Categories

    • Integration & Delivery
    • Continuous Integration
    • Continuous Deployment
    • Testing
    • Security
    • Build & Package

    Effective Pipeline Tagging

    • Use workflow-specific tags (ci, cd, cicd)
    • Include technology stacks (nodejs, java, python, golang)
    • Add deployment targets (kubernetes, cloud, containers)

    Hub Parameter Standards

    Hub-Specific Parameter Requirements

    spec:
  params:
  - name: repo-url
    description: "Git repository URL for source code"  # Clear description for Hub UI
    type: string
  - name: target-environment
    description: "Deployment target environment"
    type: string
    default: "development"  # Sensible default
  - name: build-args
    description: "Additional build arguments"
    type: array
    default: []  # Safe default for arrays

    Hub Pipeline Template

    apiVersion: tekton.dev/v1
kind: Pipeline
metadata:
  name: my-hub-pipeline
  labels:
    app.kubernetes.io/version: "0.1"  # Match catalog version
  annotations:
    tekton.dev/pipelines.minVersion: "0.17.0"
    tekton.dev/categories: "Integration & Delivery"  # Hub category
    tekton.dev/tags: "ci,build,deploy"               # Hub search tags
    tekton.dev/displayName: "My CI/CD Pipeline"      # Hub display name
    tekton.dev/platforms: "linux/amd64,linux/arm64"  # Platforms
spec:
  description: >-
    Pipeline description for Hub documentation
  params:
  - name: git-url
    description: Git repository URL
  - name: image-name
    description: Container image name
    default: "myapp:latest"
  workspaces:
  - name: source-code
    description: Source code workspace
  - name: registry-creds
    description: Distribution registry credentials
    optional: true

  tasks:
  - name: fetch-source
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: git-clone  # Reference Hub catalog task
      - name: version
        value: "0.9"
    params:
    - name: url
      value: $(params.git-url)
    workspaces:
    - name: output
      workspace: source-code

  - name: build-image
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: buildah    # Reference Hub catalog task
      - name: version
        value: "0.4"
    runAfter: [fetch-source]
    params:
    - name: image
      value: $(params.image-name)
    workspaces:
    - name: source
      workspace: source-code
    - name: registryconfig
      workspace: registry-creds

  finally:
  - name: cleanup
    taskRef:
      resolver: hub
      params:
      - name: catalog
        value: "catalog"
      - name: type
        value: tekton
      - name: kind
        value: task
      - name: name
        value: cleanup-workspace
      - name: version
        value: "0.1"
    workspaces:
    - name: source
      workspace: source-code

    Hub Best Practices

    Task Composition for Hub

    • Use Tasks from the same Hub catalog when possible
    • Reference specific task versions for stability
    • Provide clear parameter mappings
    • Document task dependencies

    Workspace Management for Hub

    • Use descriptive workspace names and descriptions
    • Mark optional workspaces as optional: true
    • Document workspace data flow between tasks
    • Minimize workspace requirements where possible

    Pipeline Reusability for Hub

    • Design for common use cases
    • Provide flexible parameters
    • Include reasonable defaults
    • Support multiple deployment scenarios

    Hub Testing Requirements

    Required Pipeline Test Files

    • Provide working samples/ directory with PipelineRun examples
    • Include run.yaml demonstrating typical usage
    • Test with various parameter combinations
    • Validate workspace configurations
    • Test error handling scenarios

    Hub Pipeline Validation Checklist

    • Required Hub metadata present
    • Sample PipelineRun works correctly
    • All parameters documented with descriptions
    • Workspaces properly described
    • Task references use Hub catalog tasks
    • Platform compatibility verified
    • Finally tasks included for cleanup

    Security for Hub Pipelines

    Hub Security Requirements

    • No hardcoded secrets in Pipeline definitions
    • Use secure task references
    • Document required service account permissions
    • Follow principle of least privilege
    • Validate input parameters

    Documentation Requirements

    Hub Pipeline Documentation Standards

    • Include comprehensive README.md in pipeline directory
    • Document the complete workflow and purpose
    • Provide clear parameter descriptions
    • Include usage examples and common configurations
    • Document prerequisites and dependencies
    • Explain workspace requirements
    • Include troubleshooting guide

    Hub Publishing Checklist

    ✅ Hub Compliance

    • Required Hub metadata (labels and annotations) present
    • Version label matches directory structure
    • All parameters have clear descriptions
    • Workspaces properly documented
    • Uses Hub catalog task references
    • Platform compatibility specified
    • Working sample PipelineRun provided
    • Complete README with usage examples
    • Passes Hub validation requirements

    ✅ Quality Standards

    • Pipeline is reusable across environments
    • Error handling and cleanup implemented
    • No hardcoded values or secrets
    • Security best practices followed
    • Cross-platform compatibility verified
    • Documentation is complete and accurate
    • Performance optimized with parallel execution where possible