Amazon CodeCatalyst is no longer open to new customers. Existing customers can continue to use the service as normal. For more information, see [How to migrate from CodeCatalyst](migration.md).
# Track and organize work with issues in CodeCatalyst
In CodeCatalyst, you can monitor features, bugs, and any other work involved in your project. Each piece of work is kept in a distinct record called an *issue*. You can break up an issue into smaller objectives by adding a checklist of tasks to it. Each issue can have a description, assignee, status, and other properties, which you can search for, group, and filter on. You can view your issues using the default views, or you can create your own views with custom filtering, sorting, or grouping. For more information about concepts related to issues, see [Issues concepts](issues-concepts.md). To learn how to create your first issue, see [Creating an issue in CodeCatalyst](issues-create-issue.md).
Here is one possible workflow for a team using issues:
Jorge Souza is a developer working in a project. He and his fellow project members Li Juan, Mateo Jackson, and Wang Xiulan collaborate to determine what work needs to be done. Every day, he and his fellow developers hold a sync-up meeting, led by Wang Xiulan. They pull up the board by navigating to one of their teams views of the board. By creating views, users and teams can save filters, groupings, and sorting of issues to easily view issues that meet their specified criteria. Their view contains issues grouped by **Assignee** and sorted by **Priority** to show the most important issues and status of the issues for each developer. As Jorge is assigned tasks to complete, he plans his work by creating an issue for each task. When creating issues, Jorge can choose the appropriate **Status**, **Priority**, and work **Estimation** effort. For larger issues, Jorge adds tasks to the issue, to break the work into smaller objectives. Jorge creates his issues with a draft status, such as **backlog**, as he doesn't plan to start on them immediately. Issues in a draft status appear on the **Drafts** view where they are to be planned and prioritized. Once Jorge is ready to start the work, he moves the corresponding issue to the board by updating its status to a status in another category (**Not Started**, **Started**, or **Completed**). As each task is being worked on, the team can filter by the title, status, assignee, label, priority, and estimation to find a specific issue or similar issues that match the specified parameter. Using the board, Jorge and his team can see the number of tasks completed for each issue, and track the day-to-day progress by dragging each issue from one status to the next until the task is complete. As the project progresses, finished issues accumulate in the **Completed** status. Wang Xiulan decides to remove them from view by archiving them using the quick archive button, so that the developers can focus on the issues that are related to current and upcoming work.
When planning their work, the developers working on the project choose **Sort by** and **Group by** to find the issues they want to move from the backlog to the board. They might choose to add issues to the board based on the highest priority customer requests, so they group the board by a **Customer request** label and sort by **Priority**. They might also sort by estimate to ensure that they're taking on a volume of work they can achieve. The project manager, Saanvi Sarkar, regularly reviews and grooms the backlog to help ensure that the priority accurately reflects the importance of each issue to the success of the project.
**Topics**
+ [Issues concepts](issues-concepts.md)
+ [Tracking work with issues](issues-tracking-work.md)
+ [Organizing work with backlogs, labels, and boards](issues-organizing-work.md)
+ [Quotas for issues in CodeCatalyst](issues-quotas.md)
# Issues concepts
Creating an issue is a quick and efficient way to track work being done within a project. You can use issues to help you discuss work in daily sync-up meetings, prioritize work, and more.
This page includes a list of concepts that will help you effectively use issues in CodeCatalyst.
## Active issues
*Active issues* are issues that are any issues that are not in a **Draft** status or archived. In other words, active issues are issues with a status in any of the following status categories: **Not started**, **Started**, and **Completed**. For more information about statuses and status categories, see [Status and status categories](#issues-concepts-status-definition).
You can view all of the active issues in your project from the default **Active issues** view.
## Archived issues
An *archived issue* is an issue that is no longer relevant to your project. For example, you can [archive an issue](issues-archive-issues.md) if it is completed and you no longer need to see it in the **Done** column, or if it was created in error. Archived issues can be unarchived if needed.
## Assignee
The *assignee* is the person the issue is assigned to. If the person doesn't appear in the list when you search for them, they have not been added to your project. To add them, see [Inviting a user to a project](projects-members.md#projects-members-add). To enable multiple assignees to an issue, see [Enabling or disabling multiple assignees](issues-settings-multiple-assignees.md). Issues with multiple assignees will appear on your board with different colored avatars, each representing one of the assignees.
## Custom fields
*Custom fields* allow you to customize different attributes of an issue according to your needs for tracking and maintaining issues within a project. For example, you can add a field for roadmapping, a specific due date, or a requester field.
## Estimate
In agile development, the *estimate* is known as story points. You can use the estimate for an issue to represent the amount of work required, in addition to the ambiguity and complexity of the issue. Consider using higher estimates for issues with greater risk, difficulty, and unknowns.
For more information about estimation types and how to configure them, see [Configuring issue effort estimation](issues-settings-estimation.md).
## Issue
An *issue* is a record that tracks the work related to your project. You can create an issue for a feature, a task, a bug, or any other body of work related to your project. If you're using agile development, an issue can also describe an epic or user story.
## Label
The *label* is used to group, sort and filter issues. You can enter a new label name or choose one of the labels from the populated list. This list consists of recently used labels in the project. An issue can have multiple labels, and a label can be removed from an issue. To customize labels, see [Categorizing work with labels](issues-labels.md).
## Priority
*Priority* refers to the level of importance of the issue. There are four options: **Low**, **Medium**, **High**, and **No priority**.
## Status and status categories
The *status* is the current state of the issue and is used to quickly check the progress of an issue through its lifecycle, from inception to completion. All issues must have a status, and each status belongs to a *status category*. Status categories are used to help organize your statuses and populate the default issue views.
There are five default statuses and four status categories in CodeCatalyst. You can create other statuses, but you cannot create other status categories. The following list contains the default statuses and their status categories in parenthesis: **Backlog (Draft)**, **To do (Not started)**, **In progress (Started)**, **In review (Started)**, and **Done (Completed)**.
For more information on working with statuses, see [Tracking work with custom statuses](issues-customize-statuses.md).
## Tasks
*Tasks* can be added to issues to further break down and organize the work of that issue. You can add tasks to an issue on creation, or add tasks to an existing issue. When viewing an issue, you can reorder, remove, or mark its tasks as completed.
## Views
Issues in your CodeCatalyst project are displayed in *views*. Views can either be grid views that show issues in list format or board views that show issues as tiles in columns organized by issue status. There are four default views, and you can [create your own views with custom grouping, filtering, and sorting](issues-creating-view.md). The following list contains details about the four default views.
+ The **Drafts** view is a grid view that shows issues not currently being worked on. Any issue created with a status in the **Draft** status category shows up in this view. This view can be used by teams to see which issues are still being defined or are waiting to be assigned and worked on.
+ The **Active issues** view is a board view of all issues that are currently being worked on. Any issue with a status in the **Not started**, **Started**, or **Completed** status categories will show up in this view.
+ The **All issues** view is a grid view that shows all the issues in the project, both *drafts* and *active issues*.
+ The **Archived** view shows all archived issues.
# Tracking work with issues
You can plan and track your work on a project by using issues. Each issue is a piece of work kept in a distinct record. Issues can be broken down into tasks to further organize and track the work of that issue. You can also create links between issues to help you keep track of related work, add labels to help you organize and categorize work, group issues, assign priorities to work, and indicate whether work is blocked.
When you're ready to work on an issue or set of issues, you can estimate the work, assign them to users, and add comments to help others understand the work and its progress. You can also export issues to help bring the information they contain into other formats.
# Creating an issue in CodeCatalyst
Development teams create issues to help track and manage their work. You can create issues within a project based on your needs. For example, you could create an issue to track updating a variable in your code. You can assign issues to other users in the project, use labels to help you track your work, and more.
Follow these instructions to create an issue in CodeCatalyst.
**To create an issue**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to create an issue.
1. On the project home page, choose **Create issue**. Alternatively, in the navigation pane, choose **Issues**.
1. Choose **Create issue**.
**Note**
You can also add issues inline when using a grid view.
1. Enter a title for the issue.
1. (Optional) Enter a **Description**. You can use Markdown to add formatting.
1. (Optional) Choose a **Status**, **Priority**, and **Estimation** for the issue.
**Note**
If the project's estimation setting is set to **Hide estimates**, there will not be an **Estimation** field.
1. (Optional) Add tasks to the issue. Tasks can be used to break down the work of an issue into smaller objectives. To add a task, choose **\$1 Add tasks**. Then, input the task name in the text field and press enter. After adding tasks, you can mark them as complete by choosing the checkbox, or reorder them by choosing and dragging the task from the left side of the checkbox.
1. (Optional) Add an existing label or create a new label and add it by choosing **\$1 Add label**.
1. To add an existing label, choose the label from the list. You can enter a search term in the field to search all labels containing that term in the project.
1. To create a new label and add it, enter the name of the label you want to create in the search field and press enter.
1. (Optional) Add an assignee by choosing **\$1 Add an assignee**. You can quickly add yourself as the assignee by choosing **\$1 Add me**.
**Tip**
You can choose to assign an issue to **Amazon Q** to have Amazon Q try to solve the issue. For more information, see [Tutorial: Using CodeCatalyst generative AI features to speed up your development work](getting-started-project-assistance.md). This feature is only available in the US West (Oregon) Region.
This functionality requires that generative AI features are enabled for the space. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html).
1. (Optional) Add an existing **custom field** or create a new custom field. Issues can have multiple custom fields.
1. To add an existing custom field, choose the custom field from the list. You can enter a search term in the field to search all custom fields containing that term in the project.
1. To create a new custom field and add it, enter the name of the custom field you want to create in the search field and press enter. Then choose the type of custom field you want to create and set a value.
1. Choose **Create issue**. A notification appears in the lower right corner: If the issue was created successfully, a confirmation message appears saying the issue was successfully created. If the issue was not created successfully, an error message with the reason for the failure appears. You can then choose **Retry** to edit and retry creating the issue, or choose **Discard** to discard the issue. Both options will dismiss the notification.
**Note**
You cannot link a pull request to an issue when you create it. However, you can [edit it](issues-edit-issue.md) after you create it to add links to pull requests.
## Best practices when creating and working with issues assigned to Amazon Q
When you create issues, sometimes some of them linger. The causes for this can be complex and variable. Sometimes it's because it's not clear who should work on it. Other times the issue requires research into or expertise with a particular part of the code base and the best candidates for the work are busy with other issues. Often there is other urgent work must be attended to first. Any or all of these causes can result in issues that aren't worked on. CodeCatalyst includes integration with a generative AI assistant called Amazon Q that can analyze an issue based on its title and its description. If you assign the issue to Amazon Q, it will attempt to create a draft solution for you to evaluate. This can help you and your team to focus and optimize work on issues that require your attention, while Amazon Q works on a solution for problems you don't have resources to address immediately.
**Note**
**Powered by Amazon Bedrock**: AWS implements [automated abuse detection](https://docs.aws.amazon.com//bedrock/latest/userguide/abuse-detection.html). Because the **Write description for me**, **Create content summary**, **Recommend tasks**, **Use Amazon Q to create or add features to a project**, and **Assign issues to Amazon Q** feature with Amazon Q Developer Agent for software development features are built on Amazon Bedrock, users can take full advantage of the controls implemented in Amazon Bedrock to enforce safety, security, and the responsible use of artificial intelligence (AI).
Amazon Q performs best on simple issues and straightforward problems. For best results, use plain language to clearly explain what you want done. The following are some best practices to help you create issues optimized for Amazon Q to work on.
**Important**
Generative AI features are only available in the US West (Oregon) Region.
+ **Keep it simple**. Amazon Q does best with simple code changes and fixes that can be explained in the title and description of the issue. Don't assign issues with vague titles or overly flowery or contradictory descriptions.
+ **Be specific**. The more information you can provide about the exact changes needed to resolve the issue, the more likely Amazon Q will be able to create a solution that solves the issue. If possible, include specific details such as the name of APIs you want changed, methods you want updated, tests that need changes, and any other details you can think of.
+ **Make sure you have all the details included in the title and description of the issue before assigning it to Amazon Q**. You can't change the title or description of an issue after you assign it to Amazon Q, so make sure you have all the information required in an issue before you assign it to Amazon Q.
+ **Only assign issues that require code changes in a single source repository**. Amazon Q can only work on code in a single source repository in CodeCatalyst. Linked repositories are not supported. Make sure that the issue only requires changes in a single source repository before you assign that issue to Amazon Q.
+ **Use the default suggested by Amazon Q for approving each step**. By default, Amazon Q will require your approval for each step it takes. This allows you to interact with Amazon Q in comments not only on the issue, but also on any pull request it creates. This provides a more interactive experience with Amazon Q that helps you adjust its approach and refine the code it creates to solve the issue.
**Note**
Amazon Q does not respond to individual comments in issues or pull requests, but it will review them when asked to reconsider its approach or create a revision.
+ **Always carefully review the approach suggested by Amazon Q**. Once you approve its approach, Amazon Q will start work on generating code based on that approach. Make sure that the approach seems correct and includes all the details you expect before you tell Amazon Q to proceed.
+ **Make sure to only allow Amazon Q to work on workflows if you don't have existing workflows that might deploy them before they're reviewed**. Your project might have workflows configured to start runs on pull request events. If so, any pull request that Amazon Q creates that includes creating or updating workflow YAML might start a run of those workflows included in the pull request. As a best practice, don't choose to allow Amazon Q to work on workflow files unless you are sure there are no workflows in your project that will automatically run these workflows before you review and approve the pull request it creates.
For more information, see [Tutorial: Using CodeCatalyst generative AI features to speed up your development work](getting-started-project-assistance.md) and [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html).
## Estimating an issue
In agile development, the *estimate* is known as story points. You can use the estimate for an issue to represent the amount of work required, in addition to the ambiguity and complexity of the issue. Consider using higher estimates for issues with greater risk, difficulty, and unknowns.
Before you can begin estimating your issues, you must first choose what type of estimates you want to use for your project. There are two types to choose from by default. To use either **T-shirt sizing** or **Fibonacci sequencing** effectively, your team must align on what each size represents. Decide together what each estimate represents to you, and then start applying those estimates to each issue. Consider periodically reviewing
Follow these steps to configure the setting for effort estimations for issues in CodeCatalyst.
**To configure effort estimation for issues**
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. In **Estimation** in the **Basic settings** section, choose how the estimation values will be displayed. The types of estimates available are **T-shirt sizing**, **Fibonacci sequencing**, or **Hide estimates**. If the project's estimation setting is set to **Hide estimates**, there will not be an **Estimation** field in the issues for the project.
When the estimation type is updated, no data will be lost and the estimation value of all issues will be converted automatically. The conversion mapping is shown in the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/issues-tracking-work.html)
To add or change an estimate for an issue, you can [edit the issue](issues-edit-issue.md).
# Editing and collaborating on issues in CodeCatalyst
**Contents**
+ [Editing an issue](issues-edit-issue.md)
+ [Working with attachments](issues-attachments.md)
+ [Viewing and managing attachments](issues-settings-attachments.md)
+ [Managing tasks on issues](issues-tasks.md)
+ [Link an issue to another issue](issues-link-issue.md)
+ [Marking an issue as blocked or unblocked](issues-mark-as-blocked.md)
+ [Adding, editing, or deleting comments](issues-comment.md)
+ [Using mentions in a comment](issues-mentions-comment.md)
# Editing an issue
Follow these steps to edit the title, description, status, assignee, priority, estimate, or labels of an issue.
**To edit an issue**
1. Choose the issue that you want to edit to view the issue details. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. To edit the issue title, choose the title, enter a new title, and press enter.
1. To edit the description, choose the description, enter a new description, and press enter. You can use Markdown to add formatting.
1. In **Tasks**, you can view and manage the tasks for the issue. If there are no tasks, you can have Amazon Q analyze the issue and recommend tasks that can break down the work in the issue into separate items that can each be assigned to a user. For more information, see [Managing tasks on issues](issues-tasks.md).
1. To edit the **Status**, **Estimate**, or **Priority**, choose an option from the respective dropdown menus.
1. In **Labels**, you can add an existing label, create a new label, or remove a label.
1. To add an existing label, choose **\$1 Add label** and choose the label from the list. You can enter a search term in the field to search all labels containing that term in the project.
1. To create a new label and add it, choose **\$1 Add label** enter the name of the label you want to create in the search field and press enter.
1. To remove a label, choose the **X** icon next to the label you want to remove. If you remove a label from all issues, the label will appear in the **Unused labels** section in the **Labels** section of issue **settings**. Unused labels appear at the end of the list of labels when using filters or adding labels to an issue. You can find an overview of all labels (used and unused) and issues that have them in the issue **settings**.
1. To assign an issue, choose **\$1 Add an assignee** in the **Assignee** section, then search and choose the assignee from the list. You can choose **\$1 Add me** to quickly add yourself as the assignee.
1. In **Attachments**, you can add, download, or remove attachments. For more information, see [Working with attachments](issues-attachments.md).
1. To link a pull request, choose **Link pull request**, and then either choose a pull request from the list or enter its URL or ID. To unlink a pull request, choose the unlink icon.
**Tip**
After you add a link to a pull request to an issue, you can quickly navigate to it by choosing its ID in the list of linked pull requests. You can use the URL of a pull request to link pull requests that are in different projects than the issue board, but only users that are members of that project will be able to view or navigate to that pull request.
1. (Optional) Add and set an existing custom field, create a new custom field, or remove a custom field. Issues can have multiple custom fields.
1. To add an existing custom field, choose the custom field from the list. You can enter a search term in the field to search all custom fields containing that term in the project.
1. To create a new custom field and add it, enter the name of the custom field you want to create in the search field and press enter. Then choose the type of custom field you want to create and set a value.
1. To remove a custom field, choose the **X** icon next to the custom field you want to remove. If you remove a custom field from all issues, the custom field will be deleted and you will no longer see it when filtering.
# Working with attachments
You can add attachments to issues in CodeCatalyst to make related files easily accessible. Use the following procedure to manage attachments for an issue.
The size of attachments added to issues counts towards your space's storage quotas. For information about viewing and managing attachments for your project, see [Viewing and managing attachments](issues-settings-attachments.md).
**Important**
Attachments to issues are not scanned or analyzed by Amazon CodeCatalyst. Any user could add an attachment to an issue that might potentially contain malicious code or content. Make sure that users are aware of best practices when it comes to managing attachments and guarding against malicious code, content, or viruses.
**To add, download, or remove attachments**
1. Choose the issue for which you want to manage attachments. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. To add an attachment, choose **Upload file**. Navigate to the file in your operating system's file explorer and select it. Choose **Open** to add it as an attachment. For quota information, such as maximum attachment size, see [Quotas for issues in CodeCatalyst](issues-quotas.md).
Note the following restrictions to attachment file names and content types:
+ The following characters are not permitted in file names:
+ Control characters: `0x00–0x1f` and `0x80–0x9f`
+ Reserved characters: `/`, `?`, `<`, `>`, `\`, `:`, `*`, `|`, and `"`
+ Unix reserved filenames: `.` and `..`
+ Trailing periods and spaces
+ Windows reserved filenames: `CON, PRN, AUX, NUL, COM1, COM2, COM3, COM4, COM5, COM6, COM7, COM8, COM9, LPT1, LPT2, LPT3, LPT4, LPT5, LPT6, LPT7, LPT8, and LPT9`
+ The content type of the attachment must adhere to the following media-type pattern:
```
media-type = type "/" [tree "."] subtype ["+" suffix]* [";" parameter];
```
For example, `text/html; charset=UTF-8`.
1. To download an attachment, choose the ellipses menu next to the attachment you want to download and choose **Download**.
1. To copy an attachment's URL, choose the ellipses menu next to the attachment of which you want to copy the URL and choose **Copy URL**.
1. To remove an attachment, choose the ellipses menu next to the attachment you want to remove and choose **Delete**.
# Viewing and managing attachments
You can view a table with every attachment added to issues in your project in issue settings. This table includes details of each attachment, including information such as content type, when it was added, the issue it's added to and its status, and the file size.
This table can be used to easily identify large attachments on issues that are completed or archived to remove them to free up space storage.
**Important**
Attachments to issues are not scanned or analyzed by Amazon CodeCatalyst. Any user could add an attachment to an issue that might potentially contain malicious code or content. Make sure that users are aware of best practices when it comes to managing attachments and guarding against malicious code, content, or viruses.
**To view and manage all issue attachments in a project**
1. In the navigation pane, choose **Issues**.
1. Choose the ellipsis icon and choose **Settings**.
1. Choose the **Attachments** tab.
# Managing tasks on issues
*Tasks* can be added to issues to further break down, organize, and track the work of that issue. You can create tasks yourself, or you can use Amazon Q to recommend tasks based on its analysis of the issue and its complexity.
Amazon Q Developer is a generative AI-powered conversational assistant that can help you to understand, build, extend, and operate AWS applications. To accelerate your building on AWS, the model that powers Amazon Q is augmented with high-quality AWS content to produce more complete, actionable, and referenced answers. For more information, see [What is Amazon Q Developer?](https://docs.aws.amazon.com/amazonq/latest/aws-builder-use-ug/what-is.html) in the *Amazon Q Developer User Guide*.
**To manage tasks on an issue**
1. Choose the issue for which you want to manage tasks. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. In **Tasks**, you can view and manage tasks for the issue.
1. To add a task, input the task name in the text field and press enter.
1. If there are no tasks for the issue, you can choose to have Amazon Q analyze the issue and create tasks based on the issue title, description, and its analysis of the complexity of the issue and the repository code, choose **Recommend tasks**. You will need to specify the source repository that contains the code for the issue. Choose **Start recomending tasks** to begin the task recommendation analysis. That dialog will close. Once the recommendation is complete, choose **View recommended tasks** to review the tasks and take any needed action, such as deleting or adding tasks to the list or reordering the recommended tasks, before choosing **Create tasks**.
After tasks are created for you, you can assign them to users and work with them the same way you work with manually created tasks.
1. To mark a task as completed, choose the checkbox of the task.
1. To view or update the details of a task, choose it from the list.
1. To reorder the tasks, choose and drag the task from the left side of the checkbox.
1. To remove a task, choose the ellipses menu of the task and choose **Remove**.
# Link an issue to another issue
If an issue is related to work in another issue, you can link them. This is a quick way to help you understand and track dependencies between work items.
When linking an issue, there are four states to choose from:
+ Related to: Use this state to indicate work that is related to the linked issue.
+ Blocked by: Use this state to indicate that the issue is blocked by the linked issue.
+ Blocking to: Use this state to indicate that the issue is blocking progress on the linked issue.
+ Duplicate: Use this state to indicate that the issue duplicates work captured in another issue.
You can change the state of a link after you create it. Links and their link state appear in **Linked issues** in both the issue where you create the link, and the issue that is linked. You can also remove links after they are created.
**To link an issue to another issue or task**
1. Open the issue you want to link to another issue. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Link issues**.
1. In **Mark as**, choose the state for the link.
In **Issue \$1**, enter the number for the issue, or choose it from the drop-down list.
1. To add another link, choose **Add linked issue**.
1. When you are done, choose **Update** to update the issue and all linked issues with the linked relationship.
# Marking an issue as blocked or unblocked
If something is preventing you from working on an issue, you might want to mark it as *blocked*. For example, your issue might be blocked if it relies on a change to another part of your code base that hasn't been merged yet.
When you mark an issue as blocked, CodeCatalyst adds a red **Blocked** label to the issue, making it highly visible in your backlog or archive, or on your board.
You can unblock the issue when outside circumstances are resolved.
**To mark an issue as blocked**
1. Open the issue you want to mark as blocked. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Actions**, and then choose **Mark as blocked**.
**To unblock an issue**
1. Open the issue that you want to unblock. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Actions**, and then choose **Mark as unblocked**.
# Adding, editing, or deleting comments
You can leave a comment on an issue. In the comments you can tag other space members, other projects in the space, related issues, and code.
**To add a comment to an issue**
1. Navigate to your project.
1. In the navigation bar choose **Issues**.
1. Choose the issue where you want to add the comment. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. Enter the comment in the **Comments** field. You can use Markdown to add formatting.
1. Choose **Send**.
**To edit a comment**
You can edit comments you make on issues. You can only edit comment that you authored.
1. Navigate to your project.
1. In the navigation bar choose **Issues**.
1. Choose the issue where you want to edit a comment. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. To edit a comment, find the comment you want to edit.
**Tip**
You can sort comments by oldest or newest first. Comments are loaded 10 at a time.
1. Choose the ellipsis icon, then choose **Edit**.
1. Edit the comment. You can use Markdown to add formatting.
1. Choose **Save**. The comment is now updated.
**To delete a comment**
You can delete comments you make on issues. You can only delete comments that you authored. When a comment is deleted, your user name will show, but with the words *This comment has been deleted* in place of the original comment text.
1. Navigate to your project.
1. In the navigation bar choose **Issues**.
1. Choose the issue where you want to delete a comment. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose the ellipsis icon, choose **Delete**, and then choose **Confirm**.
# Using mentions in a comment
You can mention space members, other projects in the space, related issues, and code in comments. Doing so creates a quick link to the user or resource you mention.
**To @mention in a comment**
1. Navigate to your project.
1. In the navigation bar choose **Issues**.
1. Choose the issue that you want to edit to view the issue details. For help on finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose the **Add a comment** textbox.
1. Type `@user_name` to mention another user.
1. Type `@project_name` to mention a project.
1. Type `@issue_name` or `@issue_number` to mention another issue.
1. Type `@file_name` to mention specific files or code in a source repository.
**Note**
A list of the top 5 items (users, source repositories, projects, etc) containing the terms that match your `@mention` will populate as you type.
1. Choose the desired item you would like to mention. The pathway showing where the item is located will populate in the comment textbox.
1. Finish your comment and choose **Send**.
# Finding and viewing issues
The following sections describe how to effectively search for and view issues within a CodeCatalyst project.
## Searching for an issue
You can find an issue by searching for specific parameters. For more information about refining your search, see [Search for code, issues, projects, and users in CodeCatalystSearch for code, issues, projects, and users](search.md).
**To search for an issue**
1. Navigate to your project.
1. Use the search bar to search for issues or information related to issues. You can use query parameters to refine your search. For more information, see [Search for code, issues, projects, and users in CodeCatalystSearch for code, issues, projects, and users](search.md).
# Sorting issues
By default, issues in CodeCatalyst are sorted by **Manual order**. Manual order displays issues in the order they are moved to by users. You can drag and drop issues when sorted in Manual order to change their order. This sorting option is helpful when grooming the issues backlog and prioritizing issues.
The following table shows how issues can be sorted in both grid and board views.
| Grid view sorting options | Board view sorting options |
| --- | --- |
| Manual order | Manual order |
| Last updated | Last updated |
| Priority | Priority |
| Estimate | Estimate |
| Title | Title |
| ID | |
| Status | |
| Blocked | |
| Custom fields | |
Use the following procedure to change how issues are sorted.
**To sort issues**
1. Navigate to your project.
1. In the navigation pane, choose **Issues**. The default view is the **Board**.
1. (Optional) Choose **Active issues** to open the **issues view switcher** dropdown menu to navigate to a different issues view.
1. To sort a grid view, there are two options:
1. Choose the **header** of the field you want to sort by. Choosing the **header** will cycle between ascending and descending order.
1. Choose the **Sort by** dropdown menu and choose a parameter to sort by. Issues will be sorted in ascending order.
1. To sort a board view, choose the **Sort by** dropdown menu and choose a parameter to sort by. Issues will be sorted in ascending order.
# Grouping issues
Grouping is used to organize issues on the board by multiple parameters, such as assignee, labels, and priority.
**To group issues**
1. Navigate to your project.
1. In the navigation pane, choose **Issues**. The default view is the **Board**.
1. (Optional) Choose **Active issues** to open the **issues view switcher** dropdown menu to navigate to a different issues view.
1. Choose **Group**.
1. In **Group by**, choose a parameter to group by:
+ If you choose **Assignee** or **Priority**, choose the **Group order**.
+ If you choose **Label**, choose the labels and then choose **Group order**.
1. (Optional) Choose the **Show empty groups** toggle to show or hide groups that have no issues currently assigned to them.
1. The view updates as you make your choices. An issue only appears in the group that matches the configured parameters.
# Filtering issues
Use filtering to find issues that contain a specified name, priority, label, custom fields, or assignee.
**To filter issues**
1. Navigate to your project.
1. In the navigation pane, choose **Issues**.
1. (Optional) Choose **Active issues** to open the **issues view switcher** dropdown menu to navigate to a different issues view.
**Note**
To filter based on a string in the issue name or description, enter the string into the issues search bar.
1. Choose **Filter**, then choose **\$1 Add filter**.
1. Choose the parameters to filter for. You can choose multiple filters and parameters. You can configure filters to show issues that match every filter or any individual filter by selecting **and** or **or**. The view will update to show the issues that match the filter.
# Progressing an issue
Every issue has a lifecycle. In CodeCatalyst, issues typically start as a draft in the backlog. When work for that issue is to be started, it is moved into another status category and moves through various statuses until it is complete, and then it is archived. You can move or progress an issue through its lifecycle in the following ways:
+ You can move an issue between the backlog and the board.
+ You can move in-progress issue through various completion stages.
+ You can archive an issue that is completed.
# Moving an issue beetween the backlog and board
You can move an issue from the backlog to the board once you begin to work on the issue. You can also move an issue back to the backlog if the work is postponed.
**To move an issue between the backlog and the board**
1. Navigate to your project.
1. In the navigation pane, choose **Issues**. The default view is the **Board**.
1. To move an issue from the board to the backlog:
1. Choose the issue that you want to move. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Backlog** from the dropdown **Status** menu.
1. To move an issue from the backlog to the board:
1. To navigate to the backlog, choose **Board** and choose **Backlog**.
1. Choose the issue that you want to move. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Add to board**, or choose a **Status** other than **Backlog**.
# Progress an issue through lifecycle stages on the board
You can move an issue within a board through different statuses until completion.
**To move an issue within the board**
1. In the navigation pane, choose **Issues**. The default view is the **Board**.
1. Do one of the following:
+ Drag and drop an issue to another status.
+ Choose an issue, and then choose a status from the **Status** dropdown menu.
+ Choose an issue, and then choose **Move to: *next-status***.
For information on archiving an issue, see [Archiving an issue](issues-archive-issues.md).
# Moving issues between groups
You can [group issues](issues-grouping.md) in the **All issues** and **Board** views by various parameters. If the issues are grouped, you can move issues from one group to another. Moving an issue from one group to another will automatically edit the field that the issues are grouped on to match the target group.
As an example scenario, assume there is a company using CodeCatalyst that has issues assigned to two people, Wang Xiulan and Saanvi Sarkar. The board is grouped by `Assignee`, and there are two groups, one for each assignee. Moving an issue from the Wang Xiulan group to the Saanvi Sarkar group will update the issue's assignee to Saanvi Sarkar.
# Archiving an issue
**Note**
Issues are not deleted within a project, they are archived. To delete issues, you must delete the project.
You can archive an issue when it is no longer needed in your project. When you archive an issue, CodeCatalyst removes it from all views that filter out archived issues. Archived issues can be viewed in the **Archived issues** default view, where they can be unarchived if needed.
You archive an issue if:
+ You have completed the issue and no longer need it in the **Done** column.
+ You have no plans to work on it.
+ You created it in error.
+ You have reached the maximum number of active issues.
**To archive an issue**
1. Open the issue you want to archive. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Actions**, and then choose **Move to archive**.
1. (Optional) To quickly archive multiple issues with a **Completed** status, choose the vertical ellipsis at the top of any **Completed** status on the board and choose **Archive issues**.
**To unarchive an issue**
1. Open the issue that you want to unarchive. You can view a list of archived issues by opening the **Archived issues** view from the **issues view switcher** dropdown menu. For help with finding your issue, see [Finding and viewing issues](issues-view.md).
1. Choose **Unarchive**.
# Exporting issues
You can export issues in your current view into a .xlsx file. To export issues, perform the following steps.
**To export issues**
1. Navigate to your project.
1. In the navigation bar choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and navigate to the view containing the issues you want to export. Only issues shown in the view will be exported.
1. Choose the ellipses menu and choose **Export to Excel**.
1. The .xlsx file downloads. By default, it is titled the name of the project and the date the export was completed.
# Organizing work with backlogs, labels, and boards
Not all teams work in the same way. You can configure the way issues appear and can be assigned in Amazon CodeCatalyst to help you precisely understand what's being worked on and the status of that work. You can choose what estimation method to allow for issues so that your users all use the same estimation method. You can create cusotm labels and statuses which can also be used to filter the view of the work. Depending on how your team works, you can configure whether to allow multiple assignees for an issue, or only allow an issue to be assigned to a single user. You can also create custom views of issues so that work is displayed in a way that shows the most relevant information to you or your team.
# Categorizing work with labels
You can customize labels for issues. This includes editing the label and changing the color. Labels can help you categorize and organize your work. For example, you can create labels for specific aspects of your software, or for different groups or teams.
**Topics**
+ [Creating a label](#issues-create-label)
+ [Editing a label](issues-edit-label.md)
+ [Deleting a label](issues-delete-label.md)
## Creating a label
In CodeCatalyst, you create labels by either adding them when you create a new issue or when you edit an existing issue. For more information, see [Creating an issue in CodeCatalyst](issues-create-issue.md) and [Editing and collaborating on issues in CodeCatalyst](issues-edit-collaborate-issue.md).
# Editing a label
Use the following procedure to change the name or color of an existing label.
**To edit a label**
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. On the **Labels** tile is a list of the labels used in the project. Choose the edit icon next to the label that you want to edit. Do one or more of the following:
1. Edit the name of the label.
1. To change the color, choose the color wheel. Use the picker to choose a new color.
1. To save the changes you made to the label, choose the check mark icon.
1. The changed label is now visible in your list of available labels. You can also see how many issues are using that label.
**Note**
You can choose the number displayed next to each label to navigate to the **All issues** page and see all issues that contain that label.
# Deleting a label
You cannot currently delete an issues label in CodeCatalyst. If you remove a label from all issues, the label will appear in the **Unused labels** section in the **Labels** section of issue **settings**. Unused labels appear at the end of the list of labels when using filters or adding labels to an issue. You can find an overview of all labels (used and unused) and issues that have them in the issue **settings**.
# Organizing work with custom fields
You can create custom fields to help organize and view the work for your project. Custom fields are added to the list of available filters in **Filter** so you can filter issues by custom fields. Custom fields are name and value pairs. You filter by the name of the custom field, and then the value of that custom field.
An issue can have multiple custom fields.
## Creating a custom field
In CodeCatalyst, you create custom fields by either adding them when you create an issue or when you edit an existing issue. For more information, see [Creating an issue in CodeCatalyst](issues-create-issue.md) and [Editing and collaborating on issues in CodeCatalyst](issues-edit-collaborate-issue.md).
## Deleting a custom field
To delete a custom field, you must remove the custom field from each issue it is added to. When a custom field is deleted, you will no longer see the custom field in **Filter**. You can use filters to view all issues with a custom field, and remove them by editing the issues. For more information, see [Finding and viewing issues](issues-view.md) and [Editing an issue](issues-edit-issue.md)
# Tracking work with custom statuses
You can add custom statuses on your board. Each custom status must belong to one of the following categories: **Draft**, **Not started**, **Started**, or **Completed**. Status categories are used to help organize statuses and populate default views. For more information about statuses and status categories, see [Status and status categories](issues-concepts.md#issues-concepts-status-definition) and for more information about views, see [Finding and viewing issues](issues-view.md).
# To create a status
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. In **Statuses**, choose the plus icon next to the category you want the status to be in.
1. Name the status, then choose check mark icon.
**Note**
Choose the X icon to cancel adding a status.
The custom status is now visible on your board and shows as an option when creating an issue.
# To edit a status
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. In **Statuses**, choose the edit icon next to the status you want to edit or change.
1. Edit the status, then choose the check mark icon.
The edited status is now visible on your board.
# To move a status
1. In the navigation pane, choose **Issues**.
1. Choose the ellipsis icon and choose **Settings**.
1. In **Statuses**, choose a status you want to move.
1. Drag and drop the status where you want it to be.
**Note**
You can only move a status within its designated category.
The statuses are now reordered on your board.
# To deactivate a status
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. In **Statuses**, choose a status you want to deactivate.
1. On the status you want to deactivate, choose the toggle on the status. The status is now grayed out.
**Note**
The deactivated status appears on the board until all issues are moved out of it. Issues cannot be added to a deactivated status.
1. To reactivate a deactivated status, choose the toggle on the status. The status is no longer grayed out.
**Note**
There must be at least one active status in each category. If there is only one status in the category, you cannot deactivate it.
# Configuring issue effort estimation
Follow these steps to configure the setting for effort estimations for issues in CodeCatalyst.
**To configure effort estimation for issues**
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. In **Estimation** in the **Basic settings** section, choose how the estimation values will be displayed. The types of estimates available are **T-shirt sizing**, **Fibonacci sequencing**, or **Hide estimates**. When the estimation type is updated, no data will be lost and the estimation value of all issues will be converted automatically. The conversion mapping is shown in the following table.
[\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/issues-settings-estimation.html)
# Enabling or disabling multiple assignees
Follow these steps to configure the setting for multiple assignees for issues in CodeCatalyst.
**To enable or disable multiple assignees**
1. In the navigation pane, choose **Issues**.
1. Choose **Active issues** to open the **issues view switcher** dropdown menu and choose **Settings**.
1. In **Assignee** in the **Basic settings** section, toggle the indicator to enable multiple assignees to be assigned to the same issue. An issue can have up to 10 assignees. If you do not enable this option, you will only be able to assign one assignee to an issue.
# Creating an issues view
You can create [views](issues-concepts.md#issues-concepts-views-definition) to quickly view issues that match a particular set of filters. This can help you save time and quickly view issues you have previously filtered, grouped, or sorted by.
**To create an issues view**
1. In the navigation pane, choose **Issues**.
1. (Optional) Depending on your use case, you may want to create a view from an existing view. To navigate to a different view, choose **Active issues** to open the **issues view switcher** dropdown menu and choose the view.
1. (Optional) Configure filters, grouping, and sorting before you create your view. You can add these while creating a view, but if you do it before, you can preview what is shown in the view before creating it.
1. Open the **issues view switcher** dropdown menu from the header bar. To create a board view where issues are viewed in columns based on status, choose the **\$1** in the **Board** column. To create a grid view where issues are viewed in a list, choose the **\$1** in the **Grid** column. You can change the type of view before it is created if you change you mind.
1. In the **Create view** dialog box, enter a **Name** for the view.
1. The **Filters**, **Group issues by**, and **Sort issues by** fields are filled based on the settings of the current view. Update them if necessary.
1. Choose **Create view** to create the view and be switched to it.
# Quotas for issues in CodeCatalyst
The following table describes quotas and limits for issues in Amazon CodeCatalyst. For more information about quotas in Amazon CodeCatalyst, see [Quotas for CodeCatalyst](quotas.md)..
| Resource | Default quota |
| --- | --- |
| Active issues | Maximum of 1,000 per project. |
| Attachment size | Maximum of 500MB per attachment. Maximum total attachment storage is impacted by the overall storage limits for your space. For more information, see [Pricing](https://codecatalyst.aws/explore/pricing). |
| Total number of issues (active and archived) | Maximum of 100,000 per project. |
| Saved views | Maximum of 50 saved issue views per project. |
| Number of pull requests you can link to an issue | Maximum of 50 pull requests per issue. |
| Statuses (per project) | Maximum of 50 per project. |
| Statuses (per issue) | Maximum of 50 per issue. |
| Labels (per project) | Maximum of 200 per project. |
| Labels (per issue) | Maximum of 50 per issue. |
| Custom fields (per issue) | Maximum of 50 per issue. |
| Assignees | Maximum of 10 per issue. |
| Comments | Maximum of 1,000 per issue. |
| Tasks | Maximum of 100 per issue. |