These release notes are for Zenhub Enterprise for Virtual Machine and Zenhub Enterprise for Kubernetes.

• For all users using Zenhub on github.com, please check out our new feature announcements on our product changelog.
• For administrators planning upgrades, please refer to the "Important Upgrade Instructions for Administrators" section.

GitHub Enterprise Server compatibility

Zenhub Enterprise 4.2.0 supports GitHub Enterprise versions: 3.11 and 3.12

What's new in Zenhub Enterprise 4.2.0

We are thrilled to announce the release of Zenhub Enterprise 4.2, packed with a host of exciting new features designed to optimize your workflow, boost productivity, and heighten collaboration. Zenhub Enterprise 4.2 includes AI components that can suggest Issue labels, acceptance criteria, and generate sprint reviews.

Features

AI Features

AI Label Suggestions

This feature uses AI with the help of minimizing a tedious task of searching for the right label(s). Start by creating an issue (Zenhub issue or GitHub issue), type in a title to best describe the issue. Once you click out of the title section you will see under the label metadata that Zenhub AI has made some suggestions. You can select one label or all, and you can also refresh if the labels suggested weren't quite right. The labels suggested are the labels that currently exist within the repository you are working in.

AI Sprint Review Report

The Sprint Review report is a new report within Zenhub that summarizes the work completed by your team within a sprint using Zenhub AI. The report features a short text summary of the completed issues, and groups closed issues by their epics, creating a useful starting point or agenda for your next sprint review or demo meeting. Sprint Reviews are automatically generated per workspace throughout the Sprint.

Features:

• Manually update a text description or leverage Zenhub AI to rephrase it: shorter, longer, more technical, less technical
• Add or remove issues from groups
• Access Sprint Reviews for a previously completed sprint from the roadmap
• Visual indication of issues closed after a sprint ended
  … and more!

AI Acceptance Criteria

AI Acceptance Criteria is a new AI feature that enables users to generate acceptance criteria for a Zenhub issue or GitHub issue. Generated acceptance criteria will automatically be added to the issue or Epic description in BDD format as a checklist for ease of use for testing and development.

Velocity Report Improvements

Available for non-GitHub-connected users

Previously exclusive to GitHub-connected users, the Velocity Report is now available to all users regardless of their GitHub-connection status. This enhancement ensures that all teams, regardless of their preferred workflow or toolset, can benefit from the valuable insights provided by the Velocity Report.

A Year in View

The Velocity Report now covers a more comprehensive date range, spanning up to one year. This allows teams to compare see and analyze performance against past quarters and identify long-term patterns of team performance. The date range selection is now 2 weeks, 1 month and then in increments of 3 months up to 1 year.

To use this, navigate to the Velocity Report and select the Date Period filter at the top section. You may also use it in association with other filters on the Report.

Multiple repository selection

Zenhub's Velocity Report now empowers users with the ability to select and analyze issues within more than one repository, offering a consolidated view for a more efficient and insightful reporting experience for teams that work across multiple repositories.

Open but "Done" Issues

You can now track velocity based on specific pipelines. This can be done by setting "Completed Pipelines" on the Velocity Report. This addition allows for a realistic view of your project's progress based on different workflows for teams that consider issues in a specific pipeline as "Done" even if those issues are not Closed.

Assignee, Epic and Label Filters

Users now have the ability to filter their Velocity Report by Epics, assignees, and labels. This provides greater flexibility and insight into team performance and project progress.

• Filter by Epics: Users can now filter their Velocity Report by Epics, allowing them to focus on specific high-level initiatives or themes within their projects. This enhancement enables teams to track the progress and velocity of individual Epics, providing valuable insights into their impact on overall project delivery.

• Filter by Assignees: In addition to filtering by Epics, users can also filter their Velocity Report by individual assignees. This feature enables teams to assess individual team members' contributions toward project velocity, identify potential bottlenecks or resource constraints, and optimize workload distribution for improved efficiency and productivity.

