Git Syncing

Retoolは、開発者によって開発者のために構築されたプラットフォームです。そのため、当社では、お客様がソフトウェア開発ライフサイクルのベスト・プラクティスを妥協していないかどうかを確認することを非常に重要視しています。Retoolアプリケーションを構築しており、やり取りしながらそれに取り組んでいるときには、本番で使用できる状態のアプリケーションをエンド・ユーザーが使用していることを確認する必要があります。当社のGit Syncing機能では、Retoolアプリケーションの開発方法とデプロイ方法を十分にカスタマイズできます。

Git Syncingを使用するには、バージョン2.41.13以降を使用している必要があります。

🚧

オンプレミス専用

Git Syncingはオンプレミス版のRetoolでのみ使用可能です。オンプレミスでのデプロイについては、こちらで営業担当者と連絡を取ることができます。

RetoolのGit Syncingの設定

Git Syncingを設定するときには、これが一方向のプロセスであることに留意してください。個々のRetoolインスタンスでできるのは、自分のGitリポジトリーへの変更内容のプッシュ、またはそのリポジトリーからの変更内容のプルのどちらかです。

一般的な設定には、以下のものが含まれます。

  • 自分のGitHubリポジトリーのdevブランチに変更内容をプッシュする単一の開発インスタンス
  • 同じリポジトリーの別々のブランチから読み取る1つ以上の追加のインスタンス(例えば、stagingブランチから読み取るステージング・インスタンスと、mainブランチから読み取る本番インスタンス)

詳細と図については、Gitワークフローのページを参照してください。

変更内容をGitHubにプッシュするようにRetoolインスタンスを構成する

1. 空のGitリポジトリーを作成します

Git Syncingを設定するには、以下のステップに従って、空のリポジトリーを初期化する必要があります。

GitHubにアクセスし、新しいリポジトリーを作成します。

新しいローカル・ディレクトリーを作成し、そのリポジトリーをクローンします。

git clone https://github.com/GITHUB_USERNAME/REPO_NAME.git

そのリポジトリーに移動します。

cd REPO_NAME

--allow-emptyフラグを使用して空のコミットを作成します。

git commit -m 'Initial commit' --allow-empty

これをGitHubにプッシュします。

git push

🚧

リポジトリーは空にしてください

注意: そのリポジトリー内にファイルを含めることはできません。空である必要があります。これで、次のような空のGitHubリポジトリーを用意できました。

2. 公開鍵を取得し、自分のブランチに接続します

管理者としてRetoolにログインし、Settings > Advancedに移動します。ページの下の方に、Git SyncingのURLとブランチのセクションがあります。

自分のGitHubのURLとブランチ名を入力し、「Save」をクリックします。HTTPS URLではなく、SSH URLを必ず入力してください。SSH URLは、以下の書式になっている必要があります。

[email protected]:USERNAME/REPO_NAME.git

Retoolインスタンスから、Git Syncingを認証するための公開鍵が提供されます。青色のリンクをクリックしてRetoolの公開鍵をダウンロードしますretool.pubファイルを開き、鍵全体をクリップボードにコピーします。

3. GitHubでデプロイ・キーを構成します

自分のGitHubリポジトリーに戻り、Settingsタブをクリックして、左側のサイドバー内のDeploy Keysをクリックします。Add Deploy Keyをクリックし、それにタイトルを付け、クリップボードからRetoolの公開鍵を貼り付けます。

Retoolでこのリポジトリーにコミットできるように、必ずAllow Write Accessのチェックボックスをオンにします。

Retoolの公開鍵を自分のGitリポジトリーに追加します。必ず書き込みアクセス権を付与しますRetoolの公開鍵を自分のGitリポジトリーに追加します。必ず書き込みアクセス権を付与します

Retoolの公開鍵を自分のGitリポジトリーに追加します。必ず書き込みアクセス権を付与します

4. 同期が機能することをテストします

Retoolで新しいアプリケーションを作成するか、既存のアプリケーションに変更を加えます。約10秒後に、変更内容が自分のリポジトリーに同期されたことが分かります。

読み取り専用のRetoolインスタンスを構成する

一般的な設定としては、本番Retoolインスタンスを読み取り専用にします。この機能を構成することで、ブラウザーから本番Retoolアプリケーションに変更を加えることができないようにして、強制的に、すべての変更内容をGitリポジトリーから読み取るようにします。

Retoolの読み取り専用インスタンスを構成する前に、変更内容を既存のリポジトリーにプッシュするように別のインスタンスを構成してあることを確認します。

🚧

このプロセスにより既存の変更内容が上書きされます

RetoolインスタンスをGitHubリポジトリーのブランチからの読み取り専用に設定すると、Git Syncingプロセスにより、Retool Postgresデータベース内の既存のすべてのアプリケーションが、そのリポジトリー内にあるものと置き換えられます。これは、既存のアプリケーションがそのリポジトリー内にまだない場合、そのアプリケーションがなくなるということです。

1. アプリケーション内変更を防ぐためにインスタンスをロックします

アプリケーション内変更を防ぐためにインスタンスをロックするには、docker.envファイル内で次の環境変数を定義します。

VERSION_CONTROL_LOCKED=true

2. 自分のGitHubリポジトリーに新しいブランチを作成します

コマンド・ラインまたはGitHub UIから、このインスタンスが従う新しいブランチを作成します。そのブランチに、このインスタンスを示す名前を付けます(例: ステージング・インスタンスの場合はstaging)。

3. 公開鍵を取得し、自分のブランチに接続します

