In this article, we’ll implement a continuous delivery (referred to as CD going forward) workflow using the Serverless framework for our demo React SPA application using Serverless Finch.

Deploying single-page applications to AWS S3 is a common use case. Manual deployment and bucket configuration can be tedious and unreliable. By using Serverless and CD platforms, we can simplify this commonly faced CD challenge.

In almost every project we have worked on, we have built a general-purpose continuous integration (referred to as CI through the rest of this article) setup as part of our basic setups. The CI requirements might range from simple test workflows to cluster deployments.

In this article, we’ll be focusing on a simple deployment workflow using Github Actions and CircleCI. Github Actions brought CI/CD to a wider community by simplifying the setup for CI pipelines. 

Prerequisites

This article assumes you have a basic understanding of CICD and AWS services such as IAM and S3. The sample application uses a basic Create React Application for the deployment demo. But knowing React.js is not required. You can implement the same flow for any other SPA or bare-bones application.

Why Github Actions?

There have always been great tools and CI platforms, such as AWS CodePipeline, Jenkins, Travis CI, CircleCI, etc. What makes Github Actions so compelling is that it’s built inside Github. Many organizations use Github for source control, and they often have to spend time configuring repositories with CI tools. On top of that, starting with Github Actions is free.

As Github Actions is built inside the Github ecosystem, it’s a piece of cake to get CI pipelines up and running. Github Actions also allow you to build your own actions. However, there are some limitations because the CI platform is quite new compared to others.

Why CircleCI?

CircleCI has been in the market for almost a decade providing CICD solutions. One of many reasons to choose CircleCI is its pricing. CircleCI offers free credits each month without any upfront payments or payment details. It also offers a wide-ranging repository of plugins called Orbs. You can even build your own orbs, which are easy. It also offers simple and reliable workflow building tools. You can check other features as well.

Let’s Get Started

To introduce the application, we’ll create a simple React application with master-detail flow added to it. We’ll be using React’s official CRA tool to create our project, which creates the boilerplate for us.

Installing Dependencies

Let’s install the create-react-app as a global package. We’ll be calling our demo project “Serverless S3”. Now, we will create our react app with the following:

yarn global add create-react-app
create-react-app serverless-s3

yarn global add create-react-app
create-react-app serverless-s3

Now that we’ve created the frontend application, we can start building something cool with it. If we run the application with yarn start, we should be able to see the default CRA welcome page:

Source: React

To implement our master-detail flow of Github repositories, we’ll need to add some navigation to our app. Also, to keep it short, we’ll be using Github’s official SDK package. So, let’s use the react-router for the same.

yarn add react-router-dom @octakit/core

yarn add react-router-dom @octakit/core

Our demo application will consist of two routes: 

1. A list of all public repos of an organization
2. The details of the repository after clicking a repo item from the list 

We’ll be using the Octokit client to fetch the data from Github’s open endpoints. This won’t need any authentication with Github.

Adding Application Components

Alright, now that we have our dependencies installed, we can add the routes to our App.js, which is the entry point for our React app.

import { BrowserRouter as Router, Switch, Route } from 'react-router-dom';
 
import RepoList from './RepoList';
import RepoDetails from './RepoDetails';
 
import './App.css';
 
function App() {
  return (
   <Router>
     <div className="App">
       <Switch>
         <Route path="/repo/:owner/:repo" component={RepoDetails} />
         <Route path="/" component={RepoList} />
       </Switch>
     </div>
   </Router>
 );
}
 
export default App;

import { BrowserRouter as Router, Switch, Route } from 'react-router-dom';
 
import RepoList from './RepoList';
import RepoDetails from './RepoDetails';
 
import './App.css';
 
function App() {
  return (
   <Router>
     <div className="App">
       <Switch>
         <Route path="/repo/:owner/:repo" component={RepoDetails} />
         <Route path="/" component={RepoList} />
       </Switch>
     </div>
   </Router>
 );
}
 
export default App;

Let’s initialize our Octokit client, which will help us make calls to Github’s open endpoints to get data.

import { Octokit } from '@octokit/core';
 
export const octokit = new Octokit({});

