Skip to content
Install

Deploy from GitLab, Gitea, and others

Orchard can build apps from repositories outside the GitHub App. Link a Git provider to your account, and you can pick its repositories in the new app form and turn on auto-deploy on push, the same way you do for GitHub. Orchard supports GitLab, Gitea, Forgejo, Codeberg, Bitbucket Cloud, GitHub with a token, and any Git host that serves HTTPS.

A provider belongs to you. Orchard lists only the repositories your token can see, and builds clone with your token.

To link a provider, sign in with OAuth or add a token. OAuth is available for GitLab and Bitbucket when a superadmin registers an OAuth app under Instance admin > Configuration. Orchard refreshes OAuth tokens for you.

  1. Go to Account settings > Connections.
  2. In Git providers, take one of these steps:
    • If your instance has OAuth configured, select Add provider, then Sign in with GitLab or Sign in with Bitbucket.
    • Otherwise, select Add with a token.
  3. If you add a token, enter the Provider, Name, Host, and Token. For Bitbucket Cloud, also enter the Atlassian account email that owns the API token. For Any git host, also enter the Username if the host expects one.
  4. Select Connect.

Orchard stores the token encrypted. Before it saves, it lists your repositories with the token, so a wrong token fails here instead of at the first build. Orchard cannot check a token for Any git host, because a plain Git host has no API. A wrong token for that host fails when the first build clones.

ProviderTokenScopes
GitLabPersonal or project access tokenread_api, read_repository
Gitea, Forgejo, CodebergAccess tokenRepository read
Bitbucket CloudAtlassian API token, or access tokenread:repository:bitbucket, plus read:webhook:bitbucket and write:webhook:bitbucket for auto-deploy
GitHub with a tokenFine-grained tokenContents read
Any Git hostThe password used to clone over HTTPSNone

You can link Bitbucket Cloud with Sign in with Bitbucket or with an Atlassian API token.

Sign in with Bitbucket uses OAuth. A superadmin turns it on in Instance admin > Configuration > Bitbucket sign-in, with the key and secret of a Bitbucket OAuth consumer that has repository read access and the callback URL <origin>/apiv1/git/oauth/bitbucket/callback, where <origin> is the address of your Orchard dashboard.

To link Bitbucket Cloud with an API token:

  1. Go to API tokens in your Atlassian account settings.
  2. Select Create API token with scopes, enter a name and an expiry date, and select Bitbucket as the app.
  3. Select the read:repository:bitbucket scope. For auto-deploy, also select read:webhook:bitbucket and write:webhook:bitbucket.
  4. Copy the token.
  5. In Orchard, select Add with a token, then select Bitbucket Cloud as the Provider.
  6. In Atlassian account email, enter the email of the Atlassian account that created the token, not your Bitbucket username.
  7. In API token, paste the token, then select Connect.

Orchard sends the email and the API token to the Bitbucket API, and clones with the token under the username x-bitbucket-api-token-auth. For details, refer to Using API tokens and API token permissions in the Atlassian documentation.

To use a workspace, project, or repository access token instead, leave Atlassian account email empty. Orchard sends the access token to the Bitbucket API as a bearer token and clones with the username x-token-auth. An access token reaches only the repositories it was created for. For details, refer to Access tokens in the Atlassian documentation.

Bitbucket Cloud does not accept app passwords. A provider that you linked with an app password shows app password, reconnect with an API token in Git providers, and listing its repositories fails with an error that asks you to reconnect.

To keep the apps that build from the provider, replace its app password with an API token through the Orchard API:

  1. Find the ID of the provider with orchard git list.

  2. Create an Atlassian API token as described in the previous steps.

  3. Send the token and your Atlassian account email to the provider, with an Orchard API token that has Deploy access:

    curl --request PATCH "https://orchard.example.com/apiv1/users/me/git-connections/<PROVIDER_ID>" \
    --header "Authorization: Bearer <ORCHARD_API_TOKEN>" \
    --header "Content-Type: application/json" \
    --data '{"username": "[email protected]", "token": "<BITBUCKET_API_TOKEN>"}'

Orchard checks the new token against the Bitbucket API before it saves it. To start over instead, link Bitbucket Cloud again with an API token or with Sign in with Bitbucket, and create the apps again from the new provider.

  1. Open a project.
  2. Select New app.
  3. In Start from scratch, select GitHub repo.
  4. In Source, select Git.
  5. In Repository, select the provider.
  6. Select a repository or enter its URL.
  7. In Branch, select a branch.
  8. Complete the rest of the form.
  9. Select Deploy.

Orchard detects Dockerfiles, frameworks, ports, and a score.yaml file the same way it does for GitHub.

Auto-deploy builds the app on each push to a branch. When you turn it on, Orchard registers a push webhook on the repository through the provider’s API, signed with a secret that belongs to that provider. A push then builds the app and applies its watch paths.

  1. Open the app.
  2. Go to Settings > Deploy behavior.
  3. In Auto-deploy, enter the branch.
  4. Turn on Deploy on push.

Webhook shows Registered on <host> when the webhook is in place.

If Orchard cannot register the webhook, the page shows the webhook URL and secret instead. This happens on a plain Git host, which has no API for Orchard to call, and when the token cannot manage webhooks on the repository. Paste the URL and secret into the webhook settings of the repository, for push events. A plain Git host must send a push payload in the GitHub, GitLab, or Bitbucket format. To print the same values from the CLI, run orchard git webhook <name>.

Only the person who linked a provider can:

  • List its repositories and branches.
  • Run detection on it.
  • Create an app from it.
  • Change which repository an app builds from. The new repository must be on the same host.

After an app exists, project membership controls access. Project members can rebuild the app, read its logs, and turn auto-deploy on or off. Builds clone with the token of the person who linked the provider.

An app keeps the provider it was created from, and builds clone with that provider’s token. If the token expires or is revoked, or the account of the person who linked it is deleted, builds from that provider fail with an error. Orchard does not let you remove a provider that is still the source of an app.

To restore builds, another member creates the app again from their own provider.