# On artifact event

Artifact event triggers run a pipeline when an artifact version is created, published, or deleted. Filter by artifact, ID pattern, and scope to react only to the releases you care about.

Artifact event triggers let you run a pipeline when something happens to an [artifact](/docs/api/artifacts.md) version in your workspace. Buddy starts all pipelines whose trigger matches the artifact - for example, deploy a container image as soon as its version is published, or clean up when a version is deleted.

There are three artifact event types:

- **Artifacts: Created** - triggered when a new artifact version is created, before it is published.
- **Artifacts: Published** - triggered when an artifact version is published and becomes available for download.
- **Artifacts: Deleted** - triggered when an artifact version is deleted.

## Configure trigger

1. Open your pipeline and go to the **Workflow** tab.
2. Click **+** in the **Triggers** section and select **Created**, **Published**, or **Deleted** in the **Artifacts** group.

   ![Artifacts group in the trigger dropdown](/docs/pipelines/triggering-pipelines/triggering-pipelines-artifacts-dropdown.png 640x485)

3. Pick the artifacts that should start the pipeline, or tick **All artifacts**.
4. Click **Apply**.

The trigger appears in the **Triggers** section with the selected artifacts and matching filters:

![Artifact and environment triggers in the pipeline workflow](/docs/pipelines/triggering-pipelines/triggering-pipelines-artifacts-environments-triggers.png 640x408)

## Filters

The trigger fires when the artifact version matches at least one of the entries in the popup.

![Artifact trigger popup with the list of artifacts](/docs/pipelines/triggering-pipelines/triggering-pipelines-artifacts-filters.png 640x454)

- **Artifacts** - existing artifact versions listed as `name:version`. Use the filter box to narrow the list and tick the versions that should start the pipeline.
- **All artifacts** - reacts to every artifact version in the workspace. In YAML this is stored as `'*'`.
- **Add or manage matching filters** - opens a modal where you define patterns instead of picking specific versions:
  - **ID** - an artifact identifier pattern in the `name:version` format with wildcards, e.g. `pdf-invoicer:v*` matches every version of `pdf-invoicer` starting with `v`.
  - **Scope** - where the artifact lives: **Any**, **Workspace**, **Project**, or **Environment**.

  ![Matching filters for the artifact trigger](/docs/pipelines/triggering-pipelines/triggering-pipelines-artifacts-matching.png 640x413)

Specific artifacts, **All artifacts**, and matching filters can be combined in a single trigger. Each artifact event type (Created, Published, Deleted) is a separate trigger with its own filters.

## YAML

The event types are `CREATE_ARTIFACT_VERSION`, `PUBLISH_ARTIFACT_VERSION`, and `DELETE_ARTIFACT_VERSION`. The `artifacts` list accepts `'*'` for all artifacts, specific `name:version` identifiers, and objects with `identifier` and `scope`:

```yaml
- pipeline: "Release notification"
  refs:
    - "refs/heads/master"
  events:
    - type: "PUBLISH_ARTIFACT_VERSION"
      artifacts:
        - "*"
        - identifier: "pdf-invoicer:v*"
          scope: "PROJECT"
  actions:
    - action: "Announce release"
      type: "BUILD"
      docker_image_name: "library/ubuntu"
      docker_image_tag: "22.04"
      commands: |-
        echo "New release of pdf-invoicer is ready"
```

`scope` takes `ANY`, `WORKSPACE`, `PROJECT`, or `ENVIRONMENT`. This pipeline removes a deployed image whenever one of its versions is deleted from the workspace:

```yaml
- pipeline: "Clean up removed image"
  refs:
    - "*"
  events:
    - type: "DELETE_ARTIFACT_VERSION"
      artifacts:
        - identifier: "api-image:*"
          scope: "WORKSPACE"
  actions:
    - action: "Remove image from server"
      type: "SSH_COMMAND"
      target: "prod-server"
      commands:
        - "docker image prune -af"
```

<Hint type="warning">
The pipeline must be allowed to use the artifact that triggered it, otherwise the run fails at the setup step with **Pipeline not allowed to Use artifact**. Open the artifact's **Permissions** tab and add the pipeline with the **Use** role, or click **Grant permissions** in the failed run and retry it.
</Hint>

<Hint type="info">
Artifact versions are produced by pipeline actions that upload to the Buddy artifact registry, or created and published from the [REST API](/docs/api/artifacts.md) and the CLI. The trigger reacts to the artifact version, not to the pipeline that produced it.
</Hint>

## See also

- [Artifacts - REST API](/docs/api/artifacts.md)
- [On environment event](/docs/pipelines/introduction/triggering-pipelines/on-environment-event.md)
- [On sandbox event](/docs/pipelines/introduction/triggering-pipelines/on-sandbox-event.md)
- [Trigger pipeline action](/docs/pipelines/introduction/triggering-pipelines/trigger-pipeline-action.md)


---
Original source: https://buddy.works/docs/pipelines/introduction/triggering-pipelines/on-artifact-event