Administrator guide

Set up a workspace

A safe order for the first project and its configuration.

Complete workspace approval and administrator MFA first. Use Configuration → Create project and choose Basic, Kanban, Scrum or service management. The wizard creates the relevant starter documents.

1. Create a small test project before changing a shared configuration.
2. Set its name, description, workflow and issue types.
3. Configure fields and screens, then bind the appropriate schemes to the project.
4. Review permissions and issue security with the Permission helper.
5. Create a test issue, reopen it and exercise each important transition.
6. Only after behavior is confirmed, apply the configuration to the intended production projects.

Workspaces are isolated organizations. A project is an area of work inside a workspace, not a new organization or account.

Save, reopen and recover configuration

Use Form controls; Advanced JSON is optional.

Open a configuration category, choose New or an existing document, and use the Form tab. Give a new document a stable ID and a readable name. IDs are permanent; changing the display name does not rename an ID.

1. Complete the controls and resolve validation messages.
2. Choose Create or Save changes.
3. Reopen or reload the document and confirm the values and version.
4. Test the setting in its consumer: an issue, board, request form or workflow action. Saving a configuration alone does not prove its runtime effect.

Use Advanced JSON only for advanced repair or compatibility needs. Form controls preserve recognized values and unknown settings rather than silently removing them. A version conflict means another update occurred: review the latest version before resubmitting.

History records revisions. The Deleted view offers recovery for soft-deleted configurations; deletion can be blocked by dependencies. Restore a test document and check its consumers before relying on recovery. A workflow has a separate draft-and-publish process below.

After saving, a history list may need a full refresh to show the newest revision. Treat the reopened document and version as the persistence check.

Projects and filing defaults

Choose the configuration that a project uses.

In Configuration → Projects, select the workflow, issue types, permission scheme, security scheme, notification scheme and screen scheme. A project can inherit selected settings from its parent; moving it does not automatically change the explicit inheritance selection.

Set filing defaults for version, milestone and assignee. The default version becomes the new issue’s affected version; choose a fix version separately when a release commitment is known. Components can supply a more specific assignee default. Open for new issues controls filing; archiving is different from deleting a project.

Set status, health, planning priority, dates and update cadence for roadmap planning. Project members and lead identify planning responsibility; they are not a replacement for permission grants.

Project properties store named structured values. Use the value controls for text, numbers, switches, lists, objects or null. Project shortcuts store named URLs; their visibility depends on the current navigation consumer.

Custom fields, choices and conditions

Design a clear filing form without writing JSON.

1. Open Configuration → Fields → New field. Choose the field type carefully; the saved type is locked.
2. Give it an ID and display name. For a dropdown, add stored values and readable labels using the choice controls.
3. Add scopes for the intended projects and issue types. Configure required state and a compatible default, including meaningful 0 or false values.
4. For conditional visibility, select the controlling field and matching values. Supply a required value when the field becomes visible.
5. Save the field and select it under the project’s Custom fields. Check the create screen and file a test issue.

Retire a choice rather than casually replacing its stored value when issues already use it. Keep labels understandable to people filing an issue.

Only fields enabled in the project apply; scopes can narrow them to particular issue types. An empty project selection enables no custom fields. On an issue, use Custom fields → Edit custom fields to edit visible fields together. Required fields are checked when they become visible, and saved zero and false values remain meaningful. Save and reopen a test issue, including the portal path if you use request types.

Screens and screen schemes

Decide which fields appear for an operation.

A screen has ordered tabs and field rows. Use the controls to choose fields, input styles, labels and required state. A screen scheme selects create, edit and view screens, with optional issue-type-specific overrides. Bind the screen scheme to the project.

Use an isolated test screen first. An issue operation may also enforce domain and workflow requirements, so hiding a required field does not necessarily make the operation valid.

A transition can select its own screen. Test that action with missing and valid values. Built-in resolution, duplicate and comment controls use configured labels and help text. Choose a compatible input type, such as List of text for labels. Reopen the issue to verify its values and post-actions.

