Learn how to integrate Zenhub's smart pipelines with GitHub Actions to create a publicly accessible, read-only project board driven by Zenhub.


Introduction

This guide explains how to leverage Zenhub's smart pipelines and GitHub Actions to create a public-facing, read-only project board. This integration provides a simple way to display project progress to external stakeholders without requiring them to sign in.


Setting Up Smart Pipelines in Zenhub

Zenhub's smart pipelines automate issue management by applying labels and triggering actions based on pipeline movements. Here’s how to set them up:

  1. Navigate to the Pipeline Settings:
    • Go to the 'In Progress' pipeline.
    • Click the triple dot menu and select 'Settings and Automation.'
  2. Configure Automation Rules:
    • In the automation settings, you'll find various rules.
    • For each pipeline, you need to set up two automations: one to add the status label when an issue enters the pipeline and another to remove the status label when it leaves.
      • For instance, dragging a card into the 'In Progress' pipeline can automatically add a label 'in progress.'
    • Conversely, dragging a card out can remove the label.

These labels are crucial as they help communicate the progress of issues.


Combining Zenhub and GitHub Actions

To create a public-facing project board, we use GitHub Actions to respond to label changes managed by Zenhub. Here’s the process:

  1. Set Up Issue Automation:
    • Add a card to the 'Sprint Backlog' with similar automation rules as the 'In Progress' pipeline.
    • Drag the card into the 'Sprint Backlog' pipeline.
    • The card will be automatically labeled 'Sprint Backlog.'
  2. Syncing with GitHub Actions:
    • GitHub Actions monitor these label changes.
    • When a label is added or removed, the action updates the project board accordingly.

This synchronization allows your GitHub project board to reflect the latest status updates from Zenhub without manual intervention.


Configuring GitHub Actions

To automate the synchronization between Zenhub and GitHub project boards, you need to configure GitHub Actions. Below is an example YAML file to set up the necessary actions:

yamlCopy code
name: Sync Zenhub Pipelines to Project Columns

env:
  gh_token: ${{ secrets.PAT }}
  organization: ZenHubHQ
  project_id: 28
  status_product_backlog: "Product Backlog"
  status_sprint_backlog: "Sprint Backlog"
  status_in_progress: "In Progress"
  status_review_qa: "Review/QA"

on:
  issues:
    types:
      - labeled
  pull_request:
    types:
      - labeled

jobs:
  manage-project:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Move Issue to ${{env.status_product_backlog}}
        uses: leonsteinhaeuser/project-beta-automations@v2.2.1
        if: ${{contains(github.event.issue.labels.*.name, env.status_product_backlog)}}
        with:
          organization: ${{env.organization}}
          project_id: ${{env.project_id}}
          gh_token: ${{env.gh_token}}
          resource_node_id: ${{ github.event.issue.node_id }}
          status_value: ${{env.status_product_backlog}}

      - name: Move Issue to ${{env.status_sprint_backlog}}
        uses: leonsteinhaeuser/project-beta-automations@v2.2.1
        if: ${{contains(github.event.issue.labels.*.name, env.status_sprint_backlog) }}
        with:
          organization: ${{env.organization}}
          project_id: ${{env.project_id}}
          gh_token: ${{env.gh_token}}
          resource_node_id: ${{ github.event.issue.node_id }}
          status_value: ${{env.status_sprint_backlog}}

      - name: Move Issue to ${{env.status_in_progress}}
        uses: leonsteinhaeuser/project-beta-automations@v2.2.1
        if: ${{contains(github.event.issue.labels.*.name, env.status_in_progress) }}
        with:
          organization: ${{env.organization}}
          project_id: ${{env.project_id}}
          gh_token: ${{env.gh_token}}
          resource_node_id: ${{ github.event.issue.node_id }}
          status_value: ${{env.status_in_progress}}

      - name: Move Issue to ${{env.status_review_qa}}
        uses: leonsteinhaeuser/project-beta-automations@v2.2.1
        if: ${{contains(github.event.issue.labels.*.name, env.status_review_qa) }}
        with:
          organization: ${{env.organization}}
          project_id: ${{env.project_id}}
          gh_token: ${{env.gh_token}}
          resource_node_id: ${{ github.event.issue.node_id }}
          status_value: ${{env.status_review_qa}}

Prerequisites

To set up GitHub Actions to automate the process described in the YAML file, follow these steps:

  1. GitHub Account: Ensure you have a GitHub account.
  2. Repository Access: You should have access to the repository where you want to set up the action.
  3. Zenhub Integration: Ensure Zenhub is integrated with your GitHub repository and you have the required access rights.
  4. Personal Access Token (PAT): Generate a GitHub PAT with appropriate scopes (e.g., repo, workflow).

Steps to Set Up GitHub Actions

  1. Generate a Personal Access Token:

    • Go to GitHub Settings.
    • Navigate to Developer settings > Personal access tokens > Tokens (classic).
    • Click on Generate new token.
    • Select the required scopes for your PAT (repo, workflow, admin:org → read:org, project → read:project).
    • Click Generate token and copy the token. Note: Store this token securely as it won't be shown again.

  2. Create a Secret for the PAT:

    • Navigate to your GitHub repository.
    • Go to Settings > Secrets and variables > Actions > New repository secret.
    • Name the secret PAT and paste your PAT in the Secret field.
    • Click Add secret.

  3. Create the Workflow File:

    • Navigate to your GitHub repository.
    • Go to Actions.
    • Click on New workflow or Set up a workflow yourself if no workflows are present.
    • Name your workflow file, for example, sync_zenhub_pipelines.yml.
    • Copy and paste the provided YAML content into the file.
    • Commit the file to your repository.

  4. Configure Zenhub and GitHub Project:

    • Ensure your Zenhub account is connected to your GitHub repository.
    • Identify the project ID from your GitHub project. Replace the project_id value in the YAML file with your actual project ID.
    • Ensure the status labels (like Product Backlog, Sprint Backlog, etc.) in your GitHub issues match those in your YAML file.

  5. Test the Workflow:

    • Create or label an issue in your GitHub repository.
    • Verify that the issue is moved to the appropriate project column based on its label.

Benefits of This Integration

By integrating Zenhub’s smart pipelines with GitHub Actions, you create a seamless workflow that provides:

  • Automation: Automatically update labels and issue statuses without manual input.
  • Transparency: A read-only, public-facing project board that external stakeholders can view without signing in.
  • Enhanced Reporting: Utilize Zenhub’s advanced reporting and AI features while maintaining an accessible view of project progress.

FAQ

Q: How do smart pipelines improve my workflow? 
A: Smart pipelines automate the process of labeling and tracking issues, reducing manual work and increasing efficiency in managing project tasks.

Q: Can external users interact with the public-facing project board? 
A: No, the public-facing project board is read-only, providing visibility into project progress without allowing external users to make changes.

Q: What are the requirements for setting up GitHub Actions with Zenhub? 
A: You need to have both Zenhub and GitHub accounts, and the necessary permissions to set up automation rules and GitHub Actions within your repositories.