import { Octokit } from '@octokit/core';
 
export const octokit = new Octokit({});

You can even make calls to authorized resources with the Octokit client. Octokit client supports both GraphQL and REST API. You can learn more about the client through the official documentation.

Let’s add the RepoList.js component to the application, which will fetch the list of repositories of a given organization and display hyperlinks to the details page.

import React, { useEffect, useState } from 'react';
import { Link } from 'react-router-dom';
import { octokit } from './client';
 
function RepoList() {
 const [repos, setRepos] = useState([]);
 useEffect(() => {
   octokit
     .request('GET /orgs/:org/repos', {
       org: 'octokit',
     })
     .then((data) => setRepos(data.data));
 }, []);
 
 return (
   <div className="repo-list-container">
     <h1>Repositories</h1>
     <ul>
       {repos.map((repo) => (
         <li key={repo.id} className="repo-list-item">
           <Link to={`/repo/${repo.owner.login}/${repo.name}`}>{repo.full_name}</Link>
         </li>
       ))}
     </ul>
   </div>
 );
}
 
export default RepoList;

import React, { useEffect, useState } from 'react';
import { Link } from 'react-router-dom';
import { octokit } from './client';
 
function RepoList() {
 const [repos, setRepos] = useState([]);
 useEffect(() => {
   octokit
     .request('GET /orgs/:org/repos', {
       org: 'octokit',
     })
     .then((data) => setRepos(data.data));
 }, []);
 
 return (
   <div className="repo-list-container">
     <h1>Repositories</h1>
     <ul>
       {repos.map((repo) => (
         <li key={repo.id} className="repo-list-item">
           <Link to={`/repo/${repo.owner.login}/${repo.name}`}>{repo.full_name}</Link>
         </li>
       ))}
     </ul>
   </div>
 );
}
 
export default RepoList;

Now that we have our list of repositories ready, we can now allow users to see some of their general details. Let’s create our details component called RepoDetails:

import { useEffect, useState } from 'react';
import { useParams } from 'react-router-dom';
import { octokit } from './client';
function RepoDetails() {
  const [repo, setRepo] = useState();
  const { repo: repoName, owner } = useParams();
  useEffect(() => {
    octokit
      .request('GET /repos/{owner}/{repo}', {
        owner,
        repo: repoName,
      })
      .then((data) => setRepo(data.data));
  }, [repoName, owner]);
  if (!repo) {
    return <b>loading...</b>;
  }
  return (
    <div className="repo-container">
      <h1>{repo.full_name}</h1>
      <p>Description: {repo.description}</p>
      <ul>
        <li><b>Forks:</b> {repo.forks}</li>
        <li><b>Subscribers:</b> {repo.subscribers_count}</li>
        <li><b>Watchers:</b> {repo.watchers}</li>
        <li><b>License:</b> {repo.license.name}</li>
      </ul>
    </div>
  );
}
export default RepoDetails;

import { useEffect, useState } from 'react';
import { useParams } from 'react-router-dom';
import { octokit } from './client';
function RepoDetails() {
  const [repo, setRepo] = useState();
  const { repo: repoName, owner } = useParams();
  useEffect(() => {
    octokit
      .request('GET /repos/{owner}/{repo}', {
        owner,
        repo: repoName,
      })
      .then((data) => setRepo(data.data));
  }, [repoName, owner]);
  if (!repo) {
    return <b>loading...</b>;
  }
  return (
    <div className="repo-container">
      <h1>{repo.full_name}</h1>
      <p>Description: {repo.description}</p>
      <ul>
        <li><b>Forks:</b> {repo.forks}</li>
        <li><b>Subscribers:</b> {repo.subscribers_count}</li>
        <li><b>Watchers:</b> {repo.watchers}</li>
        <li><b>License:</b> {repo.license.name}</li>
      </ul>
    </div>
  );
}
export default RepoDetails;

Setting up Serverless

With this done, we have our repositories master-detail flow ready. Assuming we have an AWS account setup, we can start adding the Serverless config to our project. Let’s start with the CD setup. As we said before, we’ll be using the Serverless framework to achieve our deployment workflow. Let’s add it.

