Access control
Restrict who can read which files with read access rules, for one repository or across a whole organization.
Read access rules decide which members of an organization may read files that match a path pattern.
You can keep secrets/** away from contractors, or make a directory need-to-know so only one team can
open it.
Before you start
Read access is an enterprise capability. It works only when both are true:
- Your organization's plan includes it, and
- The organization owner has enabled File / Code Access Control in Enterprise settings.
Until then, adding a rule fails with "read-ACL is an enterprise feature not enabled for this organization's plan", and no rules are enforced. An enterprise can make this capability mandatory for all its organizations with the Require read-ACL policy.
Only organization owners and admins can add or delete rules.
Where rules live
| Scope | Where | Page title |
|---|---|---|
| One repository | The repository's Settings → Access control (under Security) | Read access rules |
| Every repository in the organization | The organization's Settings → Read access | Org-wide read access |
Repository rules and organization-wide rules are evaluated together, as one set.
Add a rule
- Click ADD RULE → (repository) or Add rule (organization).
- Choose the Effect:
- deny (block this principal): the chosen principal can't read matching paths.
- allow (need-to-know): the matching paths become need-to-know. Only principals named in an allow rule for those paths can read them; everyone else is denied.
- Choose the Principal type and the principal:
- role: member or readonly. Owners and admins can't be restricted, so they aren't offered.
- team: one of the organization's teams. If there are none, the list says "No teams — create one first".
- user: the person's user id (the field hint shows the
usr_…form). To target one person without their id, put them in a team and target the team.
- Enter a Path pattern, for example
secrets/**,*.env, orconfig/prod/**. - Click CREATE RULE → (repository) or Create rule (organization).
Each rule is listed with its path pattern and a label such as deny · role:member or
allow · team:security. Click Delete (or the delete icon) to remove it.
With no rules, the pages say "No read-access rules. All members can read every file." and "No org-wide rules. All members can read every file in every repo."
How rules are evaluated
For each file a member tries to read:
- Owners and admins always keep full read access. Rules never apply to them.
- A matching deny wins. If any matching deny rule applies to the member (through their role, one of their teams, or their user id), the read is refused.
- Allow makes a path need-to-know. If any allow rule matches the path, the member must be named in one of those allow rules, or the read is refused.
- Otherwise, the read is allowed.
Operations that return content from the whole repository at once, instead of file by file, are refused for a member who is subject to any read access rule in that repository.
Path patterns
Patterns use gitignore-style matching:
| Pattern | Matches |
|---|---|
*.env | Files ending in .env, in any folder |
src/*.rs | .rs files directly inside src/ |
secrets/**/*.pem | .pem files anywhere under secrets/ |
secrets/* or secrets/** | Everything under secrets/ |
keys* | Every path that starts with keys |
A pattern that ends in * and has no other wildcard (like secrets/* or keys*) covers every path
that starts with the text before the *, at any depth.
A pattern can't be empty, can't start with !, and can't end with /. To cover a whole folder, write
secrets/** rather than secrets/.
Audit
When Enterprise Audit is on, reads that a rule refuses are recorded in the repository's audit log.
Organizations
Create an organization, understand member roles, invite people, manage Team seats and teams, and turn organization capabilities on or off.
Audit logs
See who read and changed what — the repository audit log, the organization audit log, and the enterprise audit log, and what you need to turn them on.