How to Connect Kiro IDE to SageMaker Unified Studio (SMUS) and Set Up Git Integration

A step-by-step guide to remote connectivity, Git configuration via CodeConnections, and push workflows — including enterprise/VPC environments

---

Overview

This article walks you through the complete setup to:

• Connect Kiro IDE (locally installed) to an Amazon SageMaker Unified Studio (SMUS) Space via a secure Remote-SSH tunnel
• Set up Git connections (GitHub or GitLab Self-Managed) at the domain level using AWS CodeConnections
• Clone, commit, and push code from within the remote Space using Kiro

The connection uses AWS Systems Manager Session Manager to create a secure WebSocket tunnel — no inbound ports or SSH keys required on the Space side.

---

Architecture

The remote connection from Kiro IDE to SMUS Spaces is built on four layers:

• AWS Toolkit Extension (v3.100+) — Installed in Kiro; handles IAM Identity Center authentication and provides the SMUS project/space browser.
• Session Manager Plugin — Critical middleware that establishes a secure WebSocket tunnel between the local IDE and the remote Space.
• SSH over Session Manager — Kiro uses Remote-SSH tunnelled through SSM to connect to the running Space instance.
• Network Connectivity — Outbound HTTPS (port 443) to AWS SSM endpoints is required.

Logical Connection Flow

Local Machine (Kiro + AWS Toolkit + Session Manager Plugin)
    |
    |  HTTPS / WebSocket (port 443)
    v
AWS SSM Endpoints (ssmmessages.<region>.amazonaws.com)
                  (ec2messages.<region>.amazonaws.com)
    |
    |  Secure WebSocket Tunnel (Session Manager)
    v
SMUS Space (Compute Instance + SSM Agent + SSH Server)
    |
    |  Remote-SSH
    v
Kiro IDE Remote Window <--> /home/sagemaker-user/ workspace

---

Prerequisites

Local Machine Requirements

Component	Minimum Version	Notes
Kiro IDE	v0.8.0+ (rec. v0.10.78+)	Latest version strongly preferred
AWS Toolkit extension	v3.100+	Install from Kiro Extensions marketplace
Session Manager Plugin	v1.1.23.0+	Must be executable; not blocked by security software
Operating System	Win 10/11, macOS 13+, Linux	All platforms supported
Network	Outbound HTTPS 443	To AWS SSM endpoints; via proxy if required

SMUS Space Configuration

Setting	Required Value	Where to Configure
Remote Access	Enabled	Space settings toggle
SageMaker Distribution	v2.8+ (rec. v2.11)	Space image selection
Instance RAM	Min. 8 GB (T3 Large+)	Instance type selection
Space State	Running	Start space before connecting

Project & Domain Settings

Setting	Required Value	Where to Check
enableTrustedIdentityPropagationPermissions	false (MUST be disabled)	Project Profile → Blueprint Parameters
Execution Role	sagemaker:StartSession	IAM Role attached to Space

⚠️ If enableTrustedIdentityPropagationPermissions is set to true, Kiro connection will fail silently. This is the #1 configuration blocker.

Network Requirements (VPC / Enterprise Environments)

⚠️ Missing VPC endpoints are the most common root cause of connectivity failures in enterprise environments.

• VPC Interface Endpoint: ssmmessages — Required for Session Manager WebSocket tunnel. Must be in "Available" state.
• VPC Interface Endpoint: ec2messages — Required alongside ssmmessages. Create both together.
• Alternatively: NAT Gateway — Provides internet access from VPC; eliminates need for individual endpoints.
• Proxy Configuration — If behind a corporate proxy, configure HTTP/HTTPS proxy in Kiro settings AND OS environment variables.
• Session Manager Plugin binary — Must not be blocked by endpoint security or application whitelisting software.

---

Step 1: Connect Kiro to SMUS Space

1.1 Install & Verify Session Manager Plugin

# Verify version (must be >= 1.1.23.0)
session-manager-plugin --version

# Quick execution test
session-manager-plugin "" "" StartSession "" "" ""
# Expected: "The Session Manager plugin was installed successfully..."

