GitHub actions on pull requests

Limited vCluster Tenancy Configuration Support

This feature is only available when using the following worker node types:

Host Nodes

GitHub Actions can be created for the following workflows:

• Setup vCluster: Installs the vCluster CLI
• Setup DevSpace: Installs the DevSpace CLI

Deploying virtual clusters on pull requests

These examples show how to create and delete Virtual Clusters for pull requests.

Basic

This example shows how to create and delete a virtual cluster for testing an application named the-app on pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to vCluster Platform instance
        env:
          LOFT_URL: ${{ secrets.LOFT_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $LOFT_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster create $NAME --project default
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e
      - name: Delete PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster delete $NAME --project default

Explanation:

1. The Setup vCluster action is used to install the vCluster CLI.
2. The vcluster platform login command is used to log in to the organization's platform instance. Environment variables LOFT_URL and ACCESS_KEY are populated using GitHub secrets. See Access Keys for help generating a platform access key.
3. The vcluster create command is used to create a unique virtual cluster using information about the pull request in the default project. This automatically configures the kube context for the next steps.
4. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
5. Before running tests, use kubectl to wait for the the-app deployment to become ready.
6. Now, run the end-to-end tests. The example uses make to run tests, but the command should be customized for your testing framework.
7. Finally, the vcluster delete command is used to delete the virtual cluster.

Automatic Cleanup

This example shows how to create and reuse a virtual cluster for testing an application named the-app on pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to vCluster Platform instance
        env:
          LOFT_URL: ${{ secrets.LOFT_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $LOFT_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster create $NAME --project default --upgrade
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e

Explanation:

1. The Setup vCluster action is used to install the vCluster CLI.
2. The vcluster platform login command is used to log in to the organization's platform instance. Environment variables LOFT_URL and ACCESS_KEY are populated using GitHub secrets.
3. The vcluster create command is used to create a unique virtual cluster using information about the pull request in the default project. This automatically configures the kube context for the next steps. The --upgrade flag has been added to reuse the existing virtual cluster and upgrade it to the latest version. Additional flags may be used to control the desired virtual cluster version.
4. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
5. Before running tests, use kubectl to wait for the the-app deployment to become ready.
6. Now, run the end-to-end tests. The example uses make to run tests, but the command should be customized for your testing framework.

Reuse

This example shows how to automatically delete a Virtual Cluster after testing an application named the-app for pull requests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - 'main'
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install vCluster CLI
        uses: loft-sh/setup-loft@main
        with:
          url: ${{ secrets.LOFT_URL }}
          access-key: ${{ secrets.LOFT_ACCESS_KEY }}
      - name: Create Virtual Cluster for PR
        uses: loft-sh/create-vcluster@main
        with:
          name: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
          auto-cleanup: true
      - name: Deploy Application
        run: kubectl apply -Rf ./kubernetes
      - name: Wait for Deployment
        run: kubectl rollout status deployments/the-app
      - name: Run Tests
        run: make e2e

Explanation:

1. The Setup Loft action is used to install the vCluster CLI and login using the provided url and access-key.
2. The Create Virtual Cluster action is used to create a unique virtual cluster using information about the pull request. This automatically configures the kube context for the following steps. Additionally, the auto-cleanup option is enabled, which deletes the virtual cluster after the job completes.
3. The next step deploys the application using the runner provided kubectl and manifests located under ./kubernetes.
4. Before running tests, use kubectl to wait for the the-app deployment to become ready.
5. Finally, run the end-to-end tests. This example uses make to run tests, but the command should be customized for your testing framework. There's no need to delete the virtual cluster since the auto-cleanup option was used when creating the virtual cluster.

DevSpace for running tests on pull requests

This example shows how use the Setup DevSpace GitHub Action to install the DevSpace CLI and DevSpace commands to run tests.

# .github/workflows/vclusters.yaml
name: Pull Request Checks
on:
  pull_request:
    branches:
      - "main"
jobs:
  e2e:
    runs-on: ubuntu-latest
    steps:
      - name: Install DevSpace CLI
        uses: loft-sh/setup-devspace@main
      - name: Install vCluster CLI
        uses: loft-sh/setup-vcluster@main
      - name: Login to platform instance
        env:
          LOFT_URL: ${{ secrets.LOFT_URL }}
          ACCESS_KEY: ${{ secrets.ACCESS_KEY }}
        run: vcluster platform login $LOFT_URL --access-key $ACCESS_KEY
      - name: Create PR Virtual Cluster
        env:
          NAME: repo-${{ github.event.repository.name }}-pr-${{ github.event.pull_request.number }}
        run: vcluster create $NAME --project default
      - name: Run Tests
        run: devspace run e2e

Explanation:

1. The Setup DevSpace action installs the DevSpace CLI.
2. The Setup vCluster action is used to install the vCluster CLI.
3. The vcluster platform login command is used to log in to the organization's platform instance. Environment variables LOFT_URL and ACCESS_KEY are populated using GitHub secrets.
4. The vcluster create command is used to create a unique virtual cluster using information about the pull request in the default project. This automatically configures the kube context for the next steps.
5. Finally, use devspace run e2e to perform the needed steps to deploy and test my-app.