Tutorial: Using CodeCatalyst generative AI features to speed up your development work - Amazon CodeCatalyst

Tutorial: Using CodeCatalyst generative AI features to speed up your development work

The generative AI features in Amazon CodeCatalyst are in preview release and are subject to change. They are only available in the US West (Oregon) Region. Access to generative AI features varies by tier. For more information, see Pricing.

If you have a project and a source repository in Amazon CodeCatalyst in a space where generative AI features are enabled, you can use these features to help speed up software development. Developers frequently have more tasks to do than time to accomplish them. They often don't take the time to explain their code changes to their teammates when creating pull requests for review of those changes, expecting other users to find the changes self-explanatory. Pull request creators and reviewers also don't have time to find and read all the comments on a pull request thoroughly, particularly if the pull request has multiple revisions. CodeCatalyst includes generative AI features that can both help team members accomplish their tasks more quickly, and increase the time they have to focus on the most important parts of their work.


Powered by Amazon Bedrock: AWS implements automated abuse detection. Because the Write description for me, Create content summary, and Assign issues to Amazon Q feature development capability 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).

In this tutorial, you'll learn how to use the generative AI features in CodeCatalyst to help you summarize changes between branches when creating pull requests and to summarize comments left on a pull request. You'll also learn how to create issues with your ideas for simple code changes or improvements and assign them to Amazon Q.


To work with the CodeCatalyst features in this tutorial, you must have first completed and have access to the following resources:

  • You have an AWS Builder ID or a single sign-on (SSO) identity for signing in to CodeCatalyst.

  • Your project is in a space that has generative AI features enabled. For more information, see Managing generative AI features.

  • You have the Contributor or Project administrator role in a project in that space.

  • The project has at least one source repository configured for it. Linked repositories are not supported.

  • When assigning issues to have an initial solution created by generative AI, the project cannot be configured with the Jira Software extension. The extension is not supported for this feature.

For more information, see Creating a space that supports AWS Builder ID users, Issues in CodeCatalyst, Extensions in CodeCatalyst, and Working with roles in Amazon CodeCatalyst.

This tutorial is based on a project created using the Modern three-tier web application blueprint with Python. If you use a project created with a different blueprint, you can still follow the steps, but some specifics will vary, such as sample code and language.

Create a summary of the code changes between branches when creating a pull request

A pull request is the primary way you and other project members can review, comment on, and merge code changes from one branch to another. You can use pull requests to review code changes collaboratively for minor changes or fixes, major feature additions, or new versions of your released software. Summarizing the code changes and the intent behind the changes as part of the pull request's description is helpful to others who will review the code, and also helps with a historical understanding of the changes to the code over time. However, developers often rely on their code to explain itself or provide ambiguous details rather than describing their changes with enough details for reviewers to understand what they are reviewing or what the intent was behind the changes in the code.

You can use the Write description for me feature when creating pull requests to have Amazon Q create a description of the changes contained in a pull request. When you choose this option, Amazon Q analyzes the differences between the source branch that contains the code changes and the destination branch where you want to merge these changes. It then creates a summary of what those changes are, as well as its best interpretation of the the intent and effect of those changes.

You can try this feature with any pull request you create, but in this tutorial, we'll test it out by making some simple changes to the code contained in a project created in a Python-based Modern three-tier web application blueprint.


If you are using a project created with a different blueprint or your own code, you can still follow this tutorial, but the examples in this tutorial will not match the code in your project. Instead of the suggested example below, make simple changes in your project's code in a branch, and then create a pull request to test the feature as shown in the following steps.

First, you will create a branch in the source repository. You'll then make a quick code change to a file in that branch using the text editor in the console. You'll then create a pull request, and use the Write description for me feature to summarize the changes you made.

To create a branch (console)
  1. In the CodeCatalyst console, navigate to the project where your source repository resides.

  2. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose Code, and then choose Source repositories.

  3. Choose the repository where you want to create a branch.

  4. On the overview page of the repository, choose More, and then choose Create branch.

  5. Enter a name for the branch.

  6. Choose a branch to create the branch from, and then choose Create.