We’ll also install the Serverless plugin called serverless-finch, which allows us to configure and deploy to S3 buckets.

yarn global add serverless
yarn add serverless-finch --save-dev

yarn global add serverless
yarn add serverless-finch --save-dev

Now that we have our Serverless CLI installed, we init the serverless service in our project by running the following command to create a hello-world serverless service:

serverless create -t hello-world

serverless create -t hello-world

This will create a configuration yaml file and a handler lambda function. We don’t need the handler, so we can delete handler.js. Our serverless.yml should look like this:

service: serverless-s3
frameworkVersion: '2'
 
# The `provider` block defines where your service will be deployed
provider:
 name: aws
 runtime: nodejs12.x
 
functions:
 helloWorld:
   handler: handler.hello-world
     events:
     - http:
         path: helloWorld
         method: get
         cors: true

service: serverless-s3
frameworkVersion: '2'
 
# The `provider` block defines where your service will be deployed
provider:
 name: aws
 runtime: nodejs12.x
 
functions:
 helloWorld:
   handler: handler.hello-world
     events:
     - http:
         path: helloWorld
         method: get
         cors: true

The serverless.yml file contains configurations for a lambda function called hello-world. We can remove the functions block completely. After doing that, let’s register our Serverless Finch plugin:

service: serverless-s3
frameworkVersion: '2'
 
provider:
 name: aws
 runtime: nodejs12.x
 
plugins:
 - serverless-finch

service: serverless-s3
frameworkVersion: '2'
 
provider:
 name: aws
 runtime: nodejs12.x
 
plugins:
 - serverless-finch

Alright, now that our plugin is ready to be used, we can add details about our S3 buckets so it can deploy to it. Let’s add this block, which tells Serverless to use the serverless-s3-galileo bucket to deploy our code from the build directory. Make sure you use a different bucket name, as S3 bucket names are unique globally.

custom:
 client:
   bucketName: serverles-s3-galileo
   distributionFolder: build
   indexDocument: index.html
   errorDocument: index.html

custom:
 client:
   bucketName: serverles-s3-galileo
   distributionFolder: build
   indexDocument: index.html
   errorDocument: index.html

That is it! We’re ready to deploy our app on our bucket. Haven’t created a bucket yet? No problem—serverless-finch will automatically create it. The last thing we need to add is bucket-policy so our app can be accessed publicly. Let’s create our bucket policy.

Note: The indexDocument is the entry point for our web application, which is index.html in this case. We also need to add the same to errorDocument so our React routing works well in S3 hosting.

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Principal": {
               "AWS": "*"
           },
           "Action": "s3:GetObject",
           "Resource": "arn:aws:s3:::serverles-s3-galileo/*"
       }
   ]
}

{
   "Version": "2012-10-17",
   "Statement": [
       {
           "Effect": "Allow",
           "Principal": {
               "AWS": "*"
           },
           "Action": "s3:GetObject",
           "Resource": "arn:aws:s3:::serverles-s3-galileo/*"
       }
   ]
}

As the default access to S3 assets is private, we need to set up a bucket policy for our deployment bucket. The policy gives read-only access to the public for our app so we can browse the deployed assets in the browser. You can learn more about bucket policies. Let’s update our Serverless config to use our policy. This is how our serverless.yml should look:

service: serverless-s3
frameworkVersion: '2'
 
provider:
 name: aws
 runtime: nodejs12.x
 
plugins:
 - serverless-finch
 
custom:
 client:
   bucketName: serverles-s3-galileo
   distributionFolder: build
   indexDocument: index.html
   errorDocument: index.html
   bucketPolicyFile: config/bucket-policy.json

service: serverless-s3
frameworkVersion: '2'
 
provider:
 name: aws
 runtime: nodejs12.x
 
plugins:
 - serverless-finch
 
custom:
 client:
   bucketName: serverles-s3-galileo
   distributionFolder: build
   indexDocument: index.html
   errorDocument: index.html
   bucketPolicyFile: config/bucket-policy.json

Creating Github Actions Workflow

