Step 1: Create the project and create your GitHub repository
In this step, use the console to create your project and create a connection to your new GitHub
repository. To access your GitHub repository, you create a connection resource that AWS CodeStar uses to manage authorization with GitHub. When the project is created, its additional resources are provisioned for you.
1. Sign in to the AWS Management Console, and then open the AWS CodeStar console at https://
console.aws.amazon.com/codestar/.
Step 1: Create the project and create your GitHub repository
2. Choose the AWS Region where you want to create the project and its resources.
3. On the AWS CodeStar page, choose Create project.
4. On the Choose a project template page, select the Web application, Node.js, and Amazon EC2 check boxes. Then choose from the templates available for that set of options.
For more information, see AWS CodeStar Project Templates (p. 37).
5. Choose Next.
6. For Project name, enter a name for the project (for example, MyTeamProject). If you use a different name, be sure to use it throughout this tutorial.
7. Under Project repository, choose GitHub.
8. If you chose GitHub, you will need to choose or create a connection resource. If you have an existing connection, choose it in the search field. Otherwise, you will create a new connection here. Choose Connect to GitHub.
The Create a connection page displays.
NoteTo create a connection, you must have a GitHub account. If you are creating a connection for an organization, you must be the organization owner.
a. Under Create GitHub App connection, in Connection name, enter a name for your connection.
Choose Connect to GitHub.
The Connect to GitHub page displays and shows the GitHub Apps field.
b. Under GitHub Apps, choose an app installation or choose Install a new app to create one.
NoteYou install one app for all of your connections to a particular provider. If you have already installed the AWS Connector for GitHub app, choose it and skip this step.
c. On the Install AWS Connector for GitHub page, choose the account where you want to install the app.
NoteIf you previously installed the app, you can choose Configure to proceed to a
modification page for your app installation, or you can use the back button to return to the console.
d. If the Confirm password to continue page is displayed, enter your GitHub password, and then choose Sign in.
e. On the Install AWS Connector for GitHub page, leave the defaults, and choose Install.
f. On the Connect to GitHub page, the installation ID for your new installation appears in GitHub Apps.
After the connection is successfully created, in the CodeStar create project page, the message Ready to connect displays.
Step 1: Create the project and create your GitHub repository
NoteYou can view your connection under Settings in the Developer Tools console. For more information, see Getting started with connections.
g. For Repository owner, choose the GitHub organization or your personal GitHub account.
h. For Repository name, accept the default GitHub repository name, or enter a different one.
i. Choose Public or Private.
Note
If you want to use AWS Cloud9 as your development environment, you must choose a public repository.
j. (Optional) For Repository description, enter a description for the GitHub repository.
9. Configure your Amazon EC2 instances in Amazon EC2 Configuration 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.
In Key pair, choose the Amazon EC2 key pair you created in Step 4: Create an Amazon EC2 Key Pair for AWS CodeStar Projects (p. 3). Select I acknowledge that I have access to the private key file.
10. Choose Next.
11. Review the resources and configuration details.
Step 2: View your source code
12. Choose Next or Create project. (The displayed choice depends on your project template.) Allow a few minutes while your project is created.
13. After your project is created, choose the link under Application endpoints to view your web application.
Step 2: View your source code
In this step, you view your source code and the tools you can use for your source repository.
1. In the navigation bar for your project, choose Repository.
To view a list of commits in GitHub, choose View commits. This opens your commit history in GitHub.
To view issues, choose the Issues tab for your project. To create a new issue in GitHub, choose Create GitHub issue. This opens your repository issue form in GitHub.
2. Under the Repository tab, choose the link under Repository name, and your project's repository opens in a new tab or window. This repository contains the source code for your project.
Step 3: Create a GitHub Pull Request
In this step, you make a minor change to your source code and create a pull request.
1. In GitHub, create a new feature branch in your repository. Choose the main branch drop-down field and enter a new branch in the field named feature-branch. Choose Create new branch. The branch is created and checked out for you.
2. In GitHub, make a change in the feature-branch branch. Open the public folder and open the index.html file.
3. In the AWS CodeStar console, under Pull requests, to create a pull request in GitHub, choose Create pull request. This opens your repository pull request form in GitHub. In GitHub, choose the pencil icon to edit the file.
After Congratulations!, add the string Well done, <name>! and replace <name> with your name. Choose Commit changes. The change is committed to your feature branch.
4. In the AWS CodeStar console, choose your project. Choose the Repository tab. Under Pull requests, choose Create pull request.
The form opens in GitHub. Leave the main branch in the base branch. For Compare to, choose your feature branch. View the diff.
5. In GitHub, choose Create pull request. A pull request named Update index.html is created.
6. In the AWS CodeStar console, view the new pull request. Choose Merge changes to commit the changes to the repository and merge the pull request with the main branch of your repository.
7. Return to the project in AWS CodeStar and check the Pipeline page. You should now see the pipeline deploying.
8. After your project is created, choose the link under Application endpoints to view your web application.
AWS CodeStar Project Files and Resources
AWS CodeStar Project Templates
AWS CodeStar project templates allow you to start with a sample application and deploy it using AWS resources created to support your development project. When you choose an AWS CodeStar project template, the application type, programming language, and compute platform are provisioned for you.
After you create projects with web applications, web services, Alexa skills, and static web pages, you can replace the sample application with your own.
After AWS CodeStar creates your project, you can modify the AWS resources that support delivery of your application. AWS CodeStar works with AWS CloudFormation to allow you to use code to create support services and servers/serverless platforms in the cloud. AWS CloudFormation allows you to model your entire infrastructure in a text file.
Topics
• AWS CodeStar Project Files and Resources (p. 37)
• Get Started: Choose a Project Template (p. 38)
• How to Make Changes to Your AWS CodeStar Project (p. 39)
AWS CodeStar Project Files and Resources
An AWS CodeStar project is a combination of source code and the resources created to deploy the code. The collection of resources that help you build, release, and deploy your code are called toolchain resources. At project creation, an AWS CloudFormation template provisions your toolchain resources in a continuous integration/continuous deployment (CI/CD) pipeline.
You can use AWS CodeStar to create projects in two ways, depending on your experience level with AWS resource creation:
• When you use the console to create a project, AWS CodeStar creates your toolchain resources, including your repository, and populates your repository with sample application code and project files. Use the console to quickly set up sample projects based on a set of preconfigured project options.
• When you use the CLI to create a project, you provide the AWS CloudFormation template that creates your toolchain resources and the application source code. Use the CLI to allow AWS CodeStar to create your project from your template and then populate your repository with your sample code.
An AWS CodeStar project provides a single point of management. You can use the Create project wizard in the console to set up a sample project. You can then use it as a collaboration platform for managing permissions and resources for your team. For more information, see What Is AWS CodeStar? (p. 1). When you use the console to create a project, your source code is provided as sample code, and your CI/CD toolchain resources are created for you
When you create a project in the console, AWS CodeStar provisions the following resources:
• A code repository in GitHub or CodeCommit.
• In the project repository, a README.md file that provides details of files and directories.
• In the project repository, a template.yml file that stores the definition for your application's runtime stack. You use this file to add or modify project resources that are not toolchain resources, such as AWS resources used for notifications, database support, monitoring, and tracing.
Get Started: Choose a Project Template
• AWS services and resources created in connection with your pipeline, such as the Amazon S3 artifact bucket, Amazon CloudWatch Events, and related service roles.
• A working sample application with full source code and a public HTTP endpoint.
• An AWS compute resource, based on the AWS CodeStar project template type:
• A Lambda function.
• An Amazon EC2 instance.
• An AWS Elastic Beanstalk environment.
• Starting December 6, 2018 PDT:
• A permissions boundary, which is a specialized IAM policy for controlling access to project
resources. The permissions boundary is attached by default to roles in the sample project. For more information, see IAM Permissions Boundary for Worker Roles (p. 114).
• An AWS CloudFormation IAM role for creating project resources using AWS CloudFormation that includes permissions for all AWS CloudFormation supported resources, including IAM roles.
• A toolchain IAM role.
• Execution roles for Lambda defined in the application stack, which you can modify.
• Before December 6, 2018 PDT:
• An AWS CloudFormation IAM role for creating project resources with support for a limited set of AWS CloudFormation resources.
• An IAM role for creating a CodePipeline resource.
• An IAM role for creating an CodeBuild resource.
• An IAM role for creating a CodeDeploy resource, if applicable to your project type.
• An IAM role for creating the Amazon EC2 web app, if applicable to your project type.
• An IAM role for creating a CloudWatch Events resource.
• An execution role for Lambda that is dynamically modified to include a partial set of resources.
The project includes detail pages that show status and contain links to team management, links to setup instructions for IDEs or your repository, and a commit history of source code changes in the repository.
You can also select tools for connecting to external issue tracking tools, such as Jira.
Get Started: Choose a Project Template
When you choose an AWS CodeStar project in the console, you are choosing from a set of preconfigured options with sample code and resources to get you started quickly. These options are called project templates. Each AWS CodeStar project template consists of a programming language, application type, and compute platform. The combination you select determines the project template.
Choose a Template Compute Platform
Each template configures one of the following compute platform types:
• When you choose an AWS Elastic Beanstalk project, you deploy to an AWS Elastic Beanstalk environment on Amazon Elastic Compute Cloud instances in the cloud.
• When you choose an Amazon EC2 project, AWS CodeStar creates Linux EC2 instances to host your application in the cloud. Your project team members can access the instances, and your team uses the key pair you provide to SSH into your Amazon EC2 instances. AWS CodeStar also has a managed SSH that uses team member permissions to manage key pair connections.
• When you choose AWS Lambda, AWS CodeStar creates a serverless environment accessed through Amazon API Gateway, with no instances or servers to maintain.
Choose a Template Application Type
Choose a Template Application Type
Each template configures one of the following application types:
• Web service
A web service is used for tasks that run in the background, such as calling APIs. After AWS CodeStar creates your sample web service project, you can choose the endpoint URL to see Hello World output, but the primary use of this application type is not as a user interface (UI). The AWS CodeStar project templates in this category support development in Ruby, Java, ASP.NET, PHP, Node.js, and more.
• Web application
A web application features a UI. After AWS CodeStar creates your sample web application project, you can choose the endpoint URL to see an interactive web application. The AWS CodeStar project templates in this category support development in Ruby, Java, ASP.NET, PHP, Node.js, and more.
• Static web page
Choose this template if you want a project for an HTML website. The AWS CodeStar project templates in this category support development in HTML5.
• Alexa skill
Choose this template if you want a project for an Alexa skill with an AWS Lambda function. When you create the skill project, AWS CodeStar returns an Amazon Resource Name (ARN) that you can use as a service endpoint. For more information, see Host a Custom Skill as an AWS Lambda Function.
Note
Lambda functions for Alexa skills are supported in the US East (N. Virginia), US West (Oregon), EU (Ireland), and Asia Pacific (Tokyo) Regions only.
• Config rule
Choose this template if you want a project for an AWS Config rule that lets you automate rules across AWS resources in your account. The function returns an ARN that you can use as a service endpoint for your rule.
Choose a Template Programming Language
When you choose a project template, you select a programming language, such as Ruby, Java, ASP.NET, PHP, Node.js, and more.
How to Make Changes to Your AWS CodeStar Project
You can update your project by modifying:
• Sample code and programming language resources for your application.
• Resources that make up the infrastructure where your application is stored and deployed (operating systems, support applications and services, deployment parameters, and the cloud compute platform).
You can modify application resources in the template.yml file. This is the AWS CloudFormation file that models your application's runtime environment.
Change Application Source Code and Push Changes
NoteIf you are working with an Alexa Skills AWS CodeStar project, you cannot make changes to the skill outside of the AWS CodeStar source repository (CodeCommit or GitHub). If you edit the skill in the Alexa developer portal, the change might not be visible in the source repository and the two versions will be out of sync.
Change Application Source Code and Push Changes
To modify sample source code, scripts, and other application source files, edit files in your source repository by:
• Using the Edit mode in CodeCommit or GitHub.
• Opening the project in an IDE, such as AWS Cloud9.
• Cloning the repository locally and then committing and pushing your changes. For information, see Step 4: Commit a Change (p. 10).
Change Application Resources with the Template.yml File
Instead of manually modifying an infrastructure resource, use AWS CloudFormation to model and deploy your application's runtime resources.
You can modify or add an application resource, such as a Lambda function, in your runtime stack by editing the template.yml file in your project repository. You can add any resource that is available as an AWS CloudFormation resource.
To change the code or settings of an AWS Lambda function, see Add a Resource to a Project (p. 64).
Modify the template.yml file in your project's repository to add the type of AWS CloudFormation resources that are application resources. When you add an application resource to the Resources section of the template.yml file, AWS CloudFormation and AWS CodeStar create the resource for you. For a list of AWS CloudFormation resources and their required properties, see AWS Resource Types Reference. For more information, see this example in Step 1: Edit the CloudFormation Worker Role in IAM (p. 65).
AWS CodeStar allows you to implement best practices by configuring and modeling your application's runtime environment.
How to Manage Permissions to Change Application Resources
When you use AWS CloudFormation to add runtime application resources, such as a Lambda function, the AWS CloudFormation worker role can use the permissions it already has. For some runtime application resources, you must manually adjust the AWS CloudFormation worker role's permissions before you edit the template.yml file.
For an example of changing the AWS CloudFormation worker role's permissions, see Step 5: Add Resource Permissions with an Inline Policy (p. 67).
Security Best Practices for AWS CodeStar Resources
AWS CodeStar Best Practices
AWS CodeStar is integrated with a number of products and services. The following sections describe best practices for AWS CodeStar and these related products and services.
Topics
• Security Best Practices for AWS CodeStar Resources (p. 41)
• Best Practices for Setting Versions for Dependencies (p. 41)
• Monitoring and Logging Best Practices for AWS CodeStar Resources (p. 41)
Security Best Practices for AWS CodeStar Resources
You should regularly apply patches and review security best practices for the dependencies used by your application. Use these security best practices to update your sample code and maintain your project in a production environment:
• Track ongoing security announcements and updates for your framework.
• Before you deploy your project, follow the best practices developed for your framework.
• Review dependencies for your framework on a regular basis and update as needed.
• Each AWS CodeStar template contains configuration instructions for your programming language. See the README.md file in your project's source repository.
• As a best practice for isolating project resources, manage least-privilege access to AWS resources using a multi-account strategy as introduced in Security in AWS CodeStar (p. 99).
Best Practices for Setting Versions for Dependencies
The sample source code in your AWS CodeStar project uses dependencies that are listed in the
package.json file in your source repository. As a best practice, always set your dependencies to point to a specific version. This is known as pinning the version. We do not recommend that you set the version to latest because that can introduce changes that might break your application without notice.
Monitoring and Logging Best Practices for AWS CodeStar Resources
You can use logging features in AWS to determine the actions users have taken in your account and the resources that were used. The log files show:
• The time and date of actions.
• The source IP address for an action.
Monitoring and Logging Best Practices for AWS CodeStar Resources
• Which actions failed due to inadequate permissions.
AWS CloudTrail can be used to log AWS API calls and related events made by or on behalf of an AWS account. For more information, see Logging AWS CodeStar API Calls with AWS CloudTrail (p. 137).
Working with Projects in AWS CodeStar
When you use an AWS CodeStar project template, you can quickly create a project that is already configured with the resources you need, including:
• Source repository
• Build environment
• Deployment and hosting resources
• Programming language
The template even includes sample source code so you can start working with your project right away.
After you have a project, you can add or remove resources, customize your project dashboard, and monitor progress.
The following diagram shows a basic workflow in an AWS CodeStar project.
The following diagram shows a basic workflow in an AWS CodeStar project.