Self-Service Workflows

What Is a Self-Service Workflow?

Self-Service Workflows (SSWs) are CodeCargo automations that allow you to run GitHub Actions Workflows, defined in your GitHub Organization, from our UI. CodeCargo provides unique ways to discover, organize, and share these automations within your organization.

SSWs allow you to run GitHub Actions Workflows that are called by the workflow_dispatch event trigger using the CodeCargo UI. These workflows are stored as code in your GitHub organization. You can create these workflows by yourself, or with the help of GenAI coding agents including CodeCargo's Expert Workflow Agent.

Developers don't even need to find the form: ask Dispatch in plain language ("deploy payments to staging") and it can run the right SSW as a step in its plan, after you approve.

Scope

When you create an SSW in CodeCargo, you can do so in two places:

• A single Project
• CodeCargo Organization

SSWs that are scoped to a single Project are created in the Self-Service tab of the Project UI. Anyone who is a member of that specific project can run the SSW, assuming they have write permissions on the GitHub repository where the underlying dispatchable workflow is defined.

SSWs that are scoped to your CodeCargo Organization are created in the Self-Service dashboard on the left-nav menu. Any member of the GitHub organization can run the SSW, assuming they have read permissions on the GitHub repository where the underlying dispatchable workflow is defined.

If you want a small group of users to run an SSW, create it in a single Project. If you want a few groups of users to run the SSW, you can recreate it in multiple Projects. If you want a large group of users to run the SSW, create it for your entire CodeCargo Organization, and give the target users read permissions or higher for the underlying GitHub repository.

Requirements and Permissions

To create an SSW, you need the following:

1. A GitHub Actions Workflow, triggered by workflow_dispatch
2. CodeCargo must have access to the GitHub repository where the workflow is defined
3. Single Project SSWs - your GitHub repository must be part of the Project

In addition, you need appropriate permissions in the CodeCargo platform:

1. Single Project SSWs - Project Admin or Project Editor
2. Organization SSWs - Org Admin or Org Architect

Workflows That Use Private Repositories

An SSW runs its dispatchable workflow in that workflow's own repository. If the workflow calls a reusable workflow or action stored in a different private or internal repository (for example, a Building Block in a shared platform repository), GitHub only allows the call when that repository shares it:

1. In the repository that holds the reusable workflow or action, open Settings → Actions → General.
2. Under Access, choose the option that makes it accessible from repositories in your organization (or in your enterprise, to share across organizations).
3. Save.

Without this, the run fails at the uses: step with a "workflow was not found" error, even though CodeCargo can see both repositories. See GitHub's guide to sharing actions and workflows across private repositories.

Suggested workflows

On a project's Self-Service page, and on the organization Self-Service dashboard, CodeCargo suggests dispatchable workflows that look like tasks people run on demand and that do not already have a self-service workflow anywhere in the organization. Most are workflows people already start by hand on GitHub. A workflow can also be suggested from its file alone, even when nobody has started it by hand in the last 90 days.

The Suggested workflows panel is a short list, and workflows you have started yourself come first. Each suggestion says why it was picked, including how many times it was started by hand in the last 90 days and by how many people. You only see the panel if you can create a self-service workflow in that scope. See Requirements and Permissions.

• Add a suggestion to create the self-service workflow in one click. Nothing is created until you do, and the workflow on GitHub is not changed. Adding it on a project creates it in that project; adding it on the organization dashboard creates it for the organization.
• Dismiss a suggestion to hide it from that list. Bring it back from the dismissed suggestions. A dismissal applies only to the list you are on — hiding one in a project does not hide it on the organization dashboard, or in another project.

Suggestions come from repositories you can access: the repositories linked to the project, or every active repository when you are on the organization dashboard. They can take a little while to appear after the organization finishes its first sync from GitHub.

Create and Configure an SSW

Creating an SSW scoped to either a single Project or your entire CodeCargo Organization follows the same process once you are on the appropriate page:

1. Click the button to create the SSW
2. Select the dispatchable workflow you'd like to use
3. Configure the SSW

Steps 1 and 2 are very straightforward; however, there are a lot of configuration parameters for step 3 that allow you to fully customize it for your users.

Configure the SSW

General Configuration

CodeCargo provides extensive configuration parameters for your SSW. As you begin, you'll need to provide values for the following options:

1. Git Ref: choose the branch, tag, or commit for your workflow. This will determine which version of your workflow will run when a user executes the SSW
2. Name: this user-visible field will provide a name for your SSW
3. Icon (Optional): this user-visible field will provide an icon for your SSW
4. Description: this user-visible field will provide a description for your SSW

Generate Details Automatically

Check Generate details automatically to have CodeCargo generate the SSW's Name and Description for you instead of typing them in yourself. CodeCargo produces a short name and a markdown description based on the bound workflow.

While it's checked:

• The Name and Description fields are disabled — any values you type are ignored, since CodeCargo owns them
• CodeCargo regenerates the name and description whenever the bound workflow file changes on a pushed branch
• Icons remain manual — pick your own icon regardless of the toggle

Uncheck it at any time to take back manual control over the name and description.

Input Customization

