# Source Control with VGS
Using a Source Control tool such as [git](https://git-scm.com/) provides you with a change control system allowing you to programmatically apply and compare changes and perform versioning without needing humans to manually apply changes. This is useful when you must apply changes in accordance with a specific Software Development Lifecycle (SDLC) for security or compliance purposes. By the end of this tutorial you will be able to utilize version control for route configurations using git. We also have a [fully working git flow example using Github Actions](https://github.com/vgs-samples/git-flow). ### Prerequisites 1. VGS CLI service account 2. VGS Dashboard account 3. Github account ### Overview In this guide, we cover: * How to install and set up the [vgs-cli](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli) * How to download your VGS Vault's routes and test them locally * How to integrate your VGS Routes changes into your git workflow. ## Install VGS CLI The [VGS CLI](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/getting-started) is a developer tool that helps you **build**, **test**, and **manage your configurations in VGS programmatically**. It enables the usage of VGS APIs in code or as a part of CI/CD pipelines. ### PyPI This option requires [Python 3](https://www.python.org/downloads/) to be installed. To install the latest VGS CLI from PyPI: ```bash pip install vgs-cli ``` Verify your installation by running: ```bash vgs --version ``` #### 1. Provision a Service Account After installing the CLI, you must [log in with your VGS account](https://dashboard.verygoodsecurity.com/) to authenticate the CLI in order to generate a service account programmatically. This is a one time step. ```bash vgs login ``` To create a service account for your organization do the following: 1. Generate the service account configuration from a template and store it to the `service_account.yaml` file ```bash vgs generate service-account -t vgs-cli > service_account.yaml ``` If needed, change the **name** and add/remove scopes according to your needs by editing the **service\_account.yaml** file. You can learn more about [scopes and resources](https://docs.verygoodsecurity.com/vault/vgs-cli/service-account#organization-resources)) to manage permissions. #### 2. Apply the service account configuration You can find your organization ID in the [VGS dashboard](https://dashboard.verygoodsecurity.com/) ```bash vgs apply service-account -O -f service_account.yaml ``` As a result of the above-mentioned steps, you will have an output that will look similar to: ```yaml apiVersion: 1.0.0 kind: ServiceAccount data: clientId: ACxxxxxxx-vgs-cli-xxxxx clientSecret: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx name: vgs-cli scopes: - access-logs:read - routes:write - vaults:read ``` Now, with **clientId** and **clientSecret,** you can set up [Authentication](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-cli/service-account) and test the VGS CLI. **Environment** ```bash echo export VGS_CLIENT_ID=ACxxxxxxx-vgs-cli-xxxxx >> ~/.bashrc echo export VGS_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx >> ~/.bashrc ``` or ```bash echo export VGS_CLIENT_ID=ACxxxxxxx-vgs-cli-xxxxx >> ~/.zshrc echo export VGS_CLIENT_SECRET=xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx >> ~/.zshrc ``` use source `~/.bashrc` or `source ~/.zshrc` respectively ## Working with routes Now we can store our current vault's route config in a file by piping the output from the CLI ```bash vgs get routes --vault > routes.yaml ``` Now, create a git repository to store YAML files of your routes: ```bash git init git add routes.yaml git commit -m "Initial commit" git branch -M master git remote add origin git@github.com:jsmth/my-routes.git git push -u origin master ``` ## Making changes to routes Now, let's say that we want to change the format of our credit card number [alias format](https://docs.verygoodsecurity.com/vault/tokens) to use a **Format Preserving, Luhn Valid (6T4)** representation so that BIN and the last four digits are preserved (e.g. `4111111111111111` becomes something like `4111119381251111`). In order to accomplish this, we need to: 1. Apply changes to our local routes file 2. Save changes to git 3. Apply updated routes to our vault 4. Check the vault's logs to see if everything is working correctly Let's start by updating the routes. We need to find the portions where `card_number` is being redacted and revealed in inbound and outbound routes, and changes the `public_token_generator` in both those locations from `UUID` to `FPE_SIX_T_FOUR`. You can check out all of the available VGS aliasing formats on our [docs](https://docs.verygoodsecurity.com/vault/tokens#alias-formats). ```bash git diff diff --git a/vgs_routes.yaml b/vgs_routes.yaml index b922a01..e8b089d 100644 --- a/vgs_routes.yaml +++ b/vgs_routes.yaml @@ -29,7 +29,7 @@ data: operation: REDACT operations: null phase: REQUEST - public_token_generator: UUID + public_token_generator: FPE_SIX_T_FOUR targets: - body token_manager: PERSISTENT @@ -79,7 +79,7 @@ data: operation: ENRICH operations: null phase: REQUEST - public_token_generator: UUID + public_token_generator: FPE_SIX_T_FOUR targets: - body token_manager: PERSISTENT ``` ## Apply changes to your git repo ```bash git add vgs_routes.yaml git commit -m "Changed UUID format to FPE_SIX_T_FOUR" git push -u origin master ``` ## Apply changes to your Vault To apply the newly created routes to our vault, make sure that the VGS CLI is running and authenticated. Then, use the `vgs apply` command: ```bash vgs apply routes --vault -f routes.yaml Route 4a74170c-2638-45c8-8880-1ea3cf66f38a processed Route 6d2135c7-f20b-46ba-bee6-e58159c42e6d processed Routes updated successfully for vault tntfpb2sssw ``` ### Verify Applied Changes You can validate that the changes were applied by fetching your Vaults route configuration again and comparing ```bash vgs get routes --vault > routes.yaml git diff ``` Congratulations, you've mastered the basics of using git to control your VGS Vault configuration. ### Next steps * [VGS Git Flow Example with Github Actions](https://github.com/vgs-samples/git-flow) * [Going Live](https://docs.verygoodsecurity.com/vault/developer-tools/vault-management/going-live) --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-git-flow.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.