Publishing & deployment

Overview

Now that we've updated our codebase, it's time to deploy the code, publish our schemas, and make use of our graph variants.

In this lesson, we will:

Learn how to automatically deploy changes to the staging and production environments
Learn how to apply the deployment steps from the staging environment to the production environment
Learn how to publish schema changes to the staging variant as part of the CD pipeline

Publishing to the schema registry in the CD workflow

Let's review the original CD workflow.

Diagram of the original CD workflow. See detailed image description below.

Originally, the Airlock graph only tracked the production version of the graph (the current variant). Earlier in the course, we added a staging variant to the graph to correspond to the staging environment of our subgraphs. Let's make sure to update our CD workflow!

After deploying to the staging environment, we'll publish our subgraph schema changes to the staging variant of our graph, which will trigger a launch. This process will all be taken care of automatically by two separate GitHub Actions, which we'll take a look at in the next section.

The diagram below shows our updated CD workflow, for the staging deploy. We'll have a separate (and similar!) diagram for the production deploy.

Diagram of the updated CD workflow - focusing on the staging environment. See detailed image description below.

Staging deploy

The Airlock CD pipeline includes a GitHub Action called Staging Deploy, which is responsible for deploying the code to the staging environment on Heroku. This job is automatically triggered when a pull request is merged to our main branch.

This takes care of keeping the Heroku staging apps up to date with the main branch of our GitHub repo.

Publish schema to staging

After the Staging Deploy job runs, another begins automatically: the Staging Publish Schema job. This job publishes the subgraph schema to the staging variant in the schema registry.

This job uses the rover subgraph publish command behind the scenes to publish the schema changes to the relevant subgraph in GraphOS.

Seeing the CD workflow in action

Let's see the jobs in action! After the Listings team has reviewed the changes in the pull request, we can click Merge to merge the updates into the main branch of the listings subgraph's repository.

This triggers the Staging Deploy job to deploy the changes to the Heroku app for the listings subgraph's staging environment.

Here's a screenshot of the GitHub Actions page showing the workflows that have run so far. Currently, the Staging Deploy job for the PR that was just merged is running.

https://github.com

Screenshot of GitHub Actions with Staging Deploy job in progress

When clicking the Staging Deploy job, we can follow the job's progress until it completes.

https://github.com

Screenshot of GitHub Actions with Staging Deploy job completed

After the job successfully completes, it triggers the next job, Staging Publish Schema, which publishes the new listings subgraph schema to the staging variant on GraphOS.

https://github.com

Screenshot of GitHub Actions with Publish Schema to Staging job in progress

Clicking into the details of the job, we can see the schema was successfully published to the staging variant.

https://github.com

Screenshot of Publish Schema to Staging job in GitHub completed

What happens after a schema is published to the registry? A launch starts! We can see the steps in the launch process in the Launches page of Studio, making sure we have the staging variant of our graph selected.

https://studio.apollographql.com

We can see that Launch Sequence section for this specific launch follows the steps we had covered in lesson 4: Schema checks in a supergraph. And this launch completed successfully! 🎉

Now, Lisa's changes to the listings subgraph are available in Airlock's staging environment. Teammates and other stakeholders can use the Apollo Explorer to test out the new supergraph and make sure everything works as expected.

Deploying to production

After initial testing on displaying the galactic coordinates for a listing on the staging environment is completed, we can try out deploying to production.

The diagram below illustrates the steps in our app's production workflow—and it looks a lot like our plan for the staging environment!

Diagram of the updated CD workflow - focusing on the production environment. See detailed image description below.

When we're ready to update our production environment, we first want to deploy our main code branch to the production version of the corresponding Heroku app. To do this, we can run the Production Deploy job manually on GitHub.

This pushes the latest code changes from the main branch on GitHub to the production environment hosted on Heroku. When this succeeds, it triggers another job called Production Publish Schema, which publishes the updated subgraph schema to our graph's current variant. This initiates a new launch, and we're back in the same process we've already covered in the staging environment!

Interested in what this looks like in action using GitHub? See below for detailed steps and screenshots!

Navigate to the Actions page, select Production Deploy from the list.
Click the Run workflow dropdown, select the main branch and click Run workflow to initiate the workflow.

https://github.com

Screenshot of GitHub Actions page running the Production Deploy workflow manually

Here is the workflow file for that job:

.github/workflows/deploy-prod.yml

# This job deploys the code to the production Heroku app environment
name: Production Deploy 

# This job is triggered manually in the GitHub UI
on: workflow_dispatch 

