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). # Configuring a devfile for a Dev Environment A *devfile* is an open standard that helps you to customize your development Dev Environments across your team. A devfile is a YAML file that codifies your required development tools. By configuring a devfile, you can pre-determine the project tools and application libraries you need and Amazon CodeCatalyst installs them to your Dev Environment for you. The devfile is specific to the repository for which it was created, and you can create a separate devfile for each repository. Your Dev Environment supports commands and events, and provides a default universal devfile image. If you create a project using the empty blueprint, you can create a devfile manually. If you create a project using a different blueprint, CodeCatalyst creates a devfile automatically. The `/projects` directory of a Dev Environment stores the files that are pulled from the source repository and the devfile. The `/home` directory, which is empty when you first create a Dev Environment, stores the files you create while using your Dev Environment. Everything in the `/projects` and `/home` directories of a Dev Environment is stored persistently. **Note** The `/home` folder only changes if you change the name of the devfile or devfile component name. If you change the devfile or devfile component name, the contents of the `/home` directory are replaced and your previous `/home` directory data cannot be recovered. If you create a Dev Environment with a source repository that does not contain a devfile in its root, or if you create a Dev Environment without a source repository, a default universal devfile is applied to the source repository automatically. The same default universal devfile image is used for all IDEs. CodeCatalyst currently supports devfile version 2.0.0. For more information about the devfile, see [Devfile schema - Version 2.0.0](https://devfile.io/docs/2.0.0/devfile-schema). **Note** You can only include public container images in your devfile. Note that VPC-connected Dev Environments only support the following devfile images: + Universal image + Private Amazon ECR images, if the repository is in the same region as the VPC **Topics** + [Editing a repository devfile for a Dev Environment](devenvironment-devfile-moving.md) + [Devfile features supported by CodeCatalyst](#devenvironment-devfile-support) + [Example of a devfile for a Dev Environment](#devenvironment-devfile-example) + [Troubleshooting a repository devfile using recovery mode](#devenvironment-devfile-recovery) + [Specifying universal devfile images for a Dev Environment](devenvironment-universal-image.md) + [Devfile commands](devenvironment-devfile-commands.md) + [Devfile events](devenvironment-devfile-events.md) + [Devfile components](devenvironment-devfile-components.md) # Editing a repository devfile for a Dev Environment Use the following procedure to edit a repository devfile for a Dev Environment. ## Editing a repository devfile for a Dev Environment in CodeCatalyst **To edit the repository devfile** 1. Open the CodeCatalyst console at [https://codecatalyst.aws/](https://codecatalyst.aws/). 1. Navigate to the project that contains the source repository for which you want to edit the devfile. 1. In the navigation pane, choose **Code**. 1. Choose **Source Repositories**. 1. Choose the source repository that contains the devfile that you want to edit. 1. From the list of files, choose the `devfile.yaml` file. 1. Choose **Edit**. 1. Edit the devfile. 1. Choose **Commit**, or create a pull request so a team member can review and approve the changes. **Note** If you edit your devfile, you have to restart the devfile for the changes to take effect. This can be done by running `/aws/mde/mde start --location devfile.yaml`. If there's a problem starting your devfile, it will enter recovery mode. However, if you edit a devfile associated to a VPC-connected Dev Environment, you have to restart the Dev Environment instead for the changes to take effect. You can review which devfile is being used by running `/aws/mde/mde status`. The location field has the path of the devfile relative to the environment’s `/projects` folder. ``` { "status": "STABLE", "location": "devfile.yaml" } ``` You can also move the default devfile in `/projects/devfile.yaml` to your source code repository. To update the location of the devfile, use following command: `/aws/mde/mde start --location repository-name/devfile.yaml`. ## Editing a repository devfile for a Dev Environment in an IDE To change the configuration of a Dev Environment, you must edit the devfile. We recommend that you edit the devfile in a supported IDE and then update your Dev Environment, but you can also edit the devfile from the root of the source repository in CodeCatalyst. If you edit the devfile in a supported IDE, you must commit and push your changes to the source repository or create a pull request so a team member can review and approve the devfile edits. + [Editing the repository devfile for a Dev Environment in AWS Cloud9](https://docs.aws.amazon.com/cloud9/latest/user-guide/devenvironment-cloud9.title.html#ide-toolkits-edit-devfile-cloud9) + [Editing the repository devfile for a Dev Environment in VS Code](https://docs.aws.amazon.com/toolkit-for-vscode/latest/userguide/codecatalyst-devenvironment.html#codecatalyst-devenvironment-devfile) + [Editing the repository devfile for a Dev Environment in JetBrains](https://docs.aws.amazon.com/toolkit-for-jetbrains/latest/userguide/codecatalyst-overview.html#codecatalyst-overview-default) ## Devfile features supported by CodeCatalyst CodeCatalyst supports the following devfile features on version 2.0.0. For more information about the devfile, see [Devfile schema - Version 2.0.0](https://devfile.io/docs/2.0.0/devfile-schema). | Feature | Type | | --- | --- | | `exec` | Command | | `postStart` | Event | | `container` | Component | | `args` | Component Properties | | `env` | Component Properties | | `mountSources` | Component Properties | | `volumeMounts` | Component Properties | ## Example of a devfile for a Dev Environment The following is an example of a simple devfile. ``` schemaVersion: 2.0.0 metadata: name: al2 components: - name: test container: image: public.ecr.aws/amazonlinux/amazonlinux:2 mountSources: true command: ['sleep', 'infinity'] - name: dockerstore commands: - id: setupscript exec: component: test commandLine: "chmod +x script.sh" workingDir: /projects/devfiles - id: executescript exec: component: test commandLine: "/projects/devfiles/script.sh" - id: yumupdate exec: component: test commandLine: "yum -y update --security" events: postStart: - setupscript - executescript - yumupdate ``` Devfile startup, command, and event logs are captured and stored in `/aws/mde/logs`. To debug devfile behaviour, start up your Dev Environment using a working devfile and access the logs. ## Troubleshooting a repository devfile using recovery mode If there's a problem starting your devfile, it will enter recovery mode so that you can still connect to your environment and fix your devfile. While in recovery mode, running `/aws/mde/mde status` won’t contain the location of your devfile. ``` { "status": "STABLE" } ``` You can check the error in the logs under `/aws/mde/logs`, fix the devfile, and try running `/aws/mde/mde start` again. # Specifying universal devfile images for a Dev Environment The default *universal image* includes the most commonly used programming languages and related tools that can be used for your IDE. If no image is specified, CodeCatalyst provides this image and contains tools that are maintained by CodeCatalyst. To remain notified of new image releases, see [Subscribing to universal image notifications with SNS](#devenvironment-universal-notifications). Amazon CodeCatalyst actively supports the following devfile images: | Image version | Image identifier | | --- | --- | | Universal image 4.0 | public.ecr.aws/aws-mde/universal-image:4.0 | | Universal image 5.0 | public.ecr.aws/aws-mde/universal-image:5.0 | **Note** You can also use `public.ecr.aws/aws-mde/universal-image:latest` to get the latest image, which is currently `public.ecr.aws/aws-mde/universal-image:5.0`. CodeCatalyst has deprecated the following images. You can still use these images, but they won't be cached on the build host and will result in increased Dev Environment start-up times. | Image version | Image identifier | Deprecation date | | --- | --- | --- | | Universal image 1.0 | public.ecr.aws/aws-mde/universal-image:1.0 | August 16, 2024 | | Universal image 2.0 | public.ecr.aws/aws-mde/universal-image:2.0 | August 16, 2024 | | Universal image 3.0 | public.ecr.aws/aws-mde/universal-image:3.0 | July 30, 2025 | **Note** If you're using AWS Cloud9, auto-complete will not work for PHP, Ruby and CSS after upgrading to `universal-image:3.0`. **Topics** + [Subscribing to universal image notifications with SNS](#devenvironment-universal-notifications) + [Universal image 4.0 runtime versions](#devenvironment-universal-runtimes-4.0) + [Universal image 5.0 runtime versions](#devenvironment-universal-runtimes-5.0) ## Subscribing to universal image notifications with SNS CodeCatalyst provides a universal image notification service. You can use it to subscribe to an Amazon Simple Notification Service (SNS) topic that notifies you when CodeCatalyst universal image updates have been released. For more information about SNS topics, see [What is Amazon Simple Notification Service?](https://docs.aws.amazon.com/sns/latest/dg/welcome.html). Whenever new universal images are released, we send notifications to subscribers; this section describes how to subscribe to CodeCatalyst universal image updates. **Sample message** ``` { "Type": "Notification", "MessageId": "123456789", "TopicArn": "arn:aws:sns:us-east-1:1234657890:universal-image-updates", "Subject": "New Universal Image Release", "Message": { "v1": { "Message": "A new version of the Universal Image has been released. You are now able to launch new DevEnvironments using this image.", "image ": { "release_type": "MAJOR VERSION", "image_name": "universal-image", "image_version": "2.0", "image_uri": "public.ecr.aws/amazonlinux/universal-image:2.0" } } }, "Timestamp": "2021-09-03T19:05:57.882Z", "UnsubscribeURL": "example url" } ``` **To subscribe to CodeCatalyst universal image updates using the Amazon SNS console** 1. Open the Amazon SNS console to the [Dashboard](https://console.aws.amazon.com/sns/v2/home). 1. In the navigation bar, choose your AWS Region. 1. In the navigation pane, choose **Subscriptions**, and then choose **Create subscription**. 1. In **Topic ARN**, enter `arn:aws:sns:us-east-1:089793673375:universal-image-updates`. 1. In **Protocol**, choose **Email**. 1. In **Endpoint**, provide an email address. This email address will be used to receive notifications. 1. Choose **Create subscription**. 1. You will receive a confirmation email with the subject line "AWS Notification - Subscription Confirmation". Open the email and choose **Confirm subscription**. **To unsubscribe from CodeCatalyst universal image updates using the Amazon SNS console** 1. Open the Amazon SNS console to the [Dashboard](https://console.aws.amazon.com/sns/v2/home). 1. In the navigation bar, choose your AWS Region. 1. In the navigation pane, choose **Subscriptions** and then select the subscription you want to unsubscribe from. 1. Choose **Actions**, and then choose **Delete subscriptions**. 1. Choose **Delete**. ## Universal image 4.0 runtime versions The following table lists the available runtimes for `universal-image:4.0`. **`universal-image:4.0` runtime versions** [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/codecatalyst/latest/userguide/devenvironment-universal-image.html) ## Universal image 5.0 runtime versions The following table lists the available runtimes for `universal-image:5.0`. **`universal-image:5.0` runtime versions** | Runtime name | Version | Specific major and latest minor version | | --- | --- | --- | | aws cli | 2.25 | `aws-cli: 2.x` | | docker compose | 2.34 | `docker-compose: 2.x` | | dotnet | 8.0 | `dotnet: 8.x` | | golang | 1.24 | `golang: 1.x` | | java | corretto21 | `java: corretto21.x` | | nodejs | 22.0 | `nodejs: 22.x` | | php | 8.3.16 | `php: 8.x` | | python | 3.12 | `python: 3.x` | | ruby | 3.4.2 | `ruby: 3.x` | | terraform | 1.10.5 | `terraform: 1.x` | # Devfile commands Currently, CodeCatalyst only supports `exec` commands in your devfile. For more information, see [Adding commands](https://devfile.io/docs/2.0.0/adding-commands) in the Devfile.io documentation. The following example shows you how to specify `exec` commands in your devfile. ``` commands: - id: setupscript exec: component: test commandLine: "chmod +x script.sh" workingDir: /projects/devfiles - id: executescript exec: component: test commandLine: "./projects/devfiles/script.sh" - id: updateyum exec: component: test commandLine: "yum -y update --security" ``` After you're connected to your Dev Environment, you can execute defined commands through the terminal. ``` /aws/mde/mde command /aws/mde/mde command executescript ``` For long running commands, you can use the streaming flag `-s` to output the execution of the command in real time. ``` /aws/mde/mde -s command ``` **Note** `command-id` must be lower case. ## Exec parameters supported by CodeCatalyst CodeCatalyst supports the following `exec` parameters on devfile version 2.0.0. + `commandLine` + `component` + `id` + `workingDir` # Devfile events Currently, CodeCatalyst only supports `postStart` events in your devfile. For more information, see [postStartObject](https://devfile.io/docs/2.0.0/adding-event-bindings#post-start-object) in the Devfile.io documentation. The following example shows you how to add `postStart` event bindings in your devfile. ``` commands: - id: executescript exec: component: test commandLine: "./projects/devfiles/script.sh" - id: updateyum exec: component: test commandLine: "yum -y update --security" events: postStart: - updateyum - executescript ``` After startup, your Dev Environment will execute the specified `postStart` commands in the order they are defined. If a command fails, the Dev Environment will continue running and the execution output is stored in the logs under `/aws/mde/logs`. # Devfile components Currently, CodeCatalyst only supports `container` components in your devfile. For more information, see [Adding components](https://devfile.io/docs/2.0.0/adding-components) in the Devfile.io documentation. The following example shows you how to add a startup command to your container in your devfile. ``` components: - name: test container: image: public.ecr.aws/amazonlinux/amazonlinux:2 command: ['sleep', 'infinity'] ``` **Note** When the container has short lived entry command, you must include `command: ['sleep', 'infinity']` to keep the container running. CodeCatalyst also supports the following properties in your container component: `args`, `env`, `mountSources`, and `volumeMounts`.