環境とデプロイメント

GitLab 8.9 で導入されました。

GitLabでは、ソフトウェアの継続的デプロイメントを環境によって制御することができます。

導入

ソフトウェア開発プロセスでは、ソフトウェアが市場に提供されるまでに多くのステップが必要です。

使用例

  1. 開発する
  2. テストする
  3. プロダクトを公開する前に、テスト環境やステージング環境にデプロイしましょう。

これは、ソフトウェアのバグを見つけるのに役立ちます。また、デプロイメントプロセスにおいても同様です。

GitLab CI/CDは、プロジェクトのテストやビルドだけでなく、インフラストラクチャへのデプロイも可能です。これは、デプロイを追跡する方法を提供するという付加的なメリットになります。言い換えれば、現在何がデプロイされているのか、あるいはサーバーにデプロイされているのかを常に知ることができます。

重要なこと:

  • 環境はCIジョブのタグのようなもので、コードがデプロイされる場所を記述します。
  • ジョブが環境にコードのバージョンをデプロイするときにデプロイメントが作成されるので、すべての環境に1つ以上のデプロイメントを持つことができます。

GitLab:

  • 各環境のデプロイの完全な履歴を提供します。
  • デプロイメントを追跡することで、現在何がサーバーにデプロイされているかを常に知ることができます。

Kubernetesなどのプロジェクトに関連するデプロイサービスがあれば、それを使ってデプロイを支援したり、GitLab内から自分の環境のWebターミナルにアクセスすることができます。

環境設定

環境の設定には、以下を含みます:

  1. パイプラインの仕組みを理解する
  2. 各プロジェクトの.gitlab-ci.ymlファイルで環境を定義する
  3. アプリケーションをデプロイするためのジョブ設定を作成します。このジョブは、例えば、アプリケーションをKubernetesクラスタにデプロイする環境で構成されたデプロイジョブです。

このセクションの残りの部分では、シナリオの例を挙げて環境とデプロイメントを設定する方法を説明します。すでに以下のことを行っていることを想定しています:

シナリオは次のような内容です:

  • アプリケーションを開発しています
  • すべてのブランチでアプリのテスト実行とビルドをしたいと考えています
  • デフォルトブランチはmasterです
  • masterブランチのパイプラインが実行されたときだけアプリをデプロイします

環境の定義

次の.gitlab-ci.ymlの例を考えてみましょう: 

stages:
  - test
  - build
  - deploy

test:
  stage: test
  script: echo "Running tests"

build:
  stage: build
  script: echo "Building the app"

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - master

3つのステージを定義しています:

  • test
  • build
  • deploy

これらのステージに割り当てられたジョブは、この順番で実行されます。いずれかのジョブが失敗した場合、パイプラインは失敗し、次のステージに割り当てられたジョブは実行されません。

この場合は:

  • 最初にtestジョブを実行します
  • 次にbuildジョブを実行します
  • 最後にdeploy_stagingジョブを実行します

この設定では:

  • テストが通過することを確認します
  • アプリが正常にビルドできることを確認します
  • 最後に、ステージング サーバーにデプロイします

注: 注意 環境キーワードは、アプリがデプロイされる場所を定義します。環境名とURLはGitLab内のさまざまな場所で公開されています。 環境を指定したジョブが成功するたびに、GitのSHA(ハッシュ値)と環境名とともにデプロイが記録されます。

注意：注意: 環境名には使用できない文字があります。文字、数字、スペース、-、_、/、{、}、または.のみ使用できます。また、/で始まったり、終わったりすることはできません。

まとめると、上記の .gitlab-ci.yml で以下のようになります:

  • すべてのブランチでtestとbuildジョブが実行されます
  • deploy_staging ジョブはmaster ブランチのみで実行されます。つまり、ブランチから作成されたすべてのマージリクエストはステージングサーバーにデプロイされません。
  • マージリクエストがマージされると、すべてのジョブが実行され、deploy_stagingジョブによってコードがステージングサーバにデプロイされます。デプロイメントはstagingという名前の環境に記録されます