Workflow drafts and publishing

Change behavior in a reviewed, saved revision.

A workflow defines states, resolutions and transitions. Conditions decide whether an action is offered; validators decide whether a submitted action is acceptable; post-functions perform supported actions after a successful transition.

1. Create an isolated workflow or open the intended existing workflow.
2. Create or open its editable draft and use the Form tab.
3. Configure state categories, transitions, source and destination states, conditions, validators and actions.
4. Save the draft. Publishing is disabled while local edits remain unsaved.
5. Review the saved draft and publish it deliberately. Check every project using that workflow before publishing shared changes.
6. Exercise the transition on a test issue: verify the condition, negative validation case, destination state and intended post-function.

For example, a transition can require priority P3, demand a comment, assign the current user and add a completion comment. These are separate settings and should be tested separately. A stale draft must be reloaded and reviewed before publishing.

Issue types and relationships

Choose what a project tracks and how work connects.

Issue types define categories of work and their hierarchy role. An issue type can select a workflow override. Enable the intended types in the project, then file a representative issue for each.

Link types name relationships and their direction. Choose clear inward and outward wording, save the type, then link two test issues and inspect both directions. Hierarchical work and project dependencies have their own planning semantics; a named link does not automatically create either.

Components, versions, milestones and priorities

Give issues useful delivery metadata.

Components belong to a project and can define an initial assignee or QA contact. Versions identify release scope. Milestones identify checkpoints. Choose project defaults only after these documents are saved.

Priorities define active choices, ordering, labels and color. Use a test priority before changing the tenant’s default. Keywords provide reusable issue tags. Classifications organize projects into categories.

After a change, reopen the document and file or edit a test issue. Check that the choice belongs to the intended project and that the resulting issue retains the selected value after reload.

Groups, roles and project permissions

Treat access as several independent layers.

Creating a role does not assign anyone to it. Creating a permission or security scheme does not bind it to a project. A saved search’s sharing audience does not grant issue access.

Use the Permission helper for the specific user, project, permission and issue being investigated. Test allowed and denied personas; an administrator’s successful access is insufficient evidence that restrictions work for a member or guest.

Review the resulting access before broadening a group, role or global grant. Keep a second authorized administrator available when changing administration rights.

Members, guests and portal customers

Keep organization access and service enrollment distinct.

Member and guest administration is available through the application’s administration/settings controls according to your authority. A guest authenticates through a home organization and needs a scoped host grant. Revoke the grant when access should end; already-issued tokens and download URLs have bounded lifetimes.

Customer organizations and Portal customers configure a service project’s customer enrollment. They are not new Gnok Bug workspaces and do not replace identity or guest grants. Disabling a portal customer is different from disabling a member’s organization account.

Validate changes with a genuine member or guest session. Do not assume a directory entry or an administrator’s portal access proves the guest experience.

Request types and service queues

Build a customer form and its agent view.

1. Create a service project or select an existing one.
2. In Request types, select the project and issue type, then add ordered fields with readable labels and input controls.
3. Set dropdown choices and typed defaults. A required hidden field needs a default; otherwise the customer cannot complete it.
4. Save and reopen the document, then open the portal and submit a test request.
5. In Service queues, define the project and BQL selection. Verify the new issue appears and unrelated projects do not.

Knowledge articles belong to a service project. Add a title, summary and useful content, then publish deliberately. Verify the portal’s customer-facing suggestions separately from the agent queue.

When a request uses custom fields, enable them in the project and configure visible controls or appropriate hidden defaults in the request type. Test required values and confirm that the submitted issue contains its defaults. Fields outside the project’s enabled selection do not block the portal.

Business calendars and SLA policies

Make timing rules explicit.

In Service calendars, choose a timezone, weekday windows and holiday dates. Windows cannot overlap on the same weekday. Use local start and end times and check the intended timezone before saving.

In SLA policies, select the project, metric and calendar, then set a business-minute target. Add priority-specific targets when needed. A holiday should move business-time work to the next available window.

Save and reopen both documents. Verify an actual request at a known time and inspect its deadline or timing evidence. Saving a policy is not proof of an SLA clock, escalation or contractual response commitment. Verify the calculated deadline on a test request before relying on the policy.

Notification schemes and delivery

Separate recipient rules from transport.

A notification scheme maps events to recipients: issue relationships, users, groups, roles, fields or email addresses. Configure only the necessary recipients, then bind the scheme to the project. Review private-issue and private-comment handling with the intended audience.

SMTP configures a transport, not the project’s recipient policy. Its active profile ID must be default. Keep credentials in configured secret references rather than issue content or public documentation.

Before a delivery test, confirm the recipient and purpose. An inactive transport or synthetic event that never fires is useful for saving/reopening controls, but it does not prove email delivery. Personal notification preferences are a separate setting.

Webhooks, inbound mail and collectors

Configure a connection before exposing it.

Webhooks send selected events to a configured endpoint. Inbound mail and Issue collectors accept authenticated intake and file into a configured project and issue type.

1. Create the configuration with a clearly identified endpoint, event or project scope.
2. Use the supported secret reference; do not put a raw credential in a public URL.
3. Keep it inactive while reviewing the configuration.
4. Enable only after the destination, authentication and scope are ready.
5. Send a harmless, authorized test and verify both delivery and the resulting record.

The Integrations & agents page distinguishes connections from agent identities. A connection records its provider, project/repository scope and credential references. An agent identity selects a connection, human owner, delegated scopes, rate limit and approval requirement. Review scopes and keep required human approvals enabled. Saving a connection does not prove its provider adapter has performed an external action.

A successful save of an inactive configuration does not establish external delivery, sender authorization or replay protection. Keep tests synthetic and avoid real customer content.

Teams, initiatives and project dependencies

Organize responsibility and outcomes.

Teams name a group of contributors and optional capacity. Team membership used in planning does not replace permission grants. Initiatives connect projects to an outcome; Project dependencies record a blocker and blocked project.

Save the documents, then open Roadmap or the relevant project overview. Check the initiative’s project list and the dependency direction. Project dates, status and health drive the planning display.

Saved searches, boards and sprints

Connect query, visualization and planning.

1. Create a Saved search with a tested BQL query and an appropriate sharing audience.
2. Create a Board, select its filter and projects, and choose Scrum or Kanban.
3. Map workflow statuses into columns and set optional WIP limits and quick filters.
4. Open the board and confirm issue counts, status columns and quick-filter behavior against known test issues.
5. For Scrum, create a future Sprint for the board and verify scheduling, starting and completion.

Board and saved-search documents can be owner-scoped. A board’s existence, sharing or filter never grants access to restricted issues. Some presentation options can be stored before their complete runtime rendering is available; test the board instead of relying only on its saved document.

Configured flags and planning impediments

Two different concepts with different consumers.

Flag types define named request/grant flags with optional requestees, project/component scopes and request/grant groups. Use the Form controls to configure scope and save the definition.

On an issue, use Review flags to choose an applicable type and request a named or open review. Authorized group members can grant or deny it; clear a flag when appropriate. Save, reopen and verify the result. Requests and decisions retain the flag’s identity. The separate impediment toggle is a planning flag.

Connect GitHub for the coding agent

Grant repository access deliberately.

Open Integrations & agents and use the GitHub connection controls. A GitHub App installation is limited to selected repositories; reviewing an installation can grant persistent repository access, so approve the exact selection deliberately.

The coding integration uses repository contents, pull requests and Actions read/write plus metadata read. The executor can be AWS CodeBuild; it does not require buying additional always-running application capacity. Repository permission scope and executor choice are separate concerns.

