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).
# Getting started tutorials
Amazon CodeCatalyst provides a number of different templates to help you get started with your projects. You can also choose to start with an empty project and add resources to it. Follow the steps in these tutorials to learn some of the ways you can work in CodeCatalyst.
If this is your first time using CodeCatalyst, we suggest starting with [Tutorial: Creating a project with the Modern three-tier web application blueprint](getting-started-template-project.md).
**Note**
In order to follow these tutorials, you must first complete setting up. For more information, see [Set up and sign in to CodeCatalystSet up and sign in to CodeCatalyst](setting-up-topnode.md).
**Topics**
+ [Tutorial: Creating a project with the Modern three-tier web application blueprint](getting-started-template-project.md)
+ [Tutorial: Starting with an empty project and manually adding resources](getting-started-blank-template.md)
+ [Tutorial: Using CodeCatalyst generative AI features to speed up your development work](getting-started-project-assistance.md)
For additional tutorials that focus on specific functional areas in CodeCatalyst, see:
+ [Getting started with Slack notifications](getting-started-notifications.md)
+ [Getting started with CodeCatalyst source repositories and the Single-page application blueprint](source-getting-started.md)
+ [Getting started with workflows](workflows-getting-started.md)
+ [Getting started with custom blueprints](getting-started-bp.md)
+ [Get started with the Amazon CodeCatalyst action developer guide](https://docs.aws.amazon.com/codecatalyst/latest/adk/action-development-intro.html)
For in-depth tutorials, see:
+ [Tutorial: Upload artifacts to Amazon S3](build-deploy.md)
+ [Tutorial: Deploy a serverless application](deploy-tut-lambda.md)
+ [Tutorial: Deploy an application to Amazon ECS](deploy-tut-ecs.md)
+ [Tutorial: Deploy an application to Amazon EKS](deploy-tut-eks.md)
+ [Tutorial: Lint code using a GitHub Action](integrations-github-action-tutorial.md)
+ [Tutorial: Creating and updating a React application](blueprint-getting-started-tutorial.md)
# Tutorial: Creating a project with the Modern three-tier web application blueprint
You can get started more quickly with developing software by creating a project with a blueprint. A project created with a blueprint includes the resources that you need, including a source repository to manage your code, and a workflow to build and deploy the application. In this tutorial, we will walk you through using the **Modern three-tier web application** blueprint to create a project in Amazon CodeCatalyst. The tutorial also includes viewing the deployed sample, inviting other users to work on it, and making changes to the code with pull requests that are automatically built and deployed to resources in the connected AWS account when the pull request is merged. Where CodeCatalyst creates your project with reports, activity feeds, and other tools, your blueprint creates AWS resources in the AWS account associated with your project. Your blueprint files allow you to build and test a sample modern application and deploy it to infrastructure in the AWS Cloud.
The following illustration shows how tools in CodeCatalyst are used to create an issue for tracking, merge and automatically build the change, and then start a workflow in the CodeCatalyst project that runs actions to allow AWS CDK and CloudFormation to provision your infrastructure.
The actions generate resources in the associated AWS account and deploy your application to a serverless AWS Lambdafunction with an API Gateway endpoint. The AWS Cloud Development Kit (AWS CDK) action converts one or more AWS CDK stacks to CloudFormation templates and deploys stacks to your AWS account. Resources in your stacks include Amazon CloudFront resources to distribute dynamic web content, an Amazon DynamoDB instance for your application data, and the roles and policies that support the deployed application.
![\[A code change, from the creation of an issue through the change in the source repository, which is then automatically built and deployed to resources in AWS\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/modern-app-overview.png)
When you create a project with the **Modern three-tier web application** blueprint, your project is created with the following resources:
**In the CodeCatalyst project**:
+ A [source repository](source.md) with sample code and workflow YAML
+ A [workflow](workflow.md) that builds and deploys the sample code whenever a change is made to the default branch
+ An issues board and backlog that you can use to plan and track work
+ A test reports suite with automated reports included in the sample code
**In the associated AWS account**:
+ Three AWS CloudFormation stacks that create the resources needed for the application.
For expanded details about the resources that will be created in AWS and CodeCatalyst as part of this tutorial, see [Reference](#getting-started-template-project-reference).
**Note**
The resources and samples included in a project depend on which blueprint you select. Amazon CodeCatalyst offers several project blueprints that define resources related to their defined language or framework. To learn more about blueprints, see [Creating a comprehensive project with CodeCatalyst blueprintsCreating a comprehensive project with blueprints](project-blueprints.md).
**Topics**
+ [Prerequisites](#getting-started-template-project-prerequisites)
+ [Step 1: Create the Modern three-tier web application project](#getting-started-template-project-proj-create)
+ [Step 2: Invite someone to your project](#getting-started-template-project-ipa-user)
+ [Step 3: Create issues to collaborate on and track work](#getting-started-template-project-issue)
+ [Step 4: View your source repository](#getting-started-template-project-source)
+ [Step 5: Create a Dev Environment with a test branch and make a quick code change](#getting-started-template-project-create-devenvironment)
+ [Step 6: View the workflow that builds the modern application](#getting-started-template-project-view-workflow)
+ [Step 7: Ask others to review your changes](#getting-started-template-project-pull-request)
+ [Step 8: Close the issue](#getting-started-template-project-close-issue)
+ [Clean up resources](#getting-started-template-project-clean-up)
+ [Reference](#getting-started-template-project-reference)
## Prerequisites
To create a modern application project in this tutorial, you must have completed the tasks in [Set up and sign in to CodeCatalystSet up and sign in to CodeCatalyst](setting-up-topnode.md) as follows:
+ Have an AWS Builder ID for signing in to CodeCatalyst.
+ Belong to a space and have the **Space administrator** or **Power user** role assigned to you in that space. For more information, see [Creating a space](spaces-create.md), [Granting users space permissions](spaces-members.md), and [Space administrator role](ipa-role-types.md#ipa-role-space-admin).
+ Have an AWS account associated with your space and have the IAM role you created during sign-up. For example, during sign-up, you have the option to choose to create a service role with a role policy called the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role policy. The role will have a name `CodeCatalystWorkflowDevelopmentRole-spaceName` with a unique identifier appended. For more information about the role and role policy, see [Understanding the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** service role](ipa-iam-roles.md#ipa-iam-roles-service-role). For the steps to create the role, see [Creating the **CodeCatalystWorkflowDevelopmentRole-*spaceName*** role for your account and space](ipa-iam-roles.md#ipa-iam-roles-service-create).
## Step 1: Create the Modern three-tier web application project
After you've created it, your project is where you will develop and test code, coordinate development tasks, and view project metrics. Your project also contains your development tools and resources.
In this tutorial, you will use the **Modern three-tier web application** blueprint to create an interactive application. The workflow that is created and run automatically as part of your project will build and deploy the application. The workflow only runs successfully after all roles and account information is configured for your space. After the workflow has run successfully, you can visit the endpoint URL to see the application.
**To create a project with a blueprint**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to create a project.
1. Choose **Create project**.
1. Choose **Start with a blueprint**.
1. In the search bar, enter **modern**.
1. Select the **Modern three-tier web application** blueprint, and then choose **Next**.
1. In **Name your project**, enter a project name. For example:
**MyExampleProject**.
**Note**
The name must be unique in your space.
1. In ** Account**, choose the AWS account you added during sign-up. The blueprint will install resources into this account.
1. In **Deployment Role**, choose the role that you added during sign-up. For example, choose `CodeCatalystWorkflowDevelopmentRole-spaceName`.
If there are no roles listed, add one. To add a role, choose **Add IAM role** and add the role to your AWS account. For more information, see [Allowing access to AWS resources with connected AWS accounts](ipa-connect-account.md).
1. In **Compute platform**, choose **Lambda**.
1. In **Frontend Hosting Option**, choose **Amplify Hosting**. For information about AWS Amplify, see [What is AWS Amplify Hosting?](https://docs.aws.amazon.com/amplify/latest/userguide/welcome.html) in the *AWS Amplify User Guide*.
1. In **Deployment Region**, enter the Region code of the AWS Region where you want the blueprint to deploy the Mysfits application and supporting resources. For a list of Region codes, see [Regional endpoints](https://docs.aws.amazon.com/general/latest/gr/rande.html#regional-endpoints) in the *AWS General Reference*.
1. In **Application name**, leave the default of `mysfitsstring`.
1. (Optional) Under **Generate project preview**, choose **View code** to preview the source files that the blueprint will install. Choose **View workflow** to preview the CI/CD workflow definition files that the blueprint will install. The preview dynamically updates based on your selections.
1. Choose **Create project**.
The project workflow starts as soon as you create the project. It will take a little time to finish building and deploying the code. In the meantime, go ahead and invite someone else to your project.
## Step 2: Invite someone to your project
Now that you've set up your project, invite others to work with you.
**To invite someone to your project**
1. Navigate to the project to which you want to invite users.
1. In the navigation pane, choose **Project settings**.
1. On the **Members** tab, choose **Invite**.
1. Type the email addresses of the people you want to invite as users for your project. You can type multiple email addresses separated by a space or a comma. You can also choose from members of your space who are not members of the project.
1. Choose the role for the user.
When you have finished adding users, choose **Invite**.
## Step 3: Create issues to collaborate on and track work
CodeCatalyst helps you track features, tasks, bugs, and any other work involved in your project with issues. You can create issues to track needed work and ideas. By default, when you create an issue it is added to your backlog. You can move issues to a board where you track work in progress. You can also assign an issue to a specific project member.
**To create an issue for a project**
1. In the navigation pane, choose **Issues**.
1. Choose **Create issue**.
1. In **Issue title**, provide a name for the issue. Optionally, provide a description of the issue. In this example, use **make a change in the `src/mysfit_data.json` file.**
1. Choose the priority, estimate, status, and labels. Under **assignee**, choose **\$1Add me** to assign the issue to yourself.
1. Choose **Create issue**. The issue is now visible on the board. Choose the card to move the issue to the **In progress** column.
For more information, see [Track and organize work with issues in CodeCatalystTrack and organize work with issues](issues.md).
## Step 4: View your source repository
Your blueprint installs a source repository that contains files to define and support your application or service. A few noteworthy directories and files in the source repository are:
+ **.cloud9** directory – Contains supporting files for the AWS Cloud9 Dev Environment.
+ **.codecatalyst** directory – Contains the `YAML` workflow definition file for each workflow included in the blueprint.
+ **.idea** directory – Contains supporting files for the JetBrains Dev Environments.
+ **.vscode** directory – Contains supporting files for the Visual Studio Code Dev Environment.
+ **cdkStacks** directory – Contains the AWS CDK stack files that define the infrastructure in the AWS Cloud.
+ **src** directory – Contains the application source code.
+ **tests** directory – Contains files for the integ and unit tests that are run as part of the automated CI/CD workflow that runs when you build and test your application.
+ **web** directory – Contains the frontend source code. Other files include project files such as the `package.json` file that contains important metadata about your project, the `index.html` page for the website, the `.eslintrc.cjs` file for linting code, and the `tsconfig.json` file for specifying root files and compiler options.
+ `Dockerfile` file – Describes the application's container.
+ `README.md` file – Contains configuration information for the project.
**To navigate to the source repositories for a project**
1. Navigate to your project, and do one of the following:
+ On the summary page for your project, choose the repository you want from the list, and then choose **View repository**.
+ In the navigation pane, choose **Code**, and then choose **Source repositories**. In **Source repositories**, choose the name of the repository from the list. You can filter the list of repositories by typing part of the repository name in the filter bar.
1. On the home page for the repository, view the contents of the repository and information about the associated resources such as the number of pull requests and workflows. By default, the contents for the default branch are shown. You can change the view by choosing a different branch from the drop-down list.
## Step 5: Create a Dev Environment with a test branch and make a quick code change
You can quickly work on the code in your source repository by creating a Dev Environment. For this tutorial, we assume you will:
+ Create a AWS Cloud9 Dev Environment.
+ Choose the option to work in a new branch off the **main** branch when creating the Dev Environment.
+ Use the name `test` for this new branch.
In a later step, you will use the Dev Environment to make a code change and create a pull request.
**To create a Dev Environment with a new branch**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to create a Dev Environment.
1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, choose **Source repositories**, and choose the repository for which you want to create a Dev Environment.
1. On the repository home page, choose **Create Dev Environment**.
1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](devenvironment-create.md#devenvironment-supported-ide) for more information.
1. Choose the repository to clone, choose **Work in new branch**, enter a branch name into the **Branch name** field, and choose a branch off of which to create the new branch from the **Create branch from** drop-down menu.
1. Optionally, add an alias for the Dev Environment.
1. Optionally, choose the **Dev Environment configuration** edit button to edit the Dev Environment's compute, storage, or timeout configuration.
1. Choose **Create**. While your Dev Environment is being created, the Dev Environment status column will display **Starting**, and the status column will display **Running** once the Dev Environment has been created. A new tab will open with your Dev Environment in the IDE of your choice. You can edit code and commit and push your changes.
In this section, you will work with your generated sample application in CodeCatalyst by making changes to the code with pull requests that are automatically built and deployed to resources in the connected AWS account when the pull request is merged.
**To make a change in your `src/mysfit_data.json` file**
1. Navigate to your project Dev Environment. In AWS Cloud9, expand the side navigation menu to browse the files. Expand `mysfits`, `src`, and open `src/mysfit_data.json`.
1. In the file, change the value for the `"Age":` field from 6 to 12. Your line should look like the following:
```
{
"Age": 12,
"Description": "Twilight's personality sparkles like the night sky and is looking for a forever home with a Greek hero or God. While on the smaller side at 14 hands, he is quite adept at accepting riders and can fly to 15,000 feet. Twilight needs a large area to run around in and will need to be registered with the FAA if you plan to fly him above 500 feet. His favorite activities include playing with chimeras, going on epic adventures into battle, and playing with a large inflatable ball around the paddock. If you bring him home, he'll quickly become your favorite little Pegasus.",
"GoodEvil": "Good",
"LawChaos": "Lawful",
"Name": "Twilight Glitter",
"ProfileImageUri": "https://www.mythicalmysfits.com/images/pegasus_hover.png",
"Species": "Pegasus",
"ThumbImageUri": "https://www.mythicalmysfits.com/images/pegasus_thumb.png"
},
```
1. Save the file.
1. Change to the mysfits repository with the **cd /projects/mysfits** command.
1. Add, commit and push your changes with the **git add**, **git commit**, and **git push** commands.
```
git add .
git commit -m "make an example change"
git push
```
## Step 6: View the workflow that builds the modern application
After creating the modern application project, CodeCatalyst generates several resources on your behalf, including a workflow. A *workflow* is an automated procedure defined in a .yaml file that describes how to build, test, and deploy your code.
In this tutorial, CodeCatalyst created a workflow and started it automatically when you created your project. (The workflow might still be running depending on how long ago you created your project.) Use the following procedures to check on the workflow's progress, review the generated logs and test reports, and finally, navigate to the URL of the deployed application.
**To check on the workflow progress**
1. In the CodeCatalyst console, in the navigation pane, choose **CI/CD**, and then choose **Workflows**.
A list of workflows appears. These are the workflows that the CodeCatalyst blueprint generated and started when you created your project.
1. Observe the list of workflows. You should see four:
+ The two workflows at the top correspond to the `test` branch that you created earlier in [Step 5: Create a Dev Environment with a test branch and make a quick code change](#getting-started-template-project-create-devenvironment). These workflows are clones the workflows on the `main` branch. The **ApplicationDeploymentPipeline** is not active because it is configured for use with the `main` branch. The **OnPullRequest** workflow did not run because no pull request has been made.
+ The two workflows at the bottom correspond to the `main` branch that was created when you ran the blueprint earlier. The **ApplicationDeploymentPipeline** workflow is active and has an in-progress (or finished) run.
**Note**
If the **ApplicationDeploymentPipeline** run fails with a **Build@cdk\$1bootstrap** or **DeployBackend** error, it might be because you ran the Modern three-tier web application previously, and it left old resources behind that conflict with the current blueprint. You'll need to delete these old resources and then re-run the workflow. For more information, see [Clean up resources](#getting-started-template-project-clean-up).
1. Choose the **ApplicationDeploymentPipeline** workflow associated with the `main` branch, at the bottom. This workflow was run using the source code on the `main` branch.
A workflow diagram appears. The diagram shows several blocks, each representing a task or *action*. Most actions are arranged vertically, with the actions at the top running before the ones below. Actions that are arranged side by side run in parallel. Actions that are grouped together must all run successfully before the action below them can start.
The main blocks are:
+ **WorkflowSource** – This block represents your source repository. It shows, among other information, the source repository name (**mysfits**) and the commit that automatically started the workflow run. CodeCatalyst generated this commit when you created your project.
+ **Build** – This block represents a grouping of two actions which must both complete successfully for the next action to start.
+ **DeployBackend** – This block represents an action that deploys the application's backend components into the AWS cloud.
+ **Tests** – This block represents a grouping of two test actions which must both complete successfully for the next action to start.
+ **DeployFrontend** – This block represents an action that deploys the application's frontend components into the AWS cloud.
1. Choose the **Definition** tab (near the top). The [workflow definition file](workflow-reference.md) appears on the right. The file has the following noteworthy sections:
+ A `Triggers` section, at the top. This section indicates that the workflow must start whenever code is pushed to the source repository's `main` branch. Pushes to other branches (such as `test`) will not start this workflow. The workflow runs using the files on the `main` branch.
+ An `Actions` section, under `Triggers`. This section defines the actions that you see in the workflow diagram.
1. Choose the **Latest state** tab (near the top), and choose any action in the workflow diagram.
1. On the right, choose the **Configuration** tab to see the configuration settings used by the action during the latest run. Each configuration setting has a matching property in the workflow definition file.
1. Leave the console open and go to the next procedure.
**To review the build logs and test reports**
1. Choose the **Latest state** tab.
1. In the workflow diagram, choose the **DeployFrontend** action.
1. Wait for the action to finish. Watch for the "in-progress" icon (![\[Workflow in progress.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/run-in-progress.png)) to change to a "success" icon (![\[Workflow success.\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/flows/run-success.png)).
1. Choose the **build\$1backend** action.
1. Choose the **Logs** tab, and expand a couple of sections to view the log messages for these steps. You can see messages related to the backend setup.
1. Choose the **Reports** tab, and then choose the `backend-coverage.xml` report. CodeCatalyst displays the associated report. The report shows the code coverage tests that were run, and indicates the proportion of lines of code that were successfully validated by testing, such as 80%.
For more information about test reports, see [Testing with workflowsTesting with workflows](test-workflow-actions.md).
**Tip**
You can also view your test reports by choosing **Reports** in the navigation pane.
1. Leave the CodeCatalyst console open, and go to the next procedure.
**To confirm that the modern application was deployed successfully**
1. Return to the **ApplicationDeploymentPipeline** workflow, and choose the **Run-*string*** link of the latest run.
1. In the workflow diagram, find the **DeployFrontend** action and choose the **View app** link. The Mysfit website appears.
**Note**
If you don't see the **View app** link inside the **DeployFrontend** action, make sure you chose the run ID link.
1. Search for the pegasus Mysfit named **Twilight Glitter**. Note the value for the age. It is `6`. You will make a code change to update the age.
## Step 7: Ask others to review your changes
Now that you have changes in a branch named `test`, you can ask others to review them by creating a pull request. Perform the following steps to create a pull request to merge the changes from the `test` branch into the `main` branch.
**To create a pull request**
1. Navigate to your project.
1. Do one of the following:
+ In the navigation pane, choose **Code**, choose **Pull requests**, and then choose **Create pull request**.
+ On the repository home page, choose **More**, and then choose **Create pull request**.
+ On the project page, choose **Create pull request**.
1. In **Source repository**, make sure that the specified source repository is the one that contains the committed code. This option only appears if you did not create the pull request from the repository's main page.
1. In **Destination branch**, choose the branch to merge the code into after it is reviewed.
1. In **Source branch**, choose the branch that contains the committed code.
1. In **Pull request title**, enter a title that helps other users understand what needs to be reviewed and why.
1. (Optional) In **Pull request description**, provide information such as a link to issues or a description of your changes.
**Tip**
You can choose **Write description for me** to have CodeCatalyst automatically generate a description of the changes contained in the pull request. You can make changes to the automatically generated description after you add it to the pull request.
This functionality requires that generative AI features are enabled for the space and is not available for pull requests in linked repositories. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html).
1. (Optional) In **Issues**, choose **Link issues**, and then either choose an issue from the list or enter its ID. To unlink an issue, choose the unlink icon.
1. (Optional) In **Required reviewers**, choose **Add required reviewers**. Choose from the list of project members to add them. Required reviewers must approve the changes before the pull request can be merged into the destination branch.
**Note**
You cannot add a reviewer as both a required reviewer and an optional reviewer. You cannot add yourself as a reviewer.
1. (Optional) In **Optional reviewers**, choose **Add optional reviewers**. Choose from the list of project members to add them. Optional reviewers do not have to approve the changes as a requirement before the pull request can be merged into the destination branch.
1. Review the differences between the branches. The difference displayed in a pull request is the changes between the revision in the source branch and the merge base, which is the head commit of the destination branch at the time the pull request was created. If no changes display, the branches might be identical, or you might have chosen the same branch for both the source and the destination.
1. When you are satisfied that the pull request contains the code and changes you want reviewed, choose **Create**.
**Note**
After you create the pull request, you can add comments. Comments can be added to the pull request or to individual lines in files as well as to the overall pull request. You can add links to resources, such as files, by using the @ sign followed by the name of the file.
When you create the pull request, the **OnPullRequest** workflow starts using the source files in the `test` branch. While your reviewers are approving your code change, you can observe the results by choosing the workflow and viewing the test output.
After you've had the change reviewed, you can merge the code. Merging the code to the default branch will automatically start the workflow that will build and deploy your changes.
**To merge a pull request from the CodeCatalyst console**
1. Navigate to your modern application project.
1. On the project page, under **Open pull requests**, choose the pull request you want to merge. If you do not see the pull request, choose **View all** and then choose it from the list. Choose **Merge**.
1. Choose from the available merge strategies for the pull request. Optionally select or deselect the option to delete the source branch after merging the pull request, and then choose **Merge**.
**Note**
If the **Merge** button is not active, or you see the **Not mergeable** label, either one or more required reviewers have not yet approved the pull request, or the pull request cannot be merged in the CodeCatalyst console. A reviewer who has not approved a pull request is indicated by a clock icon in **Overview** in the **Pull request details** area. If all required reviewers have approved the pull request but the **Merge** button is still not active, you might have a merge conflict. You can resolve merge conflicts for the destination branch in the CodeCatalyst console and then merge the pull request, or you can resolve conflicts and merge locally, and then push the commit that contains the merge to CodeCatalyst. For more information, see [Merging a pull request (Git)](pull-requests-merge.md#pull-requests-merge-git) and your Git documentation.
Once you've merged the changes from the `test` branch into the **main** branch, the change automatically starts the **ApplicationDeploymentPipeline** workflow that builds and deploys your change.
**To see the merged commit run through the ApplicationDeploymentPipeline workflow**
1. In the navigation pane, choose **CI/CD**, and then choose **Workflows**.
1. In **Workflows**, in **ApplicationDeploymentPipeline**, expand **Recent runs**. You can see the workflow run started by the merge commit. Optionally choose it to watch the run progress.
1. When the run completes, reload the URL you visited earlier. View the pegasus to verify that the age changed.
![\[The code change merged, built, and deployed, visible in the application\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/images/modified-mysfits.png)
## Step 8: Close the issue
When an issue is resolved, it can be closed on the CodeCatalyst console.
**To close an issue for a project**
1. Navigate to your project.
1. In the navigation pane, choose **Issues**.
1. Drag-and-drop the issue to the **Done** column.
For more information, see [Track and organize work with issues in CodeCatalystTrack and organize work with issues](issues.md).
## Clean up resources
Clean up in CodeCatalyst and AWS to remove traces of this tutorial from your environment.
You can choose to keep using the project you used for this tutorial, or you can delete the project and its associated resources.
**Note**
Deleting this project will delete all repositories, issues, and artifacts in the project for all members.
**To delete a project**
1. Navigate to your project, and then choose **Project settings**.
1. Choose the **General** tab.
1. Under the project name, choose **Delete project**.
**To delete resources in CloudFormation and Amazon S3**
1. Sign in to the AWS Management Console with the same account that you added to your CodeCatalyst space.
1. Go to the **CloudFormation** service.
1. Delete the **mysfits*string*** stack.
1. Delete the **development-mysfits*string*** stack.
1. Choose (but do not delete) the **CDKToolkit** stack. Choose the **Resources** tab. Choose the **StagingBucket** link, and delete the bucket and bucket contents in Amazon S3.
**Note**
If you don't delete this bucket manually, you may see an error when re-running the Modern three-tier web application blueprint.
1. (Optional) Delete the **CDKToolkit** stack.
## Reference
The Modern three-tier web application blueprint deploys resources into your CodeCatalyst space and your AWS account in the AWS cloud. These resources are:
+ **In your CodeCatalyst space**:
+ A CodeCatalyst project that includes the following resources:
+ A [source repository](source.md) – This repository contains sample code for a 'Mysfits' web application.
+ A [workflow](workflow.md) – This workflow builds and deploys the Mysfits application code whenever a change is made to the default branch
+ An [issues board](issues.md) and backlog – This board and backlog can be used to plan and track work.
+ A [test reports suite](test-workflow-actions.md) – This suite includes automated reports included in the sample code.
+ **In the associated AWS account**:
+ A **CDKToolkit** stack – This stack deploys the following resources:
+ An Amazon S3 staging bucket, bucket policy, and the AWS KMS key used to encrypt the bucket.
+ An IAM deployment role for the deploy action.
+ AWS IAM roles and policies in support of the resources in the stack.
**Note**
The **CDKToolkit** is not torn down and recreated for each deployment. This is a stack that is initiated in each account to support the AWS CDK.
+ A **development-mysfits*string*BackEnd** stack – This stack deploys the following backend resources:
+ An Amazon API Gateway endpoint.
+ AWS IAM roles and policies in support of the resources in the stack.
+ An AWS Lambda function and layer provides the serverless compute platform for the modern application.
+ An IAM policy and role for the bucket deployment and Lambda function.
+ A **mysfits*string*** stack – This stack deploys the AWS Amplify frontend application.
### See also
For more information about the AWS services where resources are created as part of this tutorial, see the following:
+ **Amazon S3** – A service for storing your frontend assets on an object storage service offering industry-leading scalability, data high availability, security, and performance. For more information, see [Amazon S3 User Guide](https://docs.aws.amazon.com/AmazonS3/latest/userguide/).
+ **Amazon API Gateway** – A service for creating, publishing, maintaining, monitoring, and securing REST, HTTP, and WebSocket APIs at any scale For more information, see [API Gateway Developer Guide](https://docs.aws.amazon.com/apigateway/latest/developerguide/).
+ **Amplify** – A service for hosting your frontend application. For more information, see [AWS Amplify Hosting User Guide](https://docs.aws.amazon.com/amplify/latest/userguide/welcome.html).
+ **AWS Cloud Development Kit (AWS CDK)** – A framework for defining cloud infrastructure in code and provisioning it through AWS CloudFormation. The AWS CDK includes the AWS CDK Toolkit, which is a command line tool for interacting with AWS CDK apps and stacks. For more information, see [AWS Cloud Development Kit (AWS CDK) Developer Guide](https://docs.aws.amazon.com/cdk/latest/guide/).
+ **Amazon DynamoDB** – A fully managed NoSQL database service for storing data. For more information, see [Amazon DynamoDB Developer Guide](https://docs.aws.amazon.com/amplify/latest/userguide/welcome.html).
+ **AWS Lambda** – A service for invoking your code on a high availability compute infrastructure without provisioning or managing servers. For more information, see [AWS Lambda Developer Guide](https://docs.aws.amazon.com/lambda/latest/dg/).
+ **AWS IAM** – A service for securely controlling access to AWS and its resources. For more information, see [IAM User Guide](https://docs.aws.amazon.com/IAM/latest/UserGuide/).
# Tutorial: Starting with an empty project and manually adding resources
You can create an empty project without any predefined resources inside it by choosing the **Empty project** blueprint when you create the project. After you create an empty project, you can create and add resources to it according to your project needs. Because projects created without a blueprint are empty on creation, this option requires more knowledge of creating and configuring CodeCatalyst resources to get started.
**Topics**
+ [Prerequisites](#getting-started-bt-prerequisites)
+ [Create an empty project](#getting-started-bt-proj-create)
+ [Create a source repository](#getting-started-bt-source-create)
+ [Create a workflow to build, test, and deploy a code change](#getting-started-bt-workflow-create)
+ [Invite someone to your project](#getting-started-bt-ipa-user)
+ [Create issues to collaborate on and track work](#getting-started-bt-issue)
## Prerequisites
To create an empty project, you must have the **Space administrator** or **Power user** role assigned to you. If this is your first time signing in to CodeCatalyst, see [Set up and sign in to CodeCatalystSet up and sign in to CodeCatalyst](setting-up-topnode.md).
## Create an empty project
Creating a project is the first step in being able to work together. If you want to create your own resources, such as source repositories and workflows, you can start with an empty project.
**To create an empty project**
1. Navigate to the space where you want to create a project.
1. On the space dashboard, choose **Create project**.
1. Choose **Start from scratch**.
1. Under **Give a name to your project**, enter the name that you want to assign to your project. The name must be unique within your space.
1. Choose **Create project**.
Now that you have an empty project, the next step is to create a source repository.
## Create a source repository
Create a source repository to store and collaborate on your project's code. Project members can clone this repository to their local computers to work on code. Alternatively, you can choose to link a repository hosted in a supported service, but that is not covered in this tutorial. For more information, see [Linking a source repository](source-repositories-link.md).
**To create a source repository**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to your project.
1. In the navigation pane, choose **Code**, and then choose **Source repositories**.
1. Choose **Add repository**, and then choose **Create repository**.
1. In **Repository name**, provide a name for the repository. In this guide, we use *codecatalyst-source-repository*, but you can choose a different name. Repository names must be unique within a project. For more information about requirements for repository names, see [Quotas for source repositories in CodeCatalyst](source-quotas.md).
1. (Optional) In **Description**, add a description for the repository that will help other users in the project understand what the repository is used for.
1. Choose **Create repository (default)**. This option creates a repository that includes a default branch and a README.md file. Unlike an empty repository, you can use this repository as soon as it's created.
1. In **Default branch**, leave the name as *main* unless you have a reason to choose a different name. The examples in this guide all use the name *main* for the default branch.
1. (Optional) Add a `.gitignore` file for the type of code you plan to push.
1. Choose **Create**.
**Note**
CodeCatalyst adds a `README.md` file to your repository when you create it. CodeCatalyst also creates an initial commit for the repository in a default branch named **main**. You can edit or delete the README.md file, but you can't delete the default branch.
You can quickly add code in your repository by creating a Dev Environment. For this tutorial, we recommend that you create a Dev Environment using AWS Cloud9, and choose the option to create a branch from the **main** branch when creating the Dev Environment. We use the name **test** for this branch, but you can enter a different branch name if you prefer.
**To create a Dev Environment with a new branch**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. Navigate to the project where you want to create a Dev Environment.
1. Choose the name of the repository from the list of source repositories for the project. Alternatively, in the navigation pane, choose **Code**, choose **Source repositories**, and choose the repository for which you want to create a Dev Environment.
1. On the repository home page, choose **Create Dev Environment**.
1. Choose a supported IDE from the drop-down menu. See [Supported integrated development environments for Dev Environments](devenvironment-create.md#devenvironment-supported-ide) for more information.
1. Choose the repository to clone, choose **Work in new branch**, enter a branch name into the **Branch name** field, and choose a branch off of which to create the new branch from the **Create branch from** drop-down menu.
1. Optionally, add an alias for the Dev Environment.
1. Optionally, choose the **Dev Environment configuration** edit button to edit the Dev Environment's compute, storage, or timeout configuration.
1. Choose **Create**. While your Dev Environment is being created, the Dev Environment status column will display **Starting**, and the status column will display **Running** once the Dev Environment has been created. A new tab will open with your Dev Environment in the IDE of your choice. You can edit code and commit and push your changes.
## Create a workflow to build, test, and deploy a code change
In CodeCatalyst, you organize the building, testing, and deployment of your applications or services in workflows. Workflows consist of actions and can be configured to run automatically after specified source repository events occur, such as code pushes or opening or updating a pull request. For more information about workflows, see [Build, test, and deploy with workflowsBuild, test, and deploy with workflows](workflow.md).
Follow the instructions in [Getting started with workflows](workflows-getting-started.md) to create your first workflow.
## Invite someone to your project
Now that you've set up your custom project, invite others to work with you.
**To invite someone to your project**
1. Navigate to the project to which you want to invite users.
1. In the navigation pane, choose **Project settings**.
1. On the **Members** tab, choose **Invite**.
1. Type the email addresses of the people you want to invite as users for your project. You can type multiple email addresses separated by a space or a comma. You can also choose from members of your space who are not members of the project.
1. Choose the role for the user.
When you have finished adding users, choose **Invite**.
## Create issues to collaborate on and track work
CodeCatalyst helps you track features, tasks, bugs, and any other work involved in your project with issues. You can create issues to track needed work and ideas. By default, when you create an issue it is added to your backlog. You can move issues to a board where you track work in progress. You can also assign an issue to a specific project member.
**To create an issue for a project**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
Make sure that you are navigating in the project where you want to create issues. To view all projects, in the navigation pane, choose **Amazon CodeCatalyst**, and if needed, choose **View all projects**. Choose the project where you want to create or work with issues.
1. In the navigation pane, choose **Track**, and then choose **Backlog**.
1. Choose **Create issue**.
1. In **Issue title**, provide a name for the issue. Optionally provide a description of the issue. Choose the status, priority, and estimate for the issue if desired. You can also assign the issue to a project member from the list of project members.
**Tip**
You can choose to assign an issue to **Amazon Q** to have Amazon Q try to solve the issue. If the attempt is successful, a pull request will be created and the status of the issue will change to **In review** so that you can review and test the code. For more information, see [Tutorial: Using CodeCatalyst generative AI features to speed up your development work](getting-started-project-assistance.md).
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. Choose **Save**.
After you have created issues, you can assign them to project members, estimate them, and track them on a Kanban board. For more information, see [Track and organize work with issues in CodeCatalystTrack and organize work with issues](issues.md).
# Tutorial: Using CodeCatalyst generative AI features to speed up your development work
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 integrates with the Amazon Q Developer Agent for software development to provide 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.
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*.
**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).
In this tutorial, you'll learn how to use the generative AI features in CodeCatalyst to help you create projects with blueprints, as well as add blueprints to existing projects. Additionally, you'll learn how to 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 code changes or improvements and assign them to Amazon Q. As part of working with issues assigned to Amazon Q, you'll learn how to allow Amazon Q to suggest tasks and how to assign and work on any tasks it creates as part of working on an issue.
**Topics**
+ [Prerequisites](#getting-started-project-assistance-prerequisites)
+ [Using Amazon Q to choose a blueprint when creating a project or adding functionality](#getting-started-project-assistance-create-apply-bp)
+ [Create a summary of the code changes between branches when creating a pull request](#getting-started-project-assistance-pull-request-summary)
+ [Create a summary of comments left on code changes in a pull request](#getting-started-project-assistance-comment-summary)
+ [Create an issue and assign it to Amazon Q](#getting-started-project-assistance-issue-to-code)
+ [Create an issue and have tasks recommended for it by Amazon Q](#getting-started-project-assistance-issue-to-tasks)
+ [Clean up resources](#getting-started-project-assistance-clean-up)
## Prerequisites
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 are in a space that has generative AI features enabled. For more information, see [Managing generative AI features](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html).
+ You have the Contributor or Project administrator role in a project in that space.
+ Unless you are creating a project with generative AI, your existing 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](spaces-create.md), [Track and organize work with issues in CodeCatalystTrack and organize work with issues](issues.md), [Add functionality to projects with extensions in CodeCatalystAdd functionality to projects with extensions](extensions.md), and [Granting access with user roles](ipa-roles.md).
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.
## Using Amazon Q to choose a blueprint when creating a project or adding functionality
As a project developer, you can collaborate with Amazon Q, a generative AI assistant, when creating new projects or adding components to existing projects. You can provide Amazon Q with requirements for your project by interacting with it in a chat-like interface. Based on your requirements, Amazon Q suggests a blueprint and also outlines requirements that can’t be met. If your space has custom blueprints, Amazon Q learns and includes those blueprints in the recommendations as well. You can then proceed with Amazon Q’s suggestion if you’re satisfied, and it will create the necessary resources such as a source repository with code for your requirement. Amazon Q also creates issues for requirements that can’t be satisfied with a blueprint. To learn more about available CodeCatalyst blueprints, see [Creating a comprehensive project with CodeCatalyst blueprintsCreating a comprehensive project with blueprints](project-blueprints.md). To learn more about using Amazon Q with blueprints, see [Best practices when using Amazon Q to create projects or add functionality with blueprints](projects-create.md#projects-create-amazon-q).
**To create a project with Amazon Q**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the space where you want to create a blueprint.
1. On the space dashboard, choose **Create with Amazon Q**.
1. In the Amazon Q prompt text input field, provide instructions by writing a brief description about the project you want to build. For example, `“I want to create a project in Python that has a presentation layer responsible for how the data is presented, an application layer that contains the core logic and functionality of the application, and a data layer that manages the storage and retrieval of the data.”`
(Optional) Under **Try examples**, you can use a prewritten prompt by choosing a blueprint. For example, if you choose React app, the following prompt is provided : `“I want to create a project in Python that has a presentation layer responsible for how the data is presented, an application layer that contains the core logic and functionality of the application, and a data layer that manages the storage and retrieval of the data. I also want to add authentication and authorization mechanisms for security and allowable actions.”`
1. Choose **Send** to submit your instructions to Amazon Q. The generative AI assistant provides a suggestion and outlines requirements that can’t be met by the blueprint. For example, Amazon Q might suggest the following based on your criteria:
```
I recommend using the Modern three-tier web application blueprint based on
your requirements. Blueprints are dynamic and can always be updated and edited later.
Modern three-tier web application
By Amazon Web Services
This blueprint creates a Mythical Mysfits 3-tier web application with a modular presentation, application, and data layers.
The application leverages containers, infrastructure as code (IaC), continuous integration and continuous delivery (CI/CD),
and serverless code functions.
Version: 0.1.163
View details
The following requirements could not be met so I will create issues for you.
• Add authentication and authorization mechanisms for security and allowable actions.
```
1. (Optional) To view the in-depth details of the suggested blueprint, choose **View details**.
1. Do one of the following:
1. Choose **Yes, use this blueprint** if you’re satisfied with the suggestion.
1. Choose **Edit prompt** if you want to modify the prompt.
1. Choose **Start over** if you want to clear the prompt completely.
1. Do one of the following:
1. Choose **Configure** if you want to configure the blueprint that is suggested. You can also configure the blueprint at a later time.
1. Choose **Skip** if you don’t want to modify the blueprint configurations at the moment.
1. If you chose to configure the blueprint, choose **Continue** after modifying the project resources.
1. When prompted, enter the name that you want to assign to your project and its associated resource names. The name must be unique within your space.
1. Choose **Create project** to create a project with the blueprint. Amazon Q creates resources using the blueprint. For example, if you create a project with the Single-page application blueprint, a source repository for relevant code and workflows for CI/CD are created.
1. (Optional) By default, Amazon Q also creates issues for the requirements that aren’t satisfied by a blueprint. You can choose which items you don't want to create issues for. After you choose to let Amazon Q create issues, you can then assign an issue to Amazon Q as well. It’ll analyze the issue in the context of the given source repositories, providing a summary of the relevant source files and code. For more information, see [Finding and viewing issues](issues-view.md), [Create an issue and assign it to Amazon Q](#getting-started-project-assistance-issue-to-code), and [Best practices when creating and working with issues assigned to Amazon Q](issues-create-issue.md#issues-create-issue-assign-genai-best-practices).
After creating a project with Amazon Q, you can also use Amazon Q to add new components as it suggests CodeCatalyst blueprints based on your requirements.
**To add a blueprint with Amazon Q**
1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/).
1. In the CodeCatalyst console, navigate to the project where you want to add a blueprint.
1. Choose **Add with Amazon Q**.
1. In the Amazon Q prompt text input field, provide instructions by writing a brief description about the project you want to build. For example, `“I want to create a project in Python that has a presentation layer responsible for how the data is presented, an application layer that contains the core logic and functionality of the application, and a data layer that manages the storage and retrieval of the data.”`
(Optional) Under **Try examples**, you can use a prewritten prompt by choosing a blueprint. For example, if you choose React app, the following prompt is provided : `“I want to create a project in Python that has a presentation layer responsible for how the data is presented, an application layer that contains the core logic and functionality of the application, and a data layer that manages the storage and retrieval of the data. I also want to add authentication and authorization mechanisms for security and allowable actions.”`
1. Choose **Send** to submit your instructions to Amazon Q. The generative AI assistant provides a suggestion and outlines requirements that can’t be met by the blueprint. For example, Amazon Q might suggest the following based on your criteria:
```
I recommend using the Single-page application blueprint based on your requirements. Blueprints are dynamic and can always be updated and edited later.
Single-page application
By Amazon Web Services
This blueprint creates a SPA (single-page application) using React, Vue, or Angular frameworks and deploys to AWS Amplify Hosting.
Version: 0.2.15
View details
The following requirements could not be met so I will create issues for you.
• The application should have reusable UI components
• The application should support for client-side routing
• The application may require server-side rendering for improved performance and SEO
```
1. (Optional) To view the in-depth details of the suggested blueprint, choose **View details**.
1. Do one of the following:
1. Choose **Yes, use this blueprint** if you’re satisfied with the suggestion.
1. Choose **Edit prompt** if you want to modify the prompt.
1. Choose **Start over** if you want to clear the prompt completely.
1. Do one of the following:
1. Choose **Configure** if you want to configure the blueprint that is suggested. You can also configure the blueprint at a later time.
1. Choose **Skip** if you don’t want to modify the blueprint configurations at the moment.
1. If you chose to configure the blueprint, choose **Continue** after modifying the project resources.
1. Choose **Add to project** to add resources to a project with the blueprint. Amazon Q creates resources using the blueprint. For example, if you add to a project with the Single-page application blueprint, a source repository for relevant code and workflows for CI/CD are created.
1. (Optional) By default, Amazon Q also creates issues for the requirements that aren’t satisfied by a blueprint. You can choose which items you don't want to create issues for. After you choose to let Amazon Q create issues, you can then assign an issue to Amazon Q as well. It’ll analyze the issue in the context of the given source repositories, providing a summary of the relevant source files and code. For more information, see [Create an issue and assign it to Amazon Q](#getting-started-project-assistance-issue-to-code) and [Best practices when creating and working with issues assigned to Amazon Q](issues-create-issue.md#issues-create-issue-assign-genai-best-practices).
## 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.
**Note**
This feature does not work with Git submodules. It will not summarize any changes in a Git submodule that is part of the pull request.
This feature is not available for pull requests in linked repositories.
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.
**Tip**
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.
1. 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**.
1. Choose the repository where you want to create a branch.
1. On the overview page of the repository, choose **More**, and then choose **Create branch**.
1. Enter a name for the branch.
1. 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**.
**Tip**
You can also choose to create or use a Dev Environment to make this code change. For more information, see [Creating a Dev Environment](devenvironment-create.md).
**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.
1. 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`.
1. Choose **Edit**.
1. On line 7, change the number of times all tests will be retried from:
```
def test_list_all(retry=3):
```
to:
```
def test_list_all(retry=5):
```
1. 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**.
1. In **Destination branch**, choose the branch to merge the code into after it is reviewed.
**Tip**
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.
1. In **Source branch**, choose the branch that contains the changes you just committed to the `test_endpoint.py` file.
1. In **Pull request title**, enter a title that helps other users understand what needs to be reviewed and why.
1. In **Pull request description**, choose **Write description for me** to have Amazon Q create a description of the changes contained in the pull request.
1. A summary of the changes appears. Review the suggested text and then choose **Accept and add to description**.
1. 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.
**Note**
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.
This feature does not work with any comments left on code changes in Git submodules.
This feature is not available for pull requests in linked repositories.
**To create a summary of comments in a pull request**
1. Navigate to the pull request you created in the previous procedure.
**Tip**
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.
1. Add a few comments to the pull request in **Changes** if the pull request does not already have comments.
1. In **Overview**, choose **Create comment summary**. When complete, the **Comment summary** section expands.
1. 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 Amazon Q Developer Agent for software development. You can assign issues to 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.
**Tip**
**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.
+ Whether you want to allow it to suggest creating tasks to break down the work in the issue into smaller increments that can be individually assigned to users, including Amazon Q itself. Allowing Amazon Q to suggest and create tasks can help accelerate development on complex issues by allowing multiple people to work on discrete portions of the issue. It can also help reduce the complexity of understanding the entirety of the work as the work needed to complete each task is ideally simpler than the issue it belongs to.
+ 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.
**Note**
This feature is only available through **Issues** in the US West (Oregon) Region. 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.
This feature does not work with Git submodules. It cannot make changes to any Git submodules included in the repository.
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.
An issue can be automatically moved into the **In review** column if assigned to Amazon Q if a user chooses to allow it to create tasks. However, the issue in **In review** might still have tasks that are in a different state, such as in the **In progress** state.
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**.
**Note**
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.
1. Choose **Create issue**.
1. 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.
```
1. (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 attached to this issue to the source repository as part of the work, and deploy the images to the website."
**Note**
Attached images might or might not be deployed to the website during the interactions 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.
1. In **Assignees**, choose **Assign to Amazon Q**.
1. In **Source repository**, choose the source repository that contains the project code.
1. Slide the **Require Amazon Q to stop after each step and await review of its work** selector to the active state if necessary.
**Note**
Choosing the option to have Amazon Q stop after every step allows you to comment on the issue or any created tasks to 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.
1. Leave the **Allow Amazon Q to modify workflow files** selector in the inactive state.
1. Slide the **Allow Amazon Q to suggest creating tasks** selector to the active state.
1. Choose **Create issue**. Your view changes to the Issues board.
1. Choose **Create issue** to create another issue, this time one with the title **Change the get\$1all\$1mysfits() API to return mysfits sorted by the Age attribute**. Assign this issue to **Amazon Q** and create the issue.
1. 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.
**Tip**
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. If the proposed code contains similarities to open source code that Amazon Q is aware of, it will provide a file that includes links to that code so that you can review it. 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**.
**Important**
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 Amazon Q. If present, review the background and approach it records in the description of the issue. If you chose to allow Amazon Q to suggest tasks, review any proposed tasks and take any needed action. For example, if Amazon Q suggested tasks and you would like to change the order or assign tasks to specific users, choose **Change, add, or reorder tasks** and perform any updates necessary. When you are done viewing the issue, choose **X** to close the issue pane.
**Tip**
To view progress on tasks, choose the task from the list of tasks in the issue. Tasks don't appear as separate items on the board and can only be accessed through an issue. If a task is assigned to Amazon Q, you must open the task to approve any actions it wants to perform. You must also open a task to see any linked pull requests as they will not appear as links in the issue, only in the task. To return to an issue from a task, choose the link to the issue.
1. 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. Review any tasks created for work related to this issue, including their progress, any actions you might need to take, and any comments. In **Pull requests**, choose the link to the pull request next to the **Open** label to review the code.
**Tip**
Pull requests generated for tasks only appear as linked pull requests in the task view. They don't appear as linked pull requests for the issue.
1. In the pull request, review the code changes. For more information, see [Reviewing a pull request](pull-requests-review.md). 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.
**Note**
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.
1. (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.
**Note**
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**.
1. 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](workflows-getting-started.md).
1. When you are satisfied with the latest revision of the pull request, choose **Merge**.
## Create an issue and have tasks recommended for it by Amazon Q
An issue can sometimes contain complex or lengthy amounts of work. CodeCatalyst includes integration with Amazon Q Developer Agent for software development. You can ask **Amazon Q** to analyze an issue based on its title and its description, and recommend a logical break down of the work into separate tasks. It will attempt to create a list of recommended tasks that can then review, modify, and choose whether to create. This can help you and your team to assign individual parts of the work to users in more managable ways that can be achieved more quickly.
**To create and review a list of recommended tasks for an issue**
1. In the navigation pane, choose **Issues** and make sure you are in the **Board** view.
1. Choose **Create issue**.
1. Give the issue a title that explains what you want to do in plain language. For example, for this issue, enter a title of **Change the get\$1all\$1mysfits() API to return mysfits sorted by the Good/Evil attribute**. In **Description**, provide the following details:
```
Update the API to allow sorting of mysfits by whether they are Good, Neutral, or Evil. Add a button on the website that allows users to quickly choose this sort and to exclude alignments that they don't want to see.
```
1. Review the description and make sure it contains all the details that might be needed before you proceed to the next step.
1. In **Assignees**, choose to assign the issue to yourself.
1. Choose **Create issue**. Your view changes to the Issues board.
1. Choose the issue you just created to open it. Choose **Recommend tasks**.
1. Choose the source repository that contains the code for the issuse. Choose **Start recomending tasks**.
The dialog will close and Amazon Q will begin analyzing the issue for complexity. If the issue is complex, it will suggest a break down of the work into separate, sequential tasks. When the list is ready, choose **View recommended tasks**. You can add additional tasks, modify the recommended tasks, and reorder the tasks. If you agree with the recommendations, choosing **Create tasks** will create the tasks. You can then assign those tasks to users to work on them, or even to Amazon Q itself.
## 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](https://docs.aws.amazon.com/codecatalyst/latest/adminguide/managing-generative-ai-features.html) and [Pricing](https://codecatalyst.aws/explore/pricing).
+ Move any issues where work is complete to **Done**.
+ If the project is no longer needed, delete the project.