Beginner to Advanced | macOS, Linux, Git, SSH, IAM, CodeBuild

This master tutorial covers the complete AWS CodeCommit workflow, from creating your first repository to managing source code, collaborating through branches and pull requests, and integrating with AWS CI/CD services.

Your demo1 repository is already working successfully. Your terminal output confirms that you cloned the repository, created two commits, and pushed both to AWS CodeCommit.

Your working environment

Working

Setting	Value
AWS service	CodeCommit
Repository	demo1
AWS Region	ap-southeast-2 (Sydney)
Local OS	macOS
Authentication	SSH using RSA 4096
Private key	~/.ssh/id_rsa_codecommit
Main branch	main
Latest supplied commit	b067930
Files	demo.txt, buildspec.yaml

What you will learn

AWS IAM setup and permissions

Creating and configuring repositories

Generating SSH keys and connecting securely

Clone, add, commit, push, pull and fetch

Branches, merging and pull requests

Version management, tags and rollback

CodeBuild and CI/CD integration

Common errors and troubleshooting

1. Understanding AWS CodeCommit

AWS CodeCommit is a fully managed Git repository hosting service. It stores your source code in private repositories and integrates with AWS IAM, CodeBuild, CodePipeline, CloudTrail and other AWS services.

Developer pushes code to CodeCommit, where AWS build and deployment services can consume it.

CodeCommit returned to full general availability on November 24, 2025, including access for new customers. AWS DevOps & Developer Productivity Blog

2. Prerequisites

You need an AWS account, an IAM identity with CodeCommit permissions, Git, an SSH client and optionally AWS CLI for repository management.

Step 2.1 — Install Git and AWS CLI on macOS

Using Homebrew:

brew install git awscli

Check versions:

git --version
aws --version
ssh -V

On Ubuntu/Debian:

sudo apt update
sudo apt install -y git openssh-client

Install AWS CLI v2 separately from the official AWS instructions if you need CLI functionality on Linux.

Step 2.2 — Configure AWS CLI (optional for SSH Git access)

aws configure --profile codecommit

Enter your AWS access key, secret key, default region ap-southeast-2, and output format json. Prefer temporary credentials through AWS IAM Identity Center where available.

Verify:

aws sts get-caller-identity --profile codecommit

For convenience throughout this tutorial:

export AWS_PROFILE=codecommit
export AWS_DEFAULT_REGION=ap-southeast-2

SSH-based Git operations do not require AWS CLI credentials. The CLI configuration is for AWS administration and API commands.

3. Configure AWS IAM access

AWS IAM manages authentication and authorization for CodeCommit.

Step 3.1 — Create an IAM user

1. Open the AWS IAM Console.
2. Navigate to Users → Create user.
3. Enter a username such as codecommit-developer.
4. Create the user and assign appropriate permissions.

For this training exercise, you can attach the AWS-managed policy:

AWSCodeCommitPowerUser

This provides broad CodeCommit development permissions. For production, use a least-privilege policy.

Step 3.2 — Example IAM policy for one repository

The following policy allows an IAM user to clone, fetch, pull and push to demo1.

Replace ACCOUNT_ID with your 12-digit AWS account ID.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CodeCommitGitAccess",
      "Effect": "Allow",
      "Action": [
        "codecommit:GitPull",
        "codecommit:GitPush"
      ],
      "Resource": "arn:aws:codecommit:ap-southeast-2:ACCOUNT_ID:demo1"
    }
  ]
}

GitPull is required for cloning and fetching; GitPush is required for pushing changes. Other console and API operations, including repository creation and pull-request management, require additional IAM permissions. AWS CodeCommit

4. Create a CodeCommit repository

Method 1 — AWS Console

Open the AWS CodeCommit Console.

1. Select ap-southeast-2 (Sydney).
2. Choose Create repository.
3. Set Repository name to demo1.
4. Optionally enter a description, such as AWS CodeCommit training repository.
5. Click Create.

The repository will initially be empty.

Method 2 — AWS CLI

If creating a new repository:

aws codecommit create-repository \
  --repository-name demo1 \
  --repository-description "AWS CodeCommit Demo Repository" \
  --region ap-southeast-2

Your demo1 already exists, so skip this creation command for your current environment.

List repositories:

aws codecommit list-repositories \
  --region ap-southeast-2

Get repository information:

aws codecommit get-repository \
  --repository-name demo1 \
  --region ap-southeast-2

AWS returns repository metadata, including clone URLs and the default branch after initialization. AWS CodeCommit

5. Generate an SSH key for CodeCommit

AWS CodeCommit IAM SSH authentication requires RSA-formatted public keys, not ED25519 keys. AWS Identity and Access Management

Step 5.1 — Generate a dedicated RSA key

On your Mac:

mkdir -p ~/.ssh

