CI - Preview Environments

Create a preview environment for every pull request using GitHub Actions
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 a Velocity Environment upon creation of a pull request (commonly referred to as "preview environments"). The Velocity Environment will contain the Velocity 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 Velocity Environment state can be easily seen, as well as any relevant links.
An example of a GitHub deployment notification in a Pull Request
Custom Actions you can use with Velocity
1.Providing a name for the Velocity Environment
2.Creating the Velocity Environment
3.Destroying the Velocity 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 a Velocity 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 Velocity 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 Velocity Service and {name} is a reserved keyword that will be replaced with the generated Velocity 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 a Velocity 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 Velocity Environment up-to-date with each commit's contents, by either creating a new Velocity 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) a Velocity 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 Velocity 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 Velocity Environment, so it will be accessed more conveniently. In addition, in case the Velocity 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 a Velocity Environment
Finally, whenever the PR gets closed, you will likely want to destroy the preview Velocity 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.
Tutorials - Previous
CI/CD
CD - Push blueprint updates
Last modified 2mo ago