Overview
What it does
Section titled “What it does”Deployments connects Capell to the Git repository used for package changes. An authorised package workflow can add a Composer requirement by direct commit or pull request, and Capell then shows the provider’s check status. The package does not run or roll back the server deployment itself; a failed provider check still needs attention in the repository or deployment platform.
Setup requirements
Section titled “Setup requirements”Run the package migrations and configure an OAuth client ID and secret for at least one supported provider: GitHub, GitLab, or Bitbucket. The provider application must allow the Capell callback route and have enough repository access to read composer.json, create commits and branches, open or close pull requests, and read check status. System health reports when no provider OAuth client is configured.
The page is available only while capell-deployments.enabled is enabled. There is no in-admin OAuth settings form; a developer or host operator supplies the credentials through the capell-deployments configuration.
Where it appears and who can use it
Section titled “Where it appears and who can use it”Open System > Deployment Repository. A connection summary can also appear on the System health dashboard.
View:DeploymentConnectionPagecan see active repository coordinates, install policy, and recent publication details.Manage:DeploymentConnectionPagecan connect or disconnect repositories and cancel eligible pull-request publications. Composer publication requests also fail closed unless the initiating account has this permission.
Connect a repository
Section titled “Connect a repository”Enter the repository owner or group and repository name, choose an install policy, then select the configured Git provider. The connection is completed on the provider’s OAuth screen.
- Direct commit writes the Composer change to the repository’s default branch. Use this only when branch protection and your release process make direct changes acceptable.
- Pull request, auto-merge on green CI creates a package branch and pull request and requests auto-merge when the provider reports successful checks.
- Pull request, manual review leaves the pull request for a person to review and merge.
The standard publishing integration refuses to guess when more than one active repository connection exists. Keep one active connection unless the calling integration explicitly selects a repository. Disconnecting a connection also removes its stored recent-publication history; it does not undo commits, close unrelated pull requests, or reverse a deployment that already ran.
Publication lifecycle and recovery
Section titled “Publication lifecycle and recovery”Package publication starts from another authorised workflow; Deployment Repository has no general-purpose deploy button. The page shows the five most recent Composer publications per connection, including package and constraint, status, branch, commit or pull-request reference, and time. Non-final provider status is refreshed when the page is viewed, no more than once every five minutes. A dry run validates and records the proposed Composer change without writing it to the provider.
You can cancel a non-final pull-request publication while it still has a provider pull request. Cancellation closes that pull request and marks the Capell record cancelled; it cannot cancel a direct commit or a successful publication, and it is not a rollback.
If a publication is Failed, open its provider reference and inspect the repository checks or deployment pipeline. Fix provider credentials, branch protection, Composer resolution, or the external CI failure there, then retry from the workflow that requested the package change. If OAuth reports an invalid session or token exchange failure, start the connection again; expired GitLab and Bitbucket tokens are refreshed automatically when a usable refresh token is available, but a failed refresh keeps the existing connection rather than silently replacing it.
Security and visible data
Section titled “Security and visible data”Access and refresh tokens are stored encrypted. Capell also stores the provider, repository coordinates, default branch, install policy, package name and constraint, branch, commit SHA, pull-request reference, status, and timestamps. Treat view access as repository metadata access. Any extra Composer repository URL supplied by an integration must use HTTPS on an approved host; credential-bearing and unapproved URLs are rejected.
For how to use Deployments, see the admin guide. For developers: see the README.