環境変数, Runner

GitLab 8.15以降、環境名は2つの方式でRunnerに公開されます:

  • $CI_ENVIRONMENT_NAME　.gitlab-ci.ymlで指定された名前(すべての変数を展開したもの)
  • $CI_ENVIRONMENT_SLUG　URL や DNS などで使用するのに適した “クリーンアップされた” バージョンの名前です

既存の環境の名前を変更した場合:

  • $CI_ENVIRONMENT_NAME　新しい環境名で変数を更新します
  • $CI_ENVIRONMENT_SLUG　意図しない副作用を防ぐために変数を変更しません

GitLab 9.3以降、環境のURLは $CI_ENVIRONMENT_URL でRunnerに公開されます。URLは次のどちらかで展開されます:

  • .gitlab-ci.yml.
  • 環境からの外部URL (.gitlab-ci.ymlで定義されていない場合)

ジョブ終了後に動的環境の URL を設定する

GitLab 12.9で導入されました。

ジョブスクリプトでは、静的な環境URLを指定することができます。 しかし、動的な URL を指定したい場合もあるでしょう。 例えば、https://94dd65b.amazonaws.com/qa-lambda-1234567 のように、デプロイごとにランダムな URL を生成する外部のホスティングサービスにReview Appsをデプロイした場合、デプロイスクリプトが終了する前にURLが分からなくなってしまいます。 GitLabで環境URLを使いたい場合は、手動で更新する必要があります。

この問題に対応するために、外部サービスによって動的に生成されたURLを含む変数セットをレポートバックするようにデプロイメントジョブを設定することができます。 GitLabは dotenv (.env) ファイル形式をサポートしており、environment:url の値を .env ファイルで定義された変数で展開します。

この機能を使用するには、.gitlab-ci.ymlのartifacts:reports:dotenvキーワードを指定します。

概要については、ジョブ終了後に動的URLを設定するを参照してください。

動的環境URLの設定例

次の例では、マージリクエストごとに新しい環境を作成するReviewアプリを示しています。 review ジョブはプッシュごとにトリガーされ、review/your-branch-name という名前の環境を作成または更新します。 環境URLは$DYNAMIC_ENVIRONMENT_URLに設定されています。: 

review:
  script:
    - DYNAMIC_ENVIRONMENT_URL=$(deploy-script)                                 # In script, get the environment URL.
    - echo "DYNAMIC_ENVIRONMENT_URL=$DYNAMIC_ENVIRONMENT_URL" >> deploy.env    # Add the value to a dotenv file.
  artifacts:
    reports:
      dotenv: deploy.env                                                       # Report back dotenv file to rails.
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    url: $DYNAMIC_ENVIRONMENT_URL                                              # and set the variable produced in script to `environment:url`
    on_stop: stop_review

stop_review:
  script:
    - ./teardown-environment
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_SLUG
    action: stop

review ジョブが終了すると、GitLabは review/your-branch-name 環境のURLを更新します。 これは deploy.env レポートの成果物を解析し、変数のリストを実行時に作成されたものとして登録し、environment:url: $DYNAMIC_ENVIRONMENT_URL を展開するために使用し、環境URLに設定します。 また、environment:url:でhttps://$DYNAMIC_ENVIRONMENT_URLのように、URLの静的な部分を指定することもできます。 DYNAMIC_ENVIRONMENT_URLの値が example.comの場合、最終的にはhttps://example.comとなります。

review/your-branch-name環境に割り当てられたURLは、UIに表示されます

注:

  • stop_review は dotenv レポートの成果物を生成しないので、DYNAMIC_ENVIRONMENT_URL 変数を認識しません。そのため、stop_reviewジョブでenvironment:url:を設定すべきではありません。
  • 環境URLが有効でない場合(URLが不正な場合など)、システムは環境URLを更新しません。

手動デプロイメント設定

自動実行するジョブの設定にwhen: manualを追加すると、手動でのアクションを必要とするジョブに変換されます。

前の例を拡張するために、次の例には、本番サーバーにアプリをデプロイし、production環境によって追跡される別のジョブが含まれています。

そのための.gitlab-ci.ymlファイルは以下のようになります: 

stages:
  - test
  - build
  - deploy

test:
  stage: test
  script: echo "Running tests"

build:
  stage: build
  script: echo "Building the app"

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - master

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
    - master

when: manual アクション:

  • GitLab の UI 上に、そのジョブの “play” ボタンが表示されます。
  • つまり、deploy_prod ジョブは、”play” ボタンがクリックされたときにのみトリガーされるということです。

“play” ボタンは、パイプライン、環境、デプロイメント、ジョブの各ビューに存在します。

View Screenshot
パイプライン Pipelines manual action
単一パイプライン Pipelines manual action
環境 Environments manual action
デプロイメント Deployments manual action
ジョブ Builds manual action

任意のビューで再生ボタンをクリックすると、deploy_prod ジョブが起動し、production という名前の新しい環境としてデプロイが記録されます。

NOTE :注: 環境名がproduction(すべて小文字)の場合、Value Stream Analyticsに記録されます。

動的環境の設定

ステージングや本番環境のような「安定した」環境にデプロイする場合は、通常の環境が良いでしょう。

しかし、master ブランチ以外の環境では、動的環境を使うことができます。 環境名を.gitlab-ci.ymlで動的に宣言することで、動的環境を作成することができます。

動的環境は Review Apps の基本的な部分です。

使用可能な変数

動的環境用の名前とurlパラメータは、以下を含むほとんどの利用可能なCI/CD変数を使用することができます:

ただし、定義済み変数は使えません:

  • scriptで定義されている変数
  • Runnerで定義されている変数

また、environment:nameのコンテキストでサポートされていない変数もあります。 詳しくは、変数が使える場所を参照してください。

設定例

GitLab Runner は、ジョブの実行時にさまざまな 環境変数 を公開します。

次の例では、ジョブはmasterブランチを除くすべてのブランチにデプロイされます: 

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com
  only:
    - branches
  except:
    - master

この例では:

  • ジョブの名前はdeploy_reviewで、deployステージで実行されます。
  • 環境にenvironment:nameをつけてreview/$CI_COMMIT_REF_NAMEとします。 環境名にはスラッシュ(/)を含むことができるので、このパターンを使って動的環境と通常の環境を区別することができます。
  • masterブランチを除いた各ブランチ上でのみ実行するようにジョブに指示します。

このような値の場合:

  • environment:nameの値の場合、最初の部分はreviewで、その後に/と続き、$CI_COMMIT_REF_NAMEでブランチ名の値を受け取ります

  • environment:urlの値には、ブランチごとに個別のURLが必要です。 $CI_COMMIT_REF_NAMEには/やドメイン名やURLでは無効な文字が含まれているかもしれません。そのため、有効なURLを取得することを保証する目的で$CI_ENVIRONMENT_SLUGを使用します。

    例えば、$CI_COMMIT_REF_NAMEに100-Do-The-Thingsが設定された場合、URLはhttps://100-do-the-4f99a2.example.comのようになります。 繰り返しになりますが、ユーザの設定に基づいて、これらのリクエストに対応するためにウェブサーバを設定されます。

    ここでは$CI_ENVIRONMENT_SLUGを使用していますが、これは一意性が保証されているからです。 GitLab Flow のようなワークフローを使用している場合、衝突は起こりにくく、環境名はブランチ名に近い方が良いかもしれません。その場合は、上の例のenvironment:urlで$CI_COMMIT_REF_NAMEを使うことができます。https://$CI_COMMIT_REF_NAME.example.comとすると、https://100-do-the-thing.example.comというURLになります。

NOTE：注： 動的環境の名前に同じ接頭辞を使用したり、スラッシュ(/)のみを使用したりする必要はありません。 ただし、この形式を使用すると、類似環境のグループ化機能が有効になります。.

Kubernetesデプロイメントの設定

GitLab 12.6 で導入されました。

プロジェクトに関連付けられたKubernetesクラスタにデプロイする場合、gitlab-ci.ymlファイルでデプロイを設定することができます。

