プロジェクトのセットアップ

このページでは、Customer Support Systems 向けの新しい GitLab プロジェクトを作成および設定する完全なプロセスについて説明します。

プロセス

プロセスは 7 つのステップで構成されます。

1. プロジェクトを作成する
2. プロジェクト設定を調整する
3. 適切なグループを招待する
4. 初期ファイルを追加する
5. CI/CD 変数をセットアップする
6. 追加要件を設定する（必要な場合）
7. プロジェクトを文書化する

ステップ 1 - プロジェクトを作成する

ここからプロジェクト自体を作成します。その際、次の事項を考慮する必要があります。

• プロジェクトの場所
• プロジェクトの名前
• プロジェクトのスラッグ

プロジェクトの場所

プロジェクトを作成するには、プロジェクトを置く_場所_を把握する必要があります。可能な場合は、類似するプロジェクトをまとめます。これにより、多くの場合、プロジェクトを配置する既存のサブグループを見つけられます。

たとえば、Zendesk Global 用の同期リポジトリを作成する場合、次の理由からサブグループ gitlab-support-readiness/zendesk-global 内に配置します。

• Customer Support Systems の非公開プロジェクトであるため（私たちのプライベートネームスペース gitlab-support-readiness 内）
• Zendesk Global に関連するため（サブグループ zendesk-global 内）

作成する同期リポジトリがチケット属性またはメタデータ（チケットフォーム、チケットフィールドなど）に関連する場合は、gitlab-support-readiness/zendesk-global/tickets サブグループ内に作成します。

プロジェクトを配置する既存のサブグループが見つからない場合は、チームに相談して、プロジェクトを作成する最適な場所を決定してください。

プロジェクトの名前

プロジェクトを作成するときは、簡潔で自己説明的な名前を目指す必要があります。このためには、場所を活用します。

たとえば、Zendesk US Government のチケット処理を扱うプロジェクトを作成する場合、場所を決定することで、サブグループ gitlab-support-readiness/zendesk-us-government/tickets 内に置かれることが分かります。これが分かれば、場所のパスから Zendesk US Government のチケットに関連していることがすでに分かるため、プロジェクト名は単に Processor とできます。

プロジェクト名に迷う場合は、チームに相談して使用する最適な名前を決定してください。

プロジェクトのスラッグ

名前を決定するときと同様に、スラッグもパスと組み合わせて、簡潔で自己説明的なものにします。ほとんどの場合、GitLab が生成するスラッグでこの目的を満たせます。

プロジェクトのスラッグに迷う場合は、チームに相談して使用する最適なスラッグを決定してください。

ステップ 2 - 設定を調整する

プロジェクトを作成したら、次のように設定を手動で調整する必要があります。

ステップ 3 - 適切なグループを招待する

新しいプロジェクトの設定を調整した後、適切なグループをメンバーとして招待する必要があります。継承の設定により、プロジェクトの_アクセス_はグループメンバーシップを通じて自動的に処理されます。そのため、これは実際には、マージリクエストの承認で CODEOWNERS ファイルが使用する対象に関するものです。

• Customer Support Systems のリーダーシップを必要とする対象に関するプロジェクトには、gitlab-support-readiness/cust_support_ops_critical_access を招待します。
• 米国市民権を_必要とする_プロジェクトには、gitlab-support-readiness/cust_support_ops_team_us_citizens を招待します。
  • 注記 特定の市民権を必要とするプロジェクトがないよう努めるべきです。プロジェクトで市民権が必要な場合は、プロジェクト内の何らかの出力（コード、CI/CD など）に市民権で保護されるデータが含まれていることを示します。常に回避できるわけではありませんが、gitlab.com 内に市民権で保護されるデータを_含めない_よう常に努めてください。
• その他の場合は、gitlab-support-readiness/cust_support_ops_team を招待します。

招待するグループに迷う場合は、チームに支援を求めてください。

ステップ 4 - ファイルを追加する

このステージでは、プロジェクトにファイルを追加するための初回コミットを行います。追加する必要がある正確なファイルは、プロジェクトの目的（およびその機能）に応じて異なります。プロジェクトのセットアップ方法に沿うよう、さまざまなファイルについて以下のガイドラインを確認してください。

• .gitlab/CODEOWNERS

  • 内容は使用するコードに応じて異なりますが、常に次を開始点とします。

  [Customer Support Systems]
  * @GROUP_TO_INVITE
  

  • GROUP_TO_INVITE の値の詳細については、ステップ 3を参照してください。

• bin/post_in_slack.sh

  • このファイルには常に実行権限を設定します。
  • このファイルの内容は常に次のとおりです。

  curl -ss $SLACK_URL_PIPELINE_FAIL \
    -X POST \
    -H 'Content-type: application/json' \
    --data "{\"text\": \"<$CI_PROJECT_URL|$CI_PROJECT_PATH> pipeline <$CI_PIPELINE_URL|#$CI_PIPELINE_ID> failed $DATE\", \"mrkdwn\": true }"
  

