←  back to guides
Integrate AWS Single Sign-On (SSO) and Amazon Elastic Container Registry (ECR) with Gitpod

Integrate AWS Single Sign-On (SSO) and Amazon Elastic Container Registry (ECR) with Gitpod

A common use case in organizations for developers, when working on Gitpod ephemeral environment, is the need to access various AWS services. For instance, sometimes developers need to pull or push images from or to AWS ECR. These images can be private, so some authentication is required, usually AWS SSO. AWS SSO is a cloud SSO service that makes it easy to centrally manage SSO access to multiple AWS accounts and enterprise applications.

In this guide, we will show you how you can set up AWS SSO & AWS ECR on Gitpod ephemeral workspace. In 3 simple steps, we will:

  1. Install aws-cli
  2. Setup aws-sso
  3. Access aws ecr

All these steps would be automated. So you will always get a ready-to-use workspace with AWS CLI configured, including all the required secrets. This lets you work on many ephemeral workspaces at once frictionlessly as you will not have to install or configure the settings multiple times ✨

tl;dr; You need to configure AWS secrets, add this configuration shell script in your project & this task in your .gitpod.yml for ready-to-code Gitpod Workspace 🚀


We will provide you with a setup that will provision AWS CLI and enable SSO when you open a new ephemeral Gitpod workspace. The flow diagram below describes how we have done it in our demo-aws-with-gitpod template repo in 3 steps:

Flow Diagram of Integration of AWS CLI & Gitpod
Flow Diagram of Integration of AWS CLI & Gitpod
  1. Command Task execution

As you open a new gitpod workspace, it gets configured through .gitpod.yml file, located at the root of your project. This initiates the config script.

  1. Installation

The config script automates the whole process of installing CLI and ECR helper whenever you open a new Gitpod workspace.

  1. Configuration

We will use some public configuration options from the SSO like AWS_SSO_REGION, AWS_SSO_URL etc. and add those as environment variables at Gitpod settings. It lets you configure the persistent env variables into your workspace and use them in your code.

Let’s understand the Installation, Configuration and Usage steps in detail.

💻 Installation

We will discuss various installation steps and show you a snippet of the configuration script. You can find these lines of code here in the config script.

Install AWS CLI on Gitpod

To Install AWS CLI on Gitpod, you need to run a certain set of commands given in AWS CLI docs. To automate it, we wrote it as a shell script so that you don’t need to run those commands every time.

language icon bash
curl -fSsl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip -qq awscliv2.zip
sudo ./aws/install --update
rm awscliv2.zip

In the above script, we download the AWS CLI zip, unzip it & execute that to install AWS CLI, following which we remove the zip. To automatically get credentials for Amazon ECR, we would need to install ECR-Credential Helper.

Install ECR-Credential Helper on Gitpod

The following script installs the ECR-Credential Helper:

language icon bash
if [ ! -f /usr/local/bin/docker-credential-ecr-login ]; then
    echo "Installing ecr-login helper"
    TMP_DIR="$(mktemp -d)"
    cd "${TMP_DIR}" || exit 1
    ECR_LATEST=$(curl -s https://api.github.com/repos/awslabs/amazon-ecr-credential-helper/releases/latest | jq -r ".tag_name")
    curl -o docker-credential-ecr-login -fSsL "https://amazon-ecr-credential-helper-releases.s3.us-east-2.amazonaws.com/${ECR_LATEST##*v}/linux-amd64/docker-credential-ecr-login"
    curl -o docker-credential-ecr-login.sha256 -fSsL "https://amazon-ecr-credential-helper-releases.s3.us-east-2.amazonaws.com/${ECR_LATEST##*v}/linux-amd64/docker-credential-ecr-login.sha256"
    sha256sum -c docker-credential-ecr-login.sha256
    sudo mv docker-credential-ecr-login /usr/local/bin/docker-credential-ecr-login
    sudo chmod +x /usr/local/bin/docker-credential-ecr-login
    cd "${OLD_DIR}" || exit 1
    rm -rf "${TMP_DIR}"

(Optional) Install AWS Session Manager Plugin

This is an optional step, but you should first install the Session Manager plugin on your local machine. This facilitates the AWS CLI to start and end sessions that connect you to your managed nodes.

language icon bash
if ! command -v session-manager-plugin; then
    echo "Installing AWS session manager plugin"

      TMP_DIR="$(mktemp -d)"
      cd "$TMP_DIR" || exit 1

      curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o "session-manager-plugin.deb"
      sudo dpkg -i "session-manager-plugin.deb"

      cd "$OLD_DIR"
      rm -rf "$TMP_DIR"

🧪 Configuration

Configure AWS Environment Variables in Gitpod

AWS CLI requires some environment variables to be configured for executing AWS CLI commands. To avoid configuring this every time you spawn a new gitpod ephemeral environment, you can add it with the following Key-Value Map in Gitpod Environment Variables settings:


You can read more about Configuring the Environment Variables in our documentation

Configure AWS environment variable on Gitpod Workspace

To use configured env variables with aws cli, we need to set the variables in home/gitpod/.aws/config :

language icon bash
[[ -d /home/gitpod/.aws ]] || mkdir /home/gitpod/.aws
cat <<- AWSFILE > /home/gitpod/.aws/config
sso_start_url = ${AWS_SSO_URL}
sso_region = ${AWS_SSO_REGION}
sso_account_id = ${AWS_ACCOUNT_ID}
sso_role_name = ${AWS_ROLE_NAME}
region = ${AWS_REGION}

Configure Docker config to use ECR-Login

To use the ECR-Credential helper, we need to update the docker configs :

language icon bash
# if we don't have a .docker/config.json, create:

if [ ! -d /home/gitpod/.docker ]; then
    mkdir -p /home/gitpod/.docker && echo '{}' > /home/gitpod/.docker/config.json
elif [ ! -f /home/gitpod/.docker/config.json ]; then
    echo '{}' > /home/gitpod/.docker/config.json

🚀 Usage

Now we have the whole AWS Configuration shell script ready. To execute this script at the start of your workspace, you need to add a command task in your .gitpod.yml file.

language icon yml
    - name: Initialize & Configure AWS
      command: bash $GITPOD_REPO_ROOT/configure_aws_with_gitpod.sh

In demo-aws-with-gitpod template repo, configure_aws_with_gitpod.sh is in the root directory of the repository. You can replace it with your own script’s path in command task.

You can find the example .gitpod.yml file here for your reference.

Bonus Tip ✨: You can save more time in starting your workspace by using Gitpod Prebuilds. It will prebuild your workspace & directly load that previously built container image to boot it up even faster.

Congratulations 🎉 Now, you are ready to use AWS CLI to access AWS ECR through SSO, to use private registries/images. You can also watch the following video, which thoroughly walks you through the whole process:




Join developers, everywhere.

Development environments pre-configured with the tools and dependencies needed to get inspired and start building.

Related articles

Monthly Newsletter

Subscribe to get a summary of what we've shipped over the last month, plus everything you need to know around developer experience.

By submitting this, I confirm that I have read and understood the Privacy policy.