• Filter by Labels: If you tag work by labels, the Velocity Report now enables you to visualize and track work items based on labels, offering enhanced flexibility in organizing and analyzing project data according to specific criteria or themes.

Roadmap Improvements

Key Dates

You can now seamlessly integrate important dates into your roadmap. Customize the title of each key date to accurately reflect its significance and set the corresponding date. These additions are shared across the workspace, ensuring comprehensive awareness and alignment on all upcoming events, deadlines, or important dates, and how they relate to your project timeline.

Add a key date on the roadmap by bringing your cursor up to the timeline.

Dependencies

Dependencies are now available on the roadmap, shown as lines connecting Epics that depend on one another.

Exporting and Sharing

You now have the ability to export the roadmap as a CSV, PNG and/or SVG. This allows you to pop the roadmap in a spreadsheet or a slide deck to present to your organization.

You can now select the date range you want to have displayed in the exported file, as well as the timeline scale being quarterly, monthly, or weekly. There is also now a selector for which projects and Epics you want to include in the export, so you can include exactly what you need and nothing more.

Board Improvements

Predicted Sprint and Auto Sprint Assignment

Zenhub can now let you know when an issue will be worked on by predicting which sprint it will fit into! You will notice a new sprint tag appear on your issues to help you plan future sprints.

You can also automatically assign an issue to the current sprint when the issue is moved into your sprint backlog or onwards across the board. If it’s moved back into your backlog, the sprint will be removed for you. This will help you and your team maintain your sprint hygiene automatically and improve the quality of your reports.

Additionally, when a new sprint starts, Zenhub will automatically move your issues in your prioritized backlog into your sprint backlog. To ensure both of these features work as intended, make sure to configure your pipelines following the instructions below.

Lastly, you now have the ability to add a description or goal to your sprints directly on the sprint page. These goals will show up in your reports and the roadmap to help you stay on track and find historical sprint goals!

In order for Zenhub to properly auto assign and populate your sprint backlog you will need to turn on automated sprints and configure your pipelines. You can do this easily within the 'Modify Reoccurring Sprints' section:

Issue Metadata Automation

• Users can build automations on the board, per pipeline, to have sprints, Epics, labels and assignees automatically added or removed from an issue when it enters or leaves a pipeline
• Users can configure multiple automations per pipeline and can multi-select metadata items to be applied as part of each automation
• Users can mix and match automations across multiple metadata types within the same pipeline

Flag Stale Issues

• Users can now configure a rule to highlight issues that have been in a pipeline longer then a set number of days
• The symbol and colour of the icon used to identify stale issues can be customized
• Stale issues also display the number of days an issue has been in a given pipeline

Work-in-Progress Limits for Pipelines

There is now the option to add Work-in-Progress (WIP) limits to pipelines on the board. This feature allows a user to configure a soft limit for the number of issues that should be allowed in a pipeline at any given time. When the limit is exceeded, a warning is displayed on the pipeline to alert users that the limit has been reached. This can help you and your team to maintain a steady flow of work and prevent bottlenecks.

To get started, head over to your board and click on 'Settings & Automation' from pipeline settings.

General Improvements

GitHub Metrics Enhancements - Repository and Label Filters

You can now filter your GitHub Insights by repository and label. Users can now focus on specific repositories and refine analysis by selecting specific labels within their workspaces, providing a more tailored and granular view of the 6-metric report.

Zenhub Issue File Uploads

File uploads are now supported in Zenhub Issue descriptions and comments.

Set File Uploads as Public or Private

Users can now configure permissions for files uploaded to a workspace. By default, all files are uploaded as private and only viewable to members of the Zenhub Organization. Setting File Uploads as Public will allow files uploaded to your workspace to be accessible to anyone on the web with the public link, depending on your network configuration for ZHE for VM, or your S3 bucket configuration for ZHE for K8s. This setting can be changed through the Workspace Settings page.

Licensing Change

The “Always (Unlimited)” license assignment setting has been removed in this release. If you were using this option before upgrading, your license assignment setting will be automatically changed to “Up to license limits”. If your instance has more seats allocated than active users, please remove licenses from any inactive users or contact us for assistance.

Security Fixes

• Package security updates fixing critical and high CVE

Bug Fixes

• Fixed a race condition with postgres configuration on first time installation that could cause app start up failures
• Fixed a bug causing the configuration of custom K3s CIDRs to fail to run

Changes

• With the addition of self-hosted AI features, resource requirements for ZHE for VM have been updated. Please consult the updated "Hardware Sizes" section of the documentation for what changes are required for: GPU, CPU, memory, and disk space. This is only needed if you enable the AI features.
• MongoDB has been upgraded from 4.4.13 to 5.0.24
• K3s has been upgraded from v1.26.8+k3s1 to v1.27.11+k3s1
• Kubernetes has been upgraded from v1.26.8 to v1.27.11
• You can now upgrade 2 versions of Zenhub Enterprise Server at a time starting with this release.
• The Chrome Extension Publishing documentation was updated to include recommendations that resolve the Red Nickel violation in the Chrome Webstore policies

Known Issues

• No known issues in this release

VM Embedded Component Versions

Important Upgrade Instructions for Administrators

Zenhub Enterprise for Virtual Machine

This version of ZHE newly supports skipping a feature version during the upgrade. This means you can now upgrade two feature versions at a time! For this release, you can upgrade from v4.0.X, or v4.1.X.

• For users currently running Zenhub Enterprise, contact our team for a download link for the 4.2.0 upgrade package. The upgrade process is detailed in our documentation.

• For enabling AI features, please consult the setup documentation for detailed steps and prerequisites: https://github.com/ZenHubHQ/zenhub-enterprise/tree/master/virtual-machine#12-ai-features. When you're ready to start, contact our team for a download link for the AI component installation package.

Zenhub Enterprise for Kubernetes

• The new suggested MongoDB version for Zenhub Enterprise v4.2 is the latest version of MongoDB v5.0. Please pay attention to the list of MongoDB v5.0 patch versions that should be avoided for production use here: https://www.mongodb.com/docs/manual/release-notes/5.0/#patch-releases. We suggest upgrading to MongoDB v5.0 prior to upgrading Zenhub Enterprise to v4.2.

• Some extra upgrade instructions have been added specifically for this release due to some database changes that accompany the application updates. Please follow the upgrade instructions below for this release:

⚠️ NOTE: The minimum version of Kubernetes required to run ZHE 4.2 is now v1.27.

1. Prepare

• Get the kustomization.yaml you configured to setup Zenhub
• Perform a diff to make sure no outstanding changes are waiting to be applied

kustomize build . | kubectl diff -f-

It should exit 0 and only display a warning of unused variables. If changes are pending, apply them before starting the upgrade process.

• Make a copy of your existing kustomization.yaml and keep it handy for the next step

2. Update kustomization.yaml

• Check out the zenhub-enterprise repository at the tag of this release
• Populate the new kustomization.yaml with your existing configuration values

Be sure to replace any additional customized configuration (such as ingress, TLS configuration) with your original configuration from before as well.

• In ZHE 4.0 and onwards, secret_key_base is required to be a 42 byte string, any existing 38 byte string should be updated as described in kustomization.yaml
• If you are using your own registry and not Zenhub's registry, upload the new images tagged with this release to your registry.

3. Run configmap-generator.sh

Once you have setup all the configurations in your copy of kustomization.yaml and are ready to deploy to your cluster, you must run the configmap-generator.sh script that will fill placeholders in our Kubernetes manifests with your configuration values.

To run the script, navigate to the root of the directory containing your kustomization.yaml file, which also contains the configmap-generator.sh script. Then, run the script with these two commands:

chmod 700 configmap-generator.sh
./configmap-generator.sh

4. Application updates

In your new kustomization.yaml, confirm that the cluster image tags are set to the new images for this release:

If you are using your own registry, ensure that the newName fields are configured for that instead of Zenhub's

images:
  - name: kraken-webapp
    newName: us.gcr.io/zenhub-public/kraken-webapp
    newTag: zhe-4.2.0
  - name: kraken-extension
    newName: us.gcr.io/zenhub-public/kraken-extension
    newTag: zhe-4.2.0
  - name: kraken-zhe-admin
    newName: us.gcr.io/zenhub-public/kraken-zhe-admin
    newTag: zhe-4.2.0
  - name: raptor-backend
    newName: us.gcr.io/zenhub-public/raptor-backend
    newTag: zhe-4.2.0
  - name: toad-backend
    newName: us.gcr.io/zenhub-public/toad-backend
    newTag: zhe-4.2.0
  - name: sanitycheck
    newName: us.gcr.io/zenhub-public/sanitycheck
    newTag: zhe-4.2.0
  - name: devsite
    newName: us.gcr.io/zenhub-public/devsite
    newTag: zhe-4.2.0
  - name: busybox
    newName: docker.io/library/busybox
    newTag: latest
  - name: nginx
    newName: docker.io/library/nginx
    newTag: latest

• First, delete any raptor-db-migrate and sanitycheck jobs so they may be recreated without errors:

Make sure the status of the jobs are Complete and not Running

kubectl -n <your_dedicated_namespace> delete job/raptor-db-migrate job/sanitycheck

• Then perform a diff to check what the upgrade will do (this command must be run from the directory that contains your kustomization.yaml

kustomize build . | kubectl diff -f-

• If everything looks correct and there are no errors, you can deploy to the cluster via:

kustomize build . | kubectl apply -f-

5. Database Changes for Zenhub Enterprise for Kubernetes

⚠️ NOTE: For upgrading to Zenhub Enterprise version 4.2 from 4.0.X, Zenhub will require a manual change to the PostgreSQL schema.
A constraint called pih_no_overlap from the pipeline_issue_histories table is required to be dropped and replaced.

To do this, you may follow the following steps:

1. Ensure you have a backup of the existing PostgreSQL database. Implementation may vary depending on the PostgreSQL service provider
2. Perform the following while connected to the PostgreSQL database:

ALTER table pipeline_issue_histories DROP CONSTRAINT pih_no_overlap;
ALTER TABLE ONLY public.pipeline_issue_histories
    ADD CONSTRAINT pih_no_overlap EXCLUDE USING gist (workspace_id WITH =, issue_id WITH =, tsrange(started_at, ended_at, '[)'::text) WITH &&) DEFERRABLE;

1. Verify the completion of the above with the following PostgreSQL command which should return an empty result:

SELECT * FROM pg_stat_activity WHERE query LIKE '%public.pipeline_issue_histories%';

Next, proceed to run the regular data migration script.

⚠️ NOTE: Running this script is only required if you are upgrading from ZHE 4.0.X
⚠️ NOTE: If you are using stunnel, be sure to uncomment the relevant sections in update/batch_v1_job_data_migration.yaml

• Run the script found in k8s-cluster/update/zhe-upgrade.sh via the commands below:

If you use the ZenHub registry

cd update
./zhe-upgrade.sh yourNamespace

If you use your own registry

cd update
./zhe-upgrade.sh yourNamespace yourRegistryName

6. Re Deploy Application

⚠️ NOTE: Running these commands is only required if you are upgrading from ZHE 4.0.X

The data migration script run in the previous step will have scaled down the application in order to safely migrate data without active database writes occurring. Now that the migration is complete, the application needs to be deployed to the normal desired operational state:

• First perform a diff to check what will change (this command must be run from the directory that contains your kustomization.yaml

kustomize build . | kubectl diff -f-

• If everything looks correct and there are no errors, you can deploy to the cluster via:

kustomize build . | kubectl apply -f-

7. Finalize

• Securely store the updated kustomization.yaml