Once you have a branch, edit a file in that branch with a simple change. In this example, you'll edit the test_endpoint.py file to change the number of retries for tests from 3 to 5.


You can also choose to create or use a Dev Environment to make this code change. For more information, see Creating a Dev Environment.

To edit the test_endpoint.py file in the console
  1. On the overview page for the mysfits source repository, choose the branch drop-down and choose the branch you created in the previous procedure.

  2. In Files, navigate to the file you want to edit. For example, to edit the test_endpoint.py file, expand tests, expand integ, and then choose test_endpoint.py.

  3. Choose Edit.

  4. On line 7, change the number of times all tests will be retried from:

    def test_list_all(retry=3):


    def test_list_all(retry=5):
  5. Choose Commit and commit your changes to your branch.

Now that you have a branch with a change, you can create a pull request.

Create a pull request with a summary of the changes
  1. On the overview page of the repository, choose More, and then choose Create pull request.

  2. In Destination branch, choose the branch to merge the code into after it is reviewed.


    Choose the branch that you created your branch from in the previous procedure for the simplest demonstration of this feature. For example, if you created your branch from the repository's default branch, choose that branch as the destination branch for your pull request.

  3. In Source branch, choose the branch that contains the changes you just committed to the test_endpoint.py file.

  4. In Pull request title, enter a title that helps other users understand what needs to be reviewed and why.

  5. In Pull request description, choose Write description for me to have CodeCatalyst create a description of the changes contained in the pull request.

  6. A summary of the changes appears. Review the suggested text and then choose Accept and add to description.

  7. Optionally modify the summary to better reflect the changes you made to the code. You can also choose to add reviewers or link issues to this pull request. When you have finished making any additional changes you want, choose Create.

Create a summary of comments left on code changes in a pull request

When users review a pull request, they often leave multiple comments on the changes in that pull request. If there are a lot of comments from a lot of reviewers, it can be difficult to pick out common themes in the feedback, or even be sure that you've reviewed all the comments in all revisions. You can use the Create comment summary feature to have Amazon Q analyze all the comments left on code changes in a pull request and create a summary of those comments.


Comment summaries are transient. If you refresh a pull request, the summary will disappear. Content summaries do not include comments on the overall pull request, just comments left on differences in code in revisions of the pull request.

To create a summary of comments in a pull request
  1. Navigate to the pull request you created in the previous procedure.


    If you prefer, you can use any open pull request in your project. In the navigation bar, choose Code, choose Pull requests, and choose any open pull request.

  2. Add a few comments to the pull request in Changes if the pull request does not already have comments.

  3. In Overview, choose Create comment summary. When complete, the Comment summary section expands.

  4. Review the summary of comments left on changes in the code in revisions of the pull request, and compare it to the comments in the pull request.

Create an issue and assign it to Amazon Q

Development teams create issues to track and manage their work, but sometimes an issue lingers because either it's not clear who should work on it, or the issue requires research into a particular part of the code base, or other urgent work must be attended to first. 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 your work on issues that require your attention, while Amazon Q works on a solution for problems you don't have resources to address immediately.


Amazon Q performs best on simple issues and straightforward problems. For best results, use plain language to clearly explain what you want done.

When you assign an issue to Amazon Q, CodeCatalyst will mark the issue as blocked until you confirm how you want Amazon Q to work on the issue. It requires you to answer three questions before it can continue:

  • Whether you want to confirm every step it takes or whether you want it to proceed without feedback. If you choose to confirm each step, you can reply to Amazon Q with feedback on the approach it creates so it can iterate on its approach if needed. Amazon Q can also review feedback users leave on any pull request it creates if you choose this option. If you choose not to confirm each step, Amazon Q might complete its work more quickly, but it won't review any feedback you give it in the issue or in any pull request it creates.

  • Whether you want to allow it to update workflow files as part of its work. 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.

  • What source repository you want it to work in. Even if your project has multiple source repositories, Amazon Q can only work on code in one source repository. Linked repositories are not supported.

