info:To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
1. TEMPORARY: Accommodate the current migration to [rename "services" to "integrations"](#rename-services-to-integrations):
- Add the integration's camel-cased name (`'FooBar'`) to `Gitlab::Integrations::StiType::NAMESPACED_INTEGRATIONS`.
### Define properties
Integrations can define arbitrary properties to store their configuration with the class method `Integration.prop_accessor`.
The values are stored as a serialized JSON hash in the `integrations.properties` column.
For example:
```ruby
moduleIntegrations
classFooBar<Integration
prop_accessor:url
prop_accessor:tags
end
end
```
`Integration.prop_accessor` installs accessor methods on the class. Here we would have `#url`, `#url=` and `#url_changed?`, to manage the `url` field. Fields stored in `Integration#properties` should be accessed by these accessors directly on the model, just like other ActiveRecord attributes.
You should always access the properties through their getters, and not interact with the `properties` hash directly.
You **must not** write to the `properties` hash, you **must** use the generated setter method instead. Direct writes to this
hash are not persisted.
You should also define validations for all your properties.
Also refer to the section [Customize the frontend form](#customize-the-frontend-form) below to see how these properties
are exposed in the frontend form for the integration.
There is an alternative approach using `Integration.data_field`, which you may see in other integrations.
With data fields the values are stored in a separate table per integration. At the moment we don't recommend using this for new integrations.
### Define trigger events
Integrations are triggered by calling their `#execute` method in response to events in GitLab,
which gets passed a payload hash with details about the event.
The supported events have some overlap with [webhook events](../../user/project/integrations/webhook_events.md),
and receive the same payload. You can specify the events you're interested in by overriding
the class method `Integration.supported_events` in your model.
The following events are supported for integrations:
| [Merge request event](../../user/project/integrations/webhook_events.md#merge-request-events) | ✓ | `merge_request` | A merge request is created, updated, or merged.
| [Comment event](../../user/project/integrations/webhook_events.md#comment-events) | | `comment` | A new comment is added.
| [Confidential comment event](../../user/project/integrations/webhook_events.md#comment-events) | | `confidential_note` | A new comment on a confidential issue is added.
| [Pipeline event](../../user/project/integrations/webhook_events.md#pipeline-events) | | `pipeline` | A pipeline status changes.
| [Push event](../../user/project/integrations/webhook_events.md#push-events) | ✓ | `push` | A push is made to the repository.
| [Tag push event](../../user/project/integrations/webhook_events.md#tag-events) | ✓ | `tag_push` | New tags are pushed to the repository.
| Vulnerability event **(ULTIMATE)** | | `vulnerability` | A new, unique vulnerability is recorded.
| [Wiki page event](../../user/project/integrations/webhook_events.md#wiki-page-events) | ✓ | `wiki_page` | A wiki page is created or updated.
#### Event examples
This example defines an integration that responds to `commit` and `merge_request` events:
```ruby
moduleIntegrations
classFooBar<Integration
defself.supported_events
%w[commit merge_request]
end
end
end
```
An integration can also not respond to events, and implement custom functionality some other way:
```ruby
moduleIntegrations
classFooBar<Integration
defself.supported_events
[]
end
end
end
```
### Customize the frontend form
The frontend form is generated dynamically based on metadata defined in the model.
By default, the integration form provides:
- A checkbox to enable or disable the integration.
- Checkboxes for each of the trigger events returned from `Integration#configurable_events`.
You can also add help text at the top of the form by either overriding `Integration#help`,
or providing a template in `app/views/projects/services/$INTEGRATION_NAME/_help.html.haml`.
To add your custom properties to the form, you can define the metadata for them in `Integration#fields`.
This method should return an array of hashes for each field, where the keys can be:
