devguard

Automations

Let devguard check your tools on a schedule and keep the evidence current, and open recurring tickets in GitHub, GitLab, Jira, Asana or Slack.

Automations does two kinds of recurring work for you. A check reads a setting in one of your tools on a schedule. For example, it tests whether www.example.com redirects to HTTPS. It writes the result into an evidence record, so the proof for a control stays current without a screenshot. A ticket rule opens a ticket in GitHub, GitLab, Jira or Asana, or posts a Slack message, on a schedule. A person then does the work, such as a quarterly access review.

Use a check when the proof is a setting in a tool. Use a ticket rule when the proof is that a person did something.

The tasks below follow the order of the work:

When the catalog has no check for what you need, build your own check. The tools themselves are connected under Integrations. Scripts and integrations: see API below.

The check Website TLS certificate: its steps on the left, and on the right the last result Failed, the last runs, one open High finding, the evidence record EV-025 it keeps current, the variable host and the next run.
CHK-001 found that the certificate of www.devguard.ch expires in 12 days. It marked EV-025 as failed and opened a High finding.

Enable a check from the catalog

The catalog lists every check that devguard provides, grouped by category. Most checks need a connection to the tool first. Connect it under Integrations. The HTTP / TLS checks need no connection: they test web addresses that you name. Neither do the devguard Devices checks: they read the devices enrolled on Devices.

  1. Open Automations and choose New automation, then From the catalog.
  2. Type the tool or the topic into Search integrations and checks. Each card shows a tool and the names of its checks.
  3. Choose a check. The Enable panel opens on the right.
  4. Keep or change the Check name. It is also the title of the evidence record.
  5. Fill in the variables that the check asks for, such as the domains to test. A list takes one entry per line. Commas also work.
  6. If the panel shows Credential, choose the connection the check uses.
  7. Choose a Schedule. Every check needs one. Schedules are kept under Collections → Schedules.
  8. Choose the Owner and the Approver of the evidence record. Both are business roles.
  9. Choose Enable check. The check opens and is Active. It runs at the next time in its schedule.
The Enable panel for HTTP redirects to HTTPS on every host: the check name, two domains on two lines, the schedule Weekly checks, the owner Head of IT and the approver Chief Information Security Officer.
Two domains, one per line. The owner and the approver are roles, not people.

Enabling also creates the evidence record, with the status To do. Link that record to the controls it proves, on the record's Evidence tab. See Link it to controls.

From the catalog to an active check: search, fill in the panel, choose Enable check.

Read what a check found

The Automations list shows checks and ticket rules together. For a check, Result shows how its last run ended.

The Automations list with three rows: the ticket rule A-011 and the checks CHK-002 and CHK-001, with the columns Type, Integration, Status, Result and Last activity. CHK-001 shows the result Failed.
CHK-001 is active, but its last run failed.

Open the check from the list. The left side shows the steps of the check, from the Trigger (the schedule) to the Result. Switch between Diagram and Outline at the top left. The panel on the right shows how the check is doing: Last result, Last 30 runs, Open findings, Evidence kept current, Variables, Next run and Version.

A finding is one problem that a run found, with a severity: critical, high, medium, low or info. To see each run, choose All runs. The Runs panel lists each run with its result, its age and its duration. Open a failed run to see its findings. If the run kept data as proof, the data is below the findings, as JSON. For example, it lists the users that a finding is about. On a run that did not fail, choose Show data to see it. Copy and Download give you the complete data. Show logs shows the lines that the run logged instead.

The Runs panel of the TLS check: a failed run with the finding "Certificate expiring soon: www.devguard.ch" of severity high, and two earlier passed runs.
The failed run names the problem and the threshold. The two runs before it passed.

Act on a failed check

  1. Open the check and read the finding under Open findings or in All runs.
  2. Fix the problem in the tool itself. For example, renew the certificate.
  3. Choose Run now. This is a real run. When it passes, the evidence record goes back to Done. Run now works only on an active check that is not archived.

If the check is Unhealthy, fix the cause first. Often a key has expired or was revoked: reconnect it. Or a variable is wrong: choose Edit settings on the right and correct it. Then choose Run now.

How a check keeps evidence current

Each run ends with one of three results. Only two of them change the evidence.

ResultWhat it meansWhat happens to the evidence record
PassedEvery rule of the check held.Status Done. Last reviewed is today. The next review is the next run plus three days. If the check saves what it read, devguard attaches it to the record as a file, in place of the previous one.
FailedAt least one rule did not hold.Status Failed. The active members of the owner role are notified when the check starts to fail.
ErroredThe check could not finish, for example because the key was refused or the site did not answer.No change. A run that could not finish says nothing about the control.

So a passing run counts as a review of the record. Nobody has to approve it again each week. An auditor sees in the record when the check last passed, and the file it read.

When a check errors three times in a row, it gets the Unhealthy badge. The members of the evidence owner role get the notice "Check needs attention", in the app and by email if they turned email on. The problem is then the connection or the address, not the control. The badge goes away with the next run that passes or fails.

