Create a staging workflow

[github-learning-lab[bot]]

Welcome to the course!

We'll learn how to create a workflow that enables Continuous Delivery. You'll:

• create a workflow to deploy to staging based on a label
• create a workflow to deploy to production based on merging to master

Before you start, you should be familiar with GitHub and Continuous Integration. If you aren't sure where to start, you may want to check out these two Learning Lab courses:

• Introduction to GitHub
• Continuous Integration with GitHub Actions

What is Continuous Delivery?

Martin Fowler defined Continuous Delivery very simply in a 2013 post as follows:

Continuous Delivery is a software development discipline where you build software in such a way that the software can be released to production at any time.

A lot of things go into delivering "continuously". These things can range from culture and behavior to specific automation. In this course, we're going to focus on deployment automation.

Kicking off deployments

Every deployment is kicked off by some trigger. Engineers at many companies, like at GitHub, typically use a ChatOps command as a trigger. The trigger itself isn't incredibly important. In our use case, we'll use labels. When someone applies a "stage" label to a pull request, that'll be our indicator that we'd like to deploy our application to a staging environment.

Step 1: Configure a trigger based on labels

In a GitHub Actions workflow, the on step defines what causes the workflow to run. In this case, we want the workflow to run whenever a label is applied to the pull request.

:keyboard: Activity: Configure the workflow trigger based on an a label being added

1. Edit the deploy-staging.yml file on this branch, or use this quick link (We recommend opening the quick link in another tab)
2. Change the name of the directory CHANGETHIS to workflows, so the title of this file with the path is .github/workflows/deploy-staging.yml
3. Edit the contents of this file to trigger on a label

Your result should look like this:

name: Staging deployment

on: 
  pull_request:
    types: [labeled]

jobs:
  build:
    runs-on: ubuntu-latest

[github-learning-lab[bot]]

It looks like you took an action I didn't expect.

I expected you to commit the file .github/workflows/deploy-staging.yml and a [labeled] trigger on the staging-workflow branch. Please try that to continue!

[github-learning-lab[bot]]

Job conditionals

GitHub Actions features powerful controls for when to execute jobs and the steps within them. One of these controls is if, which allows you run a job only when a specific condition is met. See jobs.<job_id>.if in Workflow syntax for GitHub Actions for more information.

Using information within GitHub

Workflows are part of the GitHub ecosystem, so each workflow run gives you access to a rich set of data that you can use to take fine-grained control.

We'd like to run our workflow on a specific label called stage, so we'll achieve this in a single line that packs a punch. We'll use:

• if: is the conditional that will decide if the job will run
• contains() is a function that allows us to determine if a value like say, a label named "stage", is contained within a set of values like say, a label array ["bug", "stage", "feature request"]
• github.event.pull_request.labels is specifically accessing the set of labels that triggered the workflow to run. It does this by accessing the github object, and the pull_request event that triggered the workflow.
• github.event.pull_request.labels.*.name uses object filters to filter out all information about the labels, like their color or description, and lets us focus on just the label names.

Step 2: Trigger a job on specific labels

Let's put all this together to run our job only when a labeled named "stage" is applied to the pull request.

:keyboard: Activity: Choose the Ubuntu environment for our app

1. Edit the deploy-staging.yml file on this branch, or use this quick link (We recommend opening the quick link in another tab)
2. Edit the contents of the file to add a conditional

Your results should look like this:

name: Staging deployment

on: 
  pull_request:
    types: [labeled]

jobs:
  build:
    runs-on: ubuntu-latest

    if: contains(github.event.pull_request.labels.*.name, 'stage')

[github-learning-lab[bot]]

Workflow steps

So far, the workflow knows what the trigger is and what environment to run in. But, what exactly is supposed to run? The "steps" section of this workflow specifies actions and scripts to be run in the Ubuntu environment when new labels are added.

Step 3: Write the steps for the staging workflow

We won't be going into detail on the steps of this workflow, but it would be a good idea to become familiar with the actions we're using. They are:

• actions/checkout
• actions/upload-artifact
• actions/download-artifact
• github/deploy-nodejs

The course Using GitHub Actions for CI also teaches how to use most of these actions in details.

:keyboard: Activity: Deploy a Node.js app to AWS for the first time

1. In a new tab, create an AWS account if you don't already have one.

   Note: You may need a credit card to create an AWS account. If you're a student, you may also be able to take advantage of the Student Developer Pack for access to AWS. If you'd like to continue with the course without an AWS account, Learning Lab will still respond, but none of the deployments will work.

2. Add a user in the IAM service with administrator permission.
   • For detailed instructions on adding users, see Creating an IAM User in Your AWS Account in the AWS docs.
3. In the confirmation screen, copy both the Access key ID and the Secret access key to a safe space. We'll use these in the next few steps as follows:
   • Access key ID ➡️ AWS_ACCESS_KEY
   • Secret access key ️️️ ➡️ AWS_SECRET_KEY
4. Back on GitHub, click on this repository's Secrets in the Settings tab.
5. Click Add a new secret
6. Name your new secret AWS_ACCESS_KEY and paste the value from the Access key ID generated on AWS.
7. Click Add secret.
8. Click Add a new secret again.
9. Name the second secret AWS_SECRET_KEY and paste the value from the Secret access key generated on AWS.
10. Click Add secret
11. Back in this pull request, edit the .github/workflows/deploy-staging.yml file to use a new action, or use this quick link (We recommend opening the quick link in another tab)

    - name: Deploy to AWS
      uses: github/deploy-nodejs@master
      env:
        AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
        AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}

    If you'd like to copy the full workflow file, it should look like this:

name: Staging deployment

on: 
  pull_request:
    types: [labeled]

jobs:
  build:
    if: contains(github.event.pull_request.labels.*.name, 'stage')

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1
      - name: npm install and build webpack
        run: |
          npm install
          npm run build
      - uses: actions/upload-artifact@master
        with:
          name: webpack artifacts
          path: public/

  deploy:
    name: Deploy Node.js app to AWS
    needs: build
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v1

      - name: Download built artifact
        uses: actions/download-artifact@master
        with:
          name: webpack artifacts
          path: public

      - name: Deploy to AWS
        uses: github/deploy-nodejs@master
        env:
          AWS_ACCESS_KEY: ${{ secrets.AWS_ACCESS_KEY }}
          AWS_SECRET_KEY: ${{ secrets.AWS_SECRET_KEY }}

[github-learning-lab[bot]]

Completed Workflow

Nice job, you've done it!

It won't be "working" yet, because our next step is to work on the configuration files that AWS will need. But, the logic for this workflow is complete.

Step 4: Merge the staging workflow

:keyboard: Activity: Merge this staging workflow pull request

1. Merge this pull request
2. Delete the staging-workflow branch

[github-learning-lab[bot]]

You can find your next steps in the next pull request.