> For the complete documentation index, see [llms.txt](https://govplane.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://govplane.gitbook.io/docs/documentation/govplane-cloud/create-a-policy.md).

# Create a Policy

A policy defines how decisions are made. It consists of one or more rules that evaluate structured input data and return a final effect.

### What Is a Policy?

In computing, a policy is a formal set of rules, guidelines, and procedures established to govern how systems and resources are accessed, used, and managed.

In Govplane, policies are the core building block of the platform.

A policy defines how decisions are made. It consists of one or more rules that evaluate structured input data and return a final effect (typically allow or deny).

Rules enable context-aware decision-making based on parameters such as:

* Service
* Resource
* Action
* Custom conditions defined through a structured JSON evaluation schema

Policies allow you to centralize governance logic and apply it consistently across your infrastructure.

***

### Requirements

Before creating a policy, you must have:

1. A Govplane account
2. Access to an organization with one of the following roles:
   * Owner
   * Admin
   * Editor
3. An existing project

***

### How to Create a Policy

Follow these steps to create your first policy.

#### 1. Access Your Project

Log in to your Govplane account and open the project where you want to create the policy.

***

#### 2. Start the Creation Process

You can create a policy in two ways:

* Click the green “Create a policy” button in the top navigation bar
* Or go to the Policies section and click “Create first policy”

***

#### 3. Define Basic Policy Information

In the modal window, provide the following details:

#### Policy Key

* Must be an alphanumeric string
* No spaces allowed
* Hyphens (-) and underscores (\_) are supported
* Serves as the canonical identifier for:
  * Creating new versions
  * Runtime evaluations
  * API integrations

#### Friendly Name

A human-readable name for easier identification.

#### Description (Optional)

Provide context or internal documentation.

#### Environment

Choose between:

* test
* production

This allows separation of evaluation contexts.

#### Default Effect

Defines the fallback behavior when:

* No rules match
* Rule evaluation fails

Available values:

* allow
* deny

***

#### 4. Activate Upon Creation (Optional but Recommended)

Enable:

> “Activate policy version upon creation”

If enabled:

* Version v1 becomes active immediately.

If disabled:

* The policy will be created as version 1 in draft state
* You must manually activate it for it to take effect.

By default, new policies are created in draft mode.

***

#### 5. Create a Rule

Click “Add a rule” and define the rule configuration.

#### Rule Fields

Rule Name

Descriptive name for internal identification.

Status

Enable or disable the rule.

Priority

Lower numbers indicate higher priority.

Rules are evaluated in priority order.

Notes (Optional)

Internal documentation or comments.

***

#### Target (Required)

Defines what the rule applies to.

* Service
* Resource
* Action

Available action types:

* read
* write
* admin
* custom

If custom is selected, you may define a custom string value.

***

#### Conditions (Optional)

Conditions allow you to define structured logic using Govplane’s JSON evaluation schema.

Example:

```json
{
  "op": "or",
  "args": [
    {
      "op": "eq",
      "path": "plan",
      "value": "free"
    },
    {
      "op": "eq",
      "path": "country",
      "value": "ES"
    }
  ]
}
```

This example evaluates to true if:

* plan equals "free"

  OR
* country equals "ES"

The schema supports logical operators and comparison operators to build expressive rule logic.

***

#### Rule Effect

Finally, define the effect applied if the rule matches:

* allow
* deny

***

#### 6. Confirm and Create

Click Confirm to create the policy.

If activation was enabled, version v1 will be active immediately.

If not, remember:

> Policies created without activation remain in draft state and must be manually activated to take effect.

***

### Important Notes

* Policies are versioned automatically.
* Only active versions are used by the runtime.
* Draft versions allow safe editing without impacting production decisions.
* Policy logic is evaluated in priority order until a matching rule determines the final effect, or the default effect is applied.

Policies are the foundation of Govplane’s governance model. Proper structuring ensures predictable, secure, and scalable decision-making across your systems.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://govplane.gitbook.io/docs/documentation/govplane-cloud/create-a-policy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.