Prerequisites Step 1: Create an AWS role Step 2: Create an Amazon S3 bucket Step 3: Create a source repository Step 4: Create a workflow Step 5: Verify the results Clean up

Tutorial: Upload artifacts to Amazon S3

In this tutorial, you learn how to upload artifacts to an Amazon S3 bucket using a CodeCatalyst workflow that includes a couple of build actions. These actions run in series when the workflow starts. The first build action generates two files, Hello.txt and Goodbye.txt, and bundles them into a build artifact. The second build action uploads the artifact to Amazon S3. You'll configure the workflow to run every time you push a commit to your source repository.

Prerequisites

Before you begin, you need the following:

You need a CodeCatalyst space with a connected AWS account. For more information, see Creating a space that supports AWS Builder ID users.
In your space, you need an empty, Start from scratch CodeCatalyst project called:
```
codecatalyst-artifact-project
```
For more information, see Creating an empty project in Amazon CodeCatalyst.
In your project, you need a CodeCatalyst environment called:
```
codecatalyst-artifact-environment
```
Configure this environment as follows:
- Choose any type, such as Development.
- Connect your AWS account to it.
For more information, see Working with environments.

Step 1: Create an AWS role

In this step, you create an AWS IAM role which you will later assign to the build action in your workflow. This role grants the CodeCatalyst build action permission to access your AWS account and write to Amazon S3 where your artifact will be stored. The role is called the Build role.

Note

If you already have a build role that you created for another tutorial, you can use it for this tutorial too. Just make sure it has the permissions and trust policy shown in the following procedure.

For more information on IAM roles, see IAM roles in the AWS AWS Identity and Access Management User Guide.

To create a build role