⚠️ On Windows, if blocked by enterprise security, move the session-manager-plugin.exe binary to an allowed directory and add it to the PATH.

1.2 Authenticate AWS Toolkit in Kiro

1. Click the AWS Toolkit icon in the left sidebar.
2. Click "Connect to AWS".
3. Choose IAM Identity Center (SSO) — provide your SMUS domain URL (e.g., https://your-domain.studio.<region>.sagemaker.aws).
4. Complete the SSO browser auth flow.

You can also authenticate using IAM credentials if your setup supports it. Both IAM and IdC authentication work for SMUS connectivity.

1.3 Connect to the Space

Method A — From Kiro (AWS Toolkit):

1. Open AWS Toolkit panel.
2. Expand "SageMaker Unified Studio".
3. Browse: Domains → Projects → Spaces. Find the project where your Space with Code Editor is created.
4. Click "Connect" on a running Space.

Method B — From SMUS Portal (Deep Link):

1. Open SMUS web portal in browser.
2. Navigate to Project → Compute → Spaces.
3. Click the Kiro icon in the Actions column.
4. Kiro opens and prompts to confirm the connection.

1.4 Remote Window Confirmation

• Kiro opens a new remote window connected to the Space.
• Bottom-left shows green "><" or remote host name.
• Terminal prompt shows: sagemaker-user@default:~$
• Session is valid for up to 12 hours.

---

Step 2: Set Up Git Connection — GitHub

Git connections in SMUS are configured at the domain level using AWS CodeConnections and apply to all projects within that domain.

2.1 Create the GitHub Connection

1. Open SageMaker console → navigate to DataZone / SMUS Domain → Connections tab.
2. Click "Create Git connection" → Choose GitHub.
3. Begin the OAuth handshake with GitHub (browser prompt).

2.2 Complete a Pending Connection

GitHub connections start as "Pending" — the OAuth handshake must be completed:

1. Go to AWS Developer Tools console: https://console.aws.amazon.com/codesuite/settings/connections (OR: Search "CodeConnections" in the AWS Console search bar.)
2. Find the connection with status "Pending".
3. Select it → click "Update pending connection".
4. Complete the GitHub OAuth authorization in the browser window.
5. Watch status change: Pending → Available.

2.3 Enable the Connection for the Domain

By default, all added Git connections are initially disabled:

1. Go back to DataZone console → Domain → Connections tab.
2. Locate the GitHub connection in the list.
3. Confirm it is set to Enabled (toggle).
4. Once enabled: all projects and Spaces in this domain can access it.

CLI Verification (Optional)

aws codeconnections list-connections --provider-type GitHub \
  --query "Connections[].ConnectionStatus"
# Expected: ["AVAILABLE"]

---

Step 3: Set Up Git Connection — GitLab Self-Managed

GitLab Self-Managed requires an additional Host setup step before completing the connection.

⚠️ Critical order of operations: (1) Set up the Host → Available, then (2) Create & Complete the Connection → Available, then (3) Enable the connection in your SMUS Domain → Connections tab.

3.1 Set Up the Host

1. AWS Console → Developer Tools → Settings → Hosts.
2. Find the pending Host entry → Click "Set up host".
3. Provide your GitLab Self-Managed Personal Access Token (PAT) with api scope.
4. Wait for Host status: Pending → Available (1-2 min).

3.2 Generate a GitLab Personal Access Token (PAT)

1. GitLab → Profile → Edit Profile → Access Tokens → "Add new token".
2. Name: aws-smus-connection, set Expiration date.
3. Scope: api only (not read_api, not read_repository — full api).
4. Click "Create personal access token".
5. Copy immediately — shown only once!

⚠️ The PAT user must have Admin access on the GitLab instance to register the OAuth application.

3.3 Troubleshooting: ProviderResourceNotFoundException

Cause	Fix
Host still Pending	Set up Host first; wait for Available status
Non-standard port	Ensure port 443 is used
GitLab URL unreachable from AWS	Check VPC or internet connectivity to GitLab host
Self-signed TLS certificate	Provide internal CA cert during host creation
Insufficient PAT permissions	Use PAT from a GitLab Admin user

---

Step 4: Clone Repository & Push Code from Kiro

⚠️ Use HTTPS (not SSH) for SMUS Spaces. SSH keys inside an SMUS Space are ephemeral and will be lost when the Space is stopped or restarted.

4.1 Clone the Repository

git clone https://github.com/your-org/your-repo.git
cd your-repo

4.2 Configure Git Identity

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

4.3 Store Credentials

git config --global credential.helper store

4.4 Make Changes, Commit, and Push

git add .
git commit -m "your commit message"
git push --set-upstream origin main
# Username: your-github-username
# Password=[REDACTED_PASSWORD] GitHub PAT — NOT your account password>

After the first successful push, credentials are stored — no prompts on future pushes.

4.5 Fix Remote URL (if SSH error occurs)

If you see "Permission denied (publickey)" on push:

git remote -v
# If it shows git@github.com:... switch to HTTPS:
git remote set-url origin https://github.com/your-org/your-repo.git

4.6 Generate a GitHub Personal Access Token (PAT)

1. GitHub → Settings → Developer settings → Personal access tokens → Generate new token (classic).
2. Set scope: repo (full control of private repositories).
3. Copy the token immediately — shown only once.

---

Troubleshooting Quick Reference

Symptom / Error	Likely Cause	Fix
Space not visible in Kiro Explorer	Missing VPC endpoints (ssmmessages, ec2messages)	Create both VPC Interface Endpoints; verify Available
"Resource space is not connected"	Session Manager Plugin blocked or network issue	Whitelist plugin binary; verify proxy settings
Session Manager Plugin not allowed to run	Enterprise security blocking the binary	Move binary to allowed path; add to PATH
Connection timeout to SSM endpoints	Proxy not configured for Kiro	Set HTTP/HTTPS proxy in Kiro settings + OS env vars
TIP error / silent connection failure	Trusted Identity Propagation enabled	Set enableTrustedIdentityPropagationPermissions = false
"Permission denied (publickey)" on git push	Remote URL set to SSH	git remote set-url origin https://...
ProviderResourceNotFoundException (GitLab)	Host not Available; or GitLab unreachable	Set up Host first; check VPC/network
GitHub connection stays "Pending"	OAuth handshake not completed	Update pending connection in Developer Tools console
Credentials re-prompted every push	credential.helper not configured	git config --global credential.helper store

---

Authentication Layers

Kiro requires two separate sign-ins:

Auth Layer	Purpose	Method
Kiro licence sign-in	Activates Kiro's agentic features (specs, hooks, steering)	AWS Builder ID or IAM Identity Center
AWS Toolkit sign-in	Connects to SMUS Spaces and AWS resources	IAM Identity Center (SSO) to the SMUS domain

⚠️ These are independent sign-ins. Having one does not substitute for the other.

---

Enterprise Environment Considerations

• Proxy Settings: Configure HTTP/HTTPS proxy in Kiro settings (Ctrl+,) AND in OS environment variables (HTTPS_PROXY, HTTP_PROXY, NO_PROXY).
• Session Manager Plugin Path: If blocked by endpoint security (McAfee, CrowdStrike), copy to a whitelisted directory and add to system PATH.
• VPC Endpoints: In air-gapped environments, provision VPC Interface Endpoints for ssmmessages and ec2messages.
• SSH Keys are Ephemeral: SSH keys generated inside SMUS Spaces are lost on stop/restart. Always prefer HTTPS + stored PAT.
• Internal CA / TLS Certificates: For internal GitLab: git config --global http.sslCAInfo /path/to/internal-ca.pem
• DNS Resolution: GitLab hostname must be resolvable from the Space's subnet — verify with nslookup or dig.

---

Related Documentation

• Kiro in Amazon SageMaker Unified Studio
• Connecting to SMUS Spaces
• Link to Kiro from SMUS (Deep Link)
• Configuring SMUS Remote Access (Admin)
• SMUS Prerequisites (TIP must be false)
• IAM Permissions (sagemaker:StartSession)
• VPC without Internet Access Setup