> For the complete documentation index, see [llms.txt](https://docs.release.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.release.com/guides-and-examples/common-setup-examples/simple-static-build-example-gatsby-starter-theme.md).

# Static site with Gatsby

## Overview

You can use Release to deploy static sites to the Release CDN. Release can detect services inside your application that are eligible for [static service deployment](/reference-documentation/static-service-deployment.md) and you can choose to build and deploy these to the Release CDN, ensuring fast performance at the edge.

In this example, we'll use [Gatsby](https://www.gatsbyjs.com) to deploy a simple static site to the CDN. Gatsby is an open-source frontend framework designed to help you build fast, scalable, and SEO-optimised static sites. It's often used to run company blogs or websites.

Here's a look at the site we'll deploy to Release:

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-e8f53d6ca6325703238e34288176c2b8cc43c767%2Fgatsby-site-example.png?alt=media\&token=686f7808-b6de-4d1c-b974-b4fb45ec81ce)

We'll also take a look at how to manage and update the site once it is deployed.

## Get the example project

You can get the code for this project by forking the repository on [GitHub](https://github.com/awesome-release/gatsby-starter-theme). By forking the repository containing the code, you create a copy of it on your account. You can then edit this copy as you wish without needing permissions on the original project.

Once you’ve forked the repository to your account, clone your copy to your development machine.

```bash
git clone https://github.com/awesome-release/gatsby-starter-theme
```

## Source control integration

Once you’ve forked and cloned the repository, you can use the Release UI to integrate directly with your source-control provider (either GitHub or GitLab in this case).

To start, ensure that you are [signed in](https://app.releasehub.com/auth/login-page) to your Release account with the SSO provider for your source control integration.

When signing in, Release will ask for read/write access to the provider API so that it can list and view your repositories.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-855c1818a612f62dba246f2b6ce61c2985777842%2Frelease-authorisation.png?alt=media\&token=2900e8de-9679-4ac2-8703-dd08bf06e558)

{% hint style="info" %}
If you use the same email address across Bitbucket, GitLab, and GitHub, Release will automatically list a combined view of repositories for you. Each integration will appear separately on your profile page.
{% endhint %}

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-574a8ba54f04dbdd260701bb60edb3ff3be56c7b%2Frelease-source-control-integrations.png?alt=media\&token=4c04b83a-8a5e-4d6c-bbcd-c43839a2c826)

Once you’ve signed in, click the **Create New App** button on the [home page](https://app.releasehub.com/admin).

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-5a3f738bc90d7e0522f124833a023549577ed2eb%2Frelease-applications-view.png?alt=media\&token=54da9539-5eb2-4c9c-9ab2-899d56bb96be)

This will open a six-step form to help you create your application. The steps are as follows:

1. Create your application: Enter a name and select your repository.
2. Analyze your repository: Let Release scan your repository for services, then select which services to add to your application.
3. Generate a template: Based on the services you selected from your repository, Release generates a template for your application.
4. Set environment variables: Set the default environment variables for your new application.
5. Set build arguments: Set arguments to use when Release builds your application's Docker images.
6. Save and deploy: Deploy your new application.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-57a457f7a91669e49b4e0689488e2ea7119470a2%2Fcreate-application.png?alt=media\&token=2cd90778-f57d-4f2f-aa45-83e372af7b20)

Give the application a name and pick a repository and then click the **Next Step** button.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-c360f8015be196026ca77b5fb770fc62ef7b94c6%2Fanalyse-repository.png?alt=media\&token=99aee49c-3a70-4680-a8a2-818353264a3c)

Ensure that you have selected the correct branch for your repository to be built and deployed from (in this case, it is the `master` branch). From the **Select files** dropdown, select the `package.json` file for Release to analyze and click **Start Analysis**. Release will now read the file you selected and create a list of services found.

Release will **automatically detect** that your project contains static assets that are eligible for static asset deployment.

Double-check that Release has inferred the correct configuration for the project.

The service type dropdown should be set to **Static** with the Build Command being `yarn build`. The build **Output Directory** should be set to `public`. Click **Next Step** to move to the template generation step.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-bd01a8cc1cba2531f8e2aa31473159cd4643bc0e%2Fapp-template.png?alt=media\&token=62cad49d-bd54-4433-b57b-42b712f7797c)

The **Application Template** acts as a blueprint for new environments in this application. Release creates a template based on the services you selected in step two. You can edit the template or proceed to the next step.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-baf5182f7fa8820da1fb8b07f69ef28e55478248%2Fenv-variables.png?alt=media\&token=b7507535-6ec3-492c-8a4c-458bdb9dced0)