ssh-keygen -t rsa -b 4096 \
  -f ~/.ssh/id_rsa_codecommit \
  -C "aws-codecommit"

Choose a strong passphrase when prompted for better security. If using your existing RSA key, do not run the generation command again or overwrite it.

This creates:

File	Purpose
~/.ssh/id_rsa_codecommit	Private SSH key; never share
~/.ssh/id_rsa_codecommit.pub	Public SSH key; upload to IAM

Step 5.2 — Display or copy your public key

cat ~/.ssh/id_rsa_codecommit.pub

On macOS:

pbcopy < ~/.ssh/id_rsa_codecommit.pub

The output should begin with:

ssh-rsa AAAAB3NzaC1yc2E...

The entire public key must be pasted as one line.

Step 5.3 — Upload the key to AWS IAM

Navigate to:

IAM → Users → Your IAM user → Security credentials → SSH keys for AWS CodeCommit → Upload SSH public key

Paste the public key and upload it.

AWS generates an SSH Key ID resembling:

APKAXXXXXXXXXXXXXXXX

This is the SSH username used for CodeCommit authentication. It is not your IAM username or your Mac login name.

Ensure the uploaded key has Active status.

6. Configure SSH on your Mac

Step 6.1 — Edit the SSH configuration

nano ~/.ssh/config

Add this configuration, replacing the placeholder with your real SSH Key ID:

Host git-codecommit.*.amazonaws.com
    User APKAXXXXXXXXXXXXXXXX
    IdentityFile ~/.ssh/id_rsa_codecommit
    IdentitiesOnly yes

Save the file.

This configuration works for CodeCommit endpoints in multiple AWS Regions, provided the IAM identity and key are valid for the target AWS account.

Step 6.2 — Set file permissions

chmod 700 ~/.ssh
chmod 600 ~/.ssh/id_rsa_codecommit
chmod 644 ~/.ssh/id_rsa_codecommit.pub
chmod 600 ~/.ssh/config

Step 6.3 — Verify the selected SSH identity

ssh -G git-codecommit.ap-southeast-2.amazonaws.com \
  | grep -E '^(user|identityfile|identitiesonly) '

Check that user shows your APKA... key ID and that identityfile points to id_rsa_codecommit.

Step 6.4 — Test SSH authentication

ssh -T git-codecommit.ap-southeast-2.amazonaws.com

A successful test returns a message similar to:

You have successfully authenticated over SSH.
You can use Git to interact with CodeCommit.

For troubleshooting:

ssh -vT git-codecommit.ap-southeast-2.amazonaws.com

The AWS documentation confirms this SSH setup and testing workflow. AWS CodeCommit

7. Clone your CodeCommit repository

Move into your desired workspace:

mkdir -p ~/aws
cd ~/aws

Clone the repository:

git clone ssh://git-codecommit.ap-southeast-2.amazonaws.com/v1/repos/demo1

For a brand-new empty repository, Git may warn that it is empty. This is normal.

Enter the repository:

cd demo1

Check the remote:

git remote -v

Expected:

origin  ssh://git-codecommit.ap-southeast-2.amazonaws.com/v1/repos/demo1 (fetch)
origin  ssh://git-codecommit.ap-southeast-2.amazonaws.com/v1/repos/demo1 (push)

For your existing clone, you do not need to clone again.

8. Configure Git identity

This controls the author information recorded in Git commits.

Global configuration:

git config --global user.name "Rajesh Kumar"
git config --global user.email "devops@rajeshkumar.xyz"
git config --global init.defaultBranch main

Or set it for the current repository only:

git config user.name "Rajesh Kumar"
git config user.email "devops@rajeshkumar.xyz"

Verify:

git config --get user.name
git config --get user.email
git config --list

The Git author email does not have to match the IAM user identity used for SSH.

9. Create files, commit and push

These are the core Git operations you already completed successfully.

Step 9.1 — Create a file

touch demo.txt

Or create it with some content:

echo "Hello AWS CodeCommit" > demo.txt

Step 9.2 — Check repository status

git status

Step 9.3 — Stage files

Stage one file:

git add demo.txt

Or stage all changed, added and deleted files:

git add --all

Step 9.4 — Commit changes

git commit -m "First commit"

Step 9.5 — Push to AWS

For a first push:

git push -u origin main

For subsequent pushes:

git push origin main

Your first push returned:

[new branch] main -> main

That confirms that the remote main branch was created.

How the Git workflow operates

10. Modify files and push additional commits

Edit the file:

echo "Second change" >> demo.txt

Review the changes:

git diff
git status

Stage, commit and push:

git add demo.txt
git commit -m "Updated demo.txt"
git push origin main

You can confirm the new commit in the CodeCommit console under Repositories → demo1 → Commits.

11. Fetch and pull code from AWS

