org_campaigns

Creates, updates, deletes, gets or lists an org_campaigns resource.

Overview

Name	org_campaigns
Type	Resource
Id	github.campaigns.org_campaigns

Fields

The following fields are returned by SELECT queries:

get_campaign_summary

Response

Name	Datatype	Description
name	string	The campaign name
alert_stats	object
closed_at	string (date-time)	The date and time the campaign was closed, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ. Will be null if the campaign is still open.
contact_link	string (uri)	The contact link of the campaign.
created_at	string (date-time)	The date and time the campaign was created, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
description	string	The campaign description
ends_at	string (date-time)	The date and time the campaign has ended, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
managers	array	The campaign managers
number	integer	The number of the newly created campaign
published_at	string (date-time)	The date and time the campaign was published, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
state	string	Indicates whether a campaign is open or closed (open, closed) (title: Campaign state)
team_managers	array	The campaign team managers
updated_at	string (date-time)	The date and time the campaign was last updated, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.

list_org_campaigns

Response

Name	Datatype	Description
name	string	The campaign name
alert_stats	object
closed_at	string (date-time)	The date and time the campaign was closed, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ. Will be null if the campaign is still open.
contact_link	string (uri)	The contact link of the campaign.
created_at	string (date-time)	The date and time the campaign was created, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
description	string	The campaign description
ends_at	string (date-time)	The date and time the campaign has ended, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
managers	array	The campaign managers
number	integer	The number of the newly created campaign
published_at	string (date-time)	The date and time the campaign was published, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.
state	string	Indicates whether a campaign is open or closed (open, closed) (title: Campaign state)
team_managers	array	The campaign team managers
updated_at	string (date-time)	The date and time the campaign was last updated, in ISO 8601 format':' YYYY-MM-DDTHH:MM:SSZ.

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_campaign_summary	select	org, campaign_number		Gets a campaign for an organization. The authenticated user must be an owner or security manager for the organization to use this endpoint. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.
list_org_campaigns	select	org	page, per_page, direction, state, sort	Lists campaigns in an organization. The authenticated user must be an owner or security manager for the organization to use this endpoint. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.
create_campaign	insert	org, name, description, ends_at, code_scanning_alerts, secret_scanning_alerts		Create a campaign for an organization. The authenticated user must be an owner or security manager for the organization to use this endpoint. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint. Fine-grained tokens must have the "Code scanning alerts" repository permissions (read) on all repositories included in the campaign.
update_campaign	update	org, campaign_number		Updates a campaign in an organization. The authenticated user must be an owner or security manager for the organization to use this endpoint. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.
delete_campaign	delete	org, campaign_number		Deletes a campaign in an organization. The authenticated user must be an owner or security manager for the organization to use this endpoint. OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
campaign_number	integer	The campaign number.
org	string	The organization name. The name is not case sensitive.
direction	string	The direction to sort the results by.
page	integer	The page number of the results to fetch. For more information, see "Using pagination in the REST API."
per_page	integer	The number of results per page (max 100). For more information, see "Using pagination in the REST API."
sort	string	The property by which to sort the results.
state	string	If specified, only campaigns with this state will be returned.

SELECT examples

get_campaign_summary

Gets a campaign for an organization.

The authenticated user must be an owner or security manager for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.

SELECT
name,
alert_stats,
closed_at,
contact_link,
created_at,
description,
ends_at,
managers,
number,
published_at,
state,
team_managers,
updated_at
FROM github.campaigns.org_campaigns
WHERE org = '{{ org }}' -- required
AND campaign_number = '{{ campaign_number }}' -- required
;

list_org_campaigns

Lists campaigns in an organization.

The authenticated user must be an owner or security manager for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.

SELECT
name,
alert_stats,
closed_at,
contact_link,
created_at,
description,
ends_at,
managers,
number,
published_at,
state,
team_managers,
updated_at
FROM github.campaigns.org_campaigns
WHERE org = '{{ org }}' -- required
AND page = '{{ page }}'
AND per_page = '{{ per_page }}'
AND direction = '{{ direction }}'
AND state = '{{ state }}'
AND sort = '{{ sort }}'
;

INSERT examples

create_campaign

Create a campaign for an organization.

The authenticated user must be an owner or security manager for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.

Fine-grained tokens must have the "Code scanning alerts" repository permissions (read) on all repositories included
in the campaign.

INSERT INTO github.campaigns.org_campaigns (
name,
description,
managers,
team_managers,
ends_at,
contact_link,
code_scanning_alerts,
generate_issues,
org
)
SELECT 
'{{ name }}' /* required */,
'{{ description }}' /* required */,
'{{ managers }}',
'{{ team_managers }}',
'{{ ends_at }}' /* required */,
'{{ contact_link }}',
'{{ code_scanning_alerts }}' /* required */,
{{ generate_issues }},
'{{ org }}'
RETURNING
name,
alert_stats,
closed_at,
contact_link,
created_at,
description,
ends_at,
managers,
number,
published_at,
state,
team_managers,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: org_campaigns
props:
  - name: org
    value: "{{ org }}"
    description: Required parameter for the org_campaigns resource.
  - name: name
    value: "{{ name }}"
    description: |
      The name of the campaign
  - name: description
    value: "{{ description }}"
    description: |
      A description for the campaign
  - name: managers
    value:
      - "{{ managers }}"
    description: |
      The logins of the users to set as the campaign managers. At this time, only a single manager can be supplied.
  - name: team_managers
    value:
      - "{{ team_managers }}"
    description: |
      The slugs of the teams to set as the campaign managers.
  - name: ends_at
    value: "{{ ends_at }}"
    description: |
      The end date and time of the campaign. The date must be in the future.
  - name: contact_link
    value: "{{ contact_link }}"
    description: |
      The contact link of the campaign. Must be a URI.
  - name: code_scanning_alerts
    description: |
      The code scanning alerts to include in this campaign
    value:
      - repository_id: {{ repository_id }}
        alert_numbers: "{{ alert_numbers }}"
  - name: generate_issues
    value: {{ generate_issues }}
    description: |
      If true, will automatically generate issues for the campaign. The default is false.
    default: false

UPDATE examples

update_campaign

Updates a campaign in an organization.

The authenticated user must be an owner or security manager for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.

UPDATE github.campaigns.org_campaigns
SET 
name = '{{ name }}',
description = '{{ description }}',
managers = '{{ managers }}',
team_managers = '{{ team_managers }}',
ends_at = '{{ ends_at }}',
contact_link = '{{ contact_link }}',
state = '{{ state }}'
WHERE 
org = '{{ org }}' --required
AND campaign_number = '{{ campaign_number }}' --required
RETURNING
name,
alert_stats,
closed_at,
contact_link,
created_at,
description,
ends_at,
managers,
number,
published_at,
state,
team_managers,
updated_at;

DELETE examples

delete_campaign

Deletes a campaign in an organization.

The authenticated user must be an owner or security manager for the organization to use this endpoint.

OAuth app tokens and personal access tokens (classic) need the security_events scope to use this endpoint.

DELETE FROM github.campaigns.org_campaigns
WHERE org = '{{ org }}' --required
AND campaign_number = '{{ campaign_number }}' --required
;