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 4 days ago

Use this page before you connect Git hosts, Docker registries, or AWS.

It complements provider guides (GitHub integration, Git source integrations, Docker registry 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, 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.
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.

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)
Webhook never arrives	Git host app settings, org firewall, or branch filter

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