Use these commands whenever the remote repository has newer changes, including changes pushed by teammates.

Fetch without modifying local files:

git fetch origin

Check incoming commits:

git log --oneline HEAD..origin/main

Pull changes into your current main branch:

git switch main
git pull --ff-only origin main

The --ff-only option avoids creating an unexpected merge commit. If Git reports divergent histories, inspect the differences and choose a deliberate merge or rebase strategy.

12. Create and manage branches

A branch lets you develop changes without immediately modifying the main branch.

Step 12.1 — Create a feature branch

git switch main
git pull --ff-only origin main
git switch -c feature/add-readme

Step 12.2 — Create a file and commit

echo "# AWS CodeCommit Demo" > README.md

git add README.md
git commit -m "Add project README"

Step 12.3 — Push the branch

git push -u origin feature/add-readme

Step 12.4 — Display and switch branches

git branch
git branch -a
git switch main
git switch feature/add-readme

Step 12.5 — Delete branches after merging

Delete the local branch once it has been merged:

git branch -d feature/add-readme

Delete its remote branch:

git push origin --delete feature/add-readme

13. Create a pull request in CodeCommit

A pull request (PR) lets developers propose changes for review before merging them into main.

Method 1 — AWS Console

1. Open CodeCommit → demo1.
2. Select Pull requests.
3. Choose Create pull request.
4. Source branch: feature/add-readme.
5. Destination branch: main.
6. Review the differences.
7. Enter a title and description.
8. Choose Create.

After review and approval, select an appropriate merge strategy, such as fast-forward, squash or three-way merge.

Method 2 — AWS CLI

aws codecommit create-pull-request \
  --title "Add README" \
  --description "Adding project documentation" \
  --targets repositoryName=demo1,sourceReference=feature/add-readme,destinationReference=main \
  --region ap-southeast-2

The output contains a pull request ID. Use that ID to review or merge the PR through the CLI if desired.

CodeCommit supports pull-request creation and merging using both the console and CLI. AWS CodeCommit+1

14. Merge and synchronize branches

For team development, prefer merging through CodeCommit after the required reviews and approvals.

After the merge:

git switch main
git pull --ff-only origin main

For a repository without review restrictions, a local merge is also possible:

git switch main
git merge feature/add-readme
git push origin main

However, direct local merges and pushes can bypass pull-request approval requirements. Use IAM controls to restrict direct pushes to protected branches in team repositories. AWS CodeCommit

15. View commit history and manage versions

Display the recent commits:

git log --oneline -10

Display the branch graph:

git log --oneline --graph --decorate --all

Inspect one commit:

git show b067930

Show files changed in the last commit:

git diff-tree --no-commit-id --name-only -r HEAD

Compare commits:

git diff 63b86f6 b067930

Your two supplied commits were:

Commit ID	Message
63b86f6	First commit
b067930	adding bs

Create a version tag

git tag -a v1.0.0 -m "First release"
git push origin v1.0.0

List tags:

git tag -l

Revert a commit safely

If a commit has already been pushed and you want to undo it without rewriting shared history:

git revert COMMIT_ID
git push origin main

This creates a new commit that reverses the selected changes. Use a real commit ID after reviewing what the revert will affect.

16. Add a .gitignore file

A .gitignore file prevents unwanted local files from being included in future Git commits.

For example:

cat > .gitignore <<'EOF'
.DS_Store
.env
.env.*
!.env.example
node_modules/
vendor/
.idea/
.vscode/
*.log
EOF

Commit it:

git add .gitignore
git commit -m "Add gitignore"
git push origin main

Do not commit passwords, access keys, SSH private keys or other secrets. .gitignore does not remove files that Git is already tracking.

17. Integrate AWS CodeBuild

You already added:

buildspec.yaml

One important point: AWS CodeBuild expects buildspec.yml by default, not buildspec.yaml.

You can either rename the file or configure CodeBuild explicitly to use your existing filename. AWS CodeBuild

Step 17.1 — Rename your existing buildspec

From your demo1 directory:

git mv buildspec.yaml buildspec.yml

git add --all
git commit -m "Use default CodeBuild buildspec filename"
git push origin main

This preserves your existing 21-line build specification.

Step 17.2 — Understand a basic buildspec

For a separate simple demonstration, this is a working example of a buildspec.yml file. Do not overwrite your existing buildspec unless you intend to replace its commands.

version: 0.2

phases:
  install:
    commands:
      - echo "Install phase started"

  pre_build:
    commands:
      - echo "Pre-build checks started"
      - test -f demo.txt

  build:
    commands:
      - echo "Building the application"
      - cat demo.txt

  post_build:
    commands:
      - echo "Build completed successfully"

The stages execute as follows:

Phase	Purpose
install	Install dependencies and tools
pre_build	Run checks and preparation
build	Compile, test or package the application
post_build	Perform final processing

Step 17.3 — Create a CodeBuild project

Open the AWS CodeBuild Console.

Choose Create build project and configure:

Setting	Value
Project name	demo1-build
Source provider	AWS CodeCommit
Repository	demo1
Source branch	main
Environment	Managed Linux
Runtime image	Current supported standard image
Compute	Small suitable compute option
Service role	New least-privilege CodeBuild role
Buildspec	buildspec.yml
Logs	CloudWatch Logs

Create the project and select Start build.

Once a build starts, CodeBuild retrieves the source, processes your buildspec and shows command execution logs.

If you keep the filename buildspec.yaml, set that exact path under Buildspec name instead. AWS CodeBuild+1

18. Connect CodeCommit with CodePipeline

AWS CodePipeline can orchestrate the steps from source changes through builds and deployments.

CodeCommitSource

CodeBuildBuild & Test

DeployOptional

For a basic pipeline:

1. Open AWS CodePipeline → Create pipeline.
2. Enter a pipeline name, such as demo1-pipeline.
3. Configure the source provider as AWS CodeCommit.
4. Select demo1 and branch main.
5. Configure a source change trigger, where available, so new commits start a pipeline.
6. Configure the build stage to use your demo1-build project.
7. Add an optional deployment stage, such as ECS, EC2 or another supported target.
8. Configure the required service role permissions and create the pipeline.

Once configured correctly, a push to main can initiate an automated build and deployment workflow.

19. Troubleshooting common AWS CodeCommit errors

Error	Likely cause	Solution
Unrecognized public key encoding	Unsupported key type or invalid formatting	Generate RSA 2048/4096 and upload its .pub contents
Permission denied (publickey)	Wrong SSH Key ID, wrong private key or inactive IAM SSH credential	Check ~/.ssh/config, IAM key status and SSH debug output
Repository does not exist	Wrong name, AWS account or Region	Check repository name, Region and AWS account
Access denied	Missing IAM permission	Review GitPull, GitPush or required API permissions
non-fast-forward	Remote contains commits absent locally	Fetch/pull and integrate changes before pushing
nothing to commit	No staged changes to record	Check git status
buildspec not found	Wrong buildspec filename or location	Use buildspec.yml or configure the alternate path
fatal: not a git repository	Working outside a Git repository	Run cd demo1 or locate the repository root
command not found: ks	ks is not a standard shell command	Use ls to list files

For SSH failures, this is the most useful diagnostic:

ssh -vT git-codecommit.ap-southeast-2.amazonaws.com

Look for the SSH username, offered public key and authentication result. AWS documents several causes of public-key authentication failures. AWS CodeCommit

20. Master Git command cheat sheet

Operation	Command
Clone	git clone <SSH-URL>
Check status	git status
Add one file	git add filename
Add all	git add --all
Commit	git commit -m "message"
Push	git push origin main
Pull	git pull --ff-only origin main
Fetch	git fetch origin
Show commits	git log --oneline
Show branches	git branch -a
Create branch	git switch -c feature/test
Switch branch	git switch main
Push a branch	git push -u origin feature/test
Merge branch	git merge feature/test
Delete local branch	git branch -d feature/test
View remote	git remote -v
View differences	git diff
Show last commit	git show HEAD
Create tag	git tag -a v1.0.0 -m "Release"
Push tags	git push origin --tags

21. Recommended repository structure

For a small application integrated with CodeBuild, a useful structure is:

demo1/
├── .gitignore
├── README.md
├── buildspec.yml
├── demo.txt
├── src/
│   └── application-code
├── tests/
│   └── application-tests
├── scripts/
│   └── build.sh
└── docs/
    └── setup.md

For team development, a simple branch strategy is to use main for reviewed stable code, feature/* for new work, bugfix/* for fixes and release/* when you need a release preparation branch.

22. Complete daily workflow

Once your SSH connection and repository are configured, most daily development comes down to these commands:

# 1. Enter repository
cd ~/aws/demo1

# 2. Switch to main and get the latest code
git switch main
git pull --ff-only origin main

# 3. Create a feature branch
git switch -c feature/new-change

# 4. Make a change
echo "New change" >> demo.txt

# 5. Review changes
git status
git diff

# 6. Stage and commit
git add --all
git commit -m "Update demo file"

# 7. Push feature branch
git push -u origin feature/new-change

Then create a pull request in CodeCommit, review and merge it.

After merging:

git switch main
git pull --ff-only origin main

# Delete local feature branch
git branch -d feature/new-change

Your workflow is now:

Create repository → Configure IAM/SSH → Clone → Edit → Stage → Commit → Push → Pull request → Merge → Build → Deploy

That covers the full source-control lifecycle you can practice with your existing AWS CodeCommit demo1 repository.