Menu
AWS CodePipeline
User Guide (API Version 2015-07-09)

Simple Pipeline Walkthrough (Amazon S3 Bucket)

The easiest way to get started with AWS CodePipeline is to use the Create Pipeline wizard in the AWS CodePipeline console to create a simple pipeline.

In this walkthrough, you will create a two-stage pipeline that uses a versioned Amazon S3 bucket and AWS CodeDeploy to release a sample application. After you create this simple pipeline, you will add an additional stage and then disable and enable the transition between stages.

Not what you're looking for? To create a simple pipeline using an AWS CodeCommit branch as a code repository, see Simple Pipeline Walkthrough (AWS CodeCommit Repository).

Before you begin this walkthrough, you should complete the prerequisites in Setting Up.

Step 1: Create an Amazon S3 Bucket for Your Application

You can store your source files or applications in any versioned location. For the purposes of this walkthrough, you will create an Amazon S3 bucket for the sample applications (one for Linux, OS X, or Unix and one for Windows) and enable versioning on that bucket. After you have enabled versioning, you will copy the sample applications to that bucket. If you want to use an existing Amazon S3 bucket, see Enable Versioning for a Bucket, copy the sample applications to that bucket, and skip ahead to Create AWS CodeDeploy Resources. If you want to use a GitHub repository for your source instead of an Amazon S3 bucket, copy the sample applications to that repository, and skip ahead to Create AWS CodeDeploy Resources.

To create an Amazon S3 bucket

  1. Sign in to the AWS Management Console and open the Amazon S3 console at https://console.aws.amazon.com/s3/.

  2. Choose Create Bucket.

  3. In Bucket Name, type a name for your bucket, such as awscodepipeline-demobucket-example-date.

    Note

    Because all bucket names in Amazon S3 must be unique, use one of your own, not the name shown in the example. You can change the example name just by adding the date to it. Make a note of this name because you will use it for the rest of this tutorial.

    In the Region drop-down box, choose the region where you will create your pipeline, such as US West (Oregon), and then choose Create.

  4. In the console for your bucket, choose Properties, expand Versioning, and then choose Enable Versioning.

    When versioning is enabled, Amazon S3 saves every version of every object in the bucket.

  5. Next, you will download a sample from a GitHub repository and save it into a folder or directory on your local computer.

    Important

    Do not use the Clone or download or Download ZIP buttons in the GitHub repositories. This creates a nested folder structure that does not work with AWS CodeDeploy.

    1. Open the GitHub repository that hosts the sample.

    2. Choose the dist folder.

    3. Choose the file name.

      • For Linux, OS X, or Unix: aws-codepipeline-s3-aws-codedeploy_linux.zip

      • For Windows: AWSCodePipeline-S3-AWSCodeDeploy_Windows.zip

    4. Choose View Raw, and then save the sample file to your local computer.

  6. In the Amazon S3 console for your bucket, choose Upload, and follow the instructions to upload your .zip files into the bucket.

Step 2: Create AWS CodeDeploy Resources to Deploy the Sample Application

You can use Elastic Beanstalk or AWS CodeDeploy to deploy your code for staging or into production. In this walkthrough, you will use the Create Deployment Walkthrough wizard in AWS CodeDeploy to create your deployment resources.