In this step, you can set default environment variables that will be available for all environments for your application. These environment variables consist of a key, a value, and an optional secret flag. For this application, you can proceed without setting environment variables.

In the next step, you can set build arguments. Build arguments are passed to Release's build process. You can proceed without setting build arguments for this application.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-bffdf299de4230432d265c4753ef8a487dbfb3b7%2Fsave-deploy.png?alt=media\&token=e8dc34c2-6fc5-492f-bb50-feb90db98eb4)

You've created your application and it is now time to save and deploy the application.

## The App Dashboard status page

While your application builds and deploys, you will be redirected to the App Dashboard status page.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-db5f8f1e641b2357daca0bf794a48f22cb4b4bdb%2Frelease-environments-view.png?alt=media\&token=aca0999f-8c46-400d-a493-b3396fe2fdca)

Here you can explore environments, builds, and deploys related to your application. You can also modify application-specific settings.

Click on the **Builds** tab to see a successful build for your Gatsby application.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-8b99cc48adc64e642b898ff31403d9de3009d266%2Frelease-view-builds.png?alt=media\&token=307804bb-b5a0-4e9e-91ad-0d2263d97700)

Once an ephemeral environment has been created and successfully deployed for your application, you should see a prompt.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-3cd2ddca4698bf2144afd601a0d29e976d1be3a7%2Frelease-view-environments.png?alt=media\&token=6796ef9d-4d23-4509-9e65-fde0459dc060)

You can also view this environment by clicking on the **Environments** tab.

## View environment details

Click on the name of an environment in the **Environments** tab to be taken to the Environment Details page.

Here you can view granular information about a particular environment, including the application instances deployed into it and the hostname URLs that exist.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-0e320b26055c3681ed1aef16fd07a44508c72371%2Frelease-deployed-environment.png?alt=media\&token=2405cfab-ef0d-4bdc-bf17-94c2aeaa27c2)

Click the hostname URL to go to your static website hosted on Release.

## Modify the application and deploy changes

In the real world, we would probably want to make changes to our application and redeploy it. Let’s add a new blog post to our application to see how this works.

Change directory into the repository we cloned earlier and open it in a text editor.

Create a new file in the `content/post` directory called `hello-release.mdx`. Add the following content to your newly created file:

```jsx
---
title: Hello Release
date: 2022-06-01
---

Hello, Release! This is a demo post illustrating how to make a change and redeploy a static website on Release.
```

Commit and push these changes to your remote repository:

```jsx
git add content/
git commit -m "Add a new post"
git push
```

Once you’ve pushed the changes, Release will automatically start a new build and deployment based on the latest commit in your repository.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-7ead519e5037d9f08f0567ff45dedfcd277c4c2b%2Frelease-build-after-change.png?alt=media\&token=44693697-e002-4636-a1b0-0990c5901884)

Once the deployment is complete, you should be able to see the updated blog at the same hostname URL you accessed earlier.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-52ced6ec229cdd4ea2e899d48bd537479c35fd55%2Frelease-updated-site.png?alt=media\&token=9fddbe18-235c-443d-b6f3-60c0bc40f54c)

## Deploy to a different branch

You probably don't want to deploy new changes directly to a production environment. Instead, you may have a development branch where you can send changes for review. Release allows you to create a new environment for this.

Let’s create a development branch in our repository and push a change to it.

```jsx
% git checkout -b develop
Switched to a new branch 'develop'
```

Create a new file in `content/posts` called `staged-post.mdx` and add the following content to it:

```jsx
---
title: Hello Release - Staged
date: 2022-06-01
---

This is a staged post that isn't in production yet.
```

Push the newly created `develop` branch remotely, including the new staged post:

```jsx
% git add .
% git commit -m "add new staged post"
[develop 3a00048] add new staged post
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 content/posts/staged-post.mdx
% git push --set-upstream origin develop
```

Navigate to the **Environments** tab in the App Dashboard of your application.

Click on **Create New Environment** and specify the `develop` branch.

![](https://585411240-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-M1neGLLQ0sDXeK6ooSo%2Fuploads%2Fgit-blob-04a45ae4eb636b212020dca9ae426ea4f42b69ba%2Frelease-new-environment.png?alt=media\&token=254616ce-86f7-4959-83ce-4b3865070b0e)

When you click **Create Environment**, Release will automatically build and deploy from the development branch.

View the deployed application by navigating to the hostname URL specified for this environment on its Environment Details page. You can now iterate and make changes on this branch without impacting your main environment.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.release.com/guides-and-examples/common-setup-examples/simple-static-build-example-gatsby-starter-theme.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.