Create a policy for the role, as follows:
1. Sign in to AWS.
2. Open the IAM console at https://console.aws.amazon.com/iam/.
3. In the navigation pane, choose Policies.
4. Choose Create policy.
5. Choose the JSON tab.
6. Delete the existing code.
7. Paste the following code:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "VisualEditor0",
            "Effect": "Allow",
            "Action": [
                "s3:PutObject",
                "s3:ListBucket"
            ],
            "Resource": "*"
        }
    ]
}
```
  Note
  The first time the role is used to run workflow actions, use the wildcard in the resource policy statement and then scope down the policy with the resource name after it is available.
```
"Resource": "*"
```
8. Choose Next: Tags.
9. Choose Next: Review.
10. In Name, enter:
```
codecatalyst-s3-build-policy
```
11. Choose Create policy.
  
  You have now created a permissions policy.
Create the build role, as follows:
1. In the navigation pane, choose Roles, and then choose Create role.
2. Choose Custom trust policy.
3. Delete the existing custom trust policy.
4. Add the following custom trust policy:
```
{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "",
            "Effect": "Allow",
            "Principal": {
                "Service":  [
                   "codecatalyst-runner.amazonaws.com",
                   "codecatalyst.amazonaws.com"
                 ]
            },
            "Action": "sts:AssumeRole"
        }
    ]
}
```
5. Choose Next.
6. In Permissions policies, search for codecatalyst-s3-build-policy and select its check box.
7. Choose Next.
8. For Role name, enter:
```
codecatalyst-s3-build-role
```
9. For Role description, enter:
```
CodeCatalyst build role
```
10. Choose Create role.
You have now created a build role with a trust policy and permissions policy.

Step 2: Create an Amazon S3 bucket

In this step, you create an Amazon S3 bucket where the Hello.txt and Goodbye.txt artifacts will be uploaded.

To create an Amazon S3 bucket

Open the Amazon S3 console at https://console.aws.amazon.com/s3/.
In the main pane, choose Create bucket.
For Bucket name, enter:
```
codecatalyst-artifact-bucket
```
For AWS Region, choose a Region. This tutorial assumes you chose US West (Oregon) us-west-2. For information about Regions supported by Amazon S3, see Amazon Simple Storage Service endpoints and quotas in the AWS General Reference.
At the bottom of the page, choose Create bucket.
Copy the name of the bucket you just created, for example:
```
codecatalyst-artifact-bucket
```

You have now created a bucket called codecatalyst-artifact-bucket in the US West (Oregon) us-west-2 Region.

Step 3: Create a source repository

In this step, you create a source repository in CodeCatalyst. This repository is used to store the tutorial's workflow definition file.

For more information on source repositories, see Creating a source repository.

To create a source repository

Open the CodeCatalyst console at https://codecatalyst.aws/.
Navigate to your project, codecatalyst-artifact-project.
In the navigation pane, choose Code, and then choose Source repositories.
Choose Add repository, and then choose Create repository.
In Repository name, enter:
```
codecatalyst-artifact-source-repository
```
Choose Create.

You have now created a repository called codecatalyst-artifact-source-repository.

Step 4: Create a workflow

In this step, you create a workflow that consists of the following building blocks that run sequentially:

A trigger – This trigger starts the workflow run automatically when you push a change to your source repository. For more information on triggers, see Working with triggers.
A build action called GenerateFiles – On trigger, the GenerateFiles action creates two files, Hello.txt and Goodbye.txt, and packages them into an output artifact called codecatalystArtifact.
Another build action called Upload – On completion of the GenerateFiles action, the Upload action runs the AWS CLI command aws s3 sync to upload the files in the codecatalystArtifact and in your source repository to your Amazon S3 bucket. The AWS CLI comes pre-installed and pre-configured on the CodeCatalyst compute platform, so you don't need to install or configure it.

For more information on the pre-packaged software on the CodeCatalyst compute platform, see Working with runtime environment Docker images. For more information on the AWS CLI's aws s3 sync command, see sync in the AWS CLI Command Reference.

For more information on the build action, see Building using workflows in CodeCatalyst.

To create a workflow

In the navigation pane, choose CI/CD, and then choose Workflows.
Choose Create workflow.
Delete the YAML sample code.

Add the following YAML code:


Name: codecatalyst-artifact-workflow
SchemaVersion: 1.0

Triggers:
  - Type: Push
    Branches:
      - main   
Actions:
  GenerateFiles:
    Identifier: aws/build@v1
    Configuration: 
      Steps:
        # Create the output files.
        - Run: echo "Hello, World!" > "Hello.txt"
        - Run: echo "Goodbye!" > "Goodbye.txt"
    Outputs:
      Artifacts:
        - Name: codecatalystArtifact
          Files:
            - "**/*"
  Upload:
    Identifier: aws/build@v1
    DependsOn: 
      - GenerateFiles
    Environment:
      Name: codecatalyst-artifact-environment
      Connections:
        - Name: codecatalyst-account-connection
          Role: codecatalyst-s3-build-role
    Inputs:
      Artifacts:
        - codecatalystArtifact
    Configuration: 
      Steps:
        # Upload the output artifact to the S3 bucket.
        - Run: aws s3 sync . s3://codecatalyst-artifact-bucket

In the code above, replace:

codecatalyst-artifact-environment with the name of the environment you created in Prerequisites.
codecatalyst-account-connection with the name of the account connection you created in Prerequisites.
codecatalyst-s3-build-role with the name of the build role that you created in Step 1: Create an AWS role.
codecatalyst-artifact-bucket with the name of the Amazon S3 you created in Step 2: Create an Amazon S3 bucket.

For information about the properties in this file, see the Build and test action reference.

(Optional) Choose Validate to make sure the YAML code is valid before committing.
Choose Commit.
On the Commit workflow dialog box, enter the following:
1. For Workflow file name, leave the default, codecatalyst-artifact-workflow.
2. For Commit message, enter:
```
add initial workflow file
```
3. For Repository, choose codecatalyst-artifact-source-repository.
4. For Branch name, choose main.
5. Choose Commit.
You have now created a workflow. A workflow run starts automatically because of the trigger defined at the top of the workflow. Specifically, when you committed (and pushed) the codecatalyst-artifact-workflow.yaml file to your source repository, the trigger started the workflow run.

To view the workflow run in progress

In the navigation pane, choose CI/CD, and then choose Workflows.
Choose the workflow you just created: codecatalyst-artifact-workflow.
Choose GenerateFiles to see the first build action progress.
Choose Upload to see the second build action progress.
When the Upload action finishes, do the following:
- If the workflow run succeeded, go to the next procedure.
- If the workflow run failed, choose Logs to troubleshoot the issue.

Step 5: Verify the results

After the workflow runs, go to the Amazon S3 service and look in your codecatalyst-artifact-bucket bucket. It should now include the following files and folders:


.
|— .aws/
|— .git/
|Goodbye.txt
|Hello.txt
|REAME.md

The Goodbye.txt and Hello.txt files were uploaded because they were part of the codecatalystArtifact artifact. The .aws/, .git/, and README.md files were uploaded because they were in your source repository.

Clean up

Clean up in CodeCatalyst and AWS to avoid being charged for these services.

To clean up in CodeCatalyst

Open the CodeCatalyst console at https://codecatalyst.aws/.
Delete the codecatalyst-artifact-source-repository source repository.
Delete the codecatalyst-artifact-workflow workflow.

To clean up in AWS

Clean up in Amazon S3, as follows:
1. Open the Amazon S3 console at https://console.aws.amazon.com/s3/.
2. Delete the files in the codecatalyst-artifact-bucket bucket.
3. Delete the codecatalyst-artifact-bucket bucket.
Clean up in IAM, as follows:
1. Open the IAM console at https://console.aws.amazon.com/iam/.
2. Delete the codecatalyst-s3-build-policy.
3. Delete the codecatalyst-s3-build-role.

Warning Javascript is disabled or is unavailable in your browser.

To use the Amazon Web Services Documentation, Javascript must be enabled. Please refer to your browser's Help pages for instructions.

Document Conventions

Viewing the results

Testing using workflows