Integration permissions and prerequisites

Checklist of provider scopes, IAM patterns, and Organisation roles before you connect Git, registries, or AWS.

Written By Zoro

Last updated 9 days ago

Use this page before you connect Git hosts, Docker registries, backup storage, Azure, or AWS. It complements provider guides (AWS integration, Azure integration, and others) 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.
You follow secret hygiene	Do not paste provider tokens into public tickets or Git. Prefer integration storage and `secret()` on Service variables.

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, Bitbucket, Gitea, Azure DevOps (tokens)

Requirement	Detail
Token still valid	Expired tokens cause clone failures; rotate before expiry.
Scopes	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.

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.

Backup storage (S3-compatible)

Requirement	Detail
Bucket access	Keys need read, write, and delete on the bucket used for dumps.
Verified status	External backups 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.

Permission error patterns (quick reference)

Message or symptom	Likely layer
`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

Deep fixes: Integration troubleshooting and Integration issues under Troubleshooting in the sidebar.