Guides · 4 of 6
Invoke a definition file
One command lowers the definition, asks once whether to connect, and invokes; the configuration file is never written.
Invoke a definition file
A connectors-definition/1 file names a vendored API document, the auth profiles that
authenticate against it and the operations it exposes. connectors invoke --definition <file> <operation> runs one of those operations with no configured instance:
it lowers the file, connects the first time after one question, and invokes through the same
owner, admission, approval and audit as a configured instance. Run the commands from the
repository root after cargo build --locked -p connectors -p connectors-build -p connectors-catalog-provider.
Lay out a definitions tree
A definitions tree holds connectors/<name>.yaml, the shared auth files under auth/ and the
vendored sources under upstream/. connectors-build definition import writes one from a
shipped selection; here the GitLab one, pointed at a self-hosted GitLab:
target/debug/connectors-build definition import --catalog gitlab --definitions target/try/defs
sed -i 's/default: gitlab.com}/default: gitlab.example.com}/' target/try/defs/connectors/gitlab.yaml
target/try/defs/connectors/gitlab.yaml
target/try/defs/upstream/gitlab/openapi_v3.yaml.gz
target/try/defs/upstream/gitlab/openapi_v3.amendments.json
target/try/defs/upstream/gitlab/LICENSE
target/try/defs/upstream/gitlab/README.md
Every variable of the definition's base_url needs a default: the instance talks to the
endpoint the definition states, and trusts the platform's roots. --definitions-root <dir>
names the tree when the file is not in its connectors/ directory.
Invoke
A configuration and a state directory, here a private pair under target/try; the
configuration configures no instance:
mkdir -m 700 target/try/cli
target/debug/connectors --config "$PWD/target/try/cli/config.toml" \
--state-dir "$PWD/target/try/cli/state" setup init | jq -r .disposition
created
On a terminal, invoke --definition target/try/defs/connectors/gitlab.yaml project.get --input-json '{"id":"group/project"}' with those two globals lowers the
file, finds that its instance holds no connection, and asks once, naming the endpoint the
credential is validated at,
No connection for gitlab/definition. Connect now to https://gitlab.example.com/api/v4/? [y/N].
An OAuth profile whose token endpoint is on another host names that host too, (tokens from https://<host>). Read the endpoint before you answer: the credential you type goes there.
Answered y, it runs the profile's
own acquisition, exactly as connections connect does: the token prompt, GitLab personal access token: with the input hidden, or, for an OAuth profile, the consent with the client file
--credential-file names. The provider validates the credential, the connection is saved, and
the operation runs. Every later run with the same file asks nothing, and neither does a run after
a change limited to the operations: the connection is bound to the provider and the profile, not
to the operation list. --schema and --revision may be left out; they are the description's.
The instance is the connector's instance definition: --connector gitlab --instance definition selects it in every other command, and results name it so. A file moved to another
host becomes another instance (below).
Reuse a stored credential
When another instance of the same connector already holds a connection, for example a configured
[connectors.gitlab.instances.selfhosted] at the same self-hosted GitLab, the one question lists
it instead: its number, gitlab/selfhosted, its API base and the account it validated as, never
the token. The question ends [1/c/N]. Answered 1, the owner copies that connection's stored
credential to a new connection of the definition's instance, has the definition's provider
validate it, and saves it only when the provider answers the same account; the operation then runs
with no token prompt. c connects fresh as above; anything else, or no terminal, refuses as
above. A connection is offered only when it is ready, not stale or revoked, and bound to the same
API base and the same auth profile; an OAuth profile whose refresh rotates is never copied,
and a definition whose profile names a token endpoint is offered nothing. When
the provider answers another account, nothing is saved, the configured instance's connection is
left as it was, and the command offers to connect fresh. After a copy the two connections are
independent: revoking one leaves the other.
Without a terminal, as in a script or a CI job, nothing is asked and nothing is sent; setsid
runs the same command that way. The refusal names the step that clears it:
setsid -w target/debug/connectors --output json --config "$PWD/target/try/cli/config.toml" \
--state-dir "$PWD/target/try/cli/state" invoke \
--definition target/try/defs/connectors/gitlab.yaml project.get \
--input-json '{"id":"group/project"}'
{"error":{"code":"failure","data":{"code":"not_found","kind":"operational","next_action":"create_connection","stage":"admission"}},"ok":false}
connections connect --connector gitlab --instance definition --profile gitlab.pat connects it
without the question.
What it keeps
The lowered definition is cached under the state directory, in an owner-only directory named by
the digest of every file its lowering reads and the lowerer's release; a run with
unchanged inputs reuses it. The instance's entry is held in the owner-only file
definitions/instances.toml beside the cache:
ls target/try/cli/state/definitions
69e791a136bb2addfbf06c965b06e8fd3c335f5bb448cbd7e1eda97d7a2a342d
instances.toml
The configuration file is never written. If it already configures the connector's instance
definition, that instance is kept and the command is refused with configuration_rule
definition_instance_configured.
Move a definition to another host
A connection stays bound to the host and auth profile it was made for, so a file whose base_url
host or auth profile changes cannot use it, and no connect under the instance definition can
follow it. The file then becomes its own instance, definition- and 16 hexadecimal digits taken
from the connector, the host and the profile: the next run asks the one connect question naming
it and the new host, No connection for gitlab/definition-<16 hex digits>. Connect now to https://<new host>/api/v4/? [y/N], and connects
fresh. A credential stored for the old host is never offered for the new one. Every later
run of the file selects the same instance and asks nothing, and a file moved back to the old host
is the instance definition again, with its connection. The connection left at the old host is
kept, unused, and connections revoke --connector gitlab --instance <the new instance> --connection <its reference> revokes it.
Forget a definition
At most 64 connector ids are held, and no command forgets one: revoke its connection with
connections revoke, then remove definitions/ from the state directory while no owner runs. The
full rules are in the CLI contract.