Plugins
Install a plugin that adds actions to your account, approve what it may call, connect its service, and see how agents, schedules and hooks use it.
A plugin adds actions to your account. An action is a short, fixed job. It can call CodeHerder, or call an outside service over HTTPS. An agent can run an action as a tool. A plugin can also run one on its own, when an event happens in your workspace or on a schedule.
A plugin does nothing until an admin installs it. At install, you approve each CodeHerder action it may call. A plugin never gets more than you approve.
A plugin is not a plugin source. A plugin source copies skills, agents and commands into your catalog. A plugin adds actions. One repo can do both.
Where plugins come from
Settings → Plugins shows two lists. Installed plugins shows what is installed here and on a parent group. Plugin catalog shows what you can install. The catalog holds two kinds of plugin:
- Built in — plugins that ship with CodeHerder. Today these are Onboarding task, which creates a first task in each new workspace, and HTTP endpoint, which sends a JSON body to one HTTPS endpoint when an event happens.
- Plugin source — a plugin from one of your plugin sources, when the pinned commit holds a plugin manifest. Add a plugin source to grow the catalog.
From the CLI, ch plugin catalog lists the same plugins. The ORIGIN column is what ch plugin install takes.
Who can install, and where
You need to be a workspace owner or admin, signed in as a person. An agent’s session cannot install, approve or remove a plugin. Any member can read the lists.
You install on an account root or on a group. A workspace that does work cannot hold an install. The page tells you to install on the group or the account root instead.
An install on a group shows in every workspace below it. There it is read-only. Change it in the group. A workspace holds one install of each plugin. If a group and a workspace below it both hold the same plugin, the nearest one wins.
Managing workspaces explains groups.
Install a plugin
From the web app:
- Open Settings → Plugins.
- Find the plugin in Plugin catalog and press Install plugin.
- Read what the plugin does. The page lists its actions, and each one shows whether it reads or writes.
- Tick the CodeHerder actions the plugin may call. Choose a Write policy. Fill in the settings the plugin asks for.
- Press Install and approve.
From the CLI:
ch plugin catalog
ch plugin install builtin:onboarding-task --approve task.create
ch plugin list
ch plugin show <installId>
--approve takes a comma-separated list. Each action must be one the plugin asks for. The default is none. --write-policy ask|allow sets the write policy. --config '<json>' or --config-file <path> sets the plugin’s settings, and CodeHerder checks them against what the plugin accepts. An install id is a full UUID.
What you approve
A plugin lists the CodeHerder actions it may call, such as task.create. You approve some, all or none. A plugin can still run an action that calls nothing in CodeHerder. An action that calls an action you did not approve does not run.
Each install creates one agent for the plugin, named after it with (plugin) at the end. The plugin acts as that agent. The agent gets the lowest role that covers your approvals. That role is admin only if you approve repo.add or variable.set, and member otherwise. It is never owner. No one staffs this agent on a task.
Write policy
An action is a read or a write. The write policy decides what happens to a write.
- Ask (the default) — a write the plugin starts on its own waits for a person to approve it. A write an agent starts files a question, and the task waits for a person to answer it. See Asking a human.
- Allow — the write runs at once.
A read always runs. Choose Allow only for a plugin you trust.
Settings and connection
Some plugins take settings. The install form shows them. Settings → Plugins → the plugin shows them again, and you can change them with Save changes. You can also change the approved actions and the write policy there.
A plugin that calls an outside service needs a connection. After you install it, open the plugin’s page and press Connect. Or open Admin → Integrations and choose the plugin. Fill in:
- the base URL of the service. It must start with
https://. - the credential. The plugin names the kind of auth: none, a bearer token, a header value, or a username and password.
CodeHerder stores the credential encrypted. A workspace below the install uses the nearest connection above it. Until you connect, the plugin’s page shows Not connected.
The HTTP endpoint plugin sends a JSON body to your endpoint. It needs a bearer token and a base URL. Its settings choose what triggers it: an event, a schedule, or both. It does nothing until you set one.
Run on a schedule
The HTTP endpoint plugin can call your endpoint on a schedule. In its settings, fill in the On schedule group:
- Schedule — a standard five-field cron expression, such as
0 9 * * 1for 09:00 every Monday. A descriptor such as@dailyalso works. Use 128 characters at most. - Timezone — an IANA zone name, such as
Europe/Paris. Leave it empty for UTC.
You can set the same thing at install from the CLI:
ch plugin install builtin:http-endpoint \
--config '{"hooks":{"on-schedule":{"schedule":"0 9 * * 1","timezone":"Europe/Paris"}}}'
Each run posts {"hookId": "on-schedule", "firedAt": "<time>"} to your endpoint. The run belongs to the group or account root that holds the install. It has no task.
- The plugin must be Active. A plugin that is disabled, waiting for approval or without its source does not fire.
- Under the Ask policy, each fire stores an offer instead of calling your endpoint. Under Allow, it calls the endpoint at once.
A scheduled offer belongs to the group or account root that holds the install. A group has no dashboard, so the web app does not show this offer. Resolve it from the CLI, with --workspace set to that group or account root:
ch plugin offers --status pending --workspace <group>
ch plugin approve-offer <offerId> --workspace <group>
ch plugin skip-offer <offerId> --workspace <group>
For an endpoint you trust, install with Allow so each fire calls it at once.
- If CodeHerder was down at the scheduled time, the run fires once when it comes back. It does not replay each missed time.
ch plugin show <installId> prints one schedule line for each scheduled hook. It shows the expression, the timezone and the next run. The web app does not show schedules.
States
The State column shows one of four states.
| State | What it means |
|---|---|
| Active | The plugin is approved and works. |
| Disabled | An admin turned it off. Nothing from this plugin runs. |
| Needs approval | A plugin source moved to a commit that changes what the plugin asks for. The plugin is off until you approve again. |
| Source removed | The plugin source was deleted, or its pinned commit no longer holds a manifest. See below. |
To approve a plugin in Needs approval, open its page, review the actions and press Approve actions. From the CLI, run ch plugin approve <installId> --actions task.create,repo.add. CodeHerder drops an approval for an action the plugin no longer asks for.
A new commit that changes only the plugin’s own description or the settings it accepts does not need a new approval. A change to any action, to the CodeHerder actions it asks for, or to its connection does.
To fix a plugin in Source removed:
- If the commit no longer holds a manifest, move the source’s pin to a commit that holds one. The plugin then moves to Needs approval. Approve it again. Plugin sources explains Update pin.
- If the plugin source was deleted, the install cannot get it back. Adding the same source again makes a new source. Uninstall the plugin first, because a workspace holds one install of each plugin. Then add the plugin source again if you need it, and install the plugin from Plugin catalog.
To turn a plugin off and on, use the button in the plugin page’s header.
What agents get
A plugin action becomes a tool when you approved every CodeHerder action it calls. A stage agent in a workspace under the install can call it, on every harness. The tool takes the action’s input and returns its result. If the plugin needs a connection, the agent gets the tool only after you connect it.
The write policy applies to every call. Under Ask, a write files a question and the task waits for a person to answer. The plugin acts as its own agent, not as the agent that called it.
Runs and offers
A plugin can run an action when an event happens, or on a schedule. Onboarding task runs when a new workspace is created. HTTP endpoint runs on the event or schedule you choose. These runs are hooks.
Each hook run is recorded:
ch plugin runs
ch plugin runs --task <taskId>
The list shows the action, the outcome, the attempts and any error. A run that fails for a temporary reason retries a few times, then stops.
Under the Ask policy, a hook that wants to write does not run at once. CodeHerder stores an offer instead. An offer waits for a person.
In the web app, open the workspace dashboard. The Plugins section lists every pending offer in that workspace. A task’s own offers also show in the Plugins section of the task page. The section does not appear when there is nothing to show.
The dashboard shows the offers of that workspace only. It does not show the offers of a group above it. A group has no dashboard, so use the CLI with --workspace <group> for a group’s offers.
Each offer has a form with the action’s input. Change the input if you need to, then press Approve offer to run the action now. Press Skip offer and the action never runs. If you may not decide an offer, you still see it. Its buttons are disabled and a line says why.
The Onboarding task offer belongs to the new workspace. It shows on that workspace’s dashboard.
From the CLI:
ch plugin offers --status pending
ch plugin approve-offer <offerId>
ch plugin skip-offer <offerId>
approve-offer runs the action now. You can pass --input '<json>' to change the input first. skip-offer means the action never runs. An offer expires after 7 days, and an expired offer never runs. By default only an admin can approve or skip an offer. You must be signed in as a person.
With the default policy, Onboarding task offers the first task and waits for you. Install it with Allow to create the task at once.
What a plugin can add to the app
A plugin from a plugin source can also add parts to the web app. The two built-in plugins add none. A plugin can add:
- a Plugins section on the task page, and items in the task’s More menu. An item opens a form or a link.
- cards on the workspace dashboard. A card shows a link, some text or the status of the plugin’s last run.
- a page for the plugin’s own settings. Open the plugin from Settings → Plugins and press Open the plugin’s page.
- extra fields on the new-workspace form. The plugin uses what you enter when it runs on a new workspace.
A form runs an action, so it needs a person with the right role. That role is admin unless the plugin sets another. Anyone else sees the form disabled, with the reason.
Test an action
Run one action by hand to check your setup:
ch plugin run <installId> <actionId> --input '{"title":"Try it"}'
You need to be a human admin. The run goes through the same checks as an agent’s call and prints the outcome with links to what it made. --target <workspaceId> runs it in a workspace below the install.
Uninstall
Open the plugin’s page and press Uninstall plugin, or run:
ch plugin uninstall <installId> --yes
CodeHerder removes the install and archives the plugin’s agent. Past runs stay in the history. The connection stays. Delete it in Admin → Integrations if you no longer need it.
Related guides
- Plugin sources — sync a team’s plugin at a pinned commit.
- Integrations — where a plugin’s connection lives.
- Asking a human — how a question reaches a person and how they answer.
- Managing workspaces — how a group’s installs reach its workspaces.
Last updated