Change, pause or remove a check

ToDo this
Change the name, variables, connection or scheduleChoose Edit settings on the check, or Actions, then Edit. The next run uses the new settings.
Pause the checkChoose Actions, then Deactivate. The check stops running. Its evidence and history stay. Activate starts it again.
Retire the checkIn the list, open the row menu and choose Archive. The check stops and leaves the list, the dashboard and search. Its runs and evidence stay. Archived above the list shows it again, and Restore brings it back.
Delete the checkChoose Actions, then Delete. This removes the check and its runs. The evidence record and its files stay.

devguard updates the checks in its catalog. Your check gets each update until you publish your own version of its steps. See Build your own check.

Create a ticket rule

A ticket rule needs a connection to GitHub, GitLab, Jira, Asana or Slack. Connect it under Integrations first. The Integration field lists only these connections.

  1. Choose New automation, then Create ticket rule. The Create ticket rule panel opens on the right.
  2. Enter a Name, such as "Quarterly access review". It becomes the ticket title.
  3. Choose a Schedule. Without a schedule, the rule never runs by itself.
  4. Choose the Integration. More fields appear for that tool, for example Repository, Assignees and Labels for GitHub. See Fields for each tool.
  5. In Template content, write what the person must do. You can use Markdown.
  6. Leave Status on Active and choose Create.
The ticket rule A-011 for GitHub: the name Quarterly access review, the schedule Access review: privileged accounts, the GitHub connection with its name blurred, the repository acme-ag/it-operations, one assignee, two labels, the template text and the status Active.
A complete rule for GitHub. The name becomes the ticket title, and the template becomes its text.

On each date in the schedule, devguard opens one ticket. The title is the rule number, a running number and the name, for example "A-011-1 Quarterly access review". GitHub and GitLab issues also get the label devguard. devguard opens at most one ticket between two dates of the schedule. On the next date it opens a new ticket, even if the last one is still open.

Follow the tickets

  1. Open the rule. The Detail tab shows the newest tickets under Recent Tickets.
  2. Open the Tickets tab to see all of them, with their status: Open, In progress or Closed. A task deleted in Asana, or a Jira issue in a status such as Cancelled, Rejected, Won't do or Duplicate, shows the status CANCELLED.
  3. When someone closes the issue in GitHub, GitLab, Jira or Asana, the status changes here too.

Watch out: closing a ticket does not change any evidence record. When the work produces proof, such as a signed export, attach it to the evidence record yourself. You can link the record on the rule's Evidence tab.

To open a ticket now, outside the schedule, choose Trigger Manually in the row menu of the list. This works for active and inactive rules, but not for archived ones. An inactive rule opens no tickets on its schedule.

Deleting a rule also deletes its ticket list in devguard. The issues in the tool stay.


Reference

The list

ColumnShows
IDCHK-001 for a check, A-001 for a ticket rule.
TypeCheck or Action. Action means a ticket rule.
IntegrationThe tool or the connection, such as HTTP / TLS or devguard Devices.
StatusActive, Inactive or Draft.
ResultFor a check, the last result. For a ticket rule, its tickets or an error.
Last activityThe last run or ticket, or Never run.
ScheduleThe schedule, or a dash.

Filter with Type, Result and Filter (status, schedule, date created). Archived shows archived rows. Select rows to archive, restore or delete them together.

Check statuses

StatusMeaning
ActiveRuns on its schedule and writes evidence.
InactivePaused. Keeps its evidence and history.
DraftNot running yet. Only checks you build start as drafts. See Build your own check.

A check can also show Unhealthy (three errors in a row) and Archived.

Fields for each tool

ToolFields after you choose the integration
GitHubRepository (required), Assignees (GitHub user names, separated by commas), Labels
GitLabProject ID (required, the path or the number), Assignees, Labels
JiraProject ID (required, the project key), Issue type (required), Assignee (email or display name), Labels, Priority
AsanaProject ID (required, the number in the project address), Assignee
SlackChannel (required)

If Jira cannot assign the ticket, it still creates it without an assignee, and the rule shows a warning. A Slack message stays Open, because Slack sends no status back.

In Template content, these placeholders are filled in when the ticket is created. Spaces inside the braces are allowed, as in {{ action.name }}. A template with any other placeholder is not saved.

PlaceholderBecomes
{{action.name}}, {{actionName}}The rule name
{{action.shortId}}, {{actionId}}The rule number
{{organization.id}}, {{organizationId}}Your organization's ID
{{schedule.name}}The schedule name, or Manual without a schedule
{{policies}}, {{risks}}, {{assets}}The names of all linked policies, risks or assets, separated by commas, or None
{{policy.name}}, {{policy.slug}}The title and slug of the first linked policy
{{risk.name}}, {{risk.description}}The name and description of the first linked risk
{{asset.name}}, {{asset.description}}The name and description of the first linked asset

Permissions

RoleChecksTicket rules
Owner, adminEnable, build, edit, run, archive, deleteCreate, edit, trigger, archive, delete
Member, auditorReadRead
EmployeeNo accessNo access
Organization tokenFull access over the APIFull access over the API

