Use Git as Storage for Libraries
Styra supports using Git as storage for policies. Each library can be configured with its own Git repository as storage.
git-storage
is an internal functionality that coordinates all the activities between the Git repository and Styra DAS.
Using Git as storage also enables the following features:
Embrace the policy-as-code philosophy, allowing you to leverage the same source of truth for your policies that you have for your code: A Git repository.
Rollback policy changes using the same machinery you do for your other code: update the tip of
main
branch to a previous workable state.Implement change control via peer-review using the Git-workflow provided by your organization.
Once you configure Git, you can use Styra the same way you always have, except when you want to promote policies for distribution to OPA.
The following shows the policy-authoring flow without configuring git-storage
:
- Make a policy change in the Styra editor.
- Promote the change. Styra stores the new policy in its backend.
- Styra distributes new policy to OPAs.
The following shows the policy-authoring flow when git-storage
is configured, it assumes that master
is the branch that is configured for tracking:
- Make a policy change in the Styra editor.
- Promote the change. Styra pushes this policy to a review branch on your private Git branch.
- The team can review, test, and merge the private branch into
master
branch. - Styra picks up the change in
master
branch and distributes the new policy to OPAs.

Policy Versions
The policy editor shows the following three different versions of policy with
git-storage
:
- A
master
branch (calledEnforced
). - A private branch (called
Branch
). - A draft (called
Draft
).
The following shows the restrictions on the policy versions:
The
Enforced
andBranch
versions are read-only. The read-only permission allows you to see the policy versions as they exist in the outside world. If required, you can also compare the policy versions. This acts as a starting point to write new policies.Before you have a
Draft
, if you look at either theEnforced
orBranch
versions, and you try to make changes, then you must create aDraft
with your changes.When you already have a
Draft
, you must either publish it to your private branch or discard it before creating a new draft.
Transition to-and-from git-storage
If you either enable git-storage
or disable git-storage
, there will be no disruption to the policies being distributed to the OPAs.
The following section shows you how to transition to-and-from git-storage
.
Turn On git-storage
- If you have already written, published, and distributed policies to OPA without
git-storage
. - Enable
git-storage
on Styra. - Styra fetches the tip of the
master
branch. If policies exist, then it copies them to the (non-Git) Styra policy backend. For Kubernetes, Styra copies theadmission_control.rego
andtest.rego
files. - Styra always distributes the policy in the Styra backend to all OPAs. If your policy is already in the
master
branch, then that policy is distributed to the OPAs. If those policies are not already in themaster
branch, then your existing policy continues to be distributed to the OPAs.
When enabling git-storage
, Styra does NOT automatically push the current policy into Git. But, you can use the Styra policy editor to push your current policy onto your private branch, and then use the standard Git workflow to merge the private branch into the master
branch. Only once you can merge your private branch into the master
branch. The master
branch is distributed to OPA; until this distribution happens, the source of truth for policy is still the Styra backend."
Turn Off git-storage
- If you have policies stored in Git, then it represents the
master
branch policies are distributed to OPAs. - Disable
git-storage
on Styra. - Styra will not copy the tip of the
master
branch into its (non-Git) policy backend. The policy in themaster
branch remains as the policy being distributed to the OPAs. - If you make any more policy changes, then they are promoted directly to the non-Git policy backend, which makes them the version of policy distributed to the OPAs.
Git Configuration Options
DAS allows you to configure a library to use its own Git repository or to use the same repository as the Workspace.
By default, every library is configured to share the Workspace Git repository settings. The changes to each library’s policies are stored in the Workspace repository along with other Workspace files such as the labels
and features
policies for each system. If the Workspace is not configured to use a Git repository, then the FetchDB
repository will be used to store these files instead. For more information, see using Git as storage in the Workspace level.
If you want a library to use a separate Git repository instead of the Workspace repository, follow these instructions to configure each library individually.
- Under LIBRARIES, select the library you want to configure.
- Click Settings >> General tab.
Configure Git Authentication
Styra DAS supports either HTTPS or SSH authentication for Git. You can navigate to the Git settings dialog and select the Git authentication mode HTTPS or SSH.
HTTPS
Git username (required): Your Git username.
Git secret (required): The secret corresponding to your Git username.
Git repository (required): A Git HTTPS URL to your Git repository. For example:
https://github.com/hooli/foo.git
.Git reference: Specify a tag or branch reference (defaults to
refs/heads/master
—themaster
branch).Git commit SHA: Specify a commit SHA.
Repository path: (Optional) The subdirectory where you want to save the policies.
SSH
SSH key (required): A private SSH key. For example: The contents of
~/.ssh/id_rsa
.SSH key passphrase: (Optional) The passphrase specified at the time the private SSH key was created.
Git repository (required): A Git SSH URL to your Git repository. For example:
git@github.com:hooli/foo.git
.Git reference: Specify a tag or branch reference (defaults to
refs/heads/master
—themaster
branch).Git commit SHA: Specify a commit SHA.
Repository path: (Optional) The subdirectory where you want to save the policies.
Click the Save changes button.
- Git reference and Git commit SHA are mutually exclusive, only one can be submitted per Git configuration.
- For SSH configuration, the corresponding SSH public key must be configured on the Git service (GitHub, Bitbucket, and so on) in order for authentication to work.
Now, create a library by clicking the ( ⨁ ) plus icon next to the LIBRARIES heading. Once created, your library is located under LIBRARIES in the left panel of the Styra DAS GUI.
Configure GitHub Repositories
Use the following tips to find the required configuration for a GitHub repository:
Git secret: Styra recommends to use a GitHub Personal access token. You can generate a token at github.com/settings/token or by clicking through
Your-picture
and navigate to Settings >> Developer Settings >> Personal access tokens.Git repository: To create a new Git repository, navigate to github.com/settings/token and click your profile icon located on the top-right of the page. To view your repositories, click Your repositories.
To add a new repository, click the New button.
In the new repository, enter the name of your new repository in the Repository name field, the Description field is optional.
Select Public (Anyone on the internet can see this repository and you can choose who can commit) or Private (You choose who can see and commit to this repository) based on your requirement.
Click the Create repository button.
Navigate your repository on GitHub and copy the link provided for Clone with HTTPS
. For example, navigate to github.com/hooli/policyrepo
and click the Clone or Download button to copy the link provided for Clone with HTTPS
.
Directory Layout in Git
When setting up a Library in Styra DAS, it is important to set up of the following:
- The directory structure in the Git repository
- The package naming in the Rego files
- The Datapath parameter in DAS
- The Repository path parameter in DAS
For more information on mounting Git repositories for libraries, see the Global Library page
Configure using the GUI
You can configure a library from the DAS UI by clicking the ( ⨁ ) plus icon in the left pane. To configure the different settings, see mounting a Git repository through the GUI. It is important to set the Datapath and Repository path correctly.
Configure using the API
export <das-id>="alice.styra.com" # the tenant URL of SaaS Styra DAS or an on-premises URL
export API_TOKEN="abcdefg" # this is generated in the workspace admin settings
# replace newlines in the key with \n
Create a secret with the private key used to access Git. This is for access using SSH keys, alternatively you can use an HTTP username and password. In that case, name should be the username and the password goes in secret. In the SSH case, name is not significant.
Replace all newlines in your private key with \n
.
curl -X PUT "https://${<das-id>}/v1/secrets/git-pk" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $API_TOKEN" \
--data-raw '
{
"description": "SSH Private Key",
"name": "git-pk",
"secret": "-----BEGIN OPENSSH PRIVATE KEY-----\n<\n-----END OPENSSH PRIVATE KEY-----"
}'
Create the Library by referencing the secret created in the previous step. Replace repository URL with your fork.
curl -X PUT "https://${<das-id>}/v1/datasources/global/jwt" \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer $API_TOKEN" \
--data-raw '
{
"category": "git/rego",
"url": "git@github.com:alice/das-demo.git",
"path": "policy/library/global/jwt",
"reference": "refs/heads/main",
"ssh_credentials":
{
"private_key": "git-pk"
}
}
Configure using the Function
See the policy/system/gateway/policy/com.styra.envoy.ingress/rules/rules/ingress.rego
rule for an example on how to actually call the Library function from a system's rule.
The Library's code will be available under the configured Datapath which is data.global.jwt
.
The Datapath should always be data.global
and only the path after this is configurable.
jwt = {"valid": valid, "payload": payload} {
token := data.global.jwt.parse_bearer_token(http_request)
valid := io.jwt.verify_<token>(token)
[_, payload, _] := io.jwt.decode(token)
}
Add Files to Git
To add files directly to Git for a library:
- Configure
git-storage
as described above. - Merge files into Git while adhering to the directory structure in this section.
The package names for the Rego files mirror the directories to which they belong. The synchronization mechanism for git-storage inspects the linked Git repository to detect all *.rego
files.