Platform.sh User Documentation

Integrate with GitHub

Upsun Beta

Access our newest offering - Upsun!

Get your free trial by clicking the link below.

Get your Upsun free trial

If you have code in a GitHub repository, you might want to connect it to a Platform.sh project. This means you can keep your GitHub workflows and treat the GitHub repository as the source of truth for your code.

Your Platform.sh project becomes a mirror of your GitHub repository. This means you shouldn’t push code directly to Platform.sh. Any changes you push directly get overwritten by the integration when changes happen in the GitHub repository.

When you set up an integration with GitHub, it automates the following processes for you:

  • Creating a new environment when a branch is created or a pull request is opened.
  • Rebuilding the environment when new code is pushed to GitHub.
  • Deleting the environment when a pull request is merged.

Before you begin Anchor to this heading

To manage source integrations, you need to be a project admin.

You also need a GitHub repository with working code.

1. Generate a token Anchor to this heading

To integrate your Platform.sh project with an existing GitHub repository, you need to generate a new token. You can generate a classic personal access token, or a fine-grained personal access token for even greater control over the permissions you grant.

For the integration to work, your GitHub user needs to have permission to push code to the repository.

When you set up or update an integration, it also needs permission to manage its webhooks. This means your user needs to be a repository admin to create the integration. You can remove this permission after setup.

Make sure you give your token a description.

If you’re generating a classic personal access token, ensure the token has the appropriate scopes based on what you want to do:

Scope Purpose
admin:repo_hook To create webhooks for events in repositories. Always needed.
public_repo To integrate with public repositories.
repo To integrate with your private repositories.
repo and read:org To integrate with private repositories in organizations you belong to.

If you’re generating a fine-grained personal access token, ensure the token has the right repository permissions for the integration to work:

Permission Access level
Commit statuses Read and write
Contents Read and write
Metadata Read-only
Pull request Read and write
Webhooks Read and write

After you’ve set the needed scopes or permissions, generate and copy your token.

2. Enable the integration Anchor to this heading

To enable the integration, use either the CLI or the Console.

Run the following command:

platform integration:add \
  --project PROJECT_ID \
  --type github \
  --repository OWNER/REPOSITORY \
  --token GITHUB_ACCESS_TOKEN \
  --base-url GITHUB_URL
  • PROJECT_ID is the ID of your Platform.sh project.
  • OWNER/REPOSITORY is the name of your repository in GitHub.
  • GITHUB_ACCESS_TOKEN is the token you generated.
  • GITHUB_URL is the base URL for your GitHub server if you self-host. If you use the public https://github.com, omit the --base-url flag when running the command.

For example, if your repository is located at https://github.com/platformsh/platformsh-docs, the command is similar to the following:

platform integration:add \
  --project abcdefgh1234567 \
  --type github \
  --repository platformsh/platformsh-docs \
  --token abc123
  1. Select the project where you want to enable the integration.
  2. Click Settings.
  3. Under Project settings, click Integrations.
  4. Click + Add integration.
  5. Under GitHub, click + Add.
  6. Add the token you generated.
  7. Optional: If your GitHub project isnโ€™t hosted at github.com, enter your GitHub custom domain.
  8. Click Continue.
  9. Choose the repository to use for the project.
  10. Check that the other options match what you want.
  11. Click Add integration.

In both the CLI and Console, you can choose from the following options:

CLI flag Default Description
fetch-branches true Whether to track all branches and create inactive environments from them.
prune-branches true Whether to delete branches from Platform.sh that donโ€™t exist in the GitHub repository. Automatically disabled when fetching branches is disabled.
build-pull-requests true Whether to track all pull requests and create active environments from them, which builds the pull request.
build-draft-pull-requests true Whether to also track and build draft pull requests. Automatically disabled when pull requests arenโ€™t built.
pull-requests-clone-parent-data true Whether to clone data from the parent environment when creating a pull request environment.
build-pull-requests-post-merge false Whether to build what would be the result of merging each pull request. Turning it on forces rebuilds any time something is merged to the target branch.

To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches and prune-branches options.

3. Validate the integration Anchor to this heading

Verify that your integration is functioning properly using the CLI:

platform integration:validate

Add the webhook manually Anchor to this heading

If the integration was added with the correct permissions, the necessary webhook is added automatically. If you see a message that the webhook wasn’t added, add one manually.

To configure a webhook on a GitHub repository, you need to have Admin user permissions.

  1. Get the webhook URL by running this command: platform integration:get --property hook_url.

  2. Copy the returned URL.

  3. In your GitHub repository, click Settings > Webhooks > Add webhook.

  4. In the Payload URL field, paste the URL you copied.

  5. For the content type, select application/json.

  6. Select Send me everything.

  7. Click Add webhook.

You can now start pushing code, creating new branches, and opening pull requests directly in your GitHub repository. Your Platform.sh environments are automatically created and updated.

Environment parent and status Anchor to this heading

When a branch is created in GitHub, an environment is created in Platform.sh with the default branch as its parent. It starts as an inactive environment with no data or services.

When a pull request is opened in GitHub, an environment is created in Platform.sh with the pull request’s target branch as its parent. It starts as an active environment with a copy of its parent’s data.

Source of truth Anchor to this heading

When you add an integration, your GitHub repository is considered to be the source of truth for the project. Your Platform.sh project is only a mirror of that repository and you should only push commits to GitHub. Any changes you push to Platform.sh get overwritten by the integration when changes happen in your GitHub repository.

To clone your code, follow these steps:

Run the following command:

platform get PROJECT_ID
  1. In the Console, open the project you want to clone.
  2. Click Code.
  3. Click Git.
  4. Run the command you find using Git.

When you do this, you're cloning from your integrated GitHub repository, if you have the appropriate access to do so.

Pull request URLs Anchor to this heading

When a pull request is deployed, 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.

Is this page helpful?