Search…
Create test environments using GitHub Actions
Spin up preview environments with a pull request in GitHub.
You can integrate Velocity into your CI/CD workflows if you are using GitHub Actions. To learn more about GitHub Actions, refer to GitHub's documentation.
For example, you can utilize Velocity's GitHub Actions to create an environment upon creation of a pull request (commonly referred to as "preview environments"). The environment will contain the services and code the PR has changed, and will be kept up-to-date whenever the PR gets updated.
This makes it simple to see and test the proposed changes in addition to reviewing the PR.
Furthermore, a GitHub deployment can be attached to the pull request, so the environment state can be easily seen, as well as any relevant links.
An example of a GitHub deployment notification in a Pull Request
There are three custom actions you can use with Velocity:
  1. 1.
    Providing a name for the environment
  2. 2.
    Creating the environment
  3. 3.
    Destroying the environment
To use any GitHub Action, you need to commit workflow files to your repository, as described in the GitHub documentation.
You will need a VELOCITY_TOKEN which you can get by contacting the Velocity Support team.

Supplying an environment's name

Every Velocity environment needs to have a unique name. It is recommended to use the techvelocity/env-name-action action to generate a name.
Then, you can pass the newly generated name to other actions (such as techvelocity/env-create-action and techvelocity/env-destroy-action) so they will reference the same environment even as the PR changes.
To use this action, include the following in your workflow file:
- uses: techvelocity/env-name-[email protected]
id: env-name # an identifier that could be used in the subsequent steps
To further customize the environment name, you may supply a pattern (optional). A common value might be:
- uses: techvelocity/env-name-[email protected]
id: env-name
with:
pattern: "service-{name}"
Where service is the name of the service in Velocity and {name} is a reserved keyword that will be replaced with the generated environment name. If a pull request number is available to the action the resulting name will be service-pr-<pr number>. If no pull request number is available, the resulting name will be service-<branch>.
For further discussion and examples, refer to the action's documentation.

Creating or updating an environment

The very heart of the "environment per PR" notion lies in this action. Behind the scenes, this action uses the Velocity CLI in order to keep the environment up-to-date with each commit's contents, by either creating a new environment or updating it as needed.
To use the action, include the following in your workflow file:
- uses: techvelocity/env-create-[email protected]
with:
velocity-token: ${{ secrets.VELOCITY_TOKEN }}
services: '${{ env.VELOCITY_SERVICE }}:${{ env.IMAGE_NAME }}:${{ env.IMAGE_TAG }}'
name: ${{ env.ENV_NAME }}
use-gh-deployments: 'false'
use-gh-comments: 'false'
env:
VELOCITY_SERVICE: myservice
This will create (and update) an environment named according to the ENV_NAME environment variable, with the given service name, image name (optional) and tag. Use a comma (,) to separate multiple services. Make sure that the VELOCITY_TOKEN is defined as a secret in your repository.
To use the environment name generated by env-name-action, simply replace the value of the name parameter with:
name: ${{ steps.env-name.outputs.name }}

Optional: GitHub Deployments

This action can optionally associate a GitHub deployment to the environment so it will be accessed more conveniently. In addition, in case the environment creation or update fails, the action can comment on the originating PR with the latest environment status. To do that, create a GitHub token as a repository secret and set it as input to the action:
- uses: techvelocity/env-create-[email protected]
with:
velocity-token: ${{ secrets.VELOCITY_TOKEN }}
services: '${{ env.VELOCITY_SERVICE }}:${{ env.IMAGE_TAG }}'
name: ${{ steps.env-name.outputs.name }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
VELOCITY_SERVICE: myservice
VELOCITY_DOMAIN: viron.xyz
For even greater comfort, provide both the VELOCITY_SERVICE and VELOCITY_DOMAIN environment variables with the Velocity service name and custom domain configured for your account, respectively. This will enable the GitHub deployment notification as mentioned above, as well as a View Deployment button to open the service's public URI.
For further discussion and examples, refer to the action's documentation.

Destroying the environment

Finally, whenever the PR gets closed, you will likely want to destroy the preview environment as well. To do so, you can create a workflow with this step:
- uses: techvelocity/env-destroy-[email protected]
with:
velocity-token: ${{ secrets.VELOCITY_TOKEN }}
name: ${{ steps.env-name.outputs.name }}
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Change the name input if you didn't use the techvelocity/env-name-action in a previous step. As always, if you don't want to decommission the GitHub deployment upon destroy nor provide a GitHub token for this action, set the use-gh-deployments input to 'false'.
For further discussion and examples, refer to the action's documentation.
Copy link
On this page
Supplying an environment's name
Creating or updating an environment
Destroying the environment