The GitHub integration allows you to manage your Platform.sh environments directly from your GitHub repository.
- Create a new environment when creating a branch or opening a pull request on GitHub.
- Rebuild the environment when pushing new code to GitHub.
- Delete the environment when merging a pull request.
To manage source integrations, you need to be a project admin.
To integrate your Platform.sh project with an existing GitHub repository, generate a new token in your GitHub settings.
Give it a description and then ensure the token has the following scopes:
- To integrate with public repositories:
- To integrate with your own private repositories:
- To integrate with your organization’s private repositories:
- To automatically create web hooks:
Copy the token and make a note of it (temporarily).
Note that for the integration to work, your GitHub user needs to have permission to push code to the repository.
Run the following command:
platform integration:add --type=gitlab --token=GITHUB_ACCESS_TOKEN --server-project=OWNER/REPOSITORY --project=PLATFORM_SH_PROJECT_ID
GITHUB_ACCESS_TOKENis the token you generated.
OWNER/REPOSITORYis the name of the repository in GitHub.
PLATFORM_SH_PROJECT_IDis the ID for your Platform.sh project.
For example, if your repository is located at
the command is similar to the following:
platform integration:add --type=github --token=abc123 --repository=platformsh/platformsh-docs --project=abcdefgh1234567
--fetch-branches: Track and deploy branches (true by default)
--prune-branches: Delete branches that don’t exist in the remote GitHub repository (true by default)
--build-pull-requests: Track and deploy pull-requests (true by default)
--build-draft-pull-requests: If set to
true, draft pull requests also have an environment created. If
false, they’re ignored. If
falsethis value is ignored. (
falseto have Platform.sh build the branch specified in a PR.
trueto build the result of merging the PR. (
--pull-requests-clone-parent-data: Set to
falseto disable cloning of parent environment data when creating a PR environment, so each PR environment starts with no data. (
--base-url: Only set if using GitHub Enterprise, hosted on your own server. If so, set this to the base URL of your private server (the part before the user and repository name).
Note that the
--prune-branches option depends on
--fetch-branches being enabled.
--fetch-branches is disabled,
--prune-branches is automatically set to false, even if specifically set to true.
- Select the project where you want to enable the integration.
- Click Settings.
- Under Project settings, click Integrations.
- Click + Add integration.
- On the GitHub integration, click + Add.
- Add the token you generated.
- Optional: If your GitHub instance has a custom domain, enter its base URL.
- Choose the repository to use for the project.
- Check that the other options match what you want.
- Click Add integration.
Verify that your integration is functioning properly using the CLI:
If the integration was added with correct permissions, the necessary webhook is added automatically.
If you see the message
Failed to read or write webhooks, you need to add a webhook manually:
- Get the webhook URL by running
- Copy the
- Go to your GitHub repository and click Settings, select the Webhooks tab, and click Add webhook.
- Paste the hook URL, select application/json for the content type, select Send me everything for the events you want to receive, and click Add webhook.
You can now start pushing code, creating new branches or opening pull requests directly on your GitHub repository.
Note that if you have created your account using the GitHub OAuth Login then to use the Platform CLI, you need to set up a password.
Environments based on GitHub pull requests have their target branch set as their parent on Platform.sh. They’re added as active environments with a copy of the parent’s data.
Environments based on branches always have the default branch set as their parent on Platform.sh. They’re added as inactive environments with no data or services.
You can clone your codebase by running
platform get <projectID>
or in your project in the console by going to Code > Git and running the
git clone command.
When you perform this action, you are actually cloning from your remote integrated repository, if you have the appropriate access to do so.
Your GitHub repository is considered to be the source of truth for the project. The project is only a mirror of that repository and all commits should be pushed only to GitHub.
For pull requests, the integration reports the primary URL for the deployed environment. So you get a link to the deployed environment right in the pull request.
If you have multiple routes, ensure the correct one is reported by specifying the primary route.