Skip to main content

Preview Environments with Github

This section will show you how to automatically create a preview environment for your applications using Okteto Cloud and Github Actions.

Pre-Requisites#

For this tutorial, we'll be using this application.

Step 1: Fork the Repository#

Start by forking the kubernetes-preview-environment repository with your Github account.

Step 2: Create the Github Workflow#

To create the preview environments, we will use our Github Actions for Okteto Cloud.

Creating a preview environment requires performing the following steps:

  1. Log into Okteto Cloud.
  2. Deploy a preview environment in Okteto Cloud.
  3. Update the PR with the URL of the preview environment.

The sample repository configured to use the workflow described above. If you want to use this on for your repositories, all you need to do is to create a .github/workflow folder in the root of your repo, and save your workflow file in it.

The workflow file to create the preview environments for Okteto Cloud users looks like this:

# file: .github/workflows/preview.yaml
on:
pull_request:
branches:
- master
jobs:
preview:
runs-on: ubuntu-latest
steps:
- name: Login
uses: okteto/[email protected]
with:
token: ${{ secrets.OKTETO_TOKEN }}
- name: Deploy preview environment
uses: okteto/deploy-[email protected]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
name: pr-${{ github.event.number }}-cindylopez
scope: personal
timeout: 15m

There are two scopes for preview environments, personal, where the only one who has access to the environment is the user, and global, where all cluster members have access to it and do not need to have the user's name at the end of the preview environment name. To create a preview environment with global scope it is necessary to have administrator permissions.

Preview Environments for Okteto Enterprise Users#

To configure preview environments for Okteto Enterprise, your GitHub workflow file will look like this:

# file: .github/workflows/preview.yaml
on:
pull_request:
branches:
- master
jobs:
preview:
runs-on: ubuntu-latest
steps:
- name: Login
uses: okteto/[email protected]
with:
token: ${{ secrets.OKTETO_TOKEN }}
url: ${{secrets.OKTETO_URL}}
- name: Deploy preview environment
uses: okteto/deploy-[email protected]
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
with:
name: pr-${{ github.event.number }}-cindylopez
scope: personal
timeout: 15m

The workflow file requires anOKTETO_URL secret variable which is your enterprise domain on Okteto. Create a repository secret OKTETO_URL containing your enterprise url e.g okteto.example.com.

Step 3: Configure your Okteto API Token#

If you noticed, the workflow uses the secrets:OKTETO_TOKEN. We do this, so we don't have to commit the token into our repo. Before you run this workflow you need to create the OKTETO_TOKEN secret in your repository, with your personal access token as the value.

Follow the process in this guide to create a personal access token.

Learn more about repository secrets in Github's official documentation.

Step 4: Open a Pull Request#

Once your changes are in your repository, go ahead and open a new pull request. Github will receive the event, and it will start your workflow. You can see the workflow's status and logs in the checks section of the pull request.

checks section of pull request

Step 5: See your changes live#

After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on it to see the changes in real-time.

preview environment message with URL

Every time the branch is updated, the same workflow will run, automatically updating the preview environment.

Step 6: Cleanup#

The sample repo also includes a workflow to cleanup the preview environments once the pull request is closed. We recommend you follow this pattern to remove the preview environment after merging a pull request automatically.

# file: .github/workflows/preview-closed.yaml
on:
pull_request:
types:
- closed
jobs:
closed:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/[email protected]
- name: Login
uses: okteto/[email protected]
with:
token: ${{ secrets.OKTETO_TOKEN }}
- name: Delete preview environment
uses: okteto/destroy-[email protected]
with:
name: pr-${{ github.event.number }}-cindylopez

For Okteto Enterprise users:

# file: .github/workflows/preview-closed.yaml
on:
pull_request:
types:
- closed
jobs:
closed:
runs-on: ubuntu-latest
steps:
- name: checkout
uses: actions/[email protected]
- name: Login
uses: okteto/[email protected]
with:
token: ${{ secrets.OKTETO_TOKEN }}
url: ${{secrets.OKTETO_URL}}
- name: Delete preview environment
uses: okteto/destroy-[email protected]
with:
name: pr-${{ github.event.number }}-cindylopez