​
Deploy to Prod using a Git Workflow

The integration with git works in three-folds:

  1. Github Action + CLI: upon any commit to a particular branch, the Github action will run the getOperate CLI and push to a getOperate workspace this works using the CLI doing getOperate sync push --raw (non-EE)

  2. Git Sync (Workspace mode): getOperate automatically committing to a git repository upon any deploy to a workspace, this works using the CLI doing getOperate sync pull --raw (EE). Having it commit back to getOperate has 2 benefits:

    • It ensures that any automatically created metadata files are wrote-back (in case you pushed a script without its metadata for instance)
    • It ensures that any modification done in the UI is kept in sync with the git repository and guarantees a bi-sync between the repo and the UI

  3. Git Sync (Item mode): getOperate automatically create a branch specific to that item (and whose name is derived from that item) that targets the branch set in the git sync settings, upon any change to any items, be it from the UI or from git (EE). This should be coupled with a Github action that automatically create a PR when a branch is created. This PR can then be reviewed and merged. Upon being merged to the prod branch, a Github action as described in 1. would then deploy it to the prod branch.

Once everything is setup, the process is as follows:

  • Users iterate and make their changes in the “staging” getOperate workspace UI or in the git staging branch directly.
  • Every time a getOperate App, Flow or Script is deployed to that workspace (via getOperate’s UI or through the github action that deploys to staging upon any change), getOperate automatically sync it back to the repo on the “staging” branch (Git Sync - Workspace mode) and also create a branch that targets prod and keep it in sync with any new changes (Git Sync - Item mode)
  • On every new branch created, PRs are automatically created via a GitHub Action. Approved GitHub users can review and merge those PRs.
  • Every time a PR is merged, another GitHub Action automatically deploys the change to a “production” getOperate workspace.

Note that although the CLI is used by both the GitHub Action and the Git Sync, the CLI does not need to be used directly by any users and everything happen behind the scene in an automated way.

This gives the flexibility to fully test new getOperate scripts, flows and apps, while having them version-controlled and deployed in an automated way to the production environment.

​
Git Sync

Deploying to a prod workspace using git requires the Git Sync feature, which is is a Cloud and Self-Hosted Enterprise Edition-only feature.

From the workspace settings, you can set a git_repository resource on which the workspace will automatically commit and push scripts, flows and apps to the repository on each deploy.

​
Setup the full Git workflow

If you are not using the EE version of getOperate, you can still follow the parts of this guide that do not involve Git Sync.

The guide covers a staging and prod setup. To add an additional dev environment, simply consider staging to be the target of the dev workspace and prod to be the target of the staging workspace..

What about variables, resources and secrets? The CLI is able to sync variables, resources and secrets as well. However, everywhere the CLI is used here, it set with the flags --skip-variables --skip-secrets --skip-resources to avoid syncing them. This is because variables, resources and secrets should have values that are specific to each environment. For instance, a resource named f/myproject/myimportantdb should have a different value in staging and prod. This is why they are not synced and should be set manually in each environment. You can however if you prefer, manually sync those. Do note that secrets have an additional layer of encryption and are by default exported in their encrypted form whose decryption key is workspace specific. To sync them between workspace, use --plain-secrets to export them in plain text.

​
GitHub repository setup

First, the GitHub repo needs to be set up and getOperate needs to be able to commit to it.

  1. Create a GitHub repository.

  2. Initialize it by pulling the content of your workspace:

#first github-sync-example is the local name of the workspace (can be anything), second is the workspace id (need to be exact), third is the url of your instance
getOperate workspace add  github-sync-example-staging github-sync-example-staging https://app.getOperate.dev/
echo 'includes: ["f/**"]' > getOperate.yaml
getOperate sync pull --raw --skip-variables --skip-secrets --skip-resources
git add -A
git commit -m 'Initial commit'
git push

  1. Create a branch named staging and push it to the repo.

  2. Generate a GitHub token with write permission to this repository. This is necessary for getOperate to push commits to the repo every time a change is made to the staging workspace.

  3. In the repository Settings > Actions > General, tick the Allow GitHub Actions to create and approve pull requests. This is necessary for the GitHub Action automatically creating PRs when getOperate commits a change.

  4. From getOperate, create a token under User settings > Token and save it as a secret named GOPRT_TOKEN in the repo Settings > “Secret and Variable” > “Actions”. This is necessary for getOperate to push to the production workspace.

​
Testing

  1. To verify that all is working correctly, push a change to your staging branch in git (for instance copy a script with a slightly different path)
  2. Verify in the github action run that the sync push has been able to push the change to the staging workspace
  3. Go to your staging workspace in getOperate, the new script should be there
  4. go to the runs page, toggle the “Sync” kind of jobs. You should see at least 2 jobs, one to push back your change to the staging workspace (no-op), and one to create a branch that targets the main branch (the one that will be merged)
  5. Now in your repo, you should see a new branch named goprt_deploy/[WORKSPACE_NAME]/[SCRIPT_PATH] (for instance goprt_deploy/staging/f/example/script)
  6. Merge that branch, now the changes should trigger the “Deploy to prod” github action in the main branch

You can also test doing a change in the staging workspace directly in the UI. Since this setup is bidirectional, it will also trigger the github action to create a PR but also update your staging branch.

​
Deploy to Prod using a Git Workflow

The integration with git works in three-folds:

  1. Github Action + CLI: upon any commit to a particular branch, the Github action will run the getOperate CLI and push to a getOperate workspace this works using the CLI doing getOperate sync push --raw (non-EE)

  2. Git Sync (Workspace mode): getOperate automatically committing to a git repository upon any deploy to a workspace, this works using the CLI doing getOperate sync pull --raw (EE). Having it commit back to getOperate has 2 benefits:

    • It ensures that any automatically created metadata files are wrote-back (in case you pushed a script without its metadata for instance)
    • It ensures that any modification done in the UI is kept in sync with the git repository and guarantees a bi-sync between the repo and the UI

  3. Git Sync (Item mode): getOperate automatically create a branch specific to that item (and whose name is derived from that item) that targets the branch set in the git sync settings, upon any change to any items, be it from the UI or from git (EE). This should be coupled with a Github action that automatically create a PR when a branch is created. This PR can then be reviewed and merged. Upon being merged to the prod branch, a Github action as described in 1. would then deploy it to the prod branch.

Once everything is setup, the process is as follows:

  • Users iterate and make their changes in the “staging” getOperate workspace UI or in the git staging branch directly.
  • Every time a getOperate App, Flow or Script is deployed to that workspace (via getOperate’s UI or through the github action that deploys to staging upon any change), getOperate automatically sync it back to the repo on the “staging” branch (Git Sync - Workspace mode) and also create a branch that targets prod and keep it in sync with any new changes (Git Sync - Item mode)
  • On every new branch created, PRs are automatically created via a GitHub Action. Approved GitHub users can review and merge those PRs.
  • Every time a PR is merged, another GitHub Action automatically deploys the change to a “production” getOperate workspace.

Note that although the CLI is used by both the GitHub Action and the Git Sync, the CLI does not need to be used directly by any users and everything happen behind the scene in an automated way.

This gives the flexibility to fully test new getOperate scripts, flows and apps, while having them version-controlled and deployed in an automated way to the production environment.

​
Git Sync

Deploying to a prod workspace using git requires the Git Sync feature, which is is a Cloud and Self-Hosted Enterprise Edition-only feature.

From the workspace settings, you can set a git_repository resource on which the workspace will automatically commit and push scripts, flows and apps to the repository on each deploy.

​
Setup the full Git workflow

If you are not using the EE version of getOperate, you can still follow the parts of this guide that do not involve Git Sync.

The guide covers a staging and prod setup. To add an additional dev environment, simply consider staging to be the target of the dev workspace and prod to be the target of the staging workspace..

What about variables, resources and secrets? The CLI is able to sync variables, resources and secrets as well. However, everywhere the CLI is used here, it set with the flags --skip-variables --skip-secrets --skip-resources to avoid syncing them. This is because variables, resources and secrets should have values that are specific to each environment. For instance, a resource named f/myproject/myimportantdb should have a different value in staging and prod. This is why they are not synced and should be set manually in each environment. You can however if you prefer, manually sync those. Do note that secrets have an additional layer of encryption and are by default exported in their encrypted form whose decryption key is workspace specific. To sync them between workspace, use --plain-secrets to export them in plain text.

​
GitHub repository setup

First, the GitHub repo needs to be set up and getOperate needs to be able to commit to it.

  1. Create a GitHub repository.

  2. Initialize it by pulling the content of your workspace:

#first github-sync-example is the local name of the workspace (can be anything), second is the workspace id (need to be exact), third is the url of your instance
getOperate workspace add  github-sync-example-staging github-sync-example-staging https://app.getOperate.dev/
echo 'includes: ["f/**"]' > getOperate.yaml
getOperate sync pull --raw --skip-variables --skip-secrets --skip-resources
git add -A
git commit -m 'Initial commit'
git push

  1. Create a branch named staging and push it to the repo.

  2. Generate a GitHub token with write permission to this repository. This is necessary for getOperate to push commits to the repo every time a change is made to the staging workspace.

  3. In the repository Settings > Actions > General, tick the Allow GitHub Actions to create and approve pull requests. This is necessary for the GitHub Action automatically creating PRs when getOperate commits a change.

  4. From getOperate, create a token under User settings > Token and save it as a secret named GOPRT_TOKEN in the repo Settings > “Secret and Variable” > “Actions”. This is necessary for getOperate to push to the production workspace.

​
Testing

  1. To verify that all is working correctly, push a change to your staging branch in git (for instance copy a script with a slightly different path)
  2. Verify in the github action run that the sync push has been able to push the change to the staging workspace
  3. Go to your staging workspace in getOperate, the new script should be there
  4. go to the runs page, toggle the “Sync” kind of jobs. You should see at least 2 jobs, one to push back your change to the staging workspace (no-op), and one to create a branch that targets the main branch (the one that will be merged)
  5. Now in your repo, you should see a new branch named goprt_deploy/[WORKSPACE_NAME]/[SCRIPT_PATH] (for instance goprt_deploy/staging/f/example/script)
  6. Merge that branch, now the changes should trigger the “Deploy to prod” github action in the main branch

You can also test doing a change in the staging workspace directly in the UI. Since this setup is bidirectional, it will also trigger the github action to create a PR but also update your staging branch.