Mastodon Post plugin

Woodpecker plugin to post statuses to Mastodon.

Usage

image: woodpeckerci/plugin-mastodon-post
settings:
  server_url: https://mastodon.social
  access_token:
    from_secret: your_access_token
  status: We just released {{ CI_COMMIT_TAG }} 🚀

Settings

Settings Name	Default	Description
server_url	none	Required. Mastodon server url, including protocol.
access_token	none	Required. Mastodon access token. (How to get Token)
status	none	Required (if ai_token is not set). Status message (Allows Templating)
sensitive	false	Mark post as sensitive (true or false)
files	none	,-separated paths or globs of images, videos or audio files, see Media
media	none	{ path, alt, focus, thumbnail } list, instead of files, see Media
in_reply_to_id	none	ID of post to reply to
spoiler_text	none	Spoiler text
visibility	null	Visibility (private, unlisted, public or direct)
language	none	Status language
ai_token	none	Required (if status is not set). Provide an AI token (OpenAI) to generate a status message
ai_model	gpt-5-nano	Select the model used to generate a status message
ai_url	OpenAI	Base URL of an OpenAI compatible API, e.g. Ollama
ai_prompt	prompt	Prompt used to generate a status message. (Allows Templating)
changelog_file	CHANGELOG.md	File to use for the AI to make a changelog from.

Get Access Token

In order to get an access token, open your Settings and go to the Development section. There create a new application and make sure that write:statuses is checked (Also requires write:media when using the files or media setting).
After creating your application, copy the text next to Your access token and use that as your access_token value.

Media

files attaches images, videos or audio files. Entries can be paths or globs like dist/*.png, and the path of each file is used as its alt text.

settings:
  files:
    - dist/screenshot.png
    - docs/release/*.png

To set your own alt texts, use media instead of files. Each entry needs a path, globs are not supported. The alt text allows Templating, and without it the path is used. Set alt: "" for purely decorative images.

• focus sets the focal point of an image as x,y, each from -1 to 1: 0,0 is the center, -1,1 the top left corner. Apps keep it visible when they crop the preview.
• thumbnail sets a custom preview image for a video or audio file, such as a poster frame or cover art.

settings:
  media:
    - path: dist/screenshot.png
      alt: The new dashboard, released in {{ CI_COMMIT_TAG }}
      focus: 0,0.8
    - path: dist/logo.png
      alt: ''

settings:
  media:
    - path: dist/demo.mp4
      alt: A 30 second tour of the new dashboard
      thumbnail: dist/demo-poster.png

A status can have up to 4 images, or one video or audio file. By default Mastodon accepts JPEG, PNG, GIF and WebP images (HEIC, HEIF and AVIF on some servers) of up to 16 MiB, and MP4, WebM, MOV or Ogg videos and MP3, Ogg, WAV, FLAC, AAC or M4A audio files of up to 99 MiB. The plugin reads the actual limits of your server and checks every file before anything is posted, reporting all problems at once. Set sensitive: true or a spoiler_text to hide the media behind a warning.

Files are uploaded before the status is posted. Mastodon processes videos and audio after the upload, and the plugin waits up to 5 minutes for that to finish. If an upload or the status fails, the files uploaded so far are deleted again.

Templating

You can use {{ CI_COMMIT_TAG }} and other environment variables in the status and ai_prompt settings and in alt texts of media. The ai_prompt template can also use {{ CHANGELOG }} to include the changelog of the release. The access_token and ai_token values are never available as placeholders, and AI generated text is posted as is.

Self-hosted models

Any server with an OpenAI compatible chat/completions endpoint works, for example Ollama. ai_token still enables the AI and is sent as bearer token; a local Ollama ignores it, so any value will do.

image: woodpeckerci/plugin-mastodon-post
settings:
  server_url: https://mastodon.social
  access_token:
    from_secret: your_access_token
  ai_url: http://ollama:11434/v1
  ai_token: unused
  ai_model: llama3.2

Default AI prompt

Used when ai_prompt is not set. Copy of the prompt defined in src/utils.ts:

We want to announce the next version of our app on Mastodon.
Write a catchy post, so users will know why they should update to the newest
version. If there is no special feature included, just summarize the changes
in a few sentences. Reply with the post text only, at most 500 characters long.

The changelog entry: {{ changelog }}