To create an AWS CodeDeploy automated deployment

  1. Open the AWS CodeDeploy console at https://console.aws.amazon.com/codedeploy in the region where you intend to create your pipeline. For example, if you intend to create your pipeline in US East (N. Virginia), choose that region in the region selector.

    For more information about the regions and endpoints available for AWS CodePipeline, see Regions and Endpoints.

    If you see the Applications page instead of the Welcome page, in the Additional Information section, choose Create Deployment Walkthrough.

  2. On the Welcome page, choose Sample Deployment, and then choose Next Step.

  3. On the Instance Settings page, do the following:

    1. Choose the operating system and Amazon EC2 instance key pair you want to use. Your choice of operating system will determine which sample application you will specify when you create your pipeline.

      Important

      If you choose Linux, OS X, or Unix, you will use aws-codepipeline-s3-aws-codedeploy_linux.zip.

      If you choose Windows, you will use AWSCodePipeline-S3-AWSCodeDeploy_Windows.zip.

    2. From the Key Pair Name drop-down list, choose the name of the Amazon EC2 instance key pair you will use to connect to the Amazon EC2 instances after they are launched.

    3. In Tag Key and Value, leave the Key name unchanged. In Value, type CodePipelineDemo.

    4. Choose Launch Instances.

    An example of configuration choices for the Amazon Linux sample application

    For more information about each of these choices, see Instance Settings.

  4. After your instances have been created, choose Next Step.

  5. On the Application Name page, in Application Name, type CodePipelineDemoApplication, and then choose Next Step.

  6. On the Revision page, choose Next Step.

  7. On the Deployment Group page, in Deployment Group Name , type CodePipelineDemoFleet, and then choose Next Step.

  8. On the Service Role page, from the Service Role drop-down box, choose Use an existing service role. In the Role Name list, choose the service role you want to use, and then choose Next Step.

    Note

    If no service roles appear in Role Name, or if you do not have a service role you want to use, choose Create a new service role or follow the steps in Create a Service Role.

    The service role you create or use for AWS CodeDeploy is different from the service role you will create for AWS CodePipeline.

  9. On the Deployment Configuration page, choose Next Step.

  10. On the Review page, choose Deploy Now. The sample application for AWS CodeDeploy is deployed to each of the Amazon EC2 instances.

  11. After the sample application is successfully deployed, verify the deployment in your web browser by going to http://PublicDNS for each Amazon EC2 instance in the deployment. To get the public DNS value for an Amazon EC2 instance, in the Amazon EC2 console, select the instance, and look for the Public DNS value on the Description tab.

    The web page will display links to the AWS CodeDeploy documentation.

    Note

    This web page is not the one you will deploy and release with the pipeline you will create in the next section.

For more information about AWS CodeDeploy, see Getting Started with AWS CodeDeploy.

Step 3: Create Your First Pipeline in AWS CodePipeline

In this part of the walkthrough, you will create the pipeline. The sample will run automatically through the pipeline.

To create an AWS CodePipeline automated release process

  1. Sign in to the AWS Management Console and open the AWS CodePipeline console at http://console.aws.amazon.com/codepipeline.

  2. On the introductory page, choose Get started.

    If you see the Welcome page, choose Create pipeline.

  3. In Step 1: Name, in Pipeline name, type MyFirstPipeline, and then choose Next step.

    Note

    If you choose another name for your pipeline, be sure to use that name instead of MyFirstPipeline for the rest of this walkthrough. After you create a pipeline, you cannot change its name. Pipeline names are subject to some limitations. For more information, see Limits.

  4. In Step 2: Source, in Source provider, choose Amazon S3. In Amazon S3 location, type the name of the Amazon S3 bucket you created in Create an Amazon S3 Bucket and the sample file you copied to that bucket. If you chose Linux, OS X, or Unix, use aws-codepipeline-s3-aws-codedeploy_linux.zip. If you chose Windows, use AWSCodePipeline-S3-AWSCodeDeploy_Windows.zip. Choose Next step.

    When using an Amazon S3 bucket, make sure to include both the file and bucket name in the location

    For example, if you named your bucket awscodepipeline-demobucket-example-date and you chose Amazon Linux for your Amazon EC2 instances in AWS CodeDeploy, you would type:

    s3://awscodepipeline-demobucket-example-date/aws-codepipeline-s3-aws-codedeploy_linux.zip

    If you named your bucket awscodepipeline-demobucket-example-date and you chose Windows for your Amazon EC2 instances in AWS CodeDeploy, you would type:

    s3://awscodepipeline-demobucket-example-date/AWSCodePipeline-S3-AWSCodeDeploy_Windows.zip

    Note

    If you chose to copy the sample application to a GitHub repository instead of an Amazon S3 bucket, choose GitHub from the list of source providers, and then follow the instructions. For more information, see Create a Pipeline (Console).

  5. In Step 3: Build, choose No Build, and then choose Next step.

    Note

    Configuring a build requires a build server or system. You can walk through the steps for setting up build resources and creating a pipeline that uses those resources in the next tutorial, Four-Stage Pipeline Tutorial.

  6. In Step 4: Beta, in Deployment Provider, choose AWS CodeDeploy. In Application name, type CodePipelineDemoApplication, or choose the Refresh button, and then choose the application name from the list. In Deployment group, type CodePipelineDemoFleet, or choose it from the list, and then choose Next step.

    Configuring a deployment stage to use an AWS CodeDeploy application and deployment group

    Note

    The name "Beta" is the name given by default to this stage of the pipeline, just as "Source" is the name given to the first stage of the pipeline.

  7. In Step 5: Service Role, choose Create role.

    On the IAM console page that describes the AWS-CodePipeline-Service role that will be created for you, choose Allow.

    On the Step 5: Service Role page where AWS-CodePipeline-Service appears in Role name, choose Next step.

    Note

    Service role creation is only required the first time you create a pipeline in AWS CodePipeline. If a service role has already been created, you will be able to choose it from the drop-down list of roles. Because the drop-down list will display all IAM service roles associated with your account, if you choose a name different from the default, be sure that the name is recognizable as the service role for AWS CodePipeline.

  8. In Step 6: Review, review the information, and then choose Create pipeline.

  9. The pipeline automatically starts to run. You can view progress and success and failure messages as the AWS CodePipeline sample deploys a web page to each of the Amazon EC2 instances in the AWS CodeDeploy deployment.

    An example view of a pipeline, including stages, actions, and status

