Deploying a GitHub Static Site to S3 with AWS CloudFormation

In the world of web development, static websites are a popular choice due to their simplicity, security, and performance. Hosting these static sites on Amazon S3 is a cost - effective and reliable solution. AWS CloudFormation, on the other hand, allows you to define and provision AWS resources in a declarative way. By integrating GitHub, a widely used version control system, we can automate the process of deploying a static site from GitHub to S3. This blog post will guide you through the core concepts, usage scenarios, common practices, and best practices of deploying a GitHub static site to S3 using AWS CloudFormation.

Table of Contents#

  1. Core Concepts
    • AWS CloudFormation
    • Amazon S3
    • GitHub
  2. Typical Usage Scenarios
  3. Common Practice
    • Prerequisites
    • Creating an AWS CloudFormation Template
    • Deploying the Stack
    • Connecting GitHub to S3
  4. Best Practices
    • Security
    • Monitoring and Logging
    • Versioning
  5. Conclusion
  6. FAQ
  7. References

Article#

Core Concepts#

AWS CloudFormation#

AWS CloudFormation is a service that enables you to model and set up your AWS resources in a text - based template. You can use YAML or JSON to define the resources, their properties, and the relationships between them. Once the template is created, CloudFormation takes care of provisioning and managing the resources in the correct order. This makes it easy to replicate the infrastructure across different environments, such as development, testing, and production.

Amazon S3#

Amazon S3 (Simple Storage Service) is an object storage service that offers industry - leading scalability, data availability, security, and performance. It can be used to store and retrieve any amount of data at any time from anywhere on the web. S3 is a popular choice for hosting static websites because it can serve static files such as HTML, CSS, JavaScript, and images directly to end - users.

GitHub#

GitHub is a web - based hosting service for version control using Git. It provides a platform for developers to collaborate on projects, track changes, and manage code repositories. GitHub offers features like pull requests, issues, and code reviews, which make it easier for teams to work together on a project.

Typical Usage Scenarios#

  • Personal Blogs: Developers or content creators can use this setup to host their personal blogs. They can write their blog posts in Markdown, manage the source code on GitHub, and use AWS CloudFormation to deploy the site to S3.
  • Small Business Websites: Small businesses can create static websites to showcase their products or services. By using GitHub for version control and S3 for hosting, they can easily update the site and ensure high availability.
  • Project Documentation: Open - source projects can use this approach to host their documentation. Developers can contribute to the documentation on GitHub, and the changes can be automatically deployed to S3 for easy access by users.

Common Practice#

Prerequisites#

  • An AWS account with appropriate permissions to create S3 buckets and CloudFormation stacks.
  • A GitHub account with a repository containing your static site code.
  • The AWS CLI installed and configured on your local machine.

Creating an AWS CloudFormation Template#

Here is a simple example of an AWS CloudFormation template in YAML to create an S3 bucket for hosting a static website:

AWSTemplateFormatVersion: '2010-09-09'
Resources:
  StaticSiteBucket:
    Type: 'AWS::S3::Bucket'
    Properties:
      BucketName: my-static-site-bucket
      WebsiteConfiguration:
        IndexDocument: index.html
        ErrorDocument: error.html
  BucketPolicy:
    Type: 'AWS::S3::BucketPolicy'
    Properties:
      Bucket: !Ref StaticSiteBucket
      PolicyDocument:
        Statement:
          - Effect: Allow
            Principal: '*'
            Action: 's3:GetObject'
            Resource: !Join 
              - ''
              - - 'arn:aws:s3:::'
                - !Ref StaticSiteBucket
                - '/*'
Outputs:
  WebsiteURL:
    Value: !GetAtt 
      - StaticSiteBucket
      - WebsiteURL
    Description: URL for website hosted on S3

Deploying the Stack#

  1. Save the above template as static - site - template.yaml.
  2. Open your terminal and run the following command to create a CloudFormation stack:
aws cloudformation create - stack --stack - name my - static - site - stack --template - body file://static - site - template.yaml
  1. You can monitor the stack creation progress using the AWS Management Console or the following CLI command:
aws cloudformation describe - stacks --stack - name my - static - site - stack

Connecting GitHub to S3#

To connect GitHub to S3, you can use a CI/CD tool like GitHub Actions. Here is a simple GitHub Actions workflow file to deploy your static site to S3:

name: Deploy to S3
 
on:
  push:
    branches:
      - main
 
jobs:
  deploy:
    runs - on: ubuntu - latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
 
      - name: Configure AWS credentials
        uses: aws - actions/configure - aws - credentials@v1
        with:
          aws - access - key - id: ${{ secrets.AWS_ACCESS_KEY_ID }}
          aws - secret - access - key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
          aws - region: us - east - 1
 
      - name: Deploy to S3
        run: aws s3 sync . s3://my - static - site - bucket

Best Practices#

Security#

  • IAM Roles and Permissions: Use AWS Identity and Access Management (IAM) roles and permissions to ensure that only authorized users and services can access your S3 bucket.
  • Encryption: Enable server - side encryption for your S3 bucket to protect your data at rest. You can use Amazon S3 - managed keys (SSE - S3) or AWS Key Management Service (KMS) keys.

Monitoring and Logging#

  • CloudWatch: Use Amazon CloudWatch to monitor the performance and health of your S3 bucket. You can set up alarms to notify you of any issues.
  • S3 Server Access Logging: Enable S3 server access logging to track all requests made to your bucket. This can help you troubleshoot issues and monitor for any unauthorized access.

Versioning#

  • S3 Versioning: Enable versioning on your S3 bucket to keep multiple versions of your files. This allows you to roll back to a previous version if needed.

Conclusion#

Deploying a GitHub static site to S3 using AWS CloudFormation is a powerful and efficient way to host static websites. By understanding the core concepts, typical usage scenarios, common practices, and best practices, software engineers can set up a reliable and scalable infrastructure for their static sites. The combination of GitHub for version control, S3 for hosting, and CloudFormation for infrastructure management provides a seamless and automated deployment process.

FAQ#

Q: Can I use other version control systems instead of GitHub? A: Yes, you can use other version control systems like GitLab or Bitbucket. The general process will be similar, but you may need to adjust the CI/CD configuration accordingly.

Q: Is it possible to use a custom domain for my S3 - hosted static site? A: Yes, you can use a custom domain by configuring Amazon Route 53 and Amazon CloudFront. CloudFront can be used to distribute your static site globally and improve performance.

Q: What if I need to make changes to my CloudFormation template after the stack is created? A: You can use the aws cloudformation update - stack command to update the stack with the new template. CloudFormation will automatically make the necessary changes to your resources.

References#

2025-10