Integration Guide

aws codecommit logo AWS CodeCommit Integration Jira Server

AWS CodeCommit is a git host service by Amazon Web Services to store and manage source code, related files and private Git repositories in the cloud.

helpful tips
You can use the AWS CLI or the AWS CodeCommit console to track and manage your repositories.

Required Permissions Important

note
Before performing an AWS CodeCommit integration, make sure to configure the recommended permissions.

The permissions detailed in the connect/autoconnect wizard are necessary for specific features to work.

We recommend that the following AWS IAM policies are configured beforehand based on what features that will be used:

Configure AWSCodeCommitReadOnly IAM policy for basic features:
Feature Required Permission
show commits, process smart commits, show branches codecommit:ListRepositories
codecommit:GitPull
show pull requests codecommit:ListPullRequests
codecommit:GetPullRequest
Configure AWSCodeCommitPowerUser IAM policy for all features:
Feature Required Permission
create pull request codecommit:CreatePullRequest
create branch codecommit:CreateBranch
delete branch codecommit:DeleteBranch
configure webhooks automatically codecommit:GetRepositoryTriggers
codecommit:PutRepositoryTriggers
sns:CreateTopic
sns:DeleteTopic
sns:Subscribe

Webhooks/Triggers Recommended

CodeCommit doesn't have webhooks but it has SNS triggers requiring a subscription confirmation.

note
For webhooks to work automatically, the IAM user used to setup the connection must have the "configure webhooks automatically" permissions.  If permissions has not been set, the repositories are connected but no webhooks are created.
note
While the new UI is not fully functional in AWS CodeCommits, users are required to create triggers via the old UI or with the API.
note
Shorthand:
With an existing AWS CC repository, enable triggers then create an SNS topic and subscribe to that topic.

For more information on Amazon SNS, see Amazon SNS: Getting Started.

Connecting to AWS CodeCommit via Auto-Connect Recommended

This process requires an AWS account with existing CodeCommit repositories.

To connect your repository to Jira thru the Git Integration for Jira Server add-on, open the Connect to Git Repository wizard:

  1. On the Jira navbar, click Git .
  2. Select Manage Git Repositories.
  3. On the following screen, we recommend to use the Auto-connect integration panel for automatic integration of git repositories.
  4. Git for Jira Server Auto-Connect panel Click the AWS CodeCommit icon.
  5. The Connect wizard screen is displayed:
  6. Auto-Connect wizard credentials screen Select the Region where the CodeCommit repositories reside then enter credentials for the Access key ID and Secret access key.
    Click Connect to continue.
  7. On the following screen, Git Integration for Jira add-on will read all available repositories from your AWS CodeCommit account. Click Import repositories.
    Repositories of the logged-in AWS CodeCommit user can be automatically connected to Jira Server. Repositories that are added or removed from AWS CodeCommit will be likewise connected or disconnected from Jira Server.
  8. After the import process, the Settings dialog is displayed:
  9. jira server connect Settings dialog
    • On the Integration Settings, setting the Require User PAT option to ON, will require users to provide PAT specific for branch and pull requests creation/deletion (via the developer panel open in new tab on the Jira issue page). For more information on this feature, see Integration Settings: Require User PAT icons.
    • Set Smart Commits open in new tab and Repository Browser open in new tab to enable/disable these features.
    • Set Project Permissions according to your organization's project association rules.
  10. Click Finish.

Tracked Folder/Repositories

The Git Integration for Jira Server add-on supports tracked folders for AWS CodeCommit git repositories. The connected git host is scanned for existing repository folders.  The found repositories can then be added to the Git Repositories configuration.

There are two ways to configure the git repository connection using tracked folders with Git for Jira Server:

  • connect via Auto-connect integration panel > AWS CodeCommit, or
  • connect via Connect to Git Repository dropdown > AWS CodeCommit.

If the connected git host has newly added repositories, the Git add-on will automatically add them to the git repositories configuration on the next reindex.  For the deleted git repositories, these will be removed from the Git add-on repositories configuration on the next reindex.

Manually Connect via HTTP/HTTPS

Connect a single AWS CodeCommit repository manually to Jira via HTTP/HTTPS connection.

  1. Use the host HTTP/HTTPS URL of your AWS CodeCommit repository.  For example, http://git-codecommit.us-east-1.amazonaws.com/v1/repos/test-repo and paste it on the Connect to Git Repository screen.
  2. Git for Jira Server connect to AWS CodeCommit screen
  3. On the Authentication screen, enter the Access Key ID as the username then the Secret Access Key as the password.
  4. Git for Jira Server - Connect to Git Repository - AWS CodeCommit authentication screen
  5. Click Connect.
  6. On the Permissions dialog, set Repository Browser and Project Association permissions, if required.  Click Next.
  7. Click Finish.

Manually Connect via SSH

Connect a single AWS CodeCommit repository manually to Jira via SSH connection.

SSH connections are handled automatically if the PUBLIC KEY was added in the AWS IAM console and the associated PRIVATE KEY was added/uploaded on the Jira side (Git Integration for Jira > SSH Keys > Add SSH Key).

If authentication issues are encountered during connecting an AWS repository to Jira, modify the original URL by inserting the SSH Key ID as the username.  The SSH Key ID is an alphanumeric sequence provided by AWS IAM when importing a PUBLIC KEY for a particular user account in IAM.

For example, the original URL is:

ssh://git-codecommit.us-east-1.amazonaws.com/v1/repos/test-repo

If the SSH Key ID 1a2b3c4d5e is applied to the original SSH URL, the resulting URL would be:

ssh://1a2b3c4d5e@git-codecommit.us-east-1.amazonaws.com/v1/repos/test-repo

The modified URL can now be used as a valid repository URL via Git Integration for Jira > Connect to Git Repository.

Working with Branches and Pull Requests Jira Server

note
This section requires the necessary permissions for all features.
  1. On your Jira Server, open a Jira issue.  On the Jira developer panel under Git Source Code, click Create Branch.
  2. The following dialog is displayed:
  3. Jira server issue page create branch dialog
    • Select a Repository from the list.
    • If there are several repositories with the same name, the listed GitLab repositories will have their names attached with a GitLab owner name.  For example, johnsmith/second-webhook-test-repo.
    • Choose a Base branch.
    • Enter a Branch name or leave it as is (recommended).
    If the Require User PAT option icons  is enabled in the Integration Settings and a user PAT isn't configured yet for the selected repository via Repository Browser, the following dialog is displayed instead: jira server issue create branch dlg PAT required
    • Click the link label to setup the PAT.  This will show the Repository Browser listing connected git repositories.
    • jira server repository browser enter user PAT
    • Click the  icons  icon to setup a PAT for the selected repository.  Paste a valid PAT of the current user to proceed.  Invalid PATs will fail the branch creation process.
    • Click  icons  to use this PAT and save it to the current user profile. Click  icons   to cancel setting up PAT for this repository.
    • After the above steps have been taken, the users will be able to proceed with branch creation.
  4. Click Create Branch.  The newly-created branch is now listed in the developer panel under Branches.

Perform a commit to the newly-created branch to be ready for merge.

Pull Request

The pull request feature works the same as merge request.

To create a pull request and pull it to the main source (master):

  1. On your Jira Server, open the Jira issue where your previously created a branch.
  2. On the developer panel under Git Source Code, click Create pull request.
  3. The following dialog is displayed:
  4. Jira issue page create pull request dialog
    • Select Repository from the list.
    • If there are several repositories with the same name, the listed AWS CodeCommit repositories will have their names attached with an AWS CodeCommit owner name.  For example, johnsmith/second-webhook-test-repo.
    • Choose the newly-created branch as the Source branch.
    • Set master as the Target branch.
    • Enter a descriptive title or leave it as is (recommended).

    If the Require User PAT option icons is enabled and a user PAT isn't configured yet for the selected repository via Repository Browser, the dialog below is displayed instead:

    jira server issue page create pat dialog requiring to setup pat

    If an invalid PAT was configured for the selected repository, the pull request creation process will fail.

  5. Click Create to create the pull request.

The pull request is listed on the developer panel of the Jira issue page.

The pull request is also ready for approval by the reviewers in your AWS CodeCommit web portal.