Once you have made and confirmed your choices, Amazon Q will move the issue into the In progress state while it attempts to determine what the request is based on the issue title and its description, as well as the code in the specified repository. It will create a pinned comment where it will provide updates on the status of its work. After reviewing the data, Amazon Q will formulate a potential approach to a solution. Amazon Q records its actions by updating its pinned comment and commenting on its progress on the the issue at every stage. Unlike pinned comments and replies, it does not keep a strictly chronological record of its work. Rather, it puts the most relevant information about its work at the top-level of the pinned comment. It will attempt to create code based on its approach and its analysis of the code already in the repository. If it successfully generates a potential solution, it will create a branch and commit code to that branch. It then creates a pull request that will merge that branch with the default branch. When Amazon Q completes its work, it moves the issue to In review so that you and your team knows there is code ready for you to evaluate.


This feature is only available through Issues. It is not available if you have configured your project to use Jira with the Jira Software extension. Additionally, if you have customized the layout of your board, the issue might not change states. For best results, only use this feature with projects that have a standard board layout.

Once you have assigned an issue to Amazon Q, you cannot change the title or description of the issue or assign it to anyone else. If you unassign Amazon Q from the issue, it will finish its current step and then stop work. It cannot resume work or be reassigned to the issue once it is unassigned.

In this portion of the tutorial, you will create three issues based on potential features for the code included in projects created with the Modern three-tier web application blueprint: one to add a to create a new mysfit creature, one to add a sort feature, and one to update a workflow to include a branch named test.


If you are working in a project with different code, create issues with titles and descriptions that relate to that code base.

To create an issue and have a solution generated for you to evaluate
  1. In the navigation pane, choose Issues and make sure you are in the Board view.

  2. Choose Create issue.

  3. Give the issue a title that explains what you want to do in plain language. For example, for this issue, enter a title of Create another mysfit named Quokkapus. In Description, provide the following details:

    Expand the table of mysfits to 13, and give the new mysfit the following characteristics: Name: Quokkapus Species: Quokka-Octopus hybrid Good/Evil: Good Lawful/Chaotic: Chaotic Age: 216 Description: Australia is full of amazing marsupials, but there's nothing there quite like the Quokkapus. She's always got a friendly smile on her face, especially when she's using her eight limbs to wrap you up in a great big hug. She exists on a diet of code bugs and caffeine. If you've got some gnarly code that needsa assistance, adopt Quokkapus and put her to work - she'll love it! Just make sure you leave enough room for her to grow, and keep that coffee coming.
  4. (Optional) Attach an image to use as the thumbnail and profile picture for the mysfit to the issue. If you do this, update the description to include details of what images you want to use and why. For example, you might add the following to the description: "The mysfit requires image files to be deployed to the website. Add these images to the source repository."


    Attached images will not be deployed to the website in this tutorial. You can add the images to the website yourself, and then leave comments for Amazon Q to update its code to point to the images you want it to use after it has created a pull request.

    Review the description and make sure it contains all the details that might be needed before you proceed to the next step.

  5. In Assignees, choose Assign to Amazon Q.

  6. In Source repository, choose the source repository that contains the project code.

  7. Slide the Require Amazon Q to stop after each step and await review of its work selector to the active state.


    Choosing the option to have Amazon Q stop after every step allows you to comment on the issue and have the option to have Amazon Q change its approach up to three times based on your comments. If you choose the option to not have Amazon Q stop after every step so that you can review its work, work might proceed more quickly because Amazon Q isn't waiting for your feedback, but you won't be able to influence the direction Amazon Q takes by leaving comments. Amazon Q will also not respond to comments left in a pull request if you choose that option.

  8. Leave the Allow Amazon Q to modify workflow files selector in the inactive state.

  9. Choose Create issue. Your view changes to the Issues board.

  10. Choose Create issue to create another issue, this time one with the title Change the get_all_mysfits() API to return mysfits sorted by the Age attribute. Assign this issue to Amazon Q and create the issue.

  11. Choose Create issue to create another issue, this time one with the title Update the OnPullRequest workflow to include a branch named test in its triggers. Optionally link to the workflow in the description. Assign this issue to Amazon Q but this time make sure that the Allow Amazon Q to modify workflow files selector is set to the active state. Create the issue to return to the Issues board.


    You can search for files, including workflow files, by entering the at symbol (@) and entering the file name.

