Integrations
Integration permissions and prerequisites
Checklist of provider scopes, IAM and Azure RBAC patterns, and Organisation roles before you connect Git, registries, backup storage, or cloud providers.
Use this page before you connect Git hosts, Docker registries, backup storage, Azure, or AWS. It complements provider guides (GitHub integration, GitLab integration, Git source integrations, Docker registry integration, Backup storage integration, Azure integration, AWS integration) with a single checklist.
dFlow Organisation and roles
| Requirement | Why it matters |
|---|---|
| You belong to the correct Organisation | Integrations are tenant-scoped; connecting under the wrong workspace breaks deploys for teammates. |
| Your dFlow role allows managing integrations | Owners and admins typically can; other roles may be read-only. See Roles and permissions under Security and Team Management in the sidebar and Tenant access model under Security and Team Management in the sidebar. |
| You follow secret hygiene | Do not paste provider tokens into public tickets or Git. Prefer integration storage and secret() on Service variables. See Security best practices under Security and Team Management in the sidebar. |
GitHub (GitHub App)
| Requirement | Detail |
|---|---|
| Install permission on user or org account | Suspended installs or org third-party app restrictions block access. |
| Repository allow-list | Only select repositories means you must update the install when you add repos. |
| Branch exists | App Services point at a real branch or tag. |
GitLab (OAuth)
| Requirement | Detail |
|---|---|
| OAuth scopes on connect | Enable api, read_user, and read_repository on the GitLab OAuth application (gitlab.com uses dFlow's shared app; self-hosted uses your BYO app). |
| Redirect URI | Must match {dashboard-url}/api/webhook/providers/gitlab exactly (copy from the connect dialog). |
| Self-hosted reachability | Instance URL must be HTTPS in production and reachable from the dFlow dashboard for OAuth and API calls; GitLab must reach dFlow for callbacks and push webhooks. |
| Encrypted credentials | Self-hosted connections store your OAuth client ID and secret encrypted for token refresh. |
GitLab, Bitbucket, Gitea, Azure DevOps (manual tokens)
| Requirement | Detail |
|---|---|
| Token still valid | Expired tokens cause clone failures; rotate before expiry. |
| Scopes | For GitLab manual deploys, use at least read_repository. For other hosts, start with read repository and read API where applicable; add write only if you push from dFlow. |
| HTTPS clone URL | Match the URL format the dFlow UI expects. |
| Bitbucket plan limits | Workspace-level tokens may be unavailable on some plans; use repository tokens if required. |
Docker registries
| Requirement | Detail |
|---|---|
| Read token or robot account | Deploy only needs pull; separate credentials if CI also pushes. |
| Correct registry host | docker.io, ghcr.io, provider-specific host must match the image reference on the Docker Service. |
| Namespace access | Token must cover the repository or organisation that owns the image. |
Backup storage (S3-compatible)
| Requirement | Detail |
|---|---|
| Bucket access | Keys need read, write, and delete on the bucket (and prefix) used for dumps. |
| Endpoint and region | Blank endpoint for AWS S3; custom S3 API endpoint for R2, B2, MinIO, and similar hosts. |
| Verified status | External backups on a database Service require a verified provider from Integrations → Backup Storage. |
| Separate from AWS EC2 keys | Backup Storage credentials are not the same as AWS integration keys used for compute provisioning. |
Azure
| Requirement | Detail |
|---|---|
| Microsoft sign-in with subscription access | OAuth connects the identity you choose at the Microsoft prompt. That identity must be able to read and create VMs, networking, and SSH keys in the target subscription or resource group. |
| Connected status in Integrations | Disconnected accounts cannot provision workers or load Azure lists. Reconnect with Microsoft if tokens expire or roles change. |
| Resource group and region | Pick or create a resource group in the region where you want the VM. Quotas and VM size availability vary by region. |
| Network path for onboarding | Basic NSG mode opens required ports for SSH, Tailscale, monitoring, HTTP, and HTTPS. Custom NSGs must allow the same traffic if you use Advanced mode. |
| Machine types (optional) | Saved templates need a dFlow gallery image in the region when you use custom images. See Azure integration. |
AWS
| Requirement | Detail |
|---|---|
| IAM principal with required EC2 (and related) APIs | Under-scoped policies return AccessDenied during provisioning. |
| Access key active | Disabled or deleted keys fail signature validation. |
| Regional quotas and networking | Even with IAM correct, limits or Security groups can block success. Security groups under Security and Team Management in the sidebar |
Worker Nodes (related but not Git or registry)
SSH and host access use SSH keys under Security and Team Management in the sidebar. If builds fail with git errors, fixing SSH on the server will not help; if SSH fails during server onboarding, Git tokens will not fix it. Use Compute and worker node issues under Troubleshooting in the sidebar for compute path problems.
Permission error patterns (quick reference)
| Message or symptom | Likely layer |
|---|---|
401, 403, permission denied on clone | Git token, GitHub App installation, or repo allow-list |
unauthorized on image pull | Registry token, wrong username, or expired credential |
| External backup failed or upload denied | Backup storage keys, endpoint, region, or bucket policy; provider not verified |
AccessDenied on AWS API | IAM policy, SCP, or wrong account (EC2 integration, not backup bucket) |
| Azure lists empty or provision fails | Azure RBAC on the signed-in identity, wrong subscription, or region quota |
| Azure account Disconnected | Reconnect with Microsoft; check tenant conditional access or expired consent |
| Webhook never arrives | Git host app settings, org firewall, or branch filter |
Deep fixes: Integration troubleshooting and Integration issues under Troubleshooting in the sidebar.
Related
Cloud provider accounts
How linked cloud accounts relate to Organisations, AWS and Azure, and least-privilege habits for infrastructure integrations.
Integration troubleshooting
Fix common Git, registry, backup storage, Azure, and AWS integration failures: reconnect, scopes, keys, and where to read logs.