Introduction: Defining Your Pipeline with GitHub Actions

While AWS CodePipeline, CodeBuild, and CodeDeploy offer a robust native AWS solution, many developers prefer to keep their CI/CD definitions alongside their code in GitHub. This is where GitHub Actions shine. GitHub Actions allow you to automate, customize, and execute your software development workflows directly in your repository.

A workflow is defined by a YAML file (.yml) in the .github/workflows/ directory of your repository. This file specifies when the workflow runs, what steps it takes, and what environment it uses.

Below, you'll find a complete example of a GitHub Actions workflow that automatically builds a simple web application and deploys it to an AWS S3 bucket every time you push changes to the main branch.

Prerequisites for this Pipeline

• A GitHub Repository with your static website files.
• An AWS S3 Bucket configured for static website hosting (as covered in the previous tutorial). Make sure its permissions allow public read access via a bucket policy.
• An AWS IAM User with programmatic access (Access Key ID and Secret Access Key) and permissions to:
  • s3:PutObject, s3:DeleteObject, s3:GetObject, s3:ListBucket on your specific S3 bucket.
• GitHub Secrets: You will need to store your AWS credentials securely in your GitHub repository's secrets. Go to your GitHub repository -> Settings -> Secrets and variables -> Actions -> New repository secret. Create two secrets:
  • AWS_ACCESS_KEY_ID
  • AWS_SECRET_ACCESS_KEY

The GitHub Actions Workflow File (.github/workflows/deploy.yml)

Create a file named deploy.yml (or any other descriptive name) inside the .github/workflows/ directory in your GitHub repository. Copy and paste the following code into it:

.github/workflows/deploy.yml

How this Workflow Works:

• name: A human-readable name for your workflow.
• on: push: branches: [main]: This defines the trigger. The workflow will run automatically whenever code is pushed to the `main` branch.
• jobs: deploy:: Defines a single job named `deploy`. Workflows can have multiple jobs.
• runs-on: ubuntu-latest: Specifies that the job will run on a fresh Ubuntu virtual machine hosted by GitHub.
• steps:: A sequence of tasks to be executed.
  • Checkout repository: Uses `actions/checkout@v4` to clone your GitHub repository onto the runner.
  • Install dependencies and build: (Optional) If your website is built using a framework (like React, Vue, Angular), this step installs Node.js dependencies and runs the build command (e.g., `npm run build`). The output is typically in a `build` or `dist` folder. If your site is just plain HTML/CSS/JS, you can remove this step.
  • Configure AWS credentials: Uses `aws-actions/configure-aws-credentials@v4` to set up AWS CLI with the `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` retrieved from your GitHub secrets. This securely authenticates your workflow with AWS.
  • Deploy to S3: Uses the `aws s3 sync` command.
    • $SOURCE_DIR/: This should be the path to your static website files (e.g., `build/`, `dist/`, or `.` if they are in the repository root).
    • s3://$S3_BUCKET_NAME/: The destination S3 bucket.
    • --delete: Removes files from S3 that are no longer present in your source directory.
    • --acl public-read: Ensures the uploaded files are publicly readable, which is necessary for static website hosting.
  • Invalidate CloudFront cache: (Optional) If you're using CloudFront for CDN and HTTPS, this step invalidates the cache, ensuring your users see the latest version of your site immediately. Remember to replace `CLOUDFRONT_DISTRIBUTION_ID` with your actual distribution ID.

Setting Up and Running Your Pipeline

1. Prepare your S3 Bucket: Ensure your S3 bucket is configured for static website hosting and has a public bucket policy, as discussed in the previous tutorial.
2. Create IAM User: In AWS IAM, create a user with programmatic access and attach a policy that grants necessary S3 permissions (s3:GetObject, s3:PutObject, s3:DeleteObject, s3:ListBucket) to your specific bucket. If you're using CloudFront invalidation, also add cloudfront:CreateInvalidation.
3. Add GitHub Secrets: Go to your GitHub repository -> Settings -> Secrets and variables -> Actions. Add `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` with the credentials from your IAM user.
4. Create Workflow File: In your GitHub repository, create the folder structure `.github/workflows/` and then create the `deploy.yml` file inside it. Paste the YAML code provided above, remembering to update the `aws-region`, `S3_BUCKET_NAME`, `SOURCE_DIR`, and `CLOUDFRONT_DISTRIBUTION_ID` (if applicable).
5. Push to GitHub: Commit and push the `deploy.yml` file to your `main` branch.

Once pushed, navigate to the "Actions" tab in your GitHub repository. You should see your workflow running. On successful completion, your static website will be updated on S3!