jobs:
  deploy:
    name: Deploy to production
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4.1.5
      - uses: akhileshns/heroku-deploy@v3.13.15
        with:
          heroku_api_key: ${{ secrets.HEROKU_API_KEY }}
          heroku_app_name: ${{ secrets.HEROKU_APP_NAME }}
          heroku_email: ${{ secrets.HEROKU_EMAIL }}

Refresh the page and select the job that was initiated. When this job successfully completes, another one is triggered.
Go back to the Actions page and select the Production Publish Schema workflow from the list. We'll see a new job running.

Here is the workflow file for that job:

.github/workflows/publish-schema-prod.yml

# This job deploys the code to the production Heroku app environment
name: Publish Schema Production 

workflow_run:
  workflows: ['Production Deploy']
  types:
    - completed 

jobs:
  publish_schema:
    name: Publish schema to current variant
    if: ${{ github.event.workflow_run.conclusion == 'success' }}
    runs-on: ubuntu-latest
    environment: apollo
    env:
      APOLLO_KEY: ${{ secrets.APOLLO_KEY }}
      APOLLO_VCS_COMMIT: ${{ github.event.pull_request.head.sha }}
      GRAPH_ID: airlock-managed-fed
      SUBGRAPH: reviews
    steps:
      - uses: actions/checkout@v4.1.5
      - name: Install Rover
        run: |
          curl -sSL https://rover.apollo.dev/nix/v0.1.0 | sh 

          # Add Rover to the $GITHUB_PATH so it can be used in another step
          # https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#adding-a-system-path
          echo "$HOME/.rover/bin" >> $GITHUB_PATH
      - name: Publish subgraph to production registry
        run: |
          rover subgraph publish $GRAPH_ID --schema ./${SUBGRAPH}.graphql --name $SUBGRAPH

Wait for this to complete successfully. Next, it will trigger a launch in GraphOS, which you can find in the Launches page of the current variant of the graph.

https://studio.apollographql.com

Screenshot of the Launches page in Studio

What happens when we want to update how the router is configured? Let's take a moment to look at what goes into the process of making changes and deploying them!

All of the code for the router lives in a single GitHub repository. It includes the router binary, the config.yaml configuration file, and a Procfile, which is specific to Heroku, where the router is hosted.

airlock-router
┣ router
┣ config.yaml
┗ Procfile

Like any other GitHub repository, we can clone and run the router repo locally. When we make changes, we open up a new PR and (once it's approved!) merge the new code to the main branch of the repo. From there, a few things are ready to occur.

Diagram describing how the router deployment process happens: after merging code changes, the router is automatically deployed to the staging environment. Deploys to production must be triggered manually.

The router repo is set up to deploy to two apps on Heroku: one for the staging environment, and one for production. Just as we've seen with our subgraph repos, when we merge code to the main branch, the deploy to the staging environment happens automatically.

When we query our staging app on Heroku, we're running operations against our graph's staging variant. This is because we've configured the Heroku app to connect to the staging variant, using the APOLLO_GRAPH_REF and APOLLO_KEY environment variables.

https://studio.apollographql.com

Screenshot of Airlock's staging app on Heroku, displaying the staging environment variables that have been configured

While the deploy to the staging app occurs automatically, we don't want to push our changes to production in the same way. Once we've tested out the updates to the staging variant and feel confident our router is running as expected, we can manually trigger a deploy of the main branch to our router's production app on Heroku. The production app runs operations against the current variant of our graph.

https://studio.apollographql.com

Screenshot of Airlock's production app on Heroku, displaying the production environment variables that have been configured

We need both instances of the router to test our staging and current graph variants separately. Heroku allows us to set a command in the router's Procfile that specifies the environment variables to use when running the router in different environments.

Diagram detailing the command that runs the router for both staging and production, with the difference of which environment variables are used

By keeping the method of deployment for each of our environments separate, we can make sure that any changes we've made to the router or its config.yaml file continue to work correctly.

Practice

Which of the following events triggers a launch in GraphOS?

When a subgraph schema is updated in a local dev environmentWhen a schema check is run locallyWhen a subgraph schema is published to the registryWhen a schema check is run as part of a CI pipeline

Key takeaways

We can automate publishing a subgraph to the registry inside our CD pipeline using the rover subgraph publish command.
Publishing a subgraph schema to any variant in the registry triggers a launch. We can view the launch sequence in the Launches page of Studio.

Up next

And there we go! We've integrated publishing to the schema registry into our CD pipeline, running automatically for us! All our checks passed successfully here, but in the next two lessons we'll see what happens when things don't go smoothly.

Overview

Publishing to the schema registry in the CD workflow

Staging deploy

Publish schema to staging

Seeing the CD workflow in action

Deploying to production

Practice

Key takeaways

Up next

Share your questions and comments about this lesson