Assuming you’ve created your repo and pushed the code to it, we can start setting up our first workflow using Github Actions. As we’re using AWS for our Serverless deployments to S3, we need to provide the details of our IAM role. The env block allows us to insert custom env variables into the CI build. In this case, we need the AWS access key and secret access key to deploy build files to the S3 bucket. 

Github allows us to store secret values that can be used in the CI environment of Github Actions. You can easily set up these secrets for your repositories. This is how they should look when configured:

Now, we can move ahead and add a Github Action workflow. Let’s create a workflow file at the .github/deploy.yml location and add the following to it.

name: Serverless S3 Deploy
on:
 push:
   branches: [ master ]
 pull_request:
   branches: [ master ]

name: Serverless S3 Deploy
on:
 push:
   branches: [ master ]
 pull_request:
   branches: [ master ]

Alright, so the Github Actions config above tells Github to trigger this workflow whenever someone pushes to the master branch or creates a PR against it.

As of now, our action config is incomplete and does nothing. Let’s add our first and only job to the workflow:

name: Serverless S3
 
on:
 push:
   branches: [ master ]
 pull_request:
   branches: [ master ]
 
jobs:
 build:
   runs-on: ubuntu-latest
   strategy:
     matrix:
       node-version: [10.x]
   steps:
   - uses: actions/checkout@v2

name: Serverless S3
 
on:
 push:
   branches: [ master ]
 pull_request:
   branches: [ master ]
 
jobs:
 build:
   runs-on: ubuntu-latest
   strategy:
     matrix:
       node-version: [10.x]
   steps:
   - uses: actions/checkout@v2

Let’s try to digest the config above:

runs-on:  ubuntu-latest

The runs-on statement specifies which executor will be running the job. In this case, it’s the latest release of Linux Ubuntu variant.

Strategy: 

     Matrix:

        node-version: [10.x]

The strategy defines the environment we want to run our job on. This is usually useful when we want to run tests on multiple machines. In our case, we don’t want that. So, we’ll be using a single node environment with version 10.x

   steps:

   – uses: actions/checkout@v2

In the configuration’s steps block, we can define various tasks to be sequentially performed within a job. actions/checkout@v2 does the work of checking out branches for us. This step is required so we can do further work on our source code.

This bare minimum setup is required for running a job in our Github workflows. After this, we will need to set up the environment and deploy our application. So, let’s add the rest of the steps to it.

name: Serverless S3
 
on:
 push:
   branches: [ master ]
 pull_request:
   branches: [ master ]
 
jobs:
 build:
   runs-on: ubuntu-latest
   strategy:
     matrix:
       node-version: [10.x]
   steps:
   - uses: actions/checkout@v2
   - name: Use Node.js ${{ matrix.node-version }}
     uses: actions/setup-node@v1
     with:
       node-version: ${{ matrix.node-version }}
   - run: yarn install
   - run: yarn build
   - name: serverless deploy s3
     uses: serverless/github-action@master
     with:
       args: client deploy --no-confirm
     env:
       AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
       AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

name: Serverless S3
 
on:
 push:
   branches: [ master ]
 pull_request:
   branches: [ master ]
 
jobs:
 build:
   runs-on: ubuntu-latest
   strategy:
     matrix:
       node-version: [10.x]
   steps:
   - uses: actions/checkout@v2
   - name: Use Node.js ${{ matrix.node-version }}
     uses: actions/setup-node@v1
     with:
       node-version: ${{ matrix.node-version }}
   - run: yarn install
   - run: yarn build
   - name: serverless deploy s3
     uses: serverless/github-action@master
     with:
       args: client deploy --no-confirm
     env:
       AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
       AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

These actions need to be executed to deploy our frontend assets to our S3 buckets. As we read through the steps, we’re doing the following things in sequence:

1. Check out the current branch code

2. Setting up our node.js environment

3. Installing our dependencies with yarn install‍

4. Building our production build with yarn build‍

5. Deploying our build to S3 with serverless deploy –no-confirm‍

• The uses block defines which custom action we’re using
• The args block allows us to pass arguments to the actions
• The –no-confirm flag is needed so Serverless Finch does not ask us for confirmations while deploying to S3 buckets. 
• The args allows us to tell action to run it with specific arguments‍
• env allows us to pass custom environment variables to an action