Once you have created and assigned the issues, the issues will move into In progress. Amazon Q will add comments tracking its progress inside the issue in a pinned comment. If it is able to define an approach to a solution, it will update the issue's description with a Background section that contains its analysis of the code base and a Approach section that details its proposed approach to creating a solution. If Amazon Q is successful in coming up with a solution to the problem described in the issue, it will create a branch and code changes in that branch that implement its proposed solution. Once the code is ready, it creates a pull request so that you can review the suggested code changes, adds a link to that pull request to the issue, and moves the issue into In review.


You should always review any code changes in a pull request before merging it. Merging code changes made by Amazon Q, like any other code changes, can negatively impact your code base and infrastructure code if the merged code is not properly reviewed and contains errors when merged.

To review an issue and linked pull request that contains changes made by Amazon Q
  1. In Issues, choose an issue assigned to Amazon Q that is in In progress. Review the comments to monitor the progress of the bot. If present, review the background and approach it records in the description of the issue, and then choose X to close the issue pane.

  2. Now choose an issue assigned to Amazon Q that is in In review. Review the background and approach it records in the description of the issue. Review the comments to understand the actions it performed. In Pull requests, choose the link to the pull request next to the Open label to review the code.

  3. In the pull request, review the code changes. For more information, see Reviewing a pull request. Leave comments on the pull request if you want Amazon Q to change any of its suggested code. Be specific when leaving comments for Amazon Q for best results.

    For example, when reviewing the pull request created for Create another mysfit named Quokkapus, you might notice that there's a typo in the description. You could leave a comment for Amazon Q that states "Change the description to fix the typo "needsa" by adding a space between "needs" and "a"." Alternatively, you could leave a comment that tells Amazon Q to update the description and provide the entire revised description for it to incorporate.

    If you uploaded images for the new mysfit to the website, you can leave a comment for Amazon Q to update the mysfit with pointers to the image and thumbnail to use for the new mysfit.


    Amazon Q will not respond to individual comments. Amazon Q will only incorporate feedback left in comments in pull requests if you chose the default option of stopping after every step for approval when you created the issue.

  4. (Optional) After you and other project users have left all the comments you want for changes to the code, choose Create revision to have Amazon Q create a revision of the pull request that incorporates the changes you requested in comments. Progress on the revision creation progress will be reported by Amazon Q in Overview, not in Changes. Make sure to refresh your browser to view the latest updates from Amazon Q on creating the revision.


    Only the user who created the issue can create a revision of the pull request. You can only request one revision of a pull request. Make sure that you have addressed all problems with comments, and that you are satisfied with the content of the comments, before you choose Create revision.

  5. A workflow is run for each pull request in this example project. Make sure that you see a successful workflow run before you merge the pull request. You can also choose to create additional workflows and environments to test the code before you merge it. For more information, see Getting started with workflows in CodeCatalyst.

  6. When you are satisfied with the latest revision of the pull request, choose Merge.

Clean up resources

Once you've completed this tutorial, consider taking the following actions to clean up any resources you created during this tutorial that you no longer need.

  • Unassign Amazon Q from any issues no longer being worked on. If Amazon Q has finished its work on an issue or could not find a solution, make sure to unassign Amazon Q to avoid reaching the maximum quota for generative AI features. For more information, see Managing generative AI features and Pricing.

  • Move any issues where work is complete to Done.

  • If the project is no longer needed, delete the project.