以下の設定オプションがサポートされています:

次の例では、アプリケーションを production というKubernetes ネームスペースにデプロイします。 

deploy:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
    kubernetes:
      namespace: production
  only:
    - master

GitLab の Kubernetes 連携を利用して Kubernetes クラスタにデプロイする場合、クラスタとネームスペースに関する情報がデプロイジョブのページのジョブのトレース情報に表示されます:

Deployment cluster information

Note:Kubernetes設定はGitLabが管理するKubernetesクラスターではサポートされません。サポートの進捗状況については、関連する課題を参照してください。

インクリメンタルロールアウト設定

インクリメンタルロールアウトを使用して、Kubernetesポッドの一部のみに本番の変更をリリースする方法を学びます。

デプロイメントの安全性

デプロイメントのジョブは、パイプラインの中の他のジョブよりも外部の影響を受けやすいので、丁寧なケアが必要になるかもしれません。GitLab には、デプロイメントのセキュリティと安定性を維持するための複数の機能があります。

完成例

このセクションの設定では、アプリが以下のような完全な開発ワークフローを提供します:

  • テスト
  • ビルド
  • Review Appとしてデプロイ
  • マージリクエストがマージされたら、ステージング サーバーにデプロイ
  • 最後に、本番サーバーに手動でデプロイ

以下は、これまでの設定例を組み合わせたものです: 

stages:
  - test
  - build
  - deploy

test:
  stage: test
  script: echo "Running tests"

build:
  stage: build
  script: echo "Building the app"

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com
  only:
    - branches
  except:
    - master

deploy_staging:
  stage: deploy
  script:
    - echo "Deploy to staging server"
  environment:
    name: staging
    url: https://staging.example.com
  only:
    - master

deploy_prod:
  stage: deploy
  script:
    - echo "Deploy to production server"
  environment:
    name: production
    url: https://example.com
  when: manual
  only:
    - master

より現実的な例としては、ウェブサーバ（例えばNGINX）がアクセスしてサービスを提供できる場所にファイルをコピーすることも含みます。

以下の例では、publicディレクトリを/srv/nginx/$CI_COMMIT_REF_SLUG/publicにコピーします: 

review_app:
  stage: deploy
  script:
    - rsync -av --delete public /srv/nginx/$CI_COMMIT_REF_SLUG
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_COMMIT_REF_SLUG.example.com

この例では、このジョブが実行されるサーバーに NGINX と GitLab Runner がセットアップされている必要があります。

NOTE:注：。 ブランチやReview Appの名前に関するエッジケースについては、制限事項のセクションを参照してください。

完成例では、開発者に以下のようなワークフローを提供しています:ローカルにブランチを作成する

  • ローカルにブランチを作成する
  • 変更を加えてコミットする
  • GitLabにブランチの変更をプッシュする
  • マージリクエストを作成する

GitLab Runnerはこれらの裏で次のようなことをしています:

  • 変更をピックアップし、ジョブの実行を開始します
  • stages で定義されているように、ジョブを順次実行します:
    • まず、テストを実行します
    • テストが成功した場合、アプリをビルドします
    • ビルドに成功した場合、アプリはブランチに固有の名前を持つ環境にデプロイされます

そして、全てのブランチに以下を行います:

詳細については、環境の URL を使うを参照してください。

保護された環境

アクセスを制限することにより、環境を”保護”できます。

詳細は、保護された環境を参照してください。

環境の操作

環境が構成されると、GitLabは環境を操作するための多くの機能を提供します。

環境とデプロイメントの表示

環境とデプロイメントの状態の一覧は、各プロジェクトの[オペレーション] > [環境]ページで確認できます。

使用例

Environment view