Configure the base branch, allowed file paths, test commands and timeout. Start with a disposable repository and an issue whose expected result can be tested. The agent reviews selected source/context with the chosen AI provider; avoid secrets and review your organization’s source-sharing policy.

Human approval is required for the exact implementation plan. The result is a draft PR, and a human decides whether to merge it. See the user workflow.

AI credits and workspace spending controls

Approve a bounded allowance without interrupting every task.

1. Open AI credits and review the rate policy and balance.
2. Explicitly approve a one-time purchase of at least $10 in the in-app card form when credits are needed. This is separate from subscription pricing.
3. Review and approve a workspace allowance and per-run ceiling. Purchasing credits does not automatically approve their use.
4. Members may start work within that authority. Limit increases or replacement allowances require a new administrator approval.
5. Inspect usage history, actual debits and outstanding holds. Reservations account for concurrent work; a hold is not a second payment.

Allowances do not renew automatically. Pausing new work does not revoke phases already authorized, which can finish and settle. Wallet, allowance, per-run and service limits can all block new work.

Gnok-managed model tokens are billed at published provider rates without model markup; sandbox runtime includes the platform margin at $0.01 per started minute. There is no flat implementation fee. Unused purchased credits carry forward during this launch. See AI Credit Terms for the authoritative rates and conditions.

Bring your own API keys

Use your provider account while paying Gnok only for runtime.

In AI credits → Use your own AI account, use the workspace provider-key controls to connect an Anthropic or OpenAI API key. Only an authorized administrator should configure or replace it. Obtain an API key from the provider; a consumer chat subscription does not provide API billing.

Workspace keys are encrypted and not exposed to repository test containers. Runs select the workspace provider and an available model explicitly; Gnok does not silently fall back to a managed model. Provider tokens appear in usage with a $0 Gnok model debit, while the provider bills them directly.

The Gnok allowance caps runtime credits only for BYOK. Set a separate budget and rate limits at the provider. Replacing or revoking a key stops future model calls pinned to its previous version, but an already-sent request can finish and be billed. Revoke a credential at the provider to invalidate it there.

Verify setup with a synthetic issue and disposable repository. Keep human plan approval and merge approval even during testing.

Assistant feature settings

Do not confuse assistant features with coding-agent spending.

Configuration → Ai settings controls the available assistant features and context options. Its active document ID is default. Enable only the features your workspace intends to use; description and comment inclusion affect the context considered.

These settings are distinct from the coding agent’s GitHub connection, workspace API keys and AI credit allowance. An enabled switch does not establish that an external model connection is available. Check the feature’s actual response and displayed provenance.

Audit, project keys and recovery

Review changes before relying on them.

Audit log lists configuration changes with the actor, document and revision. Individual document history helps compare saved versions. Record the old version before a consequential change and verify the reopened version afterward.

Change project key changes the human-facing issue-key prefix. Review the affected project and resulting keys before confirming. A key cannot reuse any current or historical project key, so treat the choice as permanent; existing issue URLs remain valid aliases. Prefer a test project first; do not casually rename a shared project during configuration work.

Export tenant is an administrator-only export intended to contain sensitive workspace data. Treat any export as confidential and verify that the download is complete before calling it a backup. The app checks the final completion record, displays a record/byte receipt and offers a download-again link. Attachment bytes remain in object storage and are referenced by metadata. A downloaded export is not evidence that restoration works.

Validate the result and get help

Use a small, repeatable acceptance check.

1. Save the configuration and reopen it after a full reload.
2. Confirm the project points to the intended document and inheritance is correct.
3. Create a synthetic issue or request and check defaults and required fields.
4. Exercise negative and positive workflow cases, then reopen the issue.
5. Check the consumer with an ordinary member or guest when access matters.
6. For an integration, verify the authorized external delivery separately.

Contact support@gnok.com with the workspace ID, configuration kind and ID, version, time and exact error. Do not include secret values, access tokens or private exports.