# Amazon CodeCatalyst for VS Code
<a name="codecatalyst-service"></a>

## What is Amazon CodeCatalyst?
<a name="codecatalyst-intro"></a>

Amazon CodeCatalyst is a cloud-based collaboration space for software development teams. Through the AWS Toolkit for Visual Studio Code, you can view and manage your CodeCatalyst resources directly from VS Code. You can also work directly in the cloud by using the AWS Toolkit to launch, Dev Environments virtual computing environments running VS Code. For more information about the CodeCatalyst service, see the [Amazon CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/welcome.html) User Guide.

The following topics describe how to connect VS Code with CodeCatalyst, and how to work with CodeCatalyst from the Toolkit for VS Code.

**Topics**
+ [What is Amazon CodeCatalyst?](#codecatalyst-intro)
+ [Getting started with CodeCatalyst](codecatalyst-setup.md)
+ [Working with CodeCatalyst resources](codecatalyst-overview.md)
+ [Working with Dev Environments](codecatalyst-devenvironment.md)
+ [Troubleshooting](codecatalyst-troubleshoot.md)

# Getting started with CodeCatalyst and the Toolkit for VS Code
<a name="codecatalyst-setup"></a>

To get started working with CodeCatalyst in VS Code, follow these procedures.

**Topics**
+ [Creating a CodeCatalyst account](#codecatalyst-setup-id)
+ [Connecting the AWS Toolkit with CodeCatalyst](#codecatalyst-setup-connect)

## Creating a CodeCatalyst account
<a name="codecatalyst-setup-id"></a>

You must have active AWS Builder ID or AWS IAM Identity Center credentials to connect to CodeCatalyst from the Toolkit for VS Code. To learn more about AWS Builder ID, IAM Identity Center, and CodeCatalyst credentials, see the [Setting up with CodeCatalyst](https://docs.aws.amazon.com/codecatalyst/latest/userguide/setting-up-topnode.html) section in the *CodeCatalyst* User Guide.

## Connecting the AWS Toolkit with CodeCatalyst
<a name="codecatalyst-setup-connect"></a>

To connect the AWS Toolkit with your CodeCatalyst account, see the [Authentication for Amazon CodeCatalyst](https://docs.aws.amazon.com//toolkit-for-vscode/latest/userguide/connect.html#catalyst) section in the *Connecting to AWS* topic of this User Guide.

# Working with Amazon CodeCatalyst resources in VS Code
<a name="codecatalyst-overview"></a>

The following sections provide an overview of the Amazon CodeCatalyst resource management features that are available from the Toolkit for VS Code.

For more information about Dev Environments and how you can access them from CodeCatalyst, see the [Dev Environments](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html) section in the *Amazon CodeCatalyst* User Guide. 

The following sections describe how to create, open, and work with Dev Environments from VS Code.

**Topics**
+ [Clone a repository](#codecatalyst-overview-clone)
+ [Opening a Dev Environment](#codecatalyst-overview-open)
+ [Creating a CodeCatalyst Dev Environment](#codecatalyst-overview-create)
+ [Creating a Dev Environment from a third-party repository](#codecatalyst-devenvironment-link-repo)
+ [CodeCatalyst commands in VS Code](#codecatalyst-overview-commands)

## Clone a repository
<a name="codecatalyst-overview-clone"></a>

CodeCatalyst is a cloud-based service that requires you to be connected to the cloud to work on CodeCatalyst projects. If you prefer to work on a project locally, you can clone your CodeCatalyst repositories to your local machine and sync it with your CodeCatalyst project online, the next time that you're connected to the cloud.

To clone a repository from your CodeCatalyst account to VS Code with the AWS Toolkit, complete the following steps:

**Note**  
If you are cloning a repository from a 3rd party service, you may be prompted to authenticate with that service's credentials.  
While the repository is being cloned, VS Code displays the progress in the **Cloning Repository** status window. After the repository is cloned, the **Would you like to open the cloned repository?** message appears.

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Expand **CodeCatalyst**, choose **Clone Repository**.

1. From the **Select a CodeCatalyst Repository** dialog, search for the repository that you want to clone, then select it to open the **Choose a folder to clone** dialog.

1. Choose **Select Repository Location** to close the prompt and begin cloning the repository.

1. From the dialog window, choose one of the following to complete the cloning process:
   + To open your repository in your current VS Code window, choose **Open**.
   + To open your repository in a new VS Code window, choose **Open in new window**.
   + To complete the cloning process without opening your repository, close the dialog window.

## Opening a Dev Environment
<a name="codecatalyst-overview-open"></a>

To open an existing Dev Environment in VS Code, complete the following steps.

**Note**  
Selecting the Dev Environment starts the process to connect VS Code with CodeCatalyst by opening your Dev Environment. During this process, VS Code displays progress updates in a CodeCatalyst status window. The status window updates when the process is complete.  
If the Dev Environment fails to open, the status updates with information about why the process failed and a link to open the process logs.
If the process is successful, your Dev Environment opens in a new window, from VS Code.

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Expand **CodeCatalyst** and choose **Open Dev Environment** to open the **Select a CodeCatalyst Dev Environment** dialog in VS Code.

1. From the **Select a CodeCatalyst Dev Environment** dialog, choose the **Dev Environment** that you want to open.

## Creating a CodeCatalyst Dev Environment
<a name="codecatalyst-overview-create"></a>

To create a new Dev Environment, complete the following steps:

**Note**  
When creating a new Dev Environment, observe the following:  
AWS recommends that you specify an alias because it simplifies organization and improves search capabilities for Dev Environments.
Dev Environments saves your work persistently. This means that your Dev Environment can be stopped without losing your work. Stopping your Dev Environment reduces the costs that are required to keep you Dev Environment up and running.
**Storage** is the only setting that can't be changed after your Dev Environment has been created.
VS Code displays the progress of your Dev Environment being created in a status window. After the Dev Environment is created, VS Code opens the Dev Environment in a new window and the **Do you trust the authors of the files in this folder?** prompt also appears. Agree to the terms and conditions to continue working in your Dev Environment.

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Expand **CodeCatalyst**, and choose the **Create Dev Environment** option to open the **Create a CodeCatalyst Dev Environment** menu in VS Code.

1. From the **Source Code** section, choose one of the following options:
   + **Use an existing CodeCatalyst Repository**: Creates a Dev Environment from an existing CodeCatalyst repository. You must select the CodeCatalyst **Project** and **Branch**.
   + **Create an empty Dev Environment**: Creates an empty Dev Environment. 

1. (Optional) From the **Alias** section, enter an alternate name for your Dev Environment.

1. (Optional) From the **Dev Environments Configuration** section, change the following settings to meet your specific needs.
   + **Compute**: Choose **Edit Compute** to change the amount of processing power and RAM that's assigned to your system.
   + **Timeout**: Choose **Edit Timeout** to change the amount of system idle time allowed before your Dev Environment is stopped.
   + **Storage**: Choose **Edit Storage Size** to change the amount of storage space that's assigned to your system.

1. Choose **Create Dev Environment** to create your new cloud development environment.

## Creating a Dev Environment from a third-party repository
<a name="codecatalyst-devenvironment-link-repo"></a>

You can create Dev Environments from a third-party repository by linking to the repository as a source.

Linking to a third-party repository as a source is handled at the project level in CodeCatalyst. For instructions and additional details on how to connect a third-party repository to your Dev Environment, see the [Linking a source repository](https://docs.aws.amazon.com//codecatalyst/latest/userguide/source-repositories-link.html) topic in the *Amazon CodeCatalyst* User Guide.

## CodeCatalyst commands in VS Code
<a name="codecatalyst-overview-commands"></a>

There are additional VS Code commands that are assigned to CodeCatalyst-related features that aren't displayed directly in the AWS Toolkit.

To view a list of commands that are assigned to CodeCatalyst from the command palette, complete the following steps:

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Choose **Show CodeCatalyst Commands** to open the **Command Palette** with a pre-populated search for `CodeCatalyst`.

1. Select a CodeCatalyst command from the list to activate it.

# Working with the Toolkit in a Dev Environments
<a name="codecatalyst-devenvironment"></a>

Dev Environments are virtual computing environments for Amazon CodeCatalyst. The following sections describe how to create, launch, and work from Dev Environments using the AWS Toolkit for Visual Studio Code.

For detailed information about Dev Environments, see the [Dev Environments](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment.html) topic in the *Amazon CodeCatalyst* User Guide.

## Configuring your Dev Environment with devfiles
<a name="codecatalyst-devenvironment-devfile"></a>

The `devfile` specification is an open-standard format for YAML that can be used to define configurations for Dev Environments. Every Dev Environment has a devfile. If you create a Dev Environment without a repository or from a repository that doesn't contain a devfile, a default is applied to the source automatically. Devfiles can be updated from CodeCatalyst or your IDE. The processes to update a devfile in a local or remote instance of VS Code are identical, but if you update a devfile locally, you must push the updates to your source repository before the updates take effect.

For detailed information about configuring Dev Environments with devfiles, see the [Configuring your Dev Environment](https://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment-devfile.html) topic in the *Amazon CodeCatalyst* User Guide.

The following procedure describes how to edit your devfile from a remote instance of the Toolkit while it's running in a Dev Environment.

**Important**  
If you edit the `Devfile` from VS Code, be aware of the following:  
Changing the name of the devfile or the devfile component name replaces the contents of your root directory. All previous content is lost and unrecoverable.
If you create a Dev Environment without a devfile in the root folder or a Dev Environment that's not associated with a source repository, a devfile with default configuration settings is generated for your Dev Environment when you create it.
For instructions on how to define and configure your `Devfile`, see the [Adding Commands](https://devfile.io/docs/2.1.0/adding-commands) documentation on the [devfile.io](https://devfile.io/) website.

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Expand **CodeCatalyst** and choose **Open Devfile** to open `devfile.yaml` in a new editor window, within your current Dev Environment.

1. From the VS Code editor, update your devfile, then save your changes. 

1. The next time you launch your Dev Environment, the configuration is updated to match the specifications that are defined in your `Devfile`.

## Authenticating and connecting to AWS from your Dev Environment
<a name="codecatalyst-devenvironment-credentials"></a>

To access all of your AWS resources from your Dev Environment, you must authenticate and connect your remote instance of the Toolkit with your AWS account. The remote instance of the Toolkit automatically authenticates with the credentials inherited from your local instance of the Toolkit when your Dev Environment is launched.

The procedures to update your credentials for a remote instance of the Toolkit are identical to the authentication experience in your local instance of the Toolkit. For detailed instructions on how to update credentials, authenticate, and connect to AWS from the Toolkit, see the [Connecting to AWS](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/connect.html#connect-to-aws) section in the *Getting started* topic of this User Guide.

For additional information about each of the AWS authentication methods compatible with the AWS Toolkit for Visual Studio Code, see the [Authentication and access](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/connect.html#connect-to-aws) topic in this User Guide.

## Working with the Toolkit for VS Code in Dev Environments
<a name="codecatalyst-devenvironment-toolkit"></a>

After you open or create a Dev Environment in VS Code, you can work from the Toolkit for VS Code, similar to how you can from a local instance of VS Code. Dev Environments running VS Code are configured to automatically install the AWS Toolkit and connect with your AWS Builder ID.

### Stopping a Dev Environment
<a name="codecatalyst-devenvironment-stop"></a>

To stop your current Dev Environment:

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Expand **CodeCatalyst** and choose **Stop Dev Environment**.

1. When prompted by VS Code, confirm that you want to stop your Dev Environment.

1. Your Dev Environment has successfully stopped when VS Code closes the remote connection and returns to a local development instance.

### Opening Dev Environment settings
<a name="codecatalyst-devenvironment-settings"></a>

To open the settings for your current Dev Environment, complete the following steps:

**Note**  
You can't change the amount of storage space assigned to your Dev Environment after it has been created.

1. From the Toolkit for VS Code, expand the **DEVELOPER TOOLS** explorer.

1. Expand **CodeCatalyst** and choose **Open Settings** to open the **Dev Environment Settings** view, for your current Dev Environment.

1. From the **Dev Environment Settings** view, the following sections contain options for your Dev Environment:
   + **Alias**: View and change the **Alias** assigned to your Dev Environment.
   + **Status**: View your current Dev Environment status, the project it's assigned to, and stop your environment.
   + **Devfile**: View the name and location of the `Devfile` for your Dev Environment. Open your `Devfile` by choosing the **Open in Editor** button.
   + **Compute Settings**: Change the size and default **Timeout Length** for your Dev Environment.

# Troubleshooting Amazon CodeCatalyst and VS Code
<a name="codecatalyst-troubleshoot"></a>

The following topics address potential technical issues when working with Amazon CodeCatalyst and VS Code.

**Topics**
+ [VS Code version](#codecatalyst-troubleshoot-vsc)
+ [Permissions for Amazon CodeCatalyst](#codecatalyst-troubleshoot-permission)
+ [Connecting to a Dev Environment from the Toolkit for VS Code](#codecatalyst-troubleshoot-connecting)

## VS Code version
<a name="codecatalyst-troubleshoot-vsc"></a>

Your version of VS Code is expected to set up a handler for `vscode://` URIs on your system. Without this handler, you can't access all CodeCatalyst features from the AWS Toolkit. For example, you encounter an error when launching a Dev Environment from VS Code Insiders. This is because VS Code Insiders handles `vscode-insiders://` URIs and doesn't handle `vscode://` URIs.

## Permissions for Amazon CodeCatalyst
<a name="codecatalyst-troubleshoot-permission"></a>

The following are file permission requirements for working with CodeCatalyst from the AWS Toolkit for Visual Studio Code:
+ Set your own access permissions for your `~/.ssh/config` file to `read` and `write`. Restrict `write` permissions for all other users.
+ Set your access permissions for the `~/.ssh/id_dsa ` and `~/.ssh/id_rsa` files to `read` only. Restrict `read`, `write` and `execute` permissions for all other users.
+ Your `globals.context.globalStorageUri.fsPath` file must be in a writable location.

## Connecting to a Dev Environment from the Toolkit for VS Code
<a name="codecatalyst-troubleshoot-connecting"></a>

If you receive the following error when attempting to connect to a Dev Environment from the AWS Toolkit for Visual Studio Code:

*Your `~/.ssh/config` has an `aws-devenv-*` section that might be out of date.*
+ Choose the **Open config. . .** button to open your `~/.ssh/config` file in the VS Code **Editor**.
+ From the **Editor**, select and delete the contents of the `Host aws-devenv-*` section.
+ Save the changes you made to the `Host aws-devenv-*` of `~/.ssh/config`. Then, close the file.
+ Reattempt to connect to a Dev Environment from the Toolkit for VS Code.