Skip to main content

​
1. Generate a token

To integrate your Upsun 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:
ScopePurpose
admin:repo_hookTo create webhooks for events in repositories. Always needed.
public_repoTo integrate with public repositories.
repoTo integrate with your private repositories.
repo and read:orgTo 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:
PermissionAccess level
Commit statusesRead and write
ContentsRead and write
MetadataRead-only
Pull requestRead and write
WebhooksRead and write
After you’ve set the needed scopes or permissions, generate and copy your token.

​
2. Enable the integration

To enable the integration, use either the CLI or the Console.
Run the following command:
upsun integration:add \
  --project <VariableBlock name="PROJECT_ID" /> \
  --type github \
  --repository <VariableBlock name="OWNER/REPOSITORY" /> \
  --token <VariableBlock name="GITHUB_ACCESS_TOKEN" /> \
  --base-url <VariableBlock name="GITHUB_URL" />
  • PROJECT_ID is the ID of your Upsun 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:
upsun integration:add \
  --project abcdefgh1234567 \
  --type github \
  --repository platformsh/platformsh-docs \
  --token abc123
In both the CLI and Console, you can choose from the following options:
CLI flagDefaultDescription
fetch-branchestrueWhether to mirror and update branches on Upsun and create inactive environments from them. When enabled, merging on an Upsun environment isn’t possible. That is, merging environments must be done on the source repository rather than on the Upsun project. See note below for details related to this flag and synchronizing code from a parent environment.
prune-branchestrueWhether to delete branches from Upsun that don’t exist in the GitHub repository. When enabled, branching (creating environments) must be done on the source repository rather than on the Upsun project. Branches created on Upsun that are not on the source repository will not persist and will be quickly pruned. Automatically disabled when fetching branches is disabled.
build-pull-requeststrueWhether to track all pull requests and create active environments from them, which builds the pull request.
build-draft-pull-requeststrueWhether to also track and build draft pull requests. Automatically disabled when pull requests aren’t built.
pull-requests-clone-parent-datatrueWhether to clone data from the parent environment when creating a pull request environment.
build-pull-requests-post-mergefalseWhether 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.
resources-initfalseTo specify a resource initialization strategy for new containers. Once set, the strategy applies to all the deployments you launch through your source integration. See more information on available resource initialization strategies.
To keep your repository clean and avoid performance issues, make sure you enable both the fetch-branches and prune-branches options.

​
Source of truth

​
Sync, fetch, and prune

Last modified on March 11, 2026