Asana deploy notifications – setup¶

What it does¶

When deploying to production (master), the workflow automatically finds Asana task URLs in PR descriptions for the commits included in the deploy, and:

1. Posts a comment on the task with the commit SHA and link
2. Sets the "Release Date" custom field to today's date
3. Marks the task as completed

Optionally, the PR description supports two additional sections:

• ## Asana settings – override the default complete_task behaviour per PR (see below)
• ## Asana comment on completion – append a custom message to the deploy comment posted on the task

Two-level setup: site projects vs. package repos¶

For projects where work flows through composer packages before landing in a site, the workflow supports a two-level approach:

Package repo – when a package is merged and released, the task gets a comment ("Package released – ready to deploy") but is left open. This signals the work is done at the package level, but not yet in production.

Site project – when the site is deployed (including the updated package), the task is completed and stamped with a release date.

This means a task accurately reflects its real state: ready but not live, then live. If a task only exists in a site project and has no package step, it is simply completed on deploy as normal.

Site project setup¶

1. Add ASANA_TOKEN as a secret in GitHub¶

Go to Settings → Secrets and variables → Actions in the project repo and add:

• Name: ASANA_TOKEN
• Value: An Asana Personal Access Token (generated under Asana → My Profile → Apps → Personal Access Tokens)

2. Add the PR template to the project repo¶

Copy .github/pull_request_template.md from this repo into the project repo. This makes the Asana task field appear automatically whenever someone opens a PR.

3. Call notify-asana in your deploy workflow¶

Manual deploy (workflow_dispatch):

name: Deploy Nuxt

on:
  workflow_dispatch:
    inputs:
      environment:
        description: "Deployment environment"
        required: true
        type: choice
        options:
          - development
          - master
      base_sha:
        description: "SHA to scan releases from (optional – leave empty for auto-mode)"
        required: false
        type: string
      skip_deploy:
        description: "Skip deploy and only run Asana notification (for testing)"
        required: false
        type: boolean
        default: false

permissions:
  contents: read
  pull-requests: read

jobs:
  deploy:
    if: ${{ !inputs.skip_deploy }}
    uses: subscribed-aps/workflows/.github/workflows/deploy-nuxt.yml@main
    with:
      environment: ${{ inputs.environment }}
    secrets: inherit

  notify-asana:
    needs: deploy
    if: always() && (needs.deploy.result == 'success' || needs.deploy.result == 'skipped')
    uses: subscribed-aps/workflows/.github/workflows/notify-asana.yml@main
    with:
      environment: ${{ inputs.environment }}
      base_sha: ${{ inputs.base_sha || github.event.before }}
    secrets:
      ASANA_TOKEN: ${{ secrets.ASANA_TOKEN }}

base_sha is optional – if left empty, automatic fallback is used (tag or 20 commits). Set skip_deploy: true to test the Asana notification without triggering a deploy.

Automatic deploy on push to master:

name: Deploy Nuxt

on:
  push:
    branches:
      - master

permissions:
  contents: read
  pull-requests: read

jobs:
  deploy:
    uses: subscribed-aps/workflows/.github/workflows/deploy-nuxt.yml@main
    with:
      environment: master
    secrets: inherit

  notify-asana:
    needs: deploy
    if: always() && needs.deploy.result == 'success'
    uses: subscribed-aps/workflows/.github/workflows/notify-asana.yml@main
    with:
      environment: master
      base_sha: ${{ github.event.before }}
    secrets:
      ASANA_TOKEN: ${{ secrets.ASANA_TOKEN }}

github.event.before is set automatically by GitHub and points to exactly the SHA that was on master before this push – no manual handling required.

Package repo setup¶

For composer packages and similar repos that are not deployed directly, call notify-asana on merge to main with complete_tasks: false. This posts a comment on the task without completing it – completion happens when the site that pulls in the package is deployed.

name: Notify Asana on release

on:
  push:
    branches:
      - main

permissions:
  contents: read
  pull-requests: read

jobs:
  notify-asana:
    uses: subscribed-aps/workflows/.github/workflows/notify-asana.yml@main
    with:
      environment: master
      base_sha: ${{ github.event.before }}
      complete_tasks: false
      comment: "📦 Package released – ready to deploy"
    secrets:
      ASANA_TOKEN: ${{ secrets.ASANA_TOKEN }}

The Asana task URL must be included in the PR description that merges the work into main. When the site repo later deploys with that package version, the same task will be completed there – as long as the Asana link also appears in the PR that updates the package in the site repo.

Optional parameters¶

Per-PR overrides¶

The PR description supports two optional sections that let individual PRs override the repo-level defaults.

complete_task¶

Controls whether the Asana task is marked as completed on deploy. Useful when a PR is a partial implementation and the task should stay open.

Add this to the PR description as plain text (not inside an HTML comment):

## Asana settings
complete_task: false

The repo-level complete_tasks input is the default. If a PR includes complete_task: true or complete_task: false, that value takes precedence for the tasks linked in that PR.

Asana comment on completion¶

Appends a custom message to the deploy notification posted on the task. Useful for giving Asana stakeholders context without requiring them to open GitHub.

## Asana comment on completion
This deploy includes the new checkout flow – let us know if you spot any issues.

The final comment in Asana will look like:

✅ Deployed to production – a1b2c3d (https://github.com/...)

This deploy includes the new checkout flow – let us know if you spot any issues.

Error handling¶

Errors against the Asana API (e.g. invalid task URL or missing permissions) do not stop the deploy – they are logged as warnings only. The deploy job has no dependency on the Asana call.