diff --git a/src/middleware.ts b/src/middleware.ts index e54eaa3e93..99c9058f16 100644 --- a/src/middleware.ts +++ b/src/middleware.ts @@ -205,6 +205,7 @@ const RedirectMap: Record = { "/nextjs/considerations": "/nextjs/comparison-to-cms-hosting", "/guides/global-cdn/global-cdn-beta": "/guides/global-cdn/next-gen-global-cdn", "/guides/global-cdn/global-cdn-beta#faq": "/guides/global-cdn/global-cdn-faq", + "/guides/external-repositories/setup": "/guides/external-repositories/github", // These are redirects that were not in AGCDN but discovered in the // process of migrating the site to Next.js. diff --git a/src/source/content/guides/external-repositories/02-github.md b/src/source/content/guides/external-repositories/02-github.md new file mode 100644 index 0000000000..0d14dfbaec --- /dev/null +++ b/src/source/content/guides/external-repositories/02-github.md @@ -0,0 +1,121 @@ +--- +title: External Repositories +subtitle: Connect GitHub +description: Instructions for setting up Pantheon's external repository integration for GitHub and creating a new site via the Pantheon Dashboard or Terminus. +tags: [continuous-integration, workflow] +contributors: [stevector,jazzsequence] +contenttype: [guide] +showtoc: true +innav: [true] +categories: [automate, workflows] +cms: [drupal, wordpress] +audience: [development] +product: [terminus] +integration: [--] +reviewed: "2026-08-26" +permalink: docs/guides/external-repositories/github +--- + +This page provides instructions for setting up a new site using Pantheon's external repository integration for GitHub. You can create new sites through the Pantheon Dashboard or via Terminus. You can also connect sites using existing repositories. + +## Requirements + +* Gold, Platinum or Diamond Workspace on Pantheon +* [Pantheon GitHub Application](https://github.com/apps/pantheon-site-integration): + * Must be installed by a user who is both a GitHub organization admin and a member of the corresponding Pantheon workspace. + * Other workspace members cannot install the app themselves. + * The GitHub organization admin must complete the installation first, and then any workspace member can create sites using repositories the app has access to. + * The GitHub Application cannot be used with GitHub Enterprise Server. +* Before connecting an existing repository to a new Pantheon site, it must use Pantheon's expected file structure: + * [WordPress Repository Specification](/guides/external-repositories/setup-wordpress) + * [Drupal Repository Specification](/guides/external-repositories/setup-drupal) + + +## Connect a repo to a new site +### From the Pantheon Dashboard +1. Go to your [Professional Workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces), and select the **Create New Site** button. + +1. Choose WordPress, Drupal or Next.js from the Create New Site page + + ![create new site dashboard](../../../images/github-app/create-new-site.png) + +1. Enter site name, and select desired region. Then click Create Site. + +1. Choose GitHub in the following prompt: + + ![select external repository](../../../images/github-app/select-external-repository.png) + + +1. Click the Connect button: + + ![connect GitHub account](../../../images/github-app/gh-connect.png) + + + + If you are part of a GitHub organization, the application must be installed by an *owner* of the GitHub organization. The user who installs the application must have the correct permissions. + + If you have previously connected the GitHub application to a site in a *different* Pantheon organization, see [the instructions below](#configure-prompts) for connecting your GitHub application to *another* Pantheon organization. + + + +1. Once connected, you should see a dropdown with your user or organization listed. Select your user/organization and click Continue. + + ![select user or organization](../../../images/github-app/gh-select-account.png) + +1. You will be prompted to create a new repository or use an existing one. + + + + If you choose to use an existing repository, it must already be set up as a Pantheon site repository (e.g. with a pantheon.yml file and a structure that Pantheon sites typically have). For details, see the following: + * [WordPress Repository Specification](/guides/external-repositories/setup-wordpress) + * [Drupal Repository Specification](/guides/external-repositories/setup-drupal) + + If you don't have an existing repository ready, you can create a new one. This will be created in the GitHub organization or user that was connected to the application. + + + + ![create new repository](../../../images/github-app/gh-create-new-repo.png) + + After naming your repository (the Pantheon site name will be automatically filled in when you click inside the Repository name field), click Deploy. + + In the background, a Pantheon site environment will be initialized and a new git repository on GitHub will be created with the starter upstream code. This may take several minutes. Be sure to leave this screen up until it changes. + + ![site creation in progress](../../../images/github-app/gh-creating-wp.png) + +After the site is created, you will be redirected to your Pantheon Site Dashboard. You should also see a new repository for the site on GitHub and a Pantheon dashboard link to take you there. + +![site dash](../../../images/github-app/gh-site-dash.png) + +### From the command-line interface +1. Use the `terminus site:create` command (see [documentation](/terminus/commands/site-create)) with the following flags: + + * `` — Any upstream your Pantheon user has access to, e.g. `nextjs16`, `WordPress`, or an upstream UUID. If omitted, a list of available upstreams will be displayed. + * `--org=` — The Pantheon organization. Required for sites using an external VCS provider. + * `--vcs-provider=github` — Required for GitHub repositories. + * `--vcs-org=` — The GitHub organization or username that owns the repository. If omitted, you will be prompted to choose from existing connections or add a new one. + * `--repository-name=` — The name of the repository to create on GitHub. Must be unique to the user or organization. + * `--no-create-repo` - (optional) Only used when connecting an existing repository, tells Terminus not to create a new repository and instead connect to the one specified by `--repository-name`. + + ```bash{promptUser: user} + terminus site:create --org= --vcs-provider=github --vcs-org= --repository-name= + ``` + + + + To connect an existing repository from the command-line, pass the `--no-create-repo` flag. This will connect the new site to your existing repository specified by `--repository-name`. + + + +1. Once the command is issued, the site creation process will begin to initialize the Pantheon site environment and the GitHub repository. This may take several minutes. Be sure not to close your terminal window before the process is complete. The command will output logs to the terminal during the process. When you see `Site creation workflow completed successfully.` and `Waiting for site dev environment to become available...` you should be able to see the site in your sites list in the Pantheon dashboard and see the build workflow in progress. + +1. When the workflow is complete, you will see `Code repository cloned successfully to the current directory.` and the dashboard link in the log. + +## Troubleshooting + +### Configure prompts + +If you find yourself at a screen that asks you to *configure* the app, it typically means you've already installed the GitHub Application and connected it to another Pantheon organization. You will need to connect the application to this organization using `terminus vcs:connection:link`. See the documentation in [Usage](/guides/external-repositories/usage). + +![Configure existing app](../../../images/github-app/github-app-configure-app.png) + +![GitHub application configuration screen](../../../images/github-app/github-app-integration-config.png) \ No newline at end of file diff --git a/src/source/content/guides/external-repositories/02-setup.md b/src/source/content/guides/external-repositories/02-setup.md deleted file mode 100644 index f75c258886..0000000000 --- a/src/source/content/guides/external-repositories/02-setup.md +++ /dev/null @@ -1,209 +0,0 @@ ---- -title: External Repositories -subtitle: Setup -description: Instructions for setting up Pantheon's external repository integration and creating a new site via the Pantheon Dashboard or Terminus. -tags: [continuous-integration, workflow] -contributors: [stevector,jazzsequence] -contenttype: [guide] -showtoc: true -innav: [true] -categories: [automate, workflows] -cms: [drupal, wordpress] -audience: [development] -product: [terminus] -integration: [--] -reviewed: "2026-06-24" -permalink: docs/guides/external-repositories/setup ---- - -This page provides instructions for setting up a new site using Pantheon's external repository integration. You can create new sites through the Pantheon Dashboard (GitHub only) or via Terminus (GitHub and GitLab). You can also connect sites using existing repositories. - -## Creating a new site with a new repository - - - - - - - -Dashboard-based site creation is currently supported for **GitHub** only. GitLab support via the Dashboard is planned for a future release. To create a site with a GitLab repository, use Terminus. - - - -1. Choose WordPress, Drupal or Next.js from the Create New Site page - - ![create new site dashboard](../../../images/github-app/github-app-create-new-site.png) - -1. Select **External Repository** as the location for your site's codebase. - - ![select external repository](../../../images/github-app/github-app-create-site.png) - -1. Connect your GitHub account. - - ![connect GitHub account](../../../images/github-app/github-app-connect-git.png) - - - - If you are part of a GitHub organization, the application must be installed by an *owner* of the GitHub organization. The user who installs the application must have the correct permissions. - - If you have previously connected the GitHub application to a site in a *different* Pantheon organization, see the instructions below for connecting your GitHub application to *another* Pantheon organization. - - - -1. Click the Connect button. - - After authorizing the GitHub application, you may be redirected to the initial site creation step to name the site and choose the region. Once continuing past that, you should see a dropdown with your user or organization listed. Select your user/organization and click Continue. - - ![select user or organization](../../../images/github-app/github-app-selectaccount.png) - -1. You will be prompted to create a new repository or use an existing one. - - - - If you choose to use an existing repository, it must already be set up as a Pantheon site repository (e.g. with a pantheon.yml file and a structure that Pantheon sites typically have). If you don't have an existing repository ready, you can create a new one. This will be created in the GitHub organization or user that was connected to the application. - - - - ![create new repository](../../../images/github-app/github-app-configure-git.png) - - After naming your repository (the Pantheon site name will be automatically filled in when you click inside the Repository name field), wait for your site to be created. In the background, a Pantheon site environment will be initialized and a new git repository on GitHub will be created with the starter upstream code. This may take several minutes. Be sure to leave this screen up until it changes. - - ![site creation in progress](../../../images/github-app/github-app-creating-nextjs.png) - -After the site is created, you will be redirected to the Builds page of your new site. You should also see a new repository for the site on GitHub and a Pantheon dashboard link to take you there. - -![builds page](../../../images/github-app/github-app-build-progress.png) - - - - - -1. Use the `terminus site:create` command (see [documentation](/terminus/commands/site-create)) with the following flags: - - * `` — Any upstream your Pantheon user has access to, e.g. `nextjs16`, `WordPress`, or an upstream UUID. If omitted, a list of available upstreams will be displayed. - * `--org=` — The Pantheon organization. Required for sites using an external VCS provider. - * `--vcs-provider=github` — Required for GitHub repositories. - * `--vcs-org=` — The GitHub organization or username that owns the repository. If omitted, you will be prompted to choose from existing connections or add a new one. - * `--repository-name=` — The name of the repository to create on GitHub. Must be unique to the user or organization. - - ```bash{promptUser: user} - terminus site:create --org= --vcs-provider=github --vcs-org= --repository-name= - ``` - -1. Once the command is issued, the site creation process will begin to initialize the Pantheon site environment and the GitHub repository. This may take several minutes. Be sure not to close your terminal window before the process is complete. The command will output logs to the terminal during the process. When you see `Site creation workflow completed successfully.` and `Waiting for site dev environment to become available...` you should be able to see the site in your sites list in the Pantheon dashboard and see the build workflow in progress. - -1. When the workflow is complete, you will see `Code repository cloned successfully to the current directory.` and the dashboard link in the log. - - - - - - - -GitLab does not allow non-expiring personal access tokens. You must set an expiration date when creating your token. When your token expires, Pantheon will no longer be able to detect code changes or trigger builds. [Refresh your token](#adding-or-refreshing-a-gitlab-connection) using `terminus vcs:connection:add` before it expires. - - - - - -You will be prompted for your GitLab token and group name the **first time** you create a GitLab-connected site in a Pantheon organization. Terminus stores the connection after that — subsequent site creations in the same organization will use the existing connection without re-prompting for a token. - - - -Your GitLab token must be a **legacy personal access token** (not a fine-grained token) with the `api` and `write_repository` scopes, or a **group access token** with those scopes and a **Maintainer** role or higher. You can pass the token directly using `--vcs-token` to avoid the interactive prompt. - -1. Use the `terminus site:create` command (see [documentation](/terminus/commands/site-create)) with the following flags: - - * `` — Any upstream your Pantheon user has access to. - * `--org=` — The Pantheon organization. Required for sites using an external VCS provider. - * `--vcs-provider=gitlab` — Required for GitLab repositories. - * `--vcs-org=` — The GitLab group name or username that owns the repository. If omitted, you will be prompted to choose from existing connections or add a new one. - * `--repository-name=` — The name of the repository to create on GitLab. Must be unique to the group or user. - * `--vcs-token=` *(optional)* — Pass your legacy GitLab personal access token directly to skip the interactive prompt. - * `--vcs-host=` *(optional)* — The domain of your self-hosted GitLab instance — the hostname your team uses to access GitLab, e.g. `git.example.com`. Omit this flag when using GitLab.com. - - ```bash{promptUser: user} - terminus site:create --org= --vcs-provider=gitlab --vcs-org= --repository-name= - ``` - - For self-hosted GitLab instances, add `--vcs-host`: - - ```bash{promptUser: user} - terminus site:create --org= --vcs-provider=gitlab --vcs-org= --repository-name= --vcs-host= - ``` - -1. Once the command is issued, the site creation process will begin. This may take several minutes. Keep your terminal open until the process is complete. - -### Adding or refreshing a GitLab connection - -To register a new GitLab connection with a Pantheon organization, or to refresh an expired token, use `terminus vcs:connection:add`: - -```bash{promptUser: user} -terminus vcs:connection:add --vcs-provider=gitlab -``` - -You will be prompted to enter your GitLab group name or path. You will also be prompted for your token unless you pass it directly with `--vcs-token=`. The token must be a legacy personal access token or a group access token with `api` and `write_repository` scopes. Group access tokens also require a **Maintainer** role or higher. For a self-hosted instance, add `--vcs-host=`, where `` is the domain of your self-hosted GitLab instance (e.g. `git.example.com`). - - - - - -## Creating a new site with an existing repository - -Pantheon's external repository integration allows you to maintain your site's source code in a GitHub or GitLab repository while deploying to Pantheon. When you push code to your repository, Pantheon automatically syncs and deploys the changes. - -For this integration to work, your repository must include certain Pantheon-specific configuration files alongside your CMS code. The exact requirements differ between WordPress and Drupal. - -### WordPress vs. Drupal - -The two CMS platforms take different approaches to Pantheon integration: - -| | WordPress | Drupal | -|---|---|---| -| **Core files** | Committed to the repository | Not committed — built by Integrated Composer on deploy | -| **Pantheon platform settings** | Manually included as `wp-config-pantheon.php` | Auto-generated by the `pantheon-systems/drupal-integrations` Composer package | -| **Web root** | Repository root (`/`) | Subdirectory (`/web/`) | -| **Dependency management** | Manual (plugins/themes committed to repo) | Composer (`composer.json` + `composer.lock` committed; dependencies built on deploy) | -| **Build step** | None | `composer install` runs on deploy | - -Select the guide for your CMS to get started: - -- [WordPress Repository Specification](/guides/external-repositories/setup-wordpress) -- [Drupal Repository Specification](/guides/external-repositories/setup-drupal) - -### Via Terminus - -To connect a new Pantheon site to an existing repository via Terminus, pass `--no-create-repo`. This tells Terminus not to create a new repository and instead connect to the one specified by `--repository-name`. - - - - - -```bash{promptUser: user} -terminus site:create --org= --vcs-provider=github --vcs-org= --repository-name= --no-create-repo -``` - - - - - -```bash{promptUser: user} -terminus site:create --org= --vcs-provider=gitlab --vcs-org= --repository-name= --no-create-repo -``` - - - - - -### Common issues - -If you find yourself at a screen that asks you to *configure* the app, it typically means you've already installed the GitHub Application and connected it to another Pantheon organization. You will need to connect the application to this organization using `terminus vcs:connection:link`. See the documentation in [Usage](/guides/external-repositories/usage). - -![Configure existing app](../../../images/github-app/github-app-configure-app.png) - -![GitHub application configuration screen](../../../images/github-app/github-app-integration-config.png) - -## More Resources - -- [Terminus Commands](/terminus/commands/site-create) - Documentation for the `terminus site:create` command -- [Next.js Documentation](https://nextjs.org/docs) - Official Next.js documentation diff --git a/src/source/content/guides/external-repositories/03-gitlab.md b/src/source/content/guides/external-repositories/03-gitlab.md new file mode 100644 index 0000000000..ae506aab61 --- /dev/null +++ b/src/source/content/guides/external-repositories/03-gitlab.md @@ -0,0 +1,134 @@ +--- +title: External Repositories +subtitle: Connect GitLab +description: Instructions for setting up Pantheon's external repository integration for GitLab and creating a new site via the Pantheon Dashboard or Terminus. +tags: [continuous-integration, workflow] +contributors: [stevector,jazzsequence] +contenttype: [guide] +showtoc: true +innav: [true] +categories: [automate, workflows] +cms: [drupal, wordpress] +audience: [development] +product: [terminus] +integration: [--] +reviewed: "2026-08-26" +permalink: docs/guides/external-repositories/gitlab +--- + +This page provides instructions for setting up a new site using Pantheon's external repository integration for GitLab. You can create new sites through the Pantheon Dashboard or via Terminus. You can also connect sites using existing repositories. + +## Requirements +* Gold, Platinum or Diamond Workspace on Pantheon +* A new or existing [GitLab group](https://docs.gitlab.com/user/group/) +* A [legacy personal access token](https://docs.gitlab.com/user/profile/personal_access_tokens/) or a [group access token](https://docs.gitlab.com/user/group/settings/group_access_tokens/) (requires group role of Maintainer or higher) + * Configure scope to include `api` and `write_repository` permissions +* Before connecting an existing repository to a new Pantheon site, it must use Pantheon's expected file structure: + * [WordPress Repository Specification](/guides/external-repositories/setup-wordpress) + * [Drupal Repository Specification](/guides/external-repositories/setup-drupal) + + + +GitLab does not allow non-expiring personal access tokens. You must set an expiration date when creating your token. When your token expires, Pantheon will no longer be able to detect code changes or trigger builds. + +[Refresh your token](#adding-or-refreshing-a-gitlab-connection) using `terminus vcs:connection:add` before it expires. + + + + +## Connect a repo to a new site +### From the Pantheon Dashboard +1. Go to your [Professional Workspace](/guides/account-mgmt/workspace-sites-teams/workspaces#switch-between-workspaces), and select the **Create New Site** button. + +1. Choose WordPress, Drupal or Next.js from the Create New Site page + + ![create new site dashboard](../../../images/github-app/create-new-site.png) + +1. Enter site name, and select desired region. Then click Create Site. + +1. Choose GitLab in the following prompt: + + ![select external repository](../../../images/github-app/select-external-repository.png) + +1. Provide your token, enter your group name, and enter your GitLab domain: + + + + You will be prompted for your GitLab token and group name the **first time** you create a GitLab-connected site in a Pantheon organization. Terminus stores the connection after that — subsequent site creations in the same organization will use the existing connection without re-prompting for a token. + + + + ![connect GitLab account](../../../images/github-app/gl-connect.png) + + +1. Once connected, you should see a dropdown with your group listed. Select your group and click Continue. + + ![connect GitLab account](../../../images/github-app/gl-select-account.png) + +1. You will be prompted to create a new repository or use an existing one. + + + + If you choose to use an existing repository, it must already be set up as a Pantheon site repository (e.g. with a pantheon.yml file and a structure that Pantheon sites typically have). For details, see the following: + * [WordPress Repository Specification](/guides/external-repositories/setup-wordpress) + * [Drupal Repository Specification](/guides/external-repositories/setup-drupal) + + If you don't have an existing repository ready, you can create a new one. This will be created in the GitLab group that was connected to the application. + + + + ![create new repository](../../../images/github-app/gl-create-new-repo.png) + + After naming your repository (the Pantheon site name will be automatically filled in when you click inside the Repository name field), click Deploy. + + In the background, a Pantheon site environment will be initialized and a new git repository on GitLab will be created with the starter upstream code. This may take several minutes. Be sure to leave this screen up until it changes. + + ![site creation in progress](../../../images/github-app/gh-creating-wp.png) + +After the site is created, you will be redirected to your Pantheon Site Dashboard. You should also see a new repository for the site on Gitlab and a Pantheon dashboard link to take you there. + +![site dash](../../../images/github-app/gl-site-dash.png) + + +### From the command-line interface + +1. Use the `terminus site:create` command (see [documentation](/terminus/commands/site-create)) with the following flags: + + * `` — Any upstream your Pantheon user has access to. + * `--org=` — The Pantheon organization. Required for sites using an external VCS provider. + * `--vcs-provider=gitlab` — Required for GitLab repositories. + * `--vcs-org=` — The GitLab group name or username that owns the repository. If omitted, you will be prompted to choose from existing connections or add a new one. + * `--repository-name=` — The name of the repository to create on GitLab. Must be unique to the group or user. + * `--vcs-token=` *(optional)* — Pass your legacy GitLab personal access token directly to skip the interactive prompt. + * `--vcs-host=` *(optional)* — The domain of your self-hosted GitLab instance — the hostname your team uses to access GitLab, e.g. `git.example.com`. Omit this flag when using GitLab.com. + * `--no-create-repo` - (optional) Only used when connecting an existing repository, tells Terminus not to create a new repository and instead connect to the one specified by `--repository-name`. + + + + To connect an existing repository from the command-line, pass the `--no-create-repo` flag. This will connect the new site to your existing repository specified by `--repository-name`. + + + + + ```bash{promptUser: user} + terminus site:create --org= --vcs-provider=gitlab --vcs-org= --repository-name= + ``` + + For self-hosted GitLab instances, add `--vcs-host`: + + ```bash{promptUser: user} + terminus site:create --org= --vcs-provider=gitlab --vcs-org= --repository-name= --vcs-host= + ``` + +1. Once the command is issued, the site creation process will begin. This may take several minutes. Keep your terminal open until the process is complete. + +## Troubleshooting +### Adding or refreshing a GitLab connection + +To register a new GitLab connection with a Pantheon organization, or to refresh an expired token, use `terminus vcs:connection:add`: + +```bash{promptUser: user} +terminus vcs:connection:add --vcs-provider=gitlab +``` + +You will be prompted to enter your GitLab group name or path. You will also be prompted for your token unless you pass it directly with `--vcs-token=`. The token must be a legacy personal access token or a group access token with `api` and `write_repository` scopes. Group access tokens also require a **Maintainer** role or higher. For a self-hosted instance, add `--vcs-host=`, where `` is the domain of your self-hosted GitLab instance (e.g. `git.example.com`). \ No newline at end of file diff --git a/src/source/content/guides/external-repositories/05-usage.md b/src/source/content/guides/external-repositories/05-usage.md index 088ca5bc15..195671a4c1 100644 --- a/src/source/content/guides/external-repositories/05-usage.md +++ b/src/source/content/guides/external-repositories/05-usage.md @@ -12,7 +12,7 @@ cms: [drupal, wordpress] audience: [development] product: [terminus] integration: [--] -reviewed: "2026-06-24" +reviewed: "2026-08-26" permalink: docs/guides/external-repositories/usage --- @@ -24,7 +24,7 @@ This page covers common usage scenarios for Pantheon's external repository integ The GitHub Application **cannot** be used with GitHub Enterprise Server. -**GitLab:** The external repository integration requires a Pantheon workspace member with a GitLab legacy personal access token or group access token with `api` and `write_repository` scopes. Group access tokens also require a **Maintainer** role or higher in the group. Self-hosted GitLab instances are supported via the `--vcs-host` flag. See [Setup](/guides/external-repositories/setup) for details. +**GitLab:** The external repository integration requires a Pantheon workspace member with a GitLab legacy personal access token or group access token with `api` and `write_repository` scopes. Group access tokens also require a **Maintainer** role or higher in the group. Self-hosted GitLab instances are supported via the `--vcs-host` flag. See [Connect GitLab](/guides/external-repositories/gitlab) for details. diff --git a/src/source/content/guides/getstarted/06-addsite.md b/src/source/content/guides/getstarted/06-addsite.md index 715fcf692e..af6f630396 100644 --- a/src/source/content/guides/getstarted/06-addsite.md +++ b/src/source/content/guides/getstarted/06-addsite.md @@ -11,7 +11,7 @@ product: [--] integration: [--] tags: [--] contributors: [wordsmither, jazzsequence] -reviewed: "2026-05-22" +reviewed: "2026-08-26" showtoc: true permalink: docs/guides/getstarted/addsite editpath: getstarted/addsite.md @@ -61,9 +61,12 @@ At this point, you have a live site with a Pantheon URL, like `http://my-site.pa ### Create a Site with external repositories -Pantheon's [external repositories](/guides/external-repositories/setup) integration connects a GitHub or GitLab repository directly to a Pantheon site, allowing you to use your preferred VCS provider as your code repository while Pantheon handles hosting and deployments. It supports WordPress, Drupal, and Next.js, and automatically creates a Multidev environment for each pull request or merge request. Merging to the `main` branch of your repository deploys code to your Pantheon Dev environment. +Pantheon's [external repositories](/guides/external-repositories) integration connects a GitHub or GitLab repository directly to a Pantheon site, allowing you to use your preferred VCS provider as your code repository while Pantheon handles hosting and deployments. It supports WordPress, Drupal, and Next.js, and automatically creates a Multidev environment for each pull request or merge request. Merging to the `main` branch of your repository deploys code to your Pantheon Dev environment. -See the [external repository setup guide](/guides/external-repositories/setup) to get started. +See the following connection guides to get started with an external respoistory: + +* [Connect GitHub](/guides/external-repositories/github) +* [Connect GitLab](/guides/external-repositories/gitlab) ## Migrate an Existing Site diff --git a/src/source/content/nextjs/comparison-to-cms.md b/src/source/content/nextjs/comparison-to-cms.md index c42e68fae3..b5798433de 100644 --- a/src/source/content/nextjs/comparison-to-cms.md +++ b/src/source/content/nextjs/comparison-to-cms.md @@ -1,7 +1,7 @@ --- title: "Comparison to CMS Hosting and other Considerations" description: Learn about the differences between how Pantheon supports Next.js compared to how it runs WordPress and Drupal. -reviewed: "2026-03-28" +reviewed: "2026-08-26" contenttype: [doc] innav: [true] audience: [development] @@ -100,7 +100,7 @@ See the following page for Next.js compatibility and requirements on Pantheon: The GitHub App **cannot** be used with GitHub Enterprise Server. If your team uses GitHub Enterprise Server, please let us know [through our Roadmap site](https://roadmap.pantheon.io/). -Self-hosted GitLab instances are supported via the `--vcs-host` flag in Terminus. See the [external repository setup guide](/guides/external-repositories/setup) for details. +Self-hosted GitLab instances are supported via the `--vcs-host` flag in Terminus. For details, see [Connect GitLab](/guides/external-repositories/gitlab). ### **Bun, Deno, and other runtimes beyond Node.js** diff --git a/src/source/images/dashboard/gitlab-repo-hosting-dashboard.png b/src/source/images/dashboard/gitlab-repo-hosting-dashboard.png new file mode 100644 index 0000000000..ae0f582182 Binary files /dev/null and b/src/source/images/dashboard/gitlab-repo-hosting-dashboard.png differ diff --git a/src/source/images/github-app/create-new-site.png b/src/source/images/github-app/create-new-site.png new file mode 100644 index 0000000000..ce9a8f40ed Binary files /dev/null and b/src/source/images/github-app/create-new-site.png differ diff --git a/src/source/images/github-app/gh-connect.png b/src/source/images/github-app/gh-connect.png new file mode 100644 index 0000000000..5d0d2032fa Binary files /dev/null and b/src/source/images/github-app/gh-connect.png differ diff --git a/src/source/images/github-app/gh-create-new-repo.png b/src/source/images/github-app/gh-create-new-repo.png new file mode 100644 index 0000000000..c304d045cb Binary files /dev/null and b/src/source/images/github-app/gh-create-new-repo.png differ diff --git a/src/source/images/github-app/gh-creating-wp.png b/src/source/images/github-app/gh-creating-wp.png new file mode 100644 index 0000000000..c813d4cfc3 Binary files /dev/null and b/src/source/images/github-app/gh-creating-wp.png differ diff --git a/src/source/images/github-app/gh-select-account.png b/src/source/images/github-app/gh-select-account.png new file mode 100644 index 0000000000..1ee2f392f5 Binary files /dev/null and b/src/source/images/github-app/gh-select-account.png differ diff --git a/src/source/images/github-app/gh-site-dash.png b/src/source/images/github-app/gh-site-dash.png new file mode 100644 index 0000000000..535e4e55f5 Binary files /dev/null and b/src/source/images/github-app/gh-site-dash.png differ diff --git a/src/source/images/github-app/github-app-configure-git.png b/src/source/images/github-app/github-app-configure-git.png deleted file mode 100644 index c68ebeeaab..0000000000 Binary files a/src/source/images/github-app/github-app-configure-git.png and /dev/null differ diff --git a/src/source/images/github-app/github-app-connect-git.png b/src/source/images/github-app/github-app-connect-git.png deleted file mode 100644 index e330ae8405..0000000000 Binary files a/src/source/images/github-app/github-app-connect-git.png and /dev/null differ diff --git a/src/source/images/github-app/github-app-create-new-site.png b/src/source/images/github-app/github-app-create-new-site.png deleted file mode 100644 index 1a75ac7a32..0000000000 Binary files a/src/source/images/github-app/github-app-create-new-site.png and /dev/null differ diff --git a/src/source/images/github-app/github-app-create-site.png b/src/source/images/github-app/github-app-create-site.png deleted file mode 100644 index e1427b9363..0000000000 Binary files a/src/source/images/github-app/github-app-create-site.png and /dev/null differ diff --git a/src/source/images/github-app/github-app-creating-nextjs.png b/src/source/images/github-app/github-app-creating-nextjs.png deleted file mode 100644 index 5e12fee5b9..0000000000 Binary files a/src/source/images/github-app/github-app-creating-nextjs.png and /dev/null differ diff --git a/src/source/images/github-app/github-app-selectaccount.png b/src/source/images/github-app/github-app-selectaccount.png deleted file mode 100644 index 54aafb6ec9..0000000000 Binary files a/src/source/images/github-app/github-app-selectaccount.png and /dev/null differ diff --git a/src/source/images/github-app/gl-connect.png b/src/source/images/github-app/gl-connect.png new file mode 100644 index 0000000000..183d540532 Binary files /dev/null and b/src/source/images/github-app/gl-connect.png differ diff --git a/src/source/images/github-app/gl-create-new-repo.png b/src/source/images/github-app/gl-create-new-repo.png new file mode 100644 index 0000000000..476dd5f678 Binary files /dev/null and b/src/source/images/github-app/gl-create-new-repo.png differ diff --git a/src/source/images/github-app/gl-creating-wp.png b/src/source/images/github-app/gl-creating-wp.png new file mode 100644 index 0000000000..f73dd603e5 Binary files /dev/null and b/src/source/images/github-app/gl-creating-wp.png differ diff --git a/src/source/images/github-app/gl-select-account.png b/src/source/images/github-app/gl-select-account.png new file mode 100644 index 0000000000..0018605003 Binary files /dev/null and b/src/source/images/github-app/gl-select-account.png differ diff --git a/src/source/images/github-app/gl-site-dash.png b/src/source/images/github-app/gl-site-dash.png new file mode 100644 index 0000000000..a6a2f1e2e1 Binary files /dev/null and b/src/source/images/github-app/gl-site-dash.png differ diff --git a/src/source/images/github-app/select-external-repository.png b/src/source/images/github-app/select-external-repository.png new file mode 100644 index 0000000000..dddbe4c7b2 Binary files /dev/null and b/src/source/images/github-app/select-external-repository.png differ diff --git a/src/source/releasenotes/2026-08-26-gitlab-support-dashboard-ga.md b/src/source/releasenotes/2026-08-26-gitlab-support-dashboard-ga.md new file mode 100644 index 0000000000..e73151b8f0 --- /dev/null +++ b/src/source/releasenotes/2026-08-26-gitlab-support-dashboard-ga.md @@ -0,0 +1,23 @@ +--- +title: "GitLab support for external repositories now available in the Dashboard" +published_date: "2026-08-26" +published_at: "2026-08-26T18:22:38Z" +categories: [new-feature, tools-apis, user-interface] +description: "Connecting a GitLab repository to a Pantheon site is now available for everyone directly from the Pantheon Dashboard." +--- + +Pantheon's [GitLab support for external repositories](/release-notes/2026/06/evcs-gitlab-support) is now generally available to everyone directly from the Pantheon Dashboard, alongside GitHub and Pantheon-hosted Git. + +## What's new + +- **Dashboard support** — When creating a new site, choose **GitLab** as your code host right alongside GitHub and Pantheon's integrated Git repository — no Terminus required. +- **Self-hosted GitLab** — Connect to GitLab.com or your own self-hosted GitLab instance. +- **Token-based authentication** — Authenticate using a personal access token or group access token with `api` and `write_repository` scopes. + +## Where to find it + +During site creation, select **GitLab** on the **Where will your code be hosted?** screen to connect your repository. + +![Where will your code be hosted screen showing GitHub, GitLab, and Pantheon options](../../../../images/dashboard/gitlab-repo-hosting-dashboard.png) + +For full setup instructions, see the [related documentation](/guides/external-repositories/gitlab).