GitHub OIDC Role
A github oidc role lets your workflow log in to a cloud account without static keys. You set up an identity provider in your cloud account and attach a trust policy to a role. Many teams build one broad role and share it across dozens of repos. When permissions are too wide, any workflow run can read or change sensitive resources. How a github oidc role works in workflow runs Every workflow job can request a signed token from the built-in identity provider. This token contains claims about th
Role-Based Access Control (RBAC) + GitHub Actions Security: the complete guide
Architecture patterns, implementation strategies, and security best practices. Delivered to your inbox.
A github oidc role lets your workflow log in to a cloud account without static keys. You set up an identity provider in your cloud account and attach a trust policy to a role. Many teams build one broad role and share it across dozens of repos. When permissions are too wide, any workflow run can read or change sensitive resources.
How a github oidc role works in workflow runs
Every workflow job can request a signed token from the built-in identity provider. This token contains claims about the repo, branch, event type, and runner job. Your cloud provider checks the digital signature against the public keys from the code host. Then the cloud provider compares the token claims against the trust policy on the role.
If the claims match your rules, the cloud service issues temporary credentials to the runner. The runner uses those credentials for the rest of the job. When the job ends or the timer expires, the credentials stop working. Teams no longer need to copy long-lived secret keys into repo settings or rotate them by hand.
Scoping trust claims to specific repos and branches
A trust policy is only safe when you check the subject claim in the token. If you only check the token issuer, any repo on the platform could assume your role. You must restrict the subject claim to your exact account and repo name. You should also lock production roles to your main branch or a specific deployment tag.
Pull requests from forks or feature branches need separate roles with read-only permissions. If a feature branch can assume a production role, a bad change in a workflow file can alter live systems. Splitting roles by branch and workflow phase keeps test jobs away from production resources. Teams should review trust policies whenever they add new repos or rename old ones.
Role-Based Access Control (RBAC) + GitHub Actions Security: architecture patterns and best practices
Continue reading? Get the full guide.
Free. No spam. Unsubscribe anytime.
What cloud role policies solve and what they leave open
Cloud role trust policies solve the problem of storing static secret keys in your code host. They verify which repo and branch started the job before granting cloud credentials. This stops leaked static keys from sitting in old build logs or developer laptops. It also ties every role assumption event in your cloud audit log to a specific workflow run.
Still, a cloud role only decides who logs in and which cloud services they can reach. Once the job connects to a database or internal system, the role does not inspect individual queries or commands. If a migration script runs a bad delete statement, the cloud role allows it. If a build task queries a table with customer emails, phone numbers, or card numbers, the role returns all raw rows. Cloud role permissions do not rewrite sensitive fields in query results or require human approval for one-off commands.
Check database and API queries on the wire
Identity tools, roles, and network rules decide who opens a session. Setup alone cannot check what each query does or mask sensitive values in a response once a session starts. When workflows touch Postgres, MySQL, SQL Server, MongoDB, ClickHouse, Kubernetes APIs, SSH, or internal HTTP APIs, hoop.dev runs beside those services as an open-source proxy, a sidecar for your Postgres or API. It inspects requests coming in and results going back on the wire.
Your login details and client tools stay as they are while hoop.dev guardrails refuse bad deletes or drops before they run. On responses, hoop.dev data masking rewrites matched sensitive values in memory. Furthermore, hoop.dev holds SOC 2 Type II, is MIT licensed, and writes every query and decision to an audit trail that generates evidence for HIPAA, GDPR, and PCI DSS. See the source on GitHub.
Frequently asked questions
Why did my workflow fail the role trust check?
Trust checks fail when the token subject claim does not match your role policy string. Check whether the job ran from a pull request, tag, or branch that your rule does not list.
Should I share one role across all my repos?
No, sharing one role gives every repo the same permissions across your cloud account. Create separate roles per repo and per deployment stage so each job gets only what it needs.
Does OIDC stop bad database queries during a deployment job?
No, OIDC only controls how the runner gets temporary cloud credentials at the start of a job. It does not inspect SQL statements, block drop commands, or mask emails and card numbers in query outputs.