Promote content from a pipeline

A deployment key promotes content along one edge of your environment graph, such as Staging to Production, and does nothing else. Use it when a release pipeline, not a person, should move a reviewed change from one authoring environment to the next.

A deployment key is separate from a management key. A management key reads and writes one environment and can never promote. A deployment key can’t read or write content at all: it plans and runs a promotion along the one edge it was made for.

Deployment keys need the Pro plan or above.

What a key is bound to

When you create a key in Content, under API Keys on the Deployment tab, you choose:

• An edge. A source environment and a target environment that your organization has already connected for promotion. The key is fixed to that edge. It can’t promote along any other edge, in either direction, and a request can’t name a different source or target.
• A role. The key acts as that role, checked against the source environment: the same folder permissions and the same limits a person with that role gets when they promote. Pick the least powerful role that can do the job.
• Scopes. content.deployment.plan shows what a promotion would do and changes nothing, so it is safe for a pull request check. content.deployment.execute carries a promotion out.
• Whether it may overwrite edits made in the target. Off unless you turn it on. See Overwriting.

If the edge is later removed from your environment graph, the key keeps authenticating and every promotion answers not_a_promotion_target. Add the edge back and the key works again.

Check the key

whoami works with any valid deployment key and reports the edge, the role and the scopes it holds.

curl https://api.ebitex.io/content/deployment/v1/whoami \
  -H "Authorization: Bearer $EBITEX_DEPLOYMENT_KEY"

edge.active is false when the edge has been removed.

Plan a promotion

Name the item to promote by kind and id. The kinds are component, node, contract, template, adapter and stream.

curl -X POST https://api.ebitex.io/content/deployment/v1/promotions/plan \
  -H "Authorization: Bearer $EBITEX_DEPLOYMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "node", "id": "5d1c0b6e-0e0c-4c57-9b1a-0f6f1b7a2c11" }'

The response lists every item the promotion would carry. Each has a state:

State	Meaning
new	The target has no copy.
update	The target copy is as the last promotion left it.
diverged	The target copy has changed since the last promotion, or was never promoted.

Dependencies such as the item’s contract and template come along automatically and are marked implicit. A non-empty blockers list means the promotion can’t run until they’re resolved.

Execute it

Send the same root and the explicit items you want written.

curl -X POST https://api.ebitex.io/content/deployment/v1/promotions/execute \
  -H "Authorization: Bearer $EBITEX_DEPLOYMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "root": { "kind": "node", "id": "5d1c0b6e-0e0c-4c57-9b1a-0f6f1b7a2c11" },
        "items": [ { "kind": "node", "id": "5d1c0b6e-0e0c-4c57-9b1a-0f6f1b7a2c11" } ]
      }'

The server plans again itself and never trusts an earlier plan, so a change between planning and executing is caught. Promotion copies drafts into the target environment. It doesn’t publish anything there. Publishing is a separate step, with a management key.

Each execute counts against your organization’s daily write allowance. Planning is never counted.

Overwriting changes made in the target

If someone edited a promoted item in the target environment, the plan marks it diverged and promoting would replace their edit. A deployment key does that only when both of these are true:

1. The key was created with Allow overwriting changes made in the target turned on.
2. The request confirms that item, with "confirmOverwrite": true on its entry in items.

Otherwise the request is refused with promotion_conflict, the body lists the items, and nothing is written. A pipeline that should never replace edits made in the target needs nothing extra: keys are created without the permission.

Errors

Status	Error	Meaning
400	not_a_promotion_target	The key’s edge is no longer in your environment graph.
400	promotion_root_required	The request has no root.
401	invalid_api_key	The key is unknown, revoked, expired, or its role was deleted.
403	scope_denied	The key doesn’t hold the scope this call needs.
403	permission_denied	The role can’t promote this item from the source environment.
409	promotion_conflict	A diverged item wasn’t both allowed and confirmed. Nothing was written.
422	promotion_blocked	The plan has blockers. They’re listed in the response.

The full request and response shapes are in the API reference.

Good practice

• Use one key per edge. A pipeline that promotes Development to Staging and then Staging to Production holds two keys, each separately revocable.
• Give a pull request check a key with only the plan scope.
• Restrict a key to your build server’s address range when it has a fixed one.
• Create a replacement before a key expires, then revoke the old one. A key can’t be extended.