この例では、以下のように表示されます:

  • 環境の名前とそのデプロイメントへのリンク
  • 最後のデプロイメントIDとそれを実行した人
  • 最後のデプロイメントのジョブIDとそれぞれのジョブ名
  • 最後のデプロイメントのコミット情報 (誰がコミットしたのか、どのブランチにコミットしたのか、コミットのGit SHAなど)
  • 最後のデプロイメントが実行された正確な時刻
  • .gitlab-ci.ymlで環境キーワードとして定義したURLに移動するボタン
  • 最新のデプロイを再デプロイするボタン。つまり、特定のコミットの環境名で定義されたジョブを実行する

環境ページに表示される情報は最新のデプロイメントに限定されますが、一つの環境に複数のデプロイメントを含めることができます。

注:

  • Webインターフェイスで手動で環境を作成することもできますが、まずは.gitlab-ci.ymlで環境を定義することをお勧めします。環境は最初のデプロイ後に自動的に作成されます。
  • 環境ページは、Reporter パーミッションを持つユーザーのみが閲覧できます。 パーミッションの詳細については、パーミッションのドキュメントを参照してください。
  • .gitlab-ci.ymlが適切に設定された後に行われたデプロイのみが環境と最後のデプロイのリストに表示されます。

デプロイに関する履歴の表示

GitLabではデプロイの記録を保持します:

  • 現在サーバーに何がデプロイされているかを常に知ることができます
  • 全ての環境に関するデプロイの完全な履歴を持つことができます

環境をクリックすると、その環境のデプロイの履歴が表示されます。以下は、複数のデプロイメントを持つEnvironmentsページの例です:

Deployments

このビューは 環境 ページに似ていますが、全てのデプロイメントが表示されます。また、このビューには ロールバック ボタンがあります。詳細については、再試行とロールバックを参照してください。

再試行とロールバック

デプロイで問題が発生した場合に、再試行またはロールバックできます。

デプロイを再試行またはロールバックするには:

  1. Operations > Environmentsを開きます
  2. 環境をクリックします
  3. 環境のデプロイ履歴リストで下記を実行します:
    • 前回の配置の横にある再試行ボタンをクリックして、その配置を再試行します
    • 前に配置が成功したときの横にあるロールバックボタンをクリックすると、その配置にロールバックします

ロールバック実施時に期待すること

特定のコミットのロールバックボタンを押すと、独自のジョブIDを持つ 新しい デプロイが起動します。

これは、ロールバック先のコミットを指す新しいデプロイが表示されることを意味します。

注意: ジョブのscriptに定義されたデプロイプロセスにより、ロールバックが成功したかどうかを決定します。

環境URLを利用する

環境URLはGitLab内で公開されています:

  • マージリクエストでのリンク: Environment URL in merge request
  • 環境ビューにあるボタン: Environment URL in environments
  • デプロイビューにあるボタン: Environment URL in deployments

この情報は、以下の場合にマージリクエスト上で直接確認することができます:

  • マージリクエストは最終的にデフォルトブランチ (通常は master) にマージされる
  • そのブランチはステージング や プロダクション 環境などにもデプロイされる

使用例

Environment URLs in merge request

ソースファイルから公開ページへ

GitLab の ルートマップ を使うと、ソースファイルからReview Appsに設定されている環境にある公開ページへのアクセスを停止します。

環境の停止

環境を停止する:

これは、複数人の開発者が同時に同じプロジェクトでの作業をして、それぞれのブランチにプッシュしている場合によく使われ、多くの動的な環境が作られる原因となります。

注意: GitLab 8.14 以降、関連するブランチが削除されると動的環境は自動的に停止します。

環境を自動的に停止する

Environments can be stopped automatically using special configuration.

Consider the following example where the deploy_review job calls stop_review to clean up and stop the environment: 

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_NAME
    url: https://$CI_ENVIRONMENT_SLUG.example.com
    on_stop: stop_review
  only:
    - branches
  except:
    - master

stop_review:
  stage: deploy
  variables:
    GIT_STRATEGY: none
  script:
    - echo "Remove review app"
  when: manual
  environment:
    name: review/$CI_COMMIT_REF_NAME
    action: stop

Setting the GIT_STRATEGY to none is necessary in the stop_review job so that the GitLab Runner won’t try to check out the code after the branch is deleted.

