FreePBX Ticket Reporting

In February of 2024, FreePBX Open Source bug ticket handling was moved to GitHub. Prior to that, tickets were handled in a Jira instance at hosted by the FreePBX project.

The current GitHub reporting procedure is outlined herein. As work processes evolve using this new procedure, this document will be updated.

The policy described here is for non-security related bugs and issues. If you have a FreePBX Security issue to report, please see this page:


Opening bug tickets at GitHub against FreePBX is a simple process. 

Open source FreePBX issues can be reported on GitHub at: GitHub user credentials are required to login.

For Commercial modules see: This Article

Commercial module tickets opened on the Open Source issue tracker will be closed and you will be forwarded to the above article.

How to Open a Ticket

Browse to and click the green “New Issue” button:


From the screen that follow select the type of issue you wish to report, bug, feature, etc. by clicking the corresponding green “Get Started” button


This will open a form with several fields for adding information. Fields marked with a red asterisk must be populated. Review the explanatory text and fill out the fields as necesary. When finished, complete the submission by clicking the green “Submit new issue“ button


  1. Please note that tickets are handled through a triage system and may not be handled in the order received.

  2. Our team monitors the bug tracker for blocker and show stopper issues but most tickets will be reviewed by members of the development team on regularly scheduled weekly triage meetings.

  3. As part of the triage process, tickets will be moved from the issue-tracker project to the FreePBX module project to which it’s related. Links to the original ticket will be maintained.

  4. Tickets may be resolved within minutes or it may take much longer. Please note a team member may change the priority - please do not change it back. The time it takes to resolve a ticket also depends on the effort required to resolve the issue. For most issues, we must be able to reproduce the issue to fix it.

Ticket Lifecycle

After a ticket is created, there is a workflow put in place, so that everyone can see what the current status of the ticket is. 

The issue lifecycle stage is managed with “Labels” on GitHub. As the issues moves through the various lifecycle stages, it’s labels are updated to reflect the current status. Quick summary:

Lifecycle Stage

GitHub Label


Lifecycle Stage

GitHub Label



All newly opened issues get the ‘triage’ label indicating that they are ready to be reviewed by the engineering team


Once an issue has been triaged, before anything else is done, it’s moved to the ‘open’ stage.

In Progress

When an engineering team member is actively working on a ticket, the label changes to ‘in-progress’.

Dev Review

Code is committed to a branch and is ready for peer review


Code is complete and changes have been merged. Marking the issue at this stage as ‘resolved’ indicates the merges are ready for QA. Code is published to the edge repo



Process is complete and code can be published to the stable repo.

In addition to the lifecycle stage, there are also a handful of labels used to add a descriptive element to tickets to indicate the issue type.

Issue Type

GitHub Label


Issue Type

GitHub Label



Issue describing a bug.


Issue describing an improvement to an existing feature or functionality.

New Feature

Issue describing a new feature

Won’t Fix

Issue has been reviewed and deemed to be something that will not be fixed by Engineering.


Issue already exists


Issue requires additional information in order to progress, either from the original reporter, or someone else.

Keeping your report alive

Bug issues may be closed for several reasons. It is important that you provide quality and timely information. IMPORTANT: the issue system is for bugs and is not for general questions, commentary or arbitrary discussion.  If you are unsure that your issue is actually a bug, or are unable to describe it in a way that allows others to reproduce it, it is best to first discuss the issue in the forums at

Things that should generally be reported as bugs:

  • Unhandled exceptions such as "Whoops Errors" including what you did to make it happen.

  • Spelling and grammatical errors.

Things that may be your browser, and should be tested in another browser or in the browsers safe/privacy mode: 

Make sure you are running the latest updated version of your chosen browser. When filing browser based bugs ensure you provide the browser and OS along with versions.

  • Form fields auto filling (password fields and prior text input).

  • Javascript/Validation errors

  • Weird visual display

  • Missing Elements

Our team must be able to:

  • Understand what your actual issue is.

  • Reproduce the issue or see the issue clearly happening in logs.

To do this they need quality information.

Quality information is:

  • What is not working

  • What you expected it to do or not do

  • What it actually did or did not do

  • Relevant log sections (please obfuscate private information)

  • Relevant Call traces (please obfuscate private information)

  • Specific Version numbers

  • Specific Hardware models

  • Firmware and boot loader versions

  • Relevant configurations (please obfuscate private information)

Quality information is NOT:

  • Huge dumps of log files

  • Vague statements like "doesn't work", "I'm using FreePBX", “latest version”

If a ticket does not contain enough information a team member may ask you for more information. If no information is provided and the reporter does not provide a timely response, the issue may be closed as invalid.

Derivative works

If you are using FreePBX as part of a derivative project and have not obtained it directly from FreePBX it may be best to start with your project maintainer. They may modify FreePBX or restrict updates. Issues may already be fixed or may not exist except with their modifications. Some of these maintainers will file a bug with us as they know their modifications and can provide more information. Some maintain their own patches and may not stay fully up to date.

Support Request

Please note the bug system is not for general questions or support requests.  If you think your issue may be configuration related please use the proper support channels. Bugs are items that affect more than one user with known good information. Bugs are typically items that can be reproduced by following a recipe.

Return to Documentation Home I Return to Sangoma Support