Skip to main content
Version: 2.0.0

Git and Permit

Hosted Git support​

This guide is demonstrating GitOps on Github, but should work in a similar fashion to other Git repositories which can be configured with an SSH key.

The main actions are, adding a SSH deploy key with write access to your repository, and configuring Permit to use it with the SSH url of your repository.

note #1

Ensure that this deploy key is configured without Two-Factor Authentication (2FA) to allow the Permit server unimpeded read and write access to your repository.

note #2

When utilizing the Copy Environment API with a brand-new Git repository that has no commits on the main branch, ensure that at least one file is added and committed. This step is essential for our system to successfully clone the branch.

GitHub Example​

Configure your git repository​

Please follow the below steps to make your Permit policy stored at your git repository.

Create a repository​

You need a repository with a default branch that exists on the remote ( with an initial commit ). If you already have a repository you can skip to next step.

Create your repository at GitHub: GitHub new repo

Project/Env mapping to Repositories and Branches​

By default the following mapping takes effect - each repository is mapped to a specific Permit project, and under it branches are created and mapped for each Permit environment under the Project. Additional layout are supported, but not currently available via the API.

Give Permit permissions to your repository​

In order for us to be able to generate and push policies to your repository, you need to create an SSH key, and add it as a "Deploy Key" with write access to your repo.

Generate an SSH key​

You can use this command to generate a secured SSH key:

ssh-keygen -t ecdsa -b 521 -C "help@permit.io"

You will be prompted to enter a location for the private and public keys ( your private key will be securely stored on our end, no passphrase will be required ) SSH key generation

The private key is at the location you chose and the public key is at the same location with a ".pub" suffix.

Add the Deploy Key​

  1. To add a "Deploy Key", go to your repository → Settings → Deploy Keys and press on "Add deploy key" button.

    Add Deploy Key Step 1

  2. Copy the public SSH key you've generated previously to your clipboard and paste it in the GitHub prompt.

    It is required to toggle the "Allow write access" Add Deploy Key Step 2

Configure Permit to use your repository​

Make Permit use the repository​

  1. Login to Permit.io.

  2. Navigate to your project. with the project selector at sidebar.

  3. Navigate to API Keys page.

    API Keys Page

  4. Create a Project or Organization API Key. (you will need it for the 8th step)

  5. Copy the SSH url from GitHub: Copy SSH url

  6. Copy the SSH private key you've generated previously and replace new lines with "\n". You can do the new line replacement using the following command:

    awk -v ORS='\\n' '1' <private-key-file>

  7. Paste your values into that json and store at in a file:

    {
      "url": "<your-ssh-url>",
      "main_branch_name": "<your-default-branch>",
      "credentials": {
        "auth_type": "ssh",
        "username": "git",
        "private_key": "<your-private-key>"
      },
      "key": "<your-custom-id-string-without-spaces>"
    }

  8. Get your project key / id from this URL

    curl -X GET "https://api.permit.io/v2/projects" -H "Content-Type: application/json" -H "Authorization: Bearer {API_KEY from step 4}"

  9. Replace the placeholder with your project id or key and execute a POST request to Permit with your json:

    curl -X POST "https://api.permit.io/v2/projects/<your-project-id-or-key>/repos" -H "Content-Type: application/json" -H "Authorization: Bearer {API_KEY from step 4}" --data-binary @"path/to/your/json"

  10. Please return to your GitHub repository. You will now observe new branches, each corresponding to a different environment in your project. These branches are named following the format permit/generated/<env_id>, where <env_id> is the unique identifier for each environment. You can specify a custom branch name by setting the custom_branch_name of your environment, see an example.

  11. After validating your new policy branches, you need to activate the new repository in Permit, to do this, replace the below placeholders with your project id or key and execute a PUT request to Permit:

    curl -X PUT "https://api.permit.io/v2/projects/<your-project-id-or-key>/repos/<your-repo-id-or-key>/activate" -H "Authorization: Bearer <your-permit-api-key>"

  12. To add custom policy code for each environment, ensure you have checked out the correct branch using permit/generated/<envid>. Insert your policy code exclusively within the custom folder. This can be done by either editing the custom/root.rego file with your custom Rego code or by creating a new file and importing it in the custom/root.rego file. _Please avoid editing policy code outside of this folder, as it could potentially be overridden by our code or break the Rego code.

Once modifications are made within an environment branch, push it to the remote GitHub repository(To the same environment branch not the main branch). Permit cloud will then detect these changes and relay them to the PDP that is associated with that environment for update.

As a result, your git repository now serves as the policy source for your PDPs.

  1. Your git repository is now ready to be synced to your PDPs 🚀

Contents