Migrate from GitHub Actions

​

Migrate an existing application with one call

ankra application pipeline convert <application-id>
ankra application pipeline convert <application-id> --keep-workflows

curl -X POST https://platform.ankra.app/api/v1/org/applications/<application-id>/pipeline-migration \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{}'

• Reads what builds the application today and converts it into .ankra/pipeline.yaml through the same converter Ankra AI uses, then stores that as the application’s pipeline definition of record.
• Records the application as building on Ankra Pipelines (pipeline_source becomes ankra_pipeline) right away, so the next push to the tracked branch builds through the pipeline. Nothing waits on a merge.
• Switches Ankra’s generated workflow off on GitHub, so the workflow and the pipeline never build the same commit twice. If the GitHub App lacks the Actions permission the answer says so, and the workflow stops building when the pull request that removes it merges.
• Opens a pull request on the fixed branch ankra/pipeline-migration that commits the pipeline file and removes the generated workflow file. --keep-workflows ({"remove_workflows": false}) leaves the file in the repository, still switched off. A workflow your repository wrote itself is never touched either way.

​

Convert with Ankra AI

• “Convert .github/workflows/ci.yml and .github/workflows/build-deploy.yml into an Ankra pipeline and show me every note.”
• “Convert this .gitlab-ci.yml into .ankra/pipeline.yaml for the orders-api application.”

​

What maps to what

​

Steps that become a stage

​

Steps that become the stage image

​

Steps that are dropped, with a note

​

Everything else

echo "This step used <reference>, which the converter could not map to an Ankra stage."
echo "Replace it with an image that already provides what the action did, a script, or an ankra/* step."
exit 1

​

What each source loses

• The permissions block is not converted: a run’s authority is the intersection of the pipeline’s own permissions, the organisation’s CI policy and the target environment, not the workflow token’s scopes.
• A trigger with no Ankra equivalent is not converted, and a trigger that narrows on something an Ankra trigger cannot (for example pull request types) loses the narrowing: the pipeline runs on more of those events than the workflow did.
• defaults.run.shell is not converted; a stage runs its script with the shell its image provides.
• Several workflows fold into one pipeline whose on: is their union - a path filter that one workflow declares and another does not leaves the union unfiltered, so every run the workflows started still starts. Each workflow’s own push and pull_request branches and paths stay on its stages as event-scoped when blocks wherever they are narrower than the union, and a workflow that does not listen to an event the pipeline does keeps its stages out of it with when.events. A note names the workflows this applied to.
• A second concurrency block is not converted: a pipeline carries one concurrency group, and the first workflow claimed it.
• A job that calls a reusable workflow (uses: ./.github/workflows/…) cannot be followed; its stage fails until it is replaced.
• A workflow that is not valid YAML contributes nothing, and the note says which.

• workflow:rules is not converted, so runs it filtered out are not filtered here.
• A top-level services: block, which gives every job a sidecar, is not converted: declare the services the stages need in the pipeline’s services block and list them on each stage, or the jobs that relied on them fail at runtime.
• A job that triggers a downstream pipeline has no equivalent.
• except: is not converted: an Ankra stage filters on the branches, paths and events it runs for, never on the ones it skips. A rules: block carrying when: never on a changes: list is not converted, and its paths go with it: that rule skips the paths it names, and an Ankra when.paths says which paths the stage runs for, so carrying them across would invert the meaning. Otherwise its changes: paths are carried, onto the stage’s flat when.paths unless the rule names an event. A rule whose if: tests $CI_PIPELINE_SOURCE == "merge_request_event" becomes when.pull_request.paths, one testing == "push" becomes when.push.paths (a matching rule with no changes: leaves that event unfiltered), and the rest go to when.paths. Any other if: condition, and the rules’ order, are not carried, and the note says so.

• A step size of 1x, 2x, 4x or 8x becomes a memory request; any other value is reported and you declare resources.memory yourself.
• bookmarks: pipelines belong to Mercurial and are not converted.
• A parallel group’s fail-fast is not converted: an Ankra run lets the other stages of a group finish when one fails.
• A pipeline that imports from another repository cannot be followed and contributes nothing.
• runs-on labels are not converted: an Ankra stage is placed by the organisation’s CI cluster and the stage’s own runs_on block.
• A manual trigger becomes an approval stage approvable by the admin and operator roles, because anyone with write access could press the Bitbucket button and no Ankra role maps onto that; narrow the roles to whoever actually held the button.
• A pull-requests: pattern is not carried as a filter. Bitbucket matches it against the pull request’s source branch, while an Ankra pull_request trigger and a stage’s when.branches match the target, and nothing in a pipeline filters on the source branch. Each section therefore runs for every pull request (on.pull_request.branches: ['**']), and the note suggests a push trigger on the pattern if that is the filter you need. A '**' section gets no note.
• A step that a branch section shares with a pull request, tag or custom section loses its branch filter, because a stage carries one branch list for all its events; the note names the filter that was dropped.
• clone: lfs: true and clone: enabled: false are not converted: the checkout stage does not fetch Git LFS objects, and every stage shares the workspace it fills. A step’s own clone: settings are not converted either, because a run checks the repository out once.