管理者としてRetoolにログインし、Settings > Advancedに移動します。ページの下の方に、Git SyncingのURLとブランチのセクションがあります。

自分のGitHubのURLとブランチ名を入力し、「Save」をクリックします。HTTPS URLではなく、SSH URLを必ず入力してください。SSH URLは、以下の書式になっている必要があります。

[email protected]:USERNAME/REPO_NAME.git

Retoolインスタンスから、Git Syncingを認証するための公開鍵が提供されます。青色のリンクをクリックしてRetoolの公開鍵をダウンロードしますretool.pubファイルを開き、鍵全体をクリップボードにコピーします。

4. GitHubでデプロイ・キーを構成します

自分のGitHubリポジトリーに戻り、Settingsタブをクリックして、左側のサイドバー内のDeploy Keysをクリックします。Add Deploy Keyをクリックし、それにタイトルを付け、クリップボードからRetoolの公開鍵を貼り付けます。

読み取り専用インスタンスのデプロイ・キーをリポジトリーに追加します。「Allow write access」オプションはオフのままにします読み取り専用インスタンスのデプロイ・キーをリポジトリーに追加します。「Allow write access」オプションはオフのままにします

読み取り専用インスタンスのデプロイ・キーをリポジトリーに追加します。「Allow write access」オプションはオフのままにします

🚧

書き込みアクセス権を有効にする必要がありますか?

これは読み取り専用インスタンスであるため、書き込みアクセス権を有効にする必要はありません。さらに言えば、想定外の動作が起こらないように、このチェックボックスをオフのままにすることをお勧めします。

5. 同期が機能することをテストします

少し待ってから、ブラウザーでRetoolのページをリフレッシュします。これで、Retoolに、自分のGitHubリポジトリー内の同じアプリケーションが表示されるようになります。

RetoolアプリケーションのDSL

Retoolでは、各Retoolアプリケーションのデータは、JSONの拡張機能を使用して内部でエンコードされます。効果的ではありますが、変更履歴を可視化するのが難しい書式であるため、Retoolでは、このデータをバージョン管理で直接保存するのではなく、YAMLファイルに書式設定し直します。

1つのクエリーからのデータを示す1つのテーブルが含まれている単純なページは、次のように表現できます。

version: 2.8.1
components:
  - id: table1
    position:
      top: 1
      right: 1
      width: 8
      height: 5
    template:
      data: "{{ query1.data }}"
      selectedIndex: ''
      columns: 
        - id
        - name
        - salary
      columnWidths: 
        - 10
        - 100
        - 50
      columnColors:
        - white
        - white
        - "{{ self > 60 : 'green' : 'red' }}"
      pageSize: 10
      alwaysShowPaginator: true
      onRowSelect: ''
      serverPaginated: false
      totalRowCount: ''
      paginationOffset: 0
      sort: null
      sortedColumn: ''
      sortedDesc: false
      allowMultiRowSelect: false
queries:
  - id: query1
    template:
      query: "select * from users"
      runWhenPageLoads: false
      runWhenModelUpdates: true
      requireConfirmation: false
      confirmationMessage: ""
      queryDisabled: "",
      triggersOnSuccess: []
      triggersOnFailure: []
      privateParams: []
      queryRefreshTime: ''
      queryThrottleTime: '750'
      queryTimeout: '10000'
      showSuccessToaster: true,
      successMessage: ''

Retoolでの保存のたびに、リポジトリー内の新しいコミット・メッセージが自動的にトリガーされます。

Retoolリリースとの統合

Retoolでは、デフォルトで、アプリケーションのユーザーにページの最新バージョンが自動表示されます。デバッグに便利ですが、保存したものをリリースとしてタグ付けし、そのバージョンのみをユーザーに表示するというのも役立ちます。リリースが作成されると、Retoolによって自動的にタグがGitリポジトリーにもプッシュされます。

デプロイ・キーの循環方法

自分のGitHubリポジトリー内のデプロイ・キーをローテーションさせる必要がある場合は、手動でRetoolのSSH鍵を再生成できます。これは、セキュリティー・チームで資格情報ローテーション・ポリシーが設けられている場合や、誤って暗号鍵を変更してしまいRetoolで既存のSSH鍵をデコードできなくなった場合に便利です。

これを行うには、RetoolのPostgresデータベースにアクセスする必要があります。

まず、ssh_keysテーブルに1つのレコードしかないことを確認します。

select * from ssh_keys

次に、このレコードを削除します。

truncate ssh_keys

その後、SSH鍵を再生成しダウンロードします。

  • 管理者として、RetoolのSettings > Advancedページに移動します。
  • 青色のリンクをクリックしてRetoolの公開鍵をダウンロードしますretool.pubファイルを開き、鍵全体をクリップボードにコピーします。
  • このリンクをクリックすると、ssh_keyテーブルに新しいレコードが生成され、ローカル・マシンに公開鍵がダウンロードされます。

次に、自分のGitHubリポジトリーに戻り、Settingsタブをクリックして、左側のサイドバー内のDeploy Keysをクリックします。Add Deploy Keyをクリックし、それにタイトルを付け、クリップボードからRetoolの公開鍵を貼り付けます。

🚧

デプロイ・キーのために書き込みアクセス権を有効にする必要がありますか?

これが読み取り専用インスタンスである場合は、Allow Write Accessオプションをオフのままにする必要があります。

これがGitHubへの書き込みを行う開発インスタンスである場合は、このオプションをオンにしてRetoolでこのリポジトリーにコミットできるようにします。