GitHub and Storage Integration Troubleshooting

Most onboarding failures during GitHub and S3 setup are customer-side configuration issues — wrong repo access, branch name, bucket policy, or IAM permissions. EnforceAuth logs the underlying error, but you only save time when you know which surface shows it.

This guide reflects patterns from enterprise pilot onboarding: run Test Connection before first deploy, then use deployment phase and pipeline logs when something still breaks.

Where to look (in order)

1. System Settings → Integrations     → GitHub App installed on the right org?
2. Entity → Policy Source               → Test Connection
3. Entity → Bundle Destination          → Test Connection
4. Deployments → failed run → Details   → which phase failed?
5. Deployment detail → pipeline logs    → clone / upload error text

Surface	What it tells you
Test Connection on policy source	Git reachability, branch exists, credentials or App auth
Test Connection on bundle destination	S3/GCS/Azure write path (S3 does write → read → delete probe)
Integrations	GitHub App install host, org, repo selection (all vs selected)
Deployment phases	Fetching ≈ Git; Deploying ≈ bundle upload to storage
Pipeline logs on the run detail	Same failures with pipeline context (commit, entity, environment)

Catch issues before deploy

Run Test Connection on both policy source and bundle destination before your first manual deploy or CI run. Many GitHub App and S3 permission mistakes surface here with actionable messages instead of a failed Fetching or Deploying phase.

GitHub App integration

Connect at System Settings → Integrations (/system-settings/integrations). See Policy sources — Connect GitHub.

App not used — deploy still asks for credentials or gets 401/403

Cause: Policy source has a Credentials Secret but the GitHub App is not installed on the repo owner, or the App installation does not include that repository.

Fix:

1. Confirm an integration row exists for the correct host (github.com or your GHES hostname) and organization.
2. In GitHub → Settings → Applications → Installed GitHub Apps, verify EnforceAuth Policy Reader covers the org and repo (or All repositories).
3. Repository URL owner must match the installed account (owner in https://github.com/owner/repo).
4. For GitHub Enterprise Server, the integration host must match exactly (e.g. github.acme.corp — no https:// prefix).

Auth resolution order at deploy time: per-source Credentials Secret (PAT) → tenant GitHub App installation token → public anonymous access (public repos only).

Connected GitHub but private repo still fails

Cause: App installed on Selected repositories and your policy repo is not in the list; or App installed on a user account but repo lives under an org.

Fix: Re-install or configure the App to include the policy repository. Disconnect and reconnect from Integrations if the installation was revoked on GitHub's side.

GHES hostname errors

Cause: Host typo, protocol in hostname field, or App registered on github.com but repo is on GHES (or vice versa).

Fix: Use hostname only in the connect dialog (e.g. github.acme.corp). Policy source Repository URL must use the same host. One tenant_github_integrations row per (tenant, host, account).

Git policy source

Configure on the entity Policy Source card. Full field reference: Policy sources.

Test Connection messages

Message / symptom	Likely cause	What to do
Branch was not found	Wrong branch name or repo empty	UI may list available branches — pick the branch that exists; check default branch in GitHub
Could not connect to the git repository	Bad URL, DNS, or network	Verify https://github.com/org/repo format; for GHES use your enterprise host
Authentication failed (401/403)	PAT expired, missing repo scope, or App cannot read repo	Refresh PAT secret or fix App repository access
Failed to retrieve git credentials	Secret ARN wrong or EnforceAuth cannot read secret	Confirm secret exists on entity or ancestor; check secret type Generic Secret
Succeeded without credentials (warning)	Public repo reachable anonymously	If repo is private, add App install or PAT — deploy will fail at Fetching
Policy path was not found (S3 source)	Prefix empty in bucket	Upload Rego under policy_path or fix prefix

Deployment Fetching phase failures

When Test Connection was skipped or passed with warnings:

• Repository not found — URL typo or App/PAT lacks access to that org
• Branch not found — environment override points at a branch that does not exist
• Authentication failed — installation revoked; reconnect GitHub App or rotate PAT
• Path not found — policy_path does not match directory layout in the repo

Open pipeline logs on the deployment run for the Git provider error snippet.

S3 bundle destination

Configure on the entity Bundle Destination card. Full reference: Bundle destinations.

Test Connection for S3 bundle destinations performs a write → read → delete probe on a temporary object under your bundle path prefix. That catches most permission gaps before the first real deploy.

Could not verify S3 bundle destination access (AccessDenied)

Cause: IAM user/role in Credentials Secret lacks object permissions, bucket policy denies EnforceAuth's principal, or region does not match the bucket.

Required IAM actions on the bundle prefix (e.g. arn:aws:s3:::my-bucket/policies/*):

• s3:PutObject
• s3:GetObject
• s3:DeleteObject (used by Test Connection cleanup; deploy needs Put/Get)

Also ensure s3:ListBucket on the bucket with a prefix condition if your policy uses one.

Example bucket policy statement (replace account, bucket, and prefix):

{
  "Effect": "Allow",
  "Principal": { "AWS": "arn:aws:iam::CUSTOMER_ACCOUNT:user/enforceauth-bundle-writer" },
  "Action": ["s3:PutObject", "s3:GetObject", "s3:DeleteObject"],
  "Resource": "arn:aws:s3:::my-policy-bundles/policies/*"
}

Checklist:

Check	Common mistake
Region	Bucket in us-west-2, config says us-east-1
Bucket name	Typo or wrong account's bucket
Bundle path	Ends with / (invalid) or points at folder without write permission on that prefix
Credentials Secret	JSON must include accessKeyId and secretAccessKey; optional sessionToken for STS
Secret scope	Secret attached to entity or ancestor the deploy uses

Failed to retrieve S3 credentials

Cause: credentials_ref points to a missing secret, wrong type, or EnforceAuth's pipeline role cannot secretsmanager:GetSecretValue on that ARN (SaaS: platform retrieves your stored secret at deploy time).

Fix: Create AWS S3 Credentials under entity Secrets; select it in the bundle destination form. Re-run Test Connection after updating the secret.

Test Connection passes but deploy fails at Deploying

Cause: Different environment override changes bundle path; credentials differ between verify and pipeline; or bucket policy allows your test principal but not the key used at deploy (rare if same secret).

Fix: Compare effective config for the environment you deployed. Re-run Test Connection after any secret rotation. Check pipeline logs for the exact S3 key and error code.

Success in console but PDP still serves old policy

Cause: PDP bundle URL does not match EnforceAuth's bundle path; PDP poll interval; or wrong environment bucket path.

Fix: Confirm object at configured path in S3. Align OPA services.enforceauth.url / bundle resource with PDP integration. See Bundle polling.

S3 policy source (policies in S3, not Git)

Less common than Git, but the same patterns apply:

• Could not access the S3 bucket — HeadBucket failed; check region, credentials, bucket name
• Policy path was not found — no objects under policy_path prefix

EnforceAuth needs read/list on the prefix; bundle destination still needs a separate write target.

Map deployment phases to integrations

Phase	Integration involved	Typical customer-side fix
Fetching	Git policy source + GitHub App or PAT	Repo access, branch, policy_path, credentials secret
Testing	Git content (local to pipeline)	Fix opa test failures in repo
Building	Git content	Rego compile errors — not storage
Deploying	Bundle destination (S3/GCS/Azure)	Write permissions, path, credentials
Complete	PDP poll (outside EnforceAuth)	PDP bundle URL and poll config

See Deployments.

GitHub Actions vs GitHub App

These are different integration paths:

Concern	Mechanism	Doc
Read policy repo (clone)	GitHub App or PAT on policy source	This page, Policy sources
Trigger deploy from CI	OIDC trust policy + deploy-action	GitHub Actions

A working GitHub App does not replace trust policies for CI deploys. Conversely, CI can deploy while Fetching fails if the App cannot read the repo.

Still stuck?

Gather before opening a support ticket:

1. Entity ID and environment name
2. Failed deployment run ID
3. Screenshot or text of Test Connection result (both source and destination)
4. Whether the repo is private and which auth path you expect (App vs PAT)
5. S3 bucket, region, and bundle path (no secrets)

For regulated tenants, support may correlate with platform logs that include additional provider detail beyond what the UI shows — your Test Connection and pipeline log exports accelerate that triage.

Related guides

• Policy sources
• Bundle destinations
• Deployments
• GitHub Actions and CI/CD
• 15-minute quickstart
• Entity model