diff --git a/astro/src/content/docs/get-started/run-in-the-cloud/github-actions.mdx b/astro/src/content/docs/get-started/run-in-the-cloud/github-actions.mdx index 92c134e60f..17c090a98c 100644 --- a/astro/src/content/docs/get-started/run-in-the-cloud/github-actions.mdx +++ b/astro/src/content/docs/get-started/run-in-the-cloud/github-actions.mdx @@ -44,7 +44,7 @@ You might have the following questions: Automating these tasks is called CI/CD or continuous integration and continuous deployment. - CI refers to testing changes to code you push to the main branch to ensure it fits in with the existing system and everything still works. -- CD refers to deploying every push to the main branch to your production (live) site. +- CD refers to deploying every push to the main branch of your production (live) site. GitHub provides a tool for automating workflows called GitHub Actions. It provides a virtual machine in which you can run scripts to check out your code, compile it, deploy alongside FusionAuth and other services, run tests, and manage deployment. @@ -54,11 +54,11 @@ The flow looks like the diagram below. ## A Simple Example Using GitHub Actions -There is a minimal but complete CI/CD example in this repository. An overview of the set-up is shown below. +There is a minimal but complete CI/CD example in this repository. An overview of the setup is shown below. -In GitHub, click Fork and add the repository to your GitHub account. Then run `git clone https://github.com//fusionauth-example-github-actions.git` in a terminal to download it. Remember to replace `` with your actual GitHub username. +In GitHub, click Fork and add the repository to your GitHub account. Then run `git clone https://github.com//fusionauth-example-github-actions.git` in a terminal to download it. Remember to replace `` with your GitHub username. Below is the repository structure. @@ -151,7 +151,7 @@ fa | 12:49:04.501 PM INFO JDBCMaintenanceModeDatabaseService - Unlock completed If you browse to FusionAuth again, you'll see that the user you created is still there. -The FusionAuth application is separate from the FusionAuth database. In this case, the database is stored in a Docker volume. When the upgrade scripts run, the data should not be broken, and upgrading FusionAuth should be unnoticeable. However, mistakes can happen, as well as database crashes, and you should backup both the FusionAuth database and your application database daily. The rest of this article will show you how to automate login tests to check that your system still works after upgrading FusionAuth or your app. If something breaks, you can restore the old version of the database and begin debugging. +The FusionAuth application is separate from the FusionAuth database. In this case, the database is stored in a Docker volume. When the upgrade scripts run, the data should not be broken, and upgrading FusionAuth should be unnoticeable. However, mistakes can happen, as well as database crashes, and you should back up both the FusionAuth database and your application database daily. The rest of this article will show you how to automate login tests to check that your system still works after upgrading FusionAuth or your app. If something breaks, you can restore the old version of the database and begin debugging. For more details on upgrading FusionAuth, including non-silent upgrades, please read this [article](/docs/get-started/download-and-install/docker#upgrading). @@ -232,7 +232,7 @@ Now that you know how to test your app after a change to it or FusionAuth, let's By default, GitHub prevents action workflows from running on forked repositories. To grant permission for the workflow to execute, navigate to the Actions tab on your forked repository and click on the I understand my workflows, go ahead and enable them button on the repository. -In this example we'll trigger the execution of the test by listening to push events on the main branch. Open the file `.github/workflows/test.yaml` in your IDE. The fifth line in the file specifies the branch name that triggers the execution of the action when commits are pushed to it. It currently reads as follows. +In this example, we'll trigger the execution of the test by listening to push events on the main branch. Open the file `.github/workflows/test.yaml` in your IDE. The fifth line in the file specifies the branch name that triggers the execution of the action when commits are pushed to it. It currently reads as follows. ```yaml - main_RENAME_THIS_TO_ENABLE_TEST @@ -293,7 +293,7 @@ The steps consist of two types of code: - Actions, which are existing tasks in GitHub like checking out a repository or installing Node.js. - Custom commands, which run code directly in the machine's terminal. -This script starts by checking out your repository then installing FusionAuth and Node.js using the respective actions. +This script starts by checking out your repository, and then installs FusionAuth and Node.js using the respective actions. ```yaml steps: @@ -330,9 +330,9 @@ Custom code then installs Node.js modules, runs the app, and runs the tests. Not working-directory: ./app ``` -Using the `fusionauth-github-action` is the preferred method to start FusionAuth in the workflow. If you want to start FusionAuth with Docker compose instead of the action you can use the commented out configuration in the `.github/workflows/test.yaml` file (for example if you need customizations such as to use a custom password hashing plugin). +Using the `fusionauth-github-action` is the preferred method to start FusionAuth in the workflow. If you want to start FusionAuth with Docker compose instead of the action, you can use the commented-out configuration in the `.github/workflows/test.yaml` file (for example, if you need customizations to use a custom password hashing plugin). -In the commented out workflow configuration the `services` section specifies that the action requires Docker where FusionAuth will run. +In the commented-out workflow configuration, the `services` section specifies that the action requires Docker where FusionAuth will run. ```yaml services: @@ -344,7 +344,7 @@ In the commented out workflow configuration the `services` section specifies tha - 9011:9011 ``` -Then FusionAuth will be started using `docker-compose` as shown below. +Then FusionAuth is started using `docker-compose`. ```yaml - name: Start FusionAuth in Docker @@ -428,7 +428,7 @@ The production environment might also be two mirrored applications and databases Each environment should correspond to a single branch in GitHub, and have its own set of secrets: passwords, URLs, and database values. -In this guide's sample application action, you set the action event to be triggered when pushing to the main branch (which corresponds to the production environment). You'll need to add other events and scripts to run tests, but not deploy, for all other environments and pull-request events. For example, you would probably want a push to the test branch to run tests, and deploy the new release to the test environment. +In this guide's sample application action, you set the action event to be triggered when pushing to the main branch (which corresponds to the production environment). You'll need to add other events and scripts to run tests, but not deploy, for all other environments and pull-request events. For example, you would probably want a push to the test branch to run tests and deploy the new release to the test environment. This application also used two `.env` files to store secrets that your app and FusionAuth use. In reality, you should never do this, as it allows anyone to access your private database with your password kept publicly on GitHub. @@ -449,11 +449,11 @@ Let's summarize what you need to do to test and deploy your application: - Configure your server to run Docker and the programming framework that your app uses. - Keep secrets safe and private in environment variables on each server, even from your developers. -- Backup your FusionAuth and app database frequently, and test that you can restore them successfully. +- Back up your FusionAuth and app database frequently, and test that you can restore them successfully. - Write Playwright tests that check your app can log in with FusionAuth and any other essential functionality, including new features that you are releasing. -- Write a GitHub action workflow that runs these tests when receiving a pull request or pushing code to a branch. +- Write a GitHub Actions workflow that runs these tests when receiving a pull request or pushing code to a branch. - Add secrets in GitHub that allow it to access your deployment environment. -- Add a deployment step to your GitHub action workflow that sends your new release to the server and starts it. +- Add a deployment step to your GitHub Actions workflow that sends your new release to the server and starts it. - Add a final step in the workflow to test that your Playwright tests work on the deployed server. - If your tests are successful, switch your public URL over to the latest release.