Members can comment on a ticket rule. Auditors can read the comments.

Limits

PlanTicket rulesActive checks
Free41
BusinessNo limitNo limit

Archived ticket rules do not count. Only active checks count, so a paused check does not. When you reach a limit, the buttons in New automation show Limit reached. Restoring a rule or an active check also counts. Describe it to AI needs a Business plan.

Import and export

The menu at the top right of the list has Import CSV, Download CSV template and Export all. These cover ticket rules only, not checks. The import and the template use the columns name, integrationCredentialId, externalTicketConfiguration, scheduleId, template and status. The export also includes ids and dates.

Where automations appear

PlaceWhat it shows
EvidenceEach check keeps one evidence record current.
DashboardActive checks whose last run failed or errored, in the Compliance Scan card.
Notifications"Check failed" and "Check needs attention", sent to the evidence owner role.
SearchChecks and ticket rules, by name or ID.
AI assistantLists your checks and the catalog, and helps you set up a check.
Audit logCreating, changing, running and deleting. Each ticket rule also has a History tab.
SchedulesA schedule that an automation uses cannot be deleted.

API

  • Base URL: https://app.devguard.ch/api.
  • Authentication: an API token, sent as Authorization: Bearer <token>. Send JSON with Content-Type: application/json.
  • Scope: the API covers ticket rules, enabling catalog checks, status, archiving and running. Building and editing check steps is in the app only.

Ticket rules (in the API, actions):

CallEndpointOrganization id
ListGET /actions/query, required
CreatePOST /actions/body, required
ReadGET /actions/{id}/not used
UpdatePATCH /actions/{id}/not used
DeleteDELETE /actions/{id}/not used
ArchivePOST /actions/{id}/archive/not used
RestorePOST /actions/{id}/restore/not used

Checks:

CallEndpointOrganization id
ListGET /integration-checks/query, required
Enable from the catalogPOST /integration-checks/body, required
Read by numberGET /integration-checks/{shortId}/query, required
Activate or deactivatePOST /integration-checks/{id}/status/body, required
ArchivePOST /integration-checks/{id}/archive/body, required
RestorePOST /integration-checks/{id}/restore/body, required
Run nowPOST /integration-checks/{id}/run/body, required

{id} is the record's id. {shortId} is the number: CHK-001 is shortId 1. GET /actions/ returns { "items": [...], "total": <number>, "page": 1, "limit": 100 }. GET /integration-checks/ returns a plain list. Add filterByArchived=archived to either list to get archived rows.

To enable a check, send the catalogCheckId, a scheduleId and, if needed, name, variableValues, integrationCredentialId, ownerId and approverId. There is no REST endpoint for the catalog. Take catalogCheckId from a check you enabled in the app, or ask the AI assistant to list the catalog. The status call takes ACTIVE or INACTIVE. Activating fails when the schedule, a required variable or a required connection is missing. variableValues takes only the variables the check declares: a number for a number, true or false for a yes/no, one of the listed values for a choice.

externalTicketConfiguration holds the fields of the tool, as JSON. assignees and labels are one string with commas, not a list.

ToolKeys
GitHubowner and name of the repository (required), assignees, labels
GitLabprojectId (required), assignees, labels
JiraprojectKey and issueType (required), assignee, labels, priority
AsanaprojectGid (required, digits only), assignee
Slackone of channelId, channel (an object with id and name) or defaultChannel (required)

The API has no endpoint for runs or findings. POST /integration-checks/{id}/run/ only queues the run. To get the result, read the check again with GET /integration-checks/{shortId}/ until lastRunAt changes, then read lastVerdict.

To create a ticket rule for GitHub, send the whole rule. PATCH /actions/{id}/ needs name, integrationCredentialId and template every time, even when they do not change. Fields you leave out (externalTicketConfiguration, scheduleId, status) keep their values. The API reference marks externalTicketConfiguration as required, so send it too, as in the example below, to be safe.

POST /actions/
{
  "organizationId": "<organization id>",
  "name": "Quarterly access review",
  "integrationCredentialId": "<connection id>",
  "scheduleId": "<schedule id>",
  "status": "ACTIVE",
  "template": "Export the user list and attach it to EV-002.",
  "externalTicketConfiguration": {
    "owner": "acme-ag",
    "name": "it-operations",
    "assignees": "acme-it-ops",
    "labels": "access-review, iso27001"
  }
}

Take the connection id from integrationCredentialId of an existing rule in GET /actions/, and the schedule id from GET /schedules/.

Run a check now
curl -s -X POST \
  -H "Authorization: Bearer $DG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"organizationId\": \"$ORG_ID\"}" \
  "https://app.devguard.ch/api/integration-checks/$CHECK_ID/run/"

Errors return { "message": ..., "code": ..., "issues": [...] }. A member's or auditor's token gets 403 on every write. An id from another organization returns 403, and an id that does not exist returns 404.

How is this guide?

On this page