Introduction & Summary
The recent introduction of Rivery CLI (Command-Line-Interface) has opened up a new host of programmatic workflows to run, edit, deploy and manage rivers that developers can take advantage of. Logic river configurations are defined by .yaml configuration files that can be edited in a simple text editor and synced with VCS tools like GitHub. In this community article, we explore setting up your GitHub remote repository to work with your Rivery account (via command line) so that you can synchronize changes, create branches, and make commits to existing logic river configurations, while also keeping track of changes and versions.
Prerequisites
In order to execute the flow described in this article, you will need the following tools/skills.
- A GitHub Account.
- The latest version of Git Bash (if using Windows) installed on your computer (default settings on the installation prompt should be fine). While it is possible to use Windows Powershell to pull, add, commit and push changes, the syntax can vary and Unix is the development standard.
- A latest version of the Rivery Command-Line-Interface installed on your computer. Please see this article for installation and setup instructions.
- A Rivery account with at least one Logic River that you wish to add to a remote repository on GitHub.
- A Rivery API key to use with the CLI tool created in your Rivery account.
- Elementary knowledge of basic command line and shell scripting.
- Elementary knowledge of GitHub VCS including branches, pulls, commits, and clones.
Setup
1. Initialize a remote Git repository (“repo”).
Navigate to your GitHub account and create a new repository to make your commits (if not using an existing one).
Follow the on-screen instructions and make sure to check the “Add a Readme file” in the settings.
2. Clone the remote repository to your desktop to synchronize changes.
Now, we want to create a working directory on our desktop to synchronize changes with the remote repository (the one stored in the GitHub VCS). We do this via the command git clone in Git Bash. In order to do this, we need to retrieve the HTTPS link in order to issue the bash command to pull the files in the remote repo and clone them on our desktop. You can find the https link by clicking on the repo, going to the dropdown under “Code”, selecting “HTTPS” and copying the link.
Open up Git Bash, navigate to a directory where you want to create a clone of your Git repo and run the following command:
git clone <your_HTTPS_link>
You should now have a folder with the name of your github repo in your directory with an empty Readme file.
3. Create a new branch to add files to.
Following Github VCS best practices, we don’t want to make commits directly into the “master” branch, but rather into our own working branch. Once the changes have been reviewed and verified, we can then merge those changes into the master branch via a pull request. To create your own working branch run the following command in Git Bash:
git checkout -b <your_branch_name>
This command will create a new branch and switch your working branch to the one that was just created.
4. Initialize the Rivery CLI and create a new project.
Using your terminal, activate the python virtual environment in which you installed the Rivery CLI and navigate to the local git directory that you created in step (2).
Run the command:
rivery init
And follow the instructions to assign a project name. You should now have a blank project.yaml file in your directory. This tells you that the command was successful and the project has been initiated.
5. Create a new profile.
In order to send the .yaml configuration that you edit/create to your rivery account, you need to create an authenticated profile(s) to hold the credentials. Rivery stores these credentials in an “entity” called profile in your project directory. The API token that you created in the prerequisites is unique to the account+environment that it was created from. Therefore, you will need to create a new profile for every account+environment combination that you are using. To create a profile, execute:
rivery configure
And follow the associated text prompts to create the profile (you will need the API token from the prerequisites section).
6. Extract the .yaml configuration file(s) from your Rivery account into your local directory.
Now you are ready to extract your desired logic river in your rivery account as a .yaml configuration file. Run the following command in your terminal/cmd to pull the configuration. Make sure to have your river_id, and the name of your profile handy:
rivery rivers --profile=<your_profile_name> import --riverId=<your_river_id> --path=<your_path>
You will also be able to import the configuration for a group of rivers with this command:
rivery rivers import --groupName=<your_group_name> --path=<your_path_name>
You should now see a single or a list of .yaml config files in your local directory specified by the --path argument.
7. Add changes from your local directory to the local git repository.
You are now ready to add changes to your local directory to your local repository, then push these changes to the remote repository (your GitHub account).
Using the
git status
command in Git Bash, you can retrieve a list of all files in the directory which are “untracked” (that is, in the directory but who’s changes are not set up to be synchronized with the local repository).
Using git add, specify the files that you wish to track from the list obtained by running the git status command above (separating each file by a space).
git add …
You can edit the Readme.md file in any way that you wish (it should automatically be tracked so no need to manually add it).
8. Commit changes to the local directory to the local git repository.
On Git bash, run the command:
git commit -m “<your_commit_message>”
Specifying a reason for this commit. A standard message for the first commit is usually “initial commit”, but this message can be anything you like that describes the changes that were made.
9. Push changes from the local git repository to the remote git repository.
On Git Bash, run the command:
git push -u origin <your_branch_name>
to synchronize changes to the branch on the local repo to the remote repo.
Now, in your Github repository UI, you should see that a new branch with changes was just pushed to the remote repo:
10. Create a pull request to merge these changes to the remote master branch (optional).
Now that the .yaml file(s) have been created and tracked, you may choose to edit them on your desktop. Once you are satisfied with the edits, you can follow steps 7-9 to synchronize these changes with the remote branch and then decide to open a pull request to merge them to your master branch in your remote repo. To do this simply click “compare & pull request” to open a new pull request, and add any comments that you desire. Once you/your team is satisfied and has reviewed the changes, click “Merge pull request” to bring these changes from the working branch into the master branch:
11. Synchronize changes to the remote master branch with your local master branch.
Once the pull request is successful, you want to make sure that your local repo’s master branch reflects the latest version in the remote branch. To do this, switch to the master branch on Git bash with the command:
git checkout master
And then run the command:
git pull origin master
To pull all of the latest changes to the remote branch and bring them to your local directory.
12. Push river configuration changes to the rivery account.
Now that your local repository is up-to-date, you can take any finalized changes to river configurations and push them to the rivery account using the Rivery CLI.
In your terminal, navigate to your local Git repo directory and run the command:
rivery --profile=<your_profile_name> rivers push --paths=<path_to_yaml_file>
to push the finalized configurations to your rivery account associated with the created profile.
For more information on available commands that you can run using the CLI, including more examples, please refer to our documentation.