• A version 2.0 configuration converts the way a 2.1 one does; any orb, command or parameter it cannot declare is simply absent. A setup configuration’s continuation pipeline cannot be followed; only the jobs declared in the file are converted.
• An inline orb is not converted; every step that calls it becomes a stage that fails until it is replaced. An orb job the converter cannot follow is reported the same way.
• A parameter whose name carries a dash is renamed (an input name may not carry one), and every reference to it is renamed the same way.
• An approval job becomes an approval stage approvable by the admin and operator roles, with the same advice to narrow them.
• Anchors and aliases are resolved before conversion, so an anchored executor or step list behaves like an inline one.

​

What to review after conversion

1. The notes, first. Each is a decision the converter took on your behalf or could not take. Stages that fail by design (exit 1 with the reference) are in the YAML so you cannot miss them.
2. Images. Every stage needs an image the organisation’s image policy allows - and so does every sidecar you declare in the pipeline’s services block, whose image and env are held to the same boundary a step’s own are, refusing the whole step rather than running beside it. A policy prefix is matched at a path boundary, and one ending in /, : or @ admits only that boundary (ghcr.io/my-org/ admits ghcr.io/my-org/api and not ghcr.io/my-org:v1) - the settings API refuses a trailing separator at write time anyway, so write the bare prefix. Pin the toolchain images the notes could not derive.
3. Network. A run stage’s tier defaults to none, which denies all egress; give defaults.network: egress-https, or a network on the stage itself, to the ones that install packages or reach a registry. The converted checkout, build and scan stages need nothing said about them: those three kinds default to egress-https (the tier a stage gets by default). That tier reaches public addresses only, so a job that pulled from a VPC-internal mirror, an in-cluster registry or an internal Git host needs its range in ci_egress_allowed_cidrs before the converted stage runs, and without it fails on a connection timeout rather than a permission error. Remember that anything above egress-https is a protected section - as are a stage’s timeout, cache, resources and with: block, and the whole services block. A converted pipeline that declares any of them runs its pull requests under the last approved authority until an administrator approves the definition on your default branch; see Logic is open, authority is closed.
4. Secrets and credentials. The converter declares what the workflow referenced; the secrets block names a source (app_env_secret, org_variable, registry, credential) that has to exist in the organisation. Delivery is live for secrets sourced app_env_secret, org_variable or registry, and for credentials sourced git or registry - each revealed once, at step start, to a file the step reads. secrets: [{from: credential}] still validates but is not deliverable yet, and a credentials binding sourced cloud or object_storage is refused by name until the run has its own scoped identity - reconsider any converted cloud-credential step against that gap.
5. Filters. Where a rules:, except: or trigger types narrowing was lost, add when: or if: so the pipeline does not run more often than the workflow did.
6. Resources and timeouts. A stage takes 500m CPU, 1Gi memory and 30 minutes unless it says otherwise; a Go build or a Playwright suite wants more of the first two. A pull request from a fork gets less than a converted workflow may expect, whatever the file asks for: 2 CPU, 4Gi, a 60-minute step timeout, 8 matrix legs per stage, no sidecar services and no caches, with 256 MiB of artifacts and logs for the whole run. The clamps are applied to the plan, so the pull request’s own status comment shows the smaller run rather than the one the file declared - see Forks.
7. Caches, if you add one by hand. A cache: block does not behave the way actions/cache does across branches. An Ankra cache claim is scoped to the trust of the run that resolved it, so every run that is not on your default branch - a feature branch, a tag, any pull request - shares one non-default scope, and none of them can read or write the claim your default branch’s builds use. GitHub restores a default-branch cache into any branch; Ankra deliberately does not, because that is the path a less-trusted ref uses to poison what production builds from. Budget one cold build per cache key on each side of that line, and none at all on a fork’s pull request, which resolves no shared cache.
8. What executes today, and what the converter never adds. checkout, run, build, scan, gate, publish and deploy all execute end to end; verify and the kinds with no executor yet (preview, agent, approval, webhook, automation, ankra, external) validate with a warning and are skipped, so a converted approval stage blocks nothing and a converted webhook notifies nobody. A deploy stage releases only to host targets outside Kubernetes, so a converted job that ran kubectl or helm does not become one; deploy to a cluster through the application’s push to deploy instead - see What is in place today. The converter itself never writes a gate or a publish stage - no source format has one to map from - so a workflow whose docker/build-push-action pushed straight to your registry converts into a pipeline whose build stage pushes a digest to Ankra’s own CI staging repository only, and stops there: without a gate stage after scan and a publish stage after gate, nothing ever reaches your real repository. Add both by hand (see the worked example) rather than assuming the converted file publishes what the workflow did.

ankra pipeline validate .ankra/pipeline.yaml --application my-service

​

Run both side by side

• Do not make Ankra pipeline a required check in branch protection until it has been green for as long as you would trust any new CI system, and never while its stages include a kind that does not execute yet. Such a stage is skipped, not failed, so the check goes green having done none of what the stage names - read the run’s skipped stages, not only its conclusion.
• Retire the workflow deliberately. Ankra does not delete a workflow for you; when it proposes retiring a generated one, it will be a reviewable pull request that you merge.