Alright, so now we have the CD workflow setup to deploy our app. We can make a commit and push to the master branch. This should trigger our workflow. You can see your workflow running in the Actions section of your repository like this:

You can check the output of the serverless deploy step and browse the S3 website URL. It should now show our application running.

Creating CircleCI Workflow

To start building a repository, we need to authorize it with our Github account. You can do that by signing up for CircleCI and following the steps here.

As we did, add the IAM role secret credentials to our actions workflow. We can set up env variables for our workflows in CircleCI. This is how they should look once configured in the project settings:

Just like the Github Actions workflow, we can create workflows in CircleCI. CircleCI also allows us to use third-party custom plugins. We can use the available plugins called Orbs in our deployment workflows in CircleCI.

We’ll need the official CircleCI distributions of the aws-cli, serverless-framework, and node.js orbs for our deploy workflow. Let’s create our first job for our workflow:

version: 2.1
 
orbs:
 aws-cli: circleci/aws-cli@1.0.0
 serverless: circleci/serverless-framework@1.0.1
 node: circleci/node@4.1.0
 
jobs:
 deploy:
   executor: serverless/default

version: 2.1
 
orbs:
 aws-cli: circleci/aws-cli@1.0.0
 serverless: circleci/serverless-framework@1.0.1
 node: circleci/node@4.1.0
 
jobs:
 deploy:
   executor: serverless/default

The executor here is a prebuilt image, which allows us to run. 

Just like we defined steps for our jobs in Github Actions, we can add for CircleCI. Here we’re using commands made available from the node orb to install dependencies, build projects, and set up Serverless with AWS. Just like we set up the secrets for Github Actions, we need to define our AWS credentials under the CircleCI environment variables.

version: 2.1
 
orbs:
 aws-cli: circleci/aws-cli@1.0.0
 serverless: circleci/serverless-framework@1.0.1
 node: circleci/node@4.1.0
 
jobs:
 deploy:
   executor: serverless/default
   steps:
     - checkout
     - node/install-yarn
     - run:
         name: install
         command: yarn install
     - run:
         name: build
         command: yarn build
     - aws-cli/setup
     - serverless/setup:
         app-name: serverless-s3
         org-name: velotio
     - run:
         name: deploy
         command: serverless client deploy --no-confirm
workflows:
 deploy:
   jobs:
     - deploy:
         filters:
           branches:
             only:
               - master

version: 2.1
 
orbs:
 aws-cli: circleci/aws-cli@1.0.0
 serverless: circleci/serverless-framework@1.0.1
 node: circleci/node@4.1.0
 
jobs:
 deploy:
   executor: serverless/default
   steps:
     - checkout
     - node/install-yarn
     - run:
         name: install
         command: yarn install
     - run:
         name: build
         command: yarn build
     - aws-cli/setup
     - serverless/setup:
         app-name: serverless-s3
         org-name: velotio
     - run:
         name: deploy
         command: serverless client deploy --no-confirm
workflows:
 deploy:
   jobs:
     - deploy:
         filters:
           branches:
             only:
               - master

The workflows section in the above yml file indicates that we want to trigger the deploy workflow whenever our master branch gets updated. Just like we mentioned the steps for the Github Actions deploy job, we did the same for CircleCI jobs.

1. Check out the code
2. Install yarn package manager with node/install-yarn 
3. Install dependencies with yarn install
4. Build the project with yarn build
5. Setup AWS and Serverless CLI
6. Deploy to s3 with serverless client deploy –no-confirm

The workflow block in the config above tells CircleCI to run the deploy job. The filters block for the deploy job above tells us that we want to run the job only when the master branch gets updated. 

Once we’re done with the above setup, we can make a test commit and check whether our workflow is running.

Conclusion

We can easily integrate build/deployment workflows with simple configurations offered through Github Actions. If we don’t primarily use GitHub as version control, we can opt for CircleCI for our workflows.

Related Articles

1. Automating Serverless Framework Deployment using Watchdog
2. To Go Serverless Or Not Is The Question

You can find the referenced code at this repo.