Configuring Codecatalyst Dev Environments

5 minute read

This article explains how to configure Codecatalyst Dev Enviroments using devfiles to enable developers to quickly contribute to a project's codebase.


Amazon recently announced the public preview availability of Amazon CodeCatalyst. CodeCatalyst is a new Amazon integrated DevOps service that makes it easy for development teams to quickly build and deliver applications on AWS. One feature that CodeCatalyst offers to achieve this goal is Dev Environments. CodeCatalyst Dev Environments enable developers to quickly access, modify, test and commit application code.

Dev Environments are configured using devfiles. Devfiles provide developers a way to model a project’s development dependencies through an open standard and simple yaml file. When a devfile is committed to the project’s repository, other collaborators benefit by being able to reproduce consistent development environments.

Use case walkthrough

Developers are often responsible for contributing to multiple projects at any given time. The projects can contain different programming languages, development frameworks, and build tools. The need for expert knowledge across these variations, along with the need to remember which framework belong to different projects, makes it difficult for developers to contribute effectively. For example, This is where devfiles help. By creating a devfile in your CodeCatalyst project, you reduce the need for other contributors to understand the dependencies and how to set up the development environment, making it easier for others to focus on writing code.

In the rest of this article, i'll walk you through how to setup a devfile. You are going to start by creating a simple python project that will be interacting with Amazon DynamoDB service. In a CodeCatalyst Space, click on Create Project. On the following screen, select Start from Scratch, and then provide a name for your project.

Getting Started

Once the project has been created, you will need a repository to store the project’s code. Navigate to Source Repositories in the Code section of the left navigation menu. Select Add repositoryCreate Repository, to create a new repository.

At this point, you can create a new Dev Environment to begin authoring your application’s code. By default Codecatalyst will create a devfile for projects that don't contain a definition, but in this walkthrough we will create one by using the Codecatalysty UI.

  • Create a python requirements.txt file. Since this project will be connecting to Amazon DynamoDB you will need the Boto3 SDK. Also, include them pytest library to support unit testing. From the repository you created earlier, click Create file. Name the file requirements.txt and add boto3 and pytest to the file as shown below.


  • Commit the file to the repo’s main branch.
  • Create a simple test to verify that the project can create a DynamoDB table. From the repository you created earlier, click Create file. Name the file tests/ Copy the below code snippet into the file and commit to the main branch.
import boto3

ddb = boto3.client('dynamodb', endpoint_url='http://localhost:8000')

def test_create_table():

    table = ddb.create_table(
            'AttributeName': 'Name',
            'AttributeType': 'S'
            'AttributeName': 'Name',
            'KeyType': 'HASH'
            'ReadCapacityUnits': 5,
            'WriteCapacityUnits': 5
    assert table.get('TableDescription')
  • For unit testing you can rely on mocks or local packages to replicate functionality of the Amazon DynamoDB service in the Dev Environment. For this example, you will leverage the AWS dynamodb-local docker image. You will include this docker image in the devfile.
  • Create a devfile that will setup a consistent dev environment for other project members. From the repository you created earlier, click Create file.
  • Name the file devfile.yaml. Copy and paste the below contents into the editor and commit the file to the main branch.
schemaVersion: 2.0.0
  name: aws-universal
  version: 1.0.1
  displayName: AWS Universal
  description: Stack with AWS Universal Tooling
  tags: ["aws", "al2"]
  projectType: "aws"
  - name: aws-runtime
      mountSources: true
        - name: docker-store
          path: /var/lib/docker
        - name: "AWS_SECRET_ACCESS_KEY"
          value: "FAKE_KEY"
        - name: "AWS_ACCESS_KEY_ID"
          value: "FAKE_ID"
  - name: docker-store
      size: 16Gi
  - name: dynamodb
      image: amazon/dynamodb-local 
      mountSources: false
        - name: dynamo
          targetPort: 8000
          exposure: public
  - id: install
      commandLine: python3 -m pip install -r requirements.txt
      workingDir: /projects/repost
      component: aws-runtime
    - install
  • In the above file, you added configuration to run an instance of DynamoDB locally to support unit testing. You also added two environment variables to the aws-runtime component so the boto3 unit tests don’t fail. Finally, you added a command to install our python dependencies and then automated running that command by using the postStart event hook.
  • To verify the project’s devfile is configured to automate the installation of the project’s dependencies, you will create a new Dev Environment. From the left navigation menu under the Code section, select Dev Environments and click Create Dev Environment and choose the IDE of your choice. Select Clone a repository and find the repository you created. Select Work in an existing branch and verify the main branch is selected. Finally click Create.


  • The Dev Environment will take up to a minute to create. Once the development environment is available, you will be able to run the unit test we created via the UI. From the IDE’s terminal window, issue the command pytest. You should receive notice that 1 test passed.



In this article we introduced AWS Codecatalyst Dev Environments and how it is possible to configure a Dev Environment by adding a devfile to a Codecatalyst source repository. While the example shows authoring a devfile from scratch via the UI, it is also possible to launch a Dev Environment first and use the Dev Environment to modify the default generated file. We would love your feedback on how Codecatalyst Dev Environments with devfiles enable you to build more efficiently.

profile pictureAWS
published 6 months ago622 views

This is a great step forward. But we have a common enterprise use case that is not covered by your doco. We need EC2 as our development environment, and we need to specify the AMI because they might be provided by RedHat for example. We need to put these EC2s in private subnets that we control, and we need to use these to test our AWSTOE components.... do you have an example devfile.yaml that we can use?

replied 6 months ago

Thanks for the question Sholto and the explanation of your use case. There are 2 limitations to Codecatalyst Dev Environments that might not meet your immediate needs. 1/ Dev Environments are container based at the moment. It is possible for you to reference public docker images in a devfile, but AMIs are not currently supported. 2/ Codecatalyst Dev Environments run inside the Codecatalyst service account, and do not support private network connectivity at this time.

Cloud 9 might be a good alternative to Codecatalyst Dev Environments. Cloud9 IDEs support both custom AMIs and gives you the ability to run the instance in the VPC of your choice. At this time, there is no devfile support for Cloud9 instances however. The devfile spec is built around container resources, which is one reason that it works in Codecatalyst, but not on the instance based Cloud9 environments. I will follow up with the service team to see what their plans are for Cloud9 native devfiles.

profile pictureAWS
replied 6 months ago