Goal
To learn how to use the CLI for getting more information on a Git integration, also how to modify certain configuration options.
Assumptions
- Access to a project hosted on Platform.sh
- Your project account has administrator rights
- Knowledge on using the Platform.sh CLI
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).