• .gitlab-ci.yml

  • 内容は使用するコードに応じて異なりますが、一般的なプロジェクトタイプでは、次の開始テンプレートを使用できます。

    同期リポジトリ

    image: "registry.gitlab.com/gitlab-support-readiness/images/ruby:3.2.2"
    
    stages:
    - compare
    - sync
    - notify
    
    before_script:
    - ruby -v
    - gem install bundler
    - bundle install
    
    compare:
      stage: compare
      script:
      - ./bin/compare
      rules:
      - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      retry:
        max: 2
        when:
        - runner_system_failure
        - stuck_or_timeout_failure
    
    sync:
      stage: sync
      script:
      - ./bin/sync
      rules:
      - if: $CI_PIPELINE_SOURCE == 'trigger'
      retry:
        max: 2
        when:
        - runner_system_failure
        - stuck_or_timeout_failure
    
    post_in_slack_on_failure:
      before_script: ''
      stage: notify
      when: on_failure
      image: registry.gitlab.com/gitlab-support-readiness/images/curl:latest
      script:
      - ./bin/post_in_slack.sh
    

    Zendesk アプリ

    image: "registry.gitlab.com/gitlab-support-readiness/images/ruby:3.2.2"
    
    stages:
    - compare
    - sync
    - notify
    
    before_script:
    - ruby -v
    - gem install bundler
    - bundle install
    
    compare_instances:
      stage: compare
      script:
      - ./bin/compare_sandbox
      - ./bin/compare_production
      rules:
      - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      retry:
        max: 2
        when:
        - runner_system_failure
        - stuck_or_timeout_failure
    
    force_sandbox_sync:
      stage: sync
      script:
      - ./bin/sync_sandbox force
      needs: ['compare_instances']
      when: manual
      rules:
      - if: $CI_PIPELINE_SOURCE == 'merge_request_event'
      retry:
        max: 2
        when:
        - runner_system_failure
        - stuck_or_timeout_failure
    
    perform_sandbox_sync:
      stage: sync
      script:
      - ./bin/sync_sandbox
      rules:
      - if: $CI_PIPELINE_SOURCE == 'schedule' && $SANDBOX == 'true'
      retry:
        max: 2
        when:
        - runner_system_failure
        - stuck_or_timeout_failure
    
    perform_production_sync:
      stage: sync
      script:
      - ./bin/sync_production
      rules:
      - if: $CI_PIPELINE_SOURCE == 'schedule' && $SANDBOX == 'false'
      retry:
        max: 2
        when:
        - runner_system_failure
        - stuck_or_timeout_failure
    
    post_in_slack_on_failure:
      before_script: ''
      stage: notify
      when: on_failure
      image: registry.gitlab.com/gitlab-support-readiness/images/curl:latest
      script:
      - ./bin/post_in_slack.sh
    

  • ここに何を含めるべきか迷う場合は、チームの他のメンバーに支援を求めてください。

• .rubocop.yml

  • このファイルの内容は、現在使用している Ruby バージョンと常に一致させる必要があります。つまり、次のとおりにします。

  AllCops:
    NewCops: enable
    TargetRubyVersion: 3.2.2
  

• .ruby-version

  • このファイルの内容は、現在使用している Ruby バージョンと常に一致させる必要があります。つまり、次のとおりにします。

  3.2.2
  

• Gemfile

  • gem のリストはアルファベット順にします。
  • 必要な gem は使用するコードに応じて異なりますが、常に次を開始点とします。

  # frozen_string_literal: true
  
  source 'https://rubygems.org'
  

• README.md

  • 正確な内容は異なりますが、README.md ファイルに次の事項が記載されていることを確認してください。
    • プロジェクト名
    • 簡単な説明
    • ファイルツリーのレイアウト
    • 要件
    • CI/CD パイプライン情報
  • ここに何を含めるべきか迷う場合は、チームの他のメンバーに支援を求めてください。

ステップ 5 - CI/CD 変数をセットアップする

プロジェクトに必要な CI/CD 変数を設定します。多くの変数は親ネームスペースから継承されるため、プロジェクト固有の値に集中してください。

追加する共通変数:

• API トークンの値（例: ZD_TOKEN、GL_TOKEN、CALENDLY_API_TOKEN など）
• Slack Webhook（継承される SLACK_URL_PIPELINE_FAIL を除く）

継承された変数を確認するには:

1. プロジェクトで Settings > CI/CD > Variables に移動します。
2. Inherited from group セクションを確認して、すでに利用できる項目を確認します。
3. 親ネームスペースからすでに提供されていない変数のみを追加します。

変数の保護:

• 機密トークンを Masked としてマークします。

ステップ 6 - 追加設定（必要な場合）

ほとんどのプロジェクトでは、ステップ 1 から 5 で十分です。ただし、一部のプロジェクトでは次のような追加設定が必要になる場合があります。

• 外部統合用の Webhook をセットアップする
• コードを別のプロジェクトにミラーリングする
• 外部サービス統合を設定する
• スケジュール済みパイプラインをセットアップする

追加設定が必要かどうか迷う場合は、チームに相談してください。

ステップ 7 - 文書化する

プロジェクト作成の最終ステップは、プロジェクトに関する情報でハンドブックページを更新することです。次の事項を含めます。

• 何であるか
• 何をするか
• どのように機能するか
• 使用するデプロイ戦略の種類
• 変更方法
• トラブルシューティング情報

プロジェクト作成後

プロジェクトを作成して文書化したら、次の状態になります。

• プロジェクトはグループメンバーシップに基づき、適切なチームメンバーがアクセス可能になります。
• CI/CD パイプラインは設定されたルールに従って実行されます。
• 変更には、CODEOWNERS の承認を伴うマージリクエストが必要です。
• プロジェクトの初期パイプラインを監視し、すべてが正しく設定されていることを確認します。

ページのソースコードを見る - ページの編集 - please contribute.