CodeCargo provides fine-tuned controls over SSW inputs. This allows your users to run the SSW in a way that is customized to them. For example, you might create an SSW to Deploy an Azure VM with name=X, deployed to resource group RG=Y, and connected to network=Z. You can customize the SSW inputs to ensure they are flexible enough to help users get their jobs done, and include constraints so they don't cause issues.

CodeCargo reads the underlying GitHub Actions workflow file to populate this list of inputs from the workflow_dispatch trigger definition. Inputs can include text, boolean, and number types, as well as choices whose values are populated from the repository's GitHub Environments. For each input, you will be able to specify the following configuration options:

Restrict Choices [Y/N]

If checked, change the user input from a basic textbox into a dropdown with a limited set of choices. 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

Value Type [User Input/Fixed Value]:

• User Input – Creates an interactive form field for the user (raw input or selection)
• Fixed Value – Hardcoded for consistency, not changeable by the user

Description [text]

Users can specify the description for an input in the yaml file that defines the workflow. Use this field to override the description to fit your specific use-case.

Required [Y/N]

• If an input is marked as required in the workflow's workflow_dispatch inputs section, a value for this input must be provided in the UI form. This field cannot be changed.
• If not marked as required in the YAML file
  • You can optionally mark it as required to force the user to provide a value
  • You can leave it alone and the user does not need to fill it out

Default Value [Y/N]

Workflows can define default values in their yaml file definitions. Check this field to override the default value of this input. If you override the input value, you must provide your own.

Fixed Value Inputs [Y/N]

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). This is useful if you want to specify inputs that you do not want your users to 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.

A Fixed Value and Restrict Choices apply to every run, not only this form — including a run started from the API or from a Dispatch plan. Leave a fixed input out, or send the value you set: a different value is refused, and an omitted one is filled in, even when the workflow marks the input required and has no default of its own. A restricted choice has to be one of the options you allowed. Leaving it out is refused when the workflow would otherwise run with a value you didn't allow.

Permissions Configuration

After configuring your SSW's general settings and inputs, you'll proceed to the Permissions step. This step allows you to control who can run the workflow by selecting from three authorization modes:

GitHub User

• Users with read-write access to the repository can run this workflow
• Uses individual GitHub user tokens for execution

GitHub App (Entire Org)

• All users in the organization can run this workflow
• Uses the GitHub App token for execution

GitHub App (Restricted)

• Only specific users and teams can run this workflow
• Uses the GitHub App token for execution
• Allows you to add individual users or teams as authorized accessors

When you select GitHub App (Restricted), you can:

• Add specific users by searching and selecting from your organization members
• Add entire teams to grant access to all team members
• Remove accessors at any time
• View a table of all current authorized users and teams

Running an SSW

When a user clicks Run Workflow on an SSW card, they are taken to the run form.

The Run Form

The form displays all configurable inputs defined during SSW creation. Input types include text fields, dropdowns (for restricted choices), number fields, and boolean checkboxes. If the SSW administrator configured environment-based inputs, those appear as dropdowns populated from the repository's GitHub Environments.

• User Inputs appear at the top of the form as editable fields
• Fixed Values appear in a separate section at the bottom, grayed out and non-editable
• If the workflow has no inputs at all, the form shows a "Ready to run!" message — just click Run Workflow to start

All required fields must be filled before submission. Validation runs on blur and blocks submission until resolved.

Run Status States

After dispatching a run, CodeCargo tracks its progress through the following states:

The UI automatically polls for status updates every 5 seconds while a run is in progress (up to 8 hours after creation).

Workflow Unavailability

Self-Service Workflows can become unavailable if their underlying GitHub Actions workflow is no longer accessible. This happens when:

• The workflow file is moved or deleted from the repository
• The workflow is removed from the repository's default branch
• The workflow no longer declares workflow_dispatch as a trigger
• The configured Git ref (branch/tag/commit) no longer exists

When you try to run an unavailable workflow, CodeCargo displays a clear message explaining why the workflow cannot be executed, rather than showing a generic error page.

Viewing Run Details

Click on a run from the history list to see its full details:

• Status — current status, with live updates while the run is in progress
• Submitted inputs — all input values that were provided at execution time
• Details — the workflow, repository and branch, the user who triggered the run, the run number and event, and when it was created and started
• View on GitHub — an external link to view the run in GitHub Actions

Troubleshooting a Failed Run

When a run's status is a failure, the run detail page shows a Troubleshoot button alongside the GitHub link. Clicking it opens a workspace with the failing workflow file already loaded, so the Expert Workflow Agent starts from the actual workflow definition instead of an empty session.

The workspace also pulls in the repositories behind any reusable workflows the failing workflow calls, giving the assistant the context it needs to diagnose and fix issues across the full call chain — not just the top-level file.

Run History

You can view SSW run history in two places:

Organization-Level Recent Runs

Navigate to Self-Service → Recent Runs from the organization sidebar. This shows all SSW runs across the organization with statistics cards:

• Total Runs — overall count
• Success Rate — percentage of successful completions
• In Progress — currently active runs
• Failed — runs that ended in failure or timeout

Project-Level Recent Runs

Navigate to a project's Self-Service → Recent Runs tab for a project-scoped view of the same data.

Filtering and Search

Both views provide filtering controls:

• Search — search across run names, repositories, and users
• Status, Name, and User — filter from the column headers of the runs table

The statistics cards update to match the runs you've filtered to.

Start Building