Congratulations! You just created a simple pipeline in AWS CodePipeline. The pipeline has two stages: a source stage named Source, which automatically detects changes in the versioned sample application stored in the Amazon S3 bucket and pulls those changes into the pipeline, and a Beta stage that deploys those changes to Amazon EC2 instances with AWS CodeDeploy. Now, verify the results.

To verify your pipeline ran successfully

  1. View the initial progress of the pipeline. The status of each stage will change from No executions yet to In Progress, and then to either Succeeded or Failed. The pipeline should complete the first run within a few minutes.

  2. After Succeeded is displayed for the action status, in the status area for the Beta stage, choose Details.

  3. In the Deployment Details section, in Instance ID, choose the instance ID of one of the successfully deployed instances.

  4. On the Description tab, in Public DNS, copy the address, and then paste it into the address bar of your web browser.

    The following page is the sample application you uploaded to your Amazon S3 bucket.

    The success page of the sample application after the pipeline completes

For more information about stages, actions, and how pipelines work, see Concepts.

Step 4: Add Another Stage to Your Pipeline

Now add another stage in the pipeline to deploy from beta servers to production servers using AWS CodeDeploy. First, you will create another deployment group in the CodePipelineDemoApplication in AWS CodeDeploy. Then you will add a stage that includes an action that uses this deployment group. To add another stage, you will use the AWS CodePipeline console or the AWS CLI to retrieve and manually edit the structure of the pipeline in a JSON file, and then run the update-pipeline command to update the pipeline with your changes.

Create a Second Deployment Group in AWS CodeDeploy

Note

In this part of the walkthrough, you will create a second deployment group, but deploy to the same Amazon EC2 instances as before. This is for demonstration purposes only. It is purposely designed to fail in order to show you how errors are displayed in AWS CodePipeline.

To create a second deployment group in AWS CodeDeploy

  1. Open the AWS CodeDeploy console at https://console.aws.amazon.com/codedeploy.

  2. Choose Applications, and in the list of applications, choose CodePipelineDemoApplication.

  3. In Deployment Groups, choose Create New Deployment Group.

  4. On the Create New Deployment Group page, in Deployment Group Name, type a name for the second deployment group, such as CodePipelineProductionFleet. In Key, leave the setting as Name, but in Value, choose CodePipelineDemo from the list. Leave the default configuration for Deployment Configuration. In Service Role, choose the same service role you used for the initial deployment, and then choose Create Deployment Group.

Add the Deployment Group as Another Stage in Your Pipeline

Now that you have another deployment group, you can add a stage that uses this deployment group to deploy to the same Amazon EC2 instances you used earlier. You can use the AWS CodePipeline console or the AWS CLI to add this stage.

Create a Third Stage (Console)

