How to utilize the CLI to modify already existing Git integrations

Goal

To learn how to use the CLI for getting more information on a Git integration, also how to modify certain configuration options.

Assumptions

Problems

None in particular. This How to is about raising awareness to the usefulness of the CLI tool.

Steps

1. Check what “integration” commands are available

platform list | grep integration  

integration
  integration:add                                Add an integration to the project
  integration:delete                             Delete an integration from a project
  integration:get                                View details of an integration
  integration:list (integrations)                View a list of project integration(s)
  integration:update                             Update an integration
  integration:validate                           Validate an existing integration

2. List the integrations added to your project

platform integration:list

+------------------+--------+-----------------------------------------------------------------------------------------------------+
| ID               | Type   | Summary                                                                                             |
+------------------+--------+-----------------------------------------------------------------------------------------------------+
| <integration id> | github | Repository: ...                                                                                     |
|                  |        | Hook URL: https://<region>.platform.sh/api/projects/<project id>/integrations/<integration id>/hook |
+------------------+--------+-----------------------------------------------------------------------------------------------------+

View integration details with: platform integration:get [id]

Add a new integration with: platform integration:add
Delete an integration with: platform integration:delete [id]

3. Get the integration details

platform integration:get <integration id>

+---------------------------------+-------------------------------------------------------------------------------------------+
| Property                        | Value                                                                                     |
+---------------------------------+-------------------------------------------------------------------------------------------+
| id                              | <integration id>                                                                          |
| type                            | github                                                                                    |
| token                           | ******                                                                                    |
| repository                      | ...                                                                                       |
| fetch_branches                  | true                                                                                      |
| prune_branches                  | true                                                                                      |
| build_pull_requests             | true                                                                                      |
| build_pull_requests_post_merge  | false                                                                                     |
| pull_requests_clone_parent_data | true                                                                                      |
| hook_url                        | https://<region>.platform.sh/api/projects/<project id>/integrations/<integration id>/hook |
+---------------------------------+-------------------------------------------------------------------------------------------+

4. Check the options and select which ones to modify

platform integration:update --help

Command: integration:update
Description: Update an integration

Usage:
 platform integration:update [--type TYPE] [--token TOKEN] [--key KEY] [--secret SECRET] [--base-url BASE-URL] [--gitlab-project GITLAB-PROJECT] [--repository REPOSITORY] [--build-merge-requests BUILD-MERGE-REQUESTS] [--build-pu>

Arguments:
  id                                                                       The ID of the integration to update

Options:
      --type=TYPE                                                          The integration type ('bitbucket', 'github', 'gitlab', 'hipchat', 'webhook', 'health.email', 'health.pagerduty', 'health.slack')
      --token=TOKEN                                                        An OAuth token for the integration
      --key=KEY                                                            A Bitbucket OAuth consumer key
      --secret=SECRET                                                      A Bitbucket OAuth consumer secret
      --base-url=BASE-URL                                                  The base URL of the GitLab installation
      --gitlab-project=GITLAB-PROJECT                                      The GitLab project (e.g. 'namespace/repo')
      --repository=REPOSITORY                                              The repository to track (e.g. 'user/repo')
      --build-merge-requests=BUILD-MERGE-REQUESTS                          GitLab: build merge requests as environments [default: true]
      --build-pull-requests=BUILD-PULL-REQUESTS                            Build every pull request as an environment [default: true]
      --build-pull-requests-post-merge=BUILD-PULL-REQUESTS-POST-MERGE      Build pull requests based on their post-merge state [default: false]
      --merge-requests-clone-parent-data=MERGE-REQUESTS-CLONE-PARENT-DATA  GitLab: clone data for merge requests [default: true]
      --pull-requests-clone-parent-data=PULL-REQUESTS-CLONE-PARENT-DATA    Clone the parent environment's data for pull requests [default: true]
      --resync-pull-requests=RESYNC-PULL-REQUESTS                          Re-sync pull request environment data on every build [default: false]
      --fetch-branches=FETCH-BRANCHES                                      Fetch all branches from the remote (as inactive environments) [default: true]
      --prune-branches=PRUNE-BRANCHES                                      Delete branches that do not exist on the remote [default: true]
      --room=ROOM                                                          HipChat room ID
      --url=URL                                                            Generic webhook: a URL to receive JSON data
      --events=EVENTS                                                      A list of events to report, e.g. environment.push [default: ["*"]] (multiple values allowed)
      --states=STATES                                                      A list of states to report, e.g. pending, in_progress, complete [default: ["complete"]] (multiple values allowed)
      --environments=ENVIRONMENTS                                          The environment IDs to include [default: ["*"]] (multiple values allowed)
      --excluded-environments=EXCLUDED-ENVIRONMENTS                        The environment IDs to exclude (multiple values allowed)
      --from-address=FROM-ADDRESS                                          The From address for alert emails [default: "noreply@platform.sh"]
      --recipients=RECIPIENTS                                              The recipient email address(es) (multiple values allowed)
      --channel=CHANNEL                                                    The Slack channel
      --routing-key=ROUTING-KEY                                            The PagerDuty routing key
  -p, --project=PROJECT                                                    The project ID or URL
      --host=HOST                                                          The project's API hostname
  -W, --no-wait                                                            Do not wait for the operation to complete
      --wait                                                               Wait for the operation to complete (default)
  -h, --help                                                               Display this help message
  -q, --quiet                                                              Do not output any message
  -V, --version                                                            Display this application version
  -y, --yes                                                                Answer "yes" to all prompts; disable interaction
  -n, --no                                                                 Answer "no" to all prompts
  -v|vv|vvv, --verbose                                                     Increase the verbosity of messages

Examples:
 Switch on the "fetch branches" option for a specific integration:
   platform integration:update ZXhhbXBsZSB --fetch-branches 1

Conclusion

The CLI is a very handy tool for listing information about integrations, also for adding new ones (or modifying those already existing).