When you have an environment that has a stop action defined (typically when the environment describes a Review App), GitLab will automatically trigger a stop action when the associated branch is deleted. The stop_review job must be in the same stage as the deploy_review job in order for the environment to automatically stop.

Additionally, both jobs should have matching rules or only/except configuration. In the example above, if the configuration is not identical, the stop_review job might not be included in all pipelines that include the deploy_review job, and it will not be possible to trigger the action: stop to stop the environment automatically.

You can read more in the .gitlab-ci.yml reference.

Environments auto-stop

GitLab 12.8で導入されました。

You can set a expiry time to environments and stop them automatically after a certain period.

For example, consider the use of this feature with Review Apps environments. When you set up Review Apps, sometimes they keep running for a long time because some merge requests are left as open. An example for this situation is when the author of the merge request is not actively working on it, due to priority changes or a different approach was decided on, and the merge requests was simply forgotten. Idle environments waste resources, therefore they should be terminated as soon as possible.

To address this problem, you can specify an optional expiration date for Review Apps environments. When the expiry time is reached, GitLab will automatically trigger a job to stop the environment, eliminating the need of manually doing so. In case an environment is updated, the expiration is renewed ensuring that only active merge requests keep running Review Apps.

To enable this feature, you need to specify the environment:auto_stop_in keyword in .gitlab-ci.yml. You can specify a human-friendly date as the value, such as 1 hour and 30 minutes or 1 day. auto_stop_in uses the same format of artifacts:expire_in docs.

Note: Due to the resource limitation, a background worker for stopping environments only runs once every hour. This means environments will not be stopped at the exact timestamp as the specified period, but will be stopped when the hourly cron worker detects expired environments.
Auto-stop example

In the following example, there is a basic review app setup that creates a new environment per merge request. The review_app job is triggered by every push and creates or updates an environment named review/your-branch-name. The environment keeps running until stop_review_app is executed: 

review_app:
  script: deploy-review-app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    on_stop: stop_review_app
    auto_stop_in: 1 week

stop_review_app:
  script: stop-review-app
  environment:
    name: review/$CI_COMMIT_REF_NAME
    action: stop
  when: manual

As long as a merge request is active and keeps getting new commits, the review app will not stop, so developers don’t need to worry about re-initiating review app.

On the other hand, since stop_review_app is set to auto_stop_in: 1 week, if a merge request becomes inactive for more than a week, GitLab automatically triggers the stop_review_app job to stop the environment.

You can also check the expiration date of environments through the GitLab UI. To do so, go to Operations > Environments > Environment. You can see the auto-stop period at the left-top section and a pin-mark button at the right-top section. This pin-mark button can be used to prevent auto-stopping the environment. By clicking this button, the auto_stop_in setting is over-written and the environment will be active until it’s stopped manually.

Environment auto stop

Delete a stopped environment

Introduced in GitLab 12.10.

You can delete stopped environments in one of two ways: through the GitLab UI or through the API.

Delete environments through the UI

To view the list of Stopped environments, navigate to Operations > Environments and click the Stopped tab.

From there, you can click the Delete button directly, or you can click the environment name to see its details and Delete it from there.

You can also delete environments by viewing the details for a stopped environment:

  1. Operations > Environmentsを開きます
  2. Click on the name of an environment within the Stopped environments list.
  3. Click on the Delete button that appears at the top for all stopped environments.
  4. Finally, confirm your chosen environment in the modal that appears to delete it.
Delete environments through the API

Environments can also be deleted by using the Environments API.

Grouping similar environments

Introduced in GitLab 8.14.

As documented in Configuring dynamic environments, you can prepend environment name with a word, followed by a /, and finally the branch name, which is automatically defined by the CI_COMMIT_REF_NAME variable.

In short, environments that are named like type/foo are all presented under the same group, named type.

In our minimal example, we named the environments review/$CI_COMMIT_REF_NAME where $CI_COMMIT_REF_NAME is the branch name. Here is a snippet of the example: 

deploy_review:
  stage: deploy
  script:
    - echo "Deploy a review app"
  environment:
    name: review/$CI_COMMIT_REF_NAME

In this case, if you visit the Environments page and the branches exist, you should see something like:

Environment groups

Monitoring environments

If you have enabled Prometheus for monitoring system and response metrics, you can monitor the behavior of your app running in each environment. For the monitoring dashboard to appear, you need to Configure Prometheus to collect at least one supported metric.

Note: Since GitLab 9.2, all deployments to an environment are shown directly on the monitoring dashboard.

Once configured, GitLab will attempt to retrieve supported performance metrics for any environment that has had a successful deployment. If monitoring data was successfully retrieved, a Monitoring button will appear for each environment.

Environment Detail with Metrics

Clicking on the Monitoring button will display a new page showing up to the last 8 hours of performance data. It may take a minute or two for data to appear after initial deployment.

All deployments to an environment are shown directly on the monitoring dashboard, which allows easy correlation between any changes in performance and new versions of the app, all without leaving GitLab.

Monitoring dashboard

Embedding metrics in GitLab Flavored Markdown

Metric charts can be embedded within GitLab Flavored Markdown. See Embedding Metrics within GitLab Flavored Markdown for more details.

Web terminals

Web terminals were added in GitLab 8.15 and are only available to project Maintainers and Owners.

If you deploy to your environments with the help of a deployment service (for example, the Kubernetes integration), GitLab can open a terminal session to your environment.

This is a powerful feature that allows you to debug issues without leaving the comfort of your web browser. To enable it, just follow the instructions given in the service integration documentation.

Once enabled, your environments will gain a “terminal” button:

Terminal button on environment index

You can also access the terminal button from the page for a specific environment:

Terminal button for an environment

Wherever you find it, clicking the button will take you to a separate page to establish the terminal session:

Terminal page

This works just like any other terminal. You’ll be in the container created by your deployment so you can:

  • Run shell commands and get responses in real time.
  • Check the logs.
  • Try out configuration or code tweaks etc.

You can open multiple terminals to the same environment, they each get their own shell session and even a multiplexer like screen or tmux.

Note: Container-based deployments often lack basic tools (like an editor), and may be stopped or restarted at any time. If this happens, you will lose all your changes. Treat this as a debugging tool, not a comprehensive online IDE.

Check out deployments locally

Since GitLab 8.13, a reference in the Git repository is saved for each deployment, so knowing the state of your current environments is only a git fetch away.

In your Git configuration, append the [remote "<your-remote>"] block with an extra fetch line: 

fetch = +refs/environments/*:refs/remotes/origin/environments/*

Scoping environments with specs

Version history

You can limit the environment scope of a variable by defining which environments it can be available for.

Wildcards can be used, and the default environment scope is *, which means any jobs will have this variable, not matter if an environment is defined or not.

For example, if the environment scope is production, then only the jobs having the environment production defined would have this specific variable. Wildcards (*) can be used along with the environment name, therefore if the environment scope is review/* then any jobs with environment names starting with review/ would have that particular variable.

Some GitLab features can behave differently for each environment. For example, you can create a secret variable to be injected only into a production environment.

In most cases, these features use the environment specs mechanism, which offers an efficient way to implement scoping within each environment group.

Let’s say there are four environments:

  • production
  • staging
  • review/feature-1
  • review/feature-2

Each environment can be matched with the following environment spec:

Environment Spec production staging review/feature-1 review/feature-2
* Matched Matched Matched Matched
production Matched      
staging   Matched    
review/*     Matched Matched
review/feature-1     Matched  

As you can see, you can use specific matching for selecting a particular environment, and also use wildcard matching (*) for selecting a particular environment group, such as Review Apps (review/*).

Note: The most specific spec takes precedence over the other wildcard matching. In this case, review/feature-1 spec takes precedence over review/* and * specs.

Environments Dashboard

See Environments Dashboard for a summary of each environment’s operational health.

制限事項

In the environment: name, you are limited to only the predefined environment variables. Re-using variables defined inside script as part of the environment name will not work.

Further reading

Below are some links you may find interesting: