AWS CodeStar
User Guide

Getting Started with AWS CodeStar

In this tutorial, you use AWS CodeStar to create a web application. This project includes sample code in a source repository, a continuous deployment toolchain, and a project dashboard where you can view and monitor your project.

By following the steps, you:

  • Create a project in AWS CodeStar.

  • Explore the project.

  • Commit a code change.

  • See your code change deployed automatically.

  • Add other people to work on your project.

  • Clean up project resources when they're no longer needed.

Note

If you haven't already, first complete the steps in Setting Up AWS CodeStar, including Step 2: Create the AWS CodeStar Service Role. You must be signed in with an account that is an administrative user in IAM. To create a project, you must sign in to the AWS Management Console using an IAM user that has the AWSCodeStarFullAccess policy.

Step 1: Create an AWS CodeStar Project

In this step, you create a JavaScript (Node.js) software development project for a web application. You use an AWS CodeStar project template to create the project.

Note

The AWS CodeStar project template used in this tutorial uses the following options:

  • Application category: Web application

  • Programming language: Node.js

  • AWS Service: Amazon EC2

If you choose other options, your experience might not match what's documented in this tutorial.

To create a project in AWS CodeStar

  1. Sign in to the AWS Management Console, and then open the AWS CodeStar console at https://console.aws.amazon.com/codestar/.

    Make sure that you are signed in to the AWS Region where you want to create the project and its resources. For example, to create a project in US East (Ohio), make sure you have selected that AWS Region. For information about AWS Regions where AWS CodeStar is available, see Regions and Endpoints in the AWS General Reference .

    
                Choosing the region where you want to create the project in AWS CodeStar
  2. On the AWS CodeStar page, choose Create a new project. (If you are the first user to create a project, choose Start a project.)

  3. On the Choose a project template page, choose the project type from the list of AWS CodeStar project templates. You can use the filter bar to narrow your choices. For example, for a web application project written in Node.js to be deployed to Amazon EC2 instances, select the Web application, Node.js, and Amazon EC2 check boxes. Then choose from the templates available for that set of options.

    
                Using the filter bar to help choose the project template

    For more information, see AWS CodeStar Project Templates.

  4. In Project name, enter a name for the project, such as My First Project. The ID for the project is derived from this project name, but is limited to 15 characters.

    For example, the default ID for a project named My First Project is my-first-projec. This project ID is the basis for the names of all resources associated with the project. AWS CodeStar uses this project ID as part of the URL for your code repository and for the names of related security access roles and policies in IAM. After the project is created, the project ID cannot be changed. To edit the project ID before you create the project, choose Edit.

    For information about the limits on project names and project IDs, see Limits in AWS CodeStar.

    Note

    Project IDs must be unique for your AWS account in an AWS Region.

    
                Providing a name and ID for your project in AWS CodeStar
  5. Choose the repository provider, AWS CodeCommit or GitHub.

  6. If you chose AWS CodeCommit, for Repository name, accept the default AWS CodeCommit repository name, or enter a different one. Then skip ahead to step 8.

  7. If you chose GitHub, choose Connect with GitHub.

    1. If the Sign in to GitHub page is displayed, enter your GitHub user name or email address and password, and then choose Sign in.

      Note

      You must have a GitHub account to complete this page. For more information, see Join GitHub on the GitHub website.

    2. If the Two-factor authentication page is displayed, for Authentication code, enter the code that GitHub sends you, and then choose Verify.

    3. On the Authorize AWS CodeStar page, choose Authorize.

      Note

      When you choose Authorize, you allow AWS CodeStar to create a GitHub repository for your personal GitHub account, or for any GitHub organization where you have permissions. (A green check in Organization access is used to indicate permissions.)

      To add a GitHub organization to the Organization access list, follow the instructions in Inviting Users to Join Your Organization on the GitHub Help website. After you join the organization, refresh the Authorize AWS CodeStar page to see the organization in the list.

      To get permissions to authorize a GitHub organization that is in the list, but does not have a green check, choose Grant. If you see Request instead, choose it, and then follow the instructions in Approving OAuth Apps for Your Organization on the GitHub Help website. Refresh the Authorize AWS CodeStar page to see the Grant button.

    4. For Owner, choose the GitHub organization or your personal GitHub account.

    5. For Repository name, accept the default GitHub repository name, or enter a different one.

    6. Choose Public repository or Private repository.

      Note

      Depending on your GitHub account type, GitHub might not allow you to create a private repository. For more information, see GitHub Pricing on the GitHub website.

    7. (Optional) For Repository description, enter a description for the GitHub repository.

    
                Choosing GitHub repository settings for your project in AWS CodeStar
  8. Choose Next.

  9. Review the resources and configuration details. Choose Edit Amazon EC2 Configuration (where available) if your project is deployed to Amazon EC2 instances and you want to make changes. For example, you can choose from available instance types for your project.

    Note

    Different Amazon EC2 instance types provide different levels of computing power and might have different associated costs. For more information, see Amazon EC2 Instance Types and Amazon EC2 Pricing.

    If you have more than one virtual private cloud (VPC) or multiple subnets created in Amazon Virtual Private Cloud, you can also choose the VPC and subnet to use. However, if you choose an Amazon EC2 instance type that is not supported on dedicated instances, you cannot choose a VPC whose instance tenancy is set to Dedicated.

    For more information, see What Is Amazon VPC? and Dedicated Instance Basics.

  10. Leave the AWS CodeStar would like permission to administer AWS resources on your behalf check box selected. Otherwise, you cannot create a project. For more information about the service role, see AWS CodeStar Service Role Policy and Permissions.

    Choose Next or Create project. (The displayed choice depends on your project template.)

  11. In Choose an Amazon EC2 Key Pair, choose the Amazon EC2 key pair you created in Step 4: Create an Amazon EC2 Key Pair for AWS CodeStar Projects. Select I acknowledge that I have access to the private key file for this key pair, and then choose Create project.

  12. It might take a few minutes to create the project (including the repository). After your project has a repository, you can use the Set up tools page to configure access to it, or you can choose Skip and configure access later. After your project has been created, you can use the links on the Welcome tile to configure other items, such as your user profile in AWS CodeStar.

    
                The Welcome tile displayed after you create a project

Step 2: Add Display Information for Your AWS CodeStar User Profile

When you create a project, you're added to the project team as an owner. If this is the first time you've used AWS CodeStar, you are asked to provide:

  • Your display name to show to other users.

  • The email address to show to other users.

This information is used in your AWS CodeStar user profile. User profiles are not project-specific, but are limited to an AWS Region. You must create a user profile in each AWS Region in which you belong to projects. Each profile can contain different information, if you prefer.

Enter a user name and email address, and then choose Next.


                Adding user profile information as you create a project

Note

This user name and email address is used in your AWS CodeStar user profile. If your project uses resources outside of AWS (for example, a GitHub repository or issues in Atlassian JIRA), those resource providers might have their own user profiles, with different user names and email addresses. For more information, see the resource provider's documentation.

Step 3: View Your Project

Your AWS CodeStar project dashboard is where you and your team view the status of your project resources, including the latest commits to your project, the state of your continuous delivery pipeline, and the performance of your instances. This information is displayed on tiles that are dedicated to a resource. To see more information about any of these resources, choose the details link on the tile. The AWS service console opens on the details page for that resource.

You can change where each tile appears on your dashboard by dragging and dropping it to a new location. You can also use the ellipsis menu on each tile to remove that tile from the display. To add a tile, in the dashboard, choose Add tile.

In your new project, you see the following tiles:

  • The Welcome tile contains links to actions you might want to perform. Unlike other tiles, you cannot move this tile to another location, or add it back after closing it.

    
                        The Welcome tile displayed after you create a project
  • The Continuous deployment tile displays a summary view of the continuous delivery pipeline for your project. The pipeline deploys the web application code when there is a change in your repository. Because your project is new, the pipeline immediately starts deploying the sample code. You can see the processing and completion of each stage as your web application is deployed. For a deployment stage, choose Endpoint to view a link to the endpoint. (If you chose the project template suggested at the start of this tutorial, the endpoint is an Amazon EC2 instance.)

    You can also see if a stage has a problem or requires approval. To see details about the state of the pipeline, its stages and actions, or to add or edit a stage, choose AWS CodePipeline details.

    
                        Continuous deployment tile
  • The Application endpoints tile displays links to the endpoints where you can view your software. This is the same link you saw in the Continuous deployment tile. Choose the link to view your application or service.

    
                        Application endpoints tile
  • The Commit history tile displays the recent commit history of the repository. When you first create a project, the most recent commit is the one made by AWS CodeStar. This commit started running the sample code through the pipeline. When you make another commit, it appears in the history, too. That code change starts running through the pipeline automatically. To view the commits of a different branch, use the branch selector button. To view all commits or details about the commits or repository, choose AWS CodeCommit details (if the code is stored in AWS CodeCommit) or Open in GitHub (if the source code is stored in GitHub).

    
                        Commit history tile
  • The Application activity tile displays Amazon CloudWatch metrics for your project. For example, it displays the CPU utilization of any Amazon EC2 instances deployed to by AWS Elastic Beanstalk or AWS CodeDeploy resources in your pipeline. In projects that use AWS Lambda, it displays invocation and error metrics for the Lambda function. This information is displayed by the hour. If you used the suggested AWS CodeStar project template for this tutorial, you should see a noticeable spike in activity as your application is first deployed to those instances. You can refresh monitoring to see changes in your instance health, which can help you identify problems or the need for more resources.

    
                        Application activity tile

    Note

    If your AWS CodeStar project includes more than one metric, you can filter the display by choosing a metric in the tile.

  • The JIRA tile is for integrating your AWS CodeStar project with an Atlassian JIRA project. Configuring this tile makes it possible for you and your project team to track JIRA issues from the project dashboard. To configure this tile, choose Connect, and then follow the instructions.

    
                        Configured JIRA tile
  • There is also a Team wiki tile. You can customize the contents of this tile to store team notes, link to useful resources for your team project, provide samples, and so on. You customize this tile in the next step.

Step 4: Customize the Team Wiki Tile and the Project Dashboard

Each AWS CodeStar project includes a customizable team wiki tile that can be used for any purpose (for example, adding links to team resources or showing code snippets for a preferred development style). This tile supports both plain text and formatted content. In this step, you customize this tile to include a link to the AWS DevOps blog.

To customize the team wiki tile

  1. In the project dashboard, on the team wiki tile, choose the ellipsis menu, and then choose Edit.

  2. In Widget title, enter Team links. In Markdown content, add an item to the list and paste the following:

    [AWS DevOps Blog](https://aws.amazon.com/blogs/devops/)

    Choose Save.

  3. Choose the link on the tile to test it.

To customize your dashboard appearance

  1. Choose one of the tiles on the dashboard. Drag and drop it to a new position. You can rearrange dashboard tiles to put the most important information in the most visible position.

  2. To remove a tile, choose the ellipsis menu () on the tile, and then choose Remove from Dashboard.

  3. To add a tile, at the top of the dashboard, choose Add tile and then choose the tile to add. You can only have one of each kind of tile on your dashboard.

Step 5: Commit a Change

First, take a look at the sample code that was included in your project, and see what the application looks like. On the Application endpoints tile, choose the link to your endpoint. Your sample web application is displayed in a new window or browser tab. This is the project sample that AWS CodeStar built and deployed.

If you'd like to look at the code, in the navigation bar, choose Code. Your project's repository opens in a new tab or window. Read the contents of the repository's readme file (README.md), and browse the content of those files.

In this step, you make a change to the code and then push the change to your repository. You can do this in one of several ways:

  • If the project's code is stored in an AWS CodeCommit or GitHub repository, you can use AWS Cloud9 to work with the code directly from your web browser, without installing any tools. For more information, see Create an AWS Cloud9 Environment for a Project.

  • If the project's code is stored in an AWS CodeCommit repository, and you have Visual Studio or Eclipse installed, you can use the AWS Toolkit for Visual Studio or AWS Toolkit for Eclipse to more easily connect to the code. For more information, see Use an IDE with AWS CodeStar. If you don't have Visual Studio or Eclipse, install a Git client, and follow the instructions later in this step.

  • If the project's code is stored in a GitHub repository, you can use your IDE's tools for connecting to GitHub.

    • For Visual Studio, you can use a tools such as the GitHub Extension for Visual Studio. For more information, see the Overview page on the GitHub Extension for Visual Studio website and Getting Started with GitHub for Visual Studio on the GitHub website.

    • For Eclipse, you can use a tool such as EGit for Eclipse. For more information, see the EGit Documentation on the EGit website.

    • For other IDEs, consult your IDE's documentation.

  • For other types of code repositories, see the repository provider's documentation.

The following instructions show you how to make a minor change to the sample.

To set up your computer to commit changes (IAM user)

Note

In this procedure, we assume that your project's code is stored in an AWS CodeCommit repository. For other types of code repositories, see the repository provider's documentation, and then skip ahead to the next procedure, To clone the project repository and make a change.

If the code is stored in AWS CodeCommit and you are already using AWS CodeCommit or you used the AWS CodeStar console to create an AWS Cloud9 development environment for the project, you don't need more configuration. Skip ahead to the next procedure, To clone the project repository and make a change.

  1. Install Git on your local computer.

  2. Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/.

    Sign in as the IAM user who will use Git credentials for connections to your AWS CodeStar project repository in AWS CodeCommit.

  3. In the IAM console, in the navigation pane, choose Users, and from the list of users, choose your IAM user.

  4. On the user details page, choose the Security Credentials tab, and in HTTPS Git credentials for AWS CodeCommit, choose Generate.

    
                        Generating Git credentials in the IAM console

    Note

    You cannot choose your own user name or password for Git credentials. For more information, see Use Git Credentials and HTTPS with AWS CodeCommit.

  5. Copy the user name and password that IAM generated for you. You can choose Show and then copy and paste this information into a secure file on your local computer, or you can choose Download credentials to download this information as a .CSV file. You need this information to connect to AWS CodeCommit.

    
                        Downloading Git credentials from the IAM console

    After you have saved your credentials, choose Close.

    Important

    This is your only chance to save the user name and password. If you do not save them, you can copy the user name from the IAM console, but you cannot look up the password. You must reset the password and then save it.

To set up your computer to commit changes (federated user)

You can use the console to upload files to your repository, or you can use Git to connect from your local computer. If you are using federated access, follow these steps to use Git to connect to and clone your repository from your local computer.

Note

In this procedure, we assume that your project's code is stored in an AWS CodeCommit repository. For other types of code repositories, see the repository provider's documentation, and then skip ahead to the next procedure, To clone the project repository and make a change.

  1. Install Git on your local computer.

  2. Install the AWS CLI.

  3. Configure your temporary security credentials for a federated user. For information, see Temporary Access to AWS CodeCommit Repositories. Temporary credentials consist of:

    • AWS access key

    • AWS secret key

    • Session token

    For more information about temporary credentials, see Permissions for GetFederationToken.

  4. Connect to your repository using the AWS CLI credential helper. For information, see Setup Steps for HTTPS Connections to AWS CodeCommit Repositories on Linux, macOS, or Unix with the AWS CLI Credential Helper or Setup Steps for HTTPS Connections to AWS CodeCommit Repositories on Windows with the AWS CLI Credential Helper

  5. The following example shows how to connect to an AWS CodeCommit repository and push a commit to it.

Example: To clone the project repository and make a change

Note

This procedure shows how to clone the project's code repository to your computer, make a change to the project's index.html file, and then push your change to the remote repository. In this procedure, we assume that your project's code is stored in an AWS CodeCommit repository and that you're using a Git client from the command line. For other types of code repositories or tools, see the provider's documentation for how to clone the repository, change the file, and then push the code.

  1. If you used the AWS CodeStar console to create an AWS Cloud9 development environment for the project, open the development environment, and then skip to step 3 in this procedure. To open the development environment, see Open an AWS Cloud9 Environment for a Project.

    With your project open in the AWS CodeStar console, on the navigation bar, choose the Project gear icon, and then choose the Connect tools button. In Clone repository URL, choose the protocol for the connection type you have set up for AWS CodeCommit, and then copy the link. For example, if you followed the steps in the previous procedure to set up Git credentials for AWS CodeCommit, choose HTTPS.

  2. On your local computer, open a terminal or command line window and change directories to a temporary directory. Run the git clone command to clone the repository to your computer. Paste the link you copied. For example, for AWS CodeCommit using HTTPS:

    git clone https://git-codecommit.us-east-2.amazonaws.com/v1/repos/my-first-projec

    The first time you connect, you are prompted for the user name and password for the repository. For AWS CodeCommit, enter the Git credentials user name and password you downloaded in the previous procedure.

  3. Navigate to the clone directory on your computer and browse the contents.

  4. Open the index.html file and make a change to the file. For example, change the header text from <H1>Congratulations!</H1> to the following:

    <H1>I did it!</H1>

    Save the file.

  5. At the terminal or command prompt, add your changed file, and then commit and push your change:

    git add index.html git commit -m "Making my first change to the web app" git push
  6. On your project dashboard, view the changes in progress. You should see that the commit history for the repository is updated with your commit, including the commit message. You can also see the pipeline pick up your change to the repository and start building and deploying it. After your web application is deployed, you can use the links you added to the project information tile to view your change.

    Note

    If Failed is displayed for any of the pipeline stages, see the following for troubleshooting help:

Step 6: Add More Team Members

Every AWS CodeStar project is already configured with three AWS CodeStar roles. Each role provides its own level of access to the project and its resources:

  • Owner: Can add and remove team members, change the project dashboard, and delete the project.

  • Contributor: Can change the project dashboard and contribute code if the code is stored in AWS CodeCommit, but cannot add or remove team members or delete the project. This is the role you should choose for most team members in an AWS CodeStar project.

  • Viewer: Can view the project dashboard, project code if the code is stored in AWS CodeCommit, and the state of the project, but cannot move, add, or remove tiles from the project dashboard.

Important

If your project uses resources outside of AWS (for example, a GitHub repository or issues in Atlassian JIRA), access to those resources is controlled by the resource provider, not AWS CodeStar. For more information, see the resource provider's documentation.

Anyone who has access to an AWS CodeStar project might be able to use the AWS CodeStar console to access resources that are outside of AWS but are related to the project.

AWS CodeStar does not allow project team members to participate in any related AWS Cloud9 development environments for a project. To allow a team member to participate in a shared environment, see Share an AWS Cloud9 Environment with a Project Team Member.

For more information about teams and project roles, see Working with AWS CodeStar Teams.

To add a team member to an AWS CodeStar project (console)

  1. Open the AWS CodeStar console at https://console.aws.amazon.com/codestar/.

    Choose the project.

  2. In the navigation bar for the project, choose Team.

  3. On the Team members page, choose Add team member.

  4. In Choose user, do one of the following:

    • If an IAM user already exists for the person you want to add, choose the IAM user name from the list.

      Note

      Users who have already been added to another AWS CodeStar project appear in the AWS CodeStar users from other projects list.

      On the Add team member tab, in Project role, choose the AWS CodeStar role (Owner, Contributor, or Viewer) for this user. This is an AWS CodeStar project-level role that can only be changed by an owner of the project. When applied to an IAM user, the role provides all permissions required to access AWS CodeStar project resources. It applies policies required for creating and managing Git credentials for code stored in AWS CodeCommit in IAM or uploading Amazon EC2 SSH keys for the user in IAM.

      Important

      You cannot provide or change the display name or email information for an IAM user unless you are signed in to the console as that user. For more information, see Manage Display Information for Your AWS CodeStar User Profile .

      Choose Add.

      
                    Adding an existing IAM user to the team for a project
    • If an IAM user does not exist for the person you want to add to the project, choose Create new IAM user. Enter the IAM user name, AWS CodeStar display name, email address, and project role you want to apply to this new user, and then choose Create.

      
                    Creating a new IAM user to add to the team for a project

      You are redirected to the IAM console to confirm user creation. Choose Create user, save the password information for that new user, and then choose Close to return to the AWS CodeStar console. The user is added to the project with the role you chose.

    Note

    For ease of management, at least one user should be assigned the Owner role for the project.

  5. Send the new team member the following information:

    • Connection information for your AWS CodeStar project.

    • If the source code is stored in AWS CodeCommit, instructions for setting up access with Git credentials to the AWS CodeCommit repository from their local computers.

    • Information about how the user can manage their display name, email address, and public Amazon EC2 SSH key, as described in Working with Your AWS CodeStar User Profile .

    • One-time password and connection information, if the user is new to AWS and you created an IAM user for that person. The password expires the first time the user signs in. The user must choose a new password.

Step 7: Clean Up

Congratulations! You've finished the tutorial. If you don't want to continue to use this project and its resources, you should delete it to avoid possible continued charges to your AWS account.

To delete a project in AWS CodeStar

  1. Open the AWS CodeStar console at https://console.aws.amazon.com/codestar/.

  2. Find the project in the list, and from the ellipsis (), choose Delete.

    Or, open the project, and in the navigation pane, choose Project. On the project details page, choose Delete project.

  3. In Type the following project ID to confirm, enter the ID of the project, and then choose Delete.

    Deleting a project can take several minutes. After it's deleted, the project no longer appears in the list of projects in the AWS CodeStar console.

    Important

    By default, when you delete a project, all resources listed under Project resources are deleted. If you clear the check box, the project resources are retained. For more information, go here.

    If your project uses resources outside of AWS (for example, a GitHub repository or issues in Atlassian JIRA), those resources are not deleted, even if you select the check box.

    Your project cannot be deleted if any AWS CodeStar managed policies have been manually attached to roles that are not IAM users. If you have attached your project's managed policies to a federated user's role, you must detach the policy before you can delete the project. For more information, see Detach an AWS CodeStar Managed Policy from the Federated User's Role.

Step 8: Get Your Project Ready for a Production Environment

After you have created your project, you are ready to create, test, and deploy code. Review the following considerations for maintaining your project in a production environment:

  • Regularly apply patches and review security best practices for the dependencies used by your application. For more information, see Security Best Practices for AWS CodeStar Resources.

  • Regularly monitor the environment settings suggested by the programming language for your project.

Next Steps

Here are some other resources to help you learn about AWS CodeStar: