Transform Complex Workflows into Simple Forms

What Is a Self-Service Workflow?

GitHub allows you to configure automated GitHub Actions Workflows executions on certain events, such as when you create a Pull Request. However, some automations must be executed "on-demand," basically when a user needs to run it. GitHub provides a workflow trigger called workflow_dispatch to accomplish this. You can execute these workflows whenever you like, but there are a few caveats that makes them difficult to use.

To improve this capability, CodeCargo provides Self-Service Workflows - this allows you to execute your GitHub Actions Reusable Workflows on-demand using a simple form. This section shows how this feature works in detail.

How It Works

CodeCargo's Self-Service Workflows are built on top of GitHub Actions Reusable Workflows and workflow_dispatch events:

To create a Self-Service Workflow:

1. Define a GitHub Actions Reusable Workflow in one of your GitHub repositories
2. Import that workflow as a Buildling Block
3. Create a Self-Service Workflow in a project

After you complete those steps, CodeCargo will create a New GitHub workflow...

• that is triggered by the workflow_dispatch event,
• stored on an orphan branch named codecargo.com/self-service,
• in the Project Repository specified in the Self-Service Workflow configuration,
• and executes the most recent version of the underlying GitHub Actions Reusable Workflow defined by the target ref

Creating a Self-Service Workflow Deep Dive

Self-Service Workflows are created in the CodeCargo UI within the Project scope. Each Self-Service Workflow is directly tied to a GitHub Actions Reusable Workflow imported as a building Block. Self-Service Workflows call the system-generated workflows using the workflow_dispatch event in your Project Repository with the inputs provided by the user.

Prerequisites

• A GitHub repository that the CodeCargo app has access to
• An existing GitHub Actions Reusable Workflow
• Appropriate permissions for the target repository

Step #1 Select a Workflow (Basic Details)

If your user permissions allow, click the + Create a Self-Service Workflow button in your project. Then pick a GitHub Actions Reusable Workflow from the Buildling Blocks and specify the target reg (branch, commit, tag).

Note: every time a user runs this Self-Service Workflow, it will call the GitHub Actions Reusable Workflow defined on the most recent version of this ref. CodeCargo recommends that you select the ref on your default branch or your production deployment branch depending on what the underlying workflow does.

After you select a workflow and ref, CodeCargo will automatically populate the name and description fields if they are present in the underlying workflow's YAML file. You can update these values. Then select an icon for your workflow.

Step #2 Workflow Configuration (Repository)

CodeCargo uses GitHub's workflow dispatch API to trigger the workflow. The permission model (read/write, secrets access) is inherited from the selected repo and ref.

Project Repository

Select a GitHub Repository for the Self-Service Workflow. This must be a GitHub Repository that is a member of the Project. CodeCargo will create a new workflow triggered by the workflow_dispatch event in this repository and save it to the codecargo.com/self-service branch. If your workflow requires any files to execute, make sure that the Project Repository contains those files.

Every time a user executes the Self-Service Workflow in the UI, our platform will call the workflow in the codeargo.com/self-service branch (workflow_dispatch event) which will then call the most recent version of the GitHub Actions Reusable Workflow you selected in the previous step.

Run in Environment

Optionally elect to have the Self-Service Workflow execute using a GitHub Environment. The GitHub Repository defined in the previous step must have access to the environment.

Checkout Code

By default, the filesystem that your Self-Service Workflow has access to will be empty. If your underlying GitHub Actions Reusable Workflow requires specific files (e.g., your workflow requires a Helm chart), you can provide that by selecting this option. When you select this option, CodeCargo will set the base filesystem for your Self-Service Workflow to be a specified branch from the Project Repository.

If you select this option, a new input called checkout-ref will be added to the list of inputs in step 3 (Define Inputs). You will specify which branch to pull the files from.

Step #3 Define Inputs (Configure)

Specify the input parameters for your Self-Service Workflow. In particular, CodeCargo reads the underlying GitHub Actions Reusable Workflow file to populate this list of inputs. If you selected Checkout Code in the previous step, you will also see an input for checkout-ref. CodeCargo lets you customize these inputs to make it easier for your users to run the workflow, and also to provide security and compliance guardrails to ensure that the workflow executions meet company standards.

Input Configuration Options

Every input has a Value Type:

• User Input – Creates an interactive form field for the user (raw input or selection)
• Fixed Value – Hardcoded for consistency, invisible to the user
• Expression – Dynamically computed at runtime (e.g. ${repo.default_branch})

Supported Input Types

For each input, CodeCargo will inherit the type as defined in the GitHub Actions Reusable Workflow source code file. You cannot change these types in the UI. If you want to change the input types, you must do so in source code.

Required

• if an input is marked marked as required in the GitHub Actions Reusable Workflow YAML file, a value for this input must be provided in the UI form
• if not marked as required in the YAML file
  • you can optionally mark it was required to force the user to provide a value
  • you can leave it alone and the user does not need to fill it out

Has Default Value?

If checked, the default value is automatically used in the input form and provided via the workflow_dispatch event. The GitHub Actions Reusable Workflow file may provide a default value. You can override this in the UI.

Restrict Choices?

If checked, change the user input from a basic textbox into a dropdown with a limited set of options. Optionally, you can add a label to each choice. If you add a label, the user will see the value of the label instead of the choice. This is useful because your users might recognize prod-aws-region over useast1

Fixed Value Inputs

If you set an input's Value Type as Fixed Value, it is your job to specify a value for the input. The user will not be able to enter any value(s) or even see that this input exists. This is useful if you want to specify inputs that you do not want your users to see/edit.

If you set Value Type as Fixed Value, the UI will gray out the variable in the center of the screen and push it to the bottom of the form.

Example YAML Workflow

Here is an example of a system-generated workflow with workflow_dispatch enabled:

run-name: ${{ fromJSON(inputs.boxbuild || '{}').runName || '' }}
jobs:
  setup:
    name: Setup
    if: ${{ github.event_name != 'push' }}
    runs-on: ubuntu-latest
    outputs:
      checkout-ref: ${{ toJSON(env.CHECKOUT_REF) }}
      playbook_name: ${{ toJSON(env.PLAYBOOK_NAME) }}
    env:
      CHECKOUT_REF: ${{ inputs.checkout-ref }}
      PLAYBOOK_NAME: ${{ inputs.playbook_name }}
    steps:
      - name: Setup
        run: echo 'Setup'
  run:
    name: Run
    permissions:
      contents: read
      packages: read
    needs: [setup]
    if: ${{ github.event_name != 'push' }}
    uses: codecargo-demo/iac-catalog/.github/workflows/ansible-playbook-run.yml@main
    with:
      playbook_name: ${{ fromJSON(needs.setup.outputs.playbook_name) }}
name: Run Ansible Playbook
on:
  push:
    branches:
      - codecargo.com/self-service
    paths:
      - .github/workflows/run-ansible-playbook-30XTrYuKmXDo9j2Iyy7Q9.yml
  workflow_dispatch:
    inputs:
      boxbuild:
        description: Optional BoxBuild JSON metadata
        required: false
        default: '{}'
      checkout-ref:
        required: true
        type: string
      playbook_name:
        required: true
        type: string

All user inputs are sanitized and injected securely into the with: block of the workflow call.

Best Practices

Workflow Design

Do:

• Keep workflows focused on a single purpose
• Use descriptive names and help text
• Provide sensible defaults
• Include dry-run options for safety

Don't:

• Create overly complex mega-workflows
• Hardcode environment-specific values
• Skip input validation
• Ignore error handling

Input Design

Do:

• Use appropriate input types (choice vs. string)
• Provide clear validation messages
• Group related inputs together
• Use conditional visibility to simplify forms

Don't:

• Ask for inputs that could be computed
• Use technical jargon in labels
• Create forms with too many required fields

Security Considerations

Do:

• Use GitHub environments for production workflows
• Implement approval gates for sensitive operations
• Audit workflow executions regularly
• Follow principle of least privilege

Don't:

• Store secrets in workflow inputs
• Allow unrestricted access to production workflows
• Skip validation on user inputs
• Ignore GitHub's branch protection rules

Start Building