You can use the AWS CodePipeline console to add a new stage that uses the new deployment group. Because this deployment group is deploying to the Amazon EC2 instances you've already used, the deploy action in this stage will fail.

  1. Sign in to the AWS Management Console and open the AWS CodePipeline console at http://console.aws.amazon.com/codepipeline.

  2. In Name, choose the name of the pipeline you created, MyFirstPipeline.

  3. On the pipeline details page, choose Edit.

  4. On the Edit page, choose + Stage to add a stage immediately after the Beta stage.

    The edit page for a pipeline
  5. In the name field for the new stage, type Production, and then choose + Action ().

  6. In the Action category drop-down list, choose Deploy. In Action name, type Deploy-Second-Deployment. In Deployment provider, choose AWS CodeDeploy from the drop-down list. In the AWS CodeDeploy section, in Application Name, choose CodePipelineDemoApplication from the drop-down list, as you did when you created the pipeline. In Deployment Group, choose the deployment group you just created, CodePipelineProductionFleet. In the Input artifacts section, type MyApp in Name, and then choose Add action.

    Tip

    The name of the input artifact, MyApp, was created automatically for you in the Create Pipeline wizard as the output artifact of the source action. Every action has an input artifact (the artifact the action works on), an output artifact (the product or result of the action), or both, depending on the action type. In this example, the deploy action inputs the output of the source action in the source stage, MyApp, and deploys it. Because the action configured for the previous stage (Beta) has already deployed the application to the same Amazon EC2 instances, this action will fail. For more information about input and output artifacts and the structure of pipelines, see Pipeline Structure Reference.

  7. On the Edit page, choose Save pipeline changes. In the Save pipeline changes dialog box, choose Save and continue.

  8. Although the new stage has been added to your pipeline, a status of No executions yet is displayed because no changes have triggered another run of the pipeline. You will have to manually rerun the last revision to see how the pipeline runs now that it has been edited. On the pipeline details page, choose Release change. This will run the most recent revision available in each source location specified in a source action through the pipeline.

    Alternatively, to use the AWS CLI to rerun the pipeline, from a terminal (Linux, OS X, or Unix) or command prompt (Windows), run the start-pipeline-execution command, specifying the name of the pipeline. This will run the application in your source bucket through the pipeline for a second time.

    aws codepipeline start-pipeline-execution --name MyFirstPipeline

    This command returns a pipelineExecutionId object.

  9. Return to the AWS CodePipeline console and choose MyFirstPipeline in the list of pipelines to open the view page for that pipeline.

    The pipeline shows three stages and the state of the artifact running through those three stages. It might take up to five minutes for the pipeline to run through all stages. You'll see the deployment succeeds on the first two stages, just as before, but the Production stage shows the Deploy-Second-Deployment action failed.

    The third stage of the pipeline fails for demonstration purposes
  10. In the Deploy-Second-Deployment action, choose Details. You will be redirected to the details page for the AWS CodeDeploy deployment. In this case, the failure is the result of the first instance group deploying to all of the Amazon EC2 instances, leaving no instances for the second deployment group.

    Note

    This failure is by design, to demonstrate what happens when there is a failure in a pipeline stage.

Create a Third Stage (CLI)

Although using the AWS CLI to add a stage to your pipeline is more complex than using the console, it provides more visibility into the structure of the pipeline.

To create a third stage for your pipeline

  1. Open a terminal session (Linux, OS X, or Unix) or command prompt (Windows) and run the get-pipeline command to display the structure of the pipeline you just created. For MyFirstPipeline, you would type the following command:

    aws codepipeline get-pipeline --name "MyFirstPipeline"

    This command returns the structure of MyFirstPipeline. The first part of the output should look similar to the following:

    {
        "pipeline": {
            "roleArn": "arn:aws:iam::80398EXAMPLE:role/AWS-CodePipeline-Service",
            "stages": [
        ...
    }    
    
  2. Copy and paste this structure into a plain-text editor, and save the file as pipeline.json. For convenience, save this file in the same directory where you run the aws codepipeline commands.

    Tip

    You can pipe the JSON directly into a file with the get-pipeline command as follows:

    aws codepipeline get-pipeline --name MyFirstPipeline >pipeline.json
  3. Copy the Beta stage section and paste it after the first two stages. Because it is a deploy stage, just like the Beta stage, you will use it as a template for the third stage.

  4. Change the name of the stage and the deployment group details, and then save the file.

    The following example shows the JSON you will add to the pipeline.json file after the Beta stage. Edit the emphasized elements with new values. Remember to include a comma to separate the Beta and Production stage definitions.

    ,
    {
        "name": "Production",
         "actions": [
            {
             "inputArtifacts": [
                 {
                  "name": "MyApp"
                 }
               ],
              "name": "Deploy-Second-Deployment",
              "actionTypeId": {
                  "category": "Deploy",
                  "owner": "AWS",
                  "version": "1",
                  "provider": "CodeDeploy"
                  },
             "outputArtifacts": [],
             "configuration": {
                  "ApplicationName": "CodePipelineDemoApplication",
                  "DeploymentGroupName": "CodePipelineProductionFleet"
                   },
             "runOrder": 1
            }
        ]
    }
  5. Run the update-pipeline command, specifying the name of the pipeline and the pipeline JSON file, similar to the following:

    Important

    Be sure to include file:// before the file name. It is required in this command.

    aws codepipeline update-pipeline --cli-input-json file://pipeline.json

    This command returns the entire structure of the updated pipeline.

  6. Run the start-pipeline-execution command, specifying the name of the pipeline. This will run the application in your source bucket through the pipeline for a second time.

    aws codepipeline start-pipeline-execution --name MyFirstPipeline

    This command returns a pipelineExecutionId object.

  7. Open the AWS CodePipeline console and choose MyFirstPipeline from the list of pipelines.

    The pipeline shows three stages and the state of the artifact running through those three stages. It might take up to five minutes for the pipeline to run through all stages. Although the deployment succeeds on the first two stages, just as before, the Production stage shows that the Deploy-Second-Deployment action failed.

    The third stage of the pipeline fails for demonstration purposes
  8. In the Deploy-Second-Deployment action, choose Details to see details of the failure. You will be redirected to the details page for the AWS CodeDeploy deployment. In this case, the failure is the result of the first instance group deploying to all of the Amazon EC2 instances, leaving no instances for the second deployment group.

    Note

    This failure is by design, to demonstrate what happens when there is a failure in a pipeline stage.

Step 5: Disable and Enable Transitions Between Stages in AWS CodePipeline

You can enable or disable the transition between stages in a pipeline. Disabling the transition between stages allows you to manually control transitions between one stage and another. For example, you might want to run the first two stages of a pipeline, but disable transitions to the third stage until you are ready to deploy to production, or while you troubleshoot a problem or failure with that stage.

To disable and enable transitions between stages in an AWS CodePipeline pipeline

  1. Open the AWS CodePipeline console and choose MyFirstPipeline from the list of pipelines.

  2. On the details page for the pipeline, choose the arrow that indicates the transition between the second stage, Beta, and the third stage that you added in the previous section, Production.

  3. In the Disable Transition dialog box, type a reason for disabling the transition between the stages, and then choose Disable.

    The arrow between stages displays an icon and color change indicating that the transition has been disabled.

    Disabling a transition between the second and third stages of a pipeline
  4. Upload your sample again to the Amazon S3 bucket. Because the bucket is versioned, this change will automatically start the pipeline. For information, see Upload the sample application.

  5. Return to the details page for your pipeline and watch the status of the stages. The pipeline view will change to show progress and success on the first two stages, but no changes will occur on the third stage. This process might take a few minutes.

  6. Enable the transition by choosing the arrow that indicates the transition has been disabled between the two stages. In the Enable Transition dialog box, choose Enable. The stage will begin running in a few minutes and attempt to process the artifact that has already been run through the first two stages of the pipeline.

    Note

    If you want this third stage to succeed, edit the CodePipelineProductionFleet deployment group before you enable the transition, and specify a different set of Amazon EC2 instances where you will deploy the application. For more information about how to do this, see Change Deployment Group Settings. If you create more Amazon EC2 instances, you may incur additional costs.

Step 6: Clean Up Resources

You can use some of the resources you created in this walkthrough for the tutorial, Four-Stage Pipeline Tutorial. For example, you can reuse the AWS CodeDeploy application and deployment. However, after you complete this and any other tutorials, you should delete the pipeline and the resources it uses, so that you will not be charged for the continued use of those resources. First, delete the pipeline, then the AWS CodeDeploy application and its associated Amazon EC2 instances, and finally, the Amazon S3 bucket.

To clean up the resources used in this tutorial

  1. To clean up your AWS CodePipeline resources, follow the instructions in Delete a Pipeline in AWS CodePipeline.

  2. To clean up your AWS CodeDeploy resources, follow the instructions in Clean Up Deployment Walkthrough Resources.

  3. To delete the Amazon S3 bucket, follow the instructions in Deleting or Emptying an Amazon S3 Bucket. If you do not intend to create more pipelines, delete the Amazon S3 bucket created for storing your pipeline artifacts. For more information about this bucket, see Concepts.