How GovIntel Works
Verifying the connection
Connected is a measurement, not an assertion. It is reachable only by a real run that assumed your role and checked the boundary held.
When you press Verify Connection, GovIntel dispatches a verification workflow. That workflow assumes the role you just created, through GitHub OIDC, and checks that the access boundary is what the template says it is.
Why this exists
Before it did, the connection state was a dropdown an operator chose from. "Validated" recorded an intention, not a measurement, and nothing in the system had ever spoken to AWS.
CONNECTED now records only what was measured. There is no API field, no admin route and no override that can produce it. It is reachable by exactly one path: a verification run assumed your role and the boundary checks passed.
The connection states
| State | Meaning |
|---|---|
NOT_CONNECTED | Nothing has been attempted |
AUTHORIZATION_REQUIRED | You have been asked to authorize access |
PROVISIONING | You have supplied an account ID and are deploying the stack |
VERIFYING | A verification run is in flight |
CONNECTED | A real run assumed the role and the boundary held. The only state that permits an assessment |
FAILED | Verification ran and did not pass |
EXPIRED | The engagement expiry has passed. The role now denies everything |
REVOKED | Access has been withdrawn |
How the state was established
Every engagement also records how its state was reached: oidc_verification for a real run, operator_assertion for a human judgement, or none.
Records predating the verification mechanism carry operator_assertion and are re-verified before an assessment can run. Promoting them silently would launder an opinion into a measurement, which is the exact failure this design exists to end.
If verification fails
You are told which check failed. The usual causes are a stack that has not finished, the identity provider checkbox answered the other way, or